System Requirements
- Shopware 6.4+
- PHP 8.0+
- MySQL/MariaDB 10.3+
- 500MB free disk space for backups
- Network access to api-free.deepl.com
Installation Steps
- Install Plugin
bin/console plugin:refresh
bin/console plugin:install --activate TopdataMachineTranslationsSW6
- Configure DeepL API Key
Permanent configuration (recommended):
# Add to your environment configuration (e.g., .env)
DEEPL_FREE_API_KEY=your-api-key-here
Temporary usage:
DEEPL_FREE_API_KEY=your-key-here bin/console topdata:translate [...]
- Verify Installation
bin/console topdata:translate --list-languages
Post-Installation
- Backup directory:
/tmp/database-backups(configurable via plugin settings) - First-run recommendation: Use
--tableoption to test specific tables
Environment Variables
DEEPL_FREE_API_KEY
- Required: Yes
- Description: DeepL API authentication key
- Format: String
- Example:
export DEEPL_FREE_API_KEY=your-key-here
Command Options
--table
- Type: Multiple values allowed
- Description: Specific tables to translate
- Example:
--table=product_translation --table=category_translation
--from
- Default:
de-DE - Description: Source language (4-letter code)
- Supported Formats:
xx-XXorxx
--to
- Default:
cs-CZ - Description: Target language (4-letter code)
- Note: Actual code converted to 2-letter format for DeepL API
--no-backup
- Type: Flag
- Description: Disable automatic backups
- Risk: Not recommended for production use
Backup Configuration
- Location:
/tmp/database-backups - Retention: Manual cleanup required
- Format: SQL dump per table with timestamp
Translation Settings
- Excluded Columns:
- Fields ending with
_idor_config created_at/updated_attimestamps
- Fields ending with
- Batch Size: Individual row processing
- Error Handling: Skips failed translations, continues with next column
Configuration XML Translation Command
The topdata:machine-translations:translate-config-xml command translates configuration XML files using DeepL translation service. This command is designed to automatically translate specific text elements in Shopware 6 configuration XML files to multiple target languages.
Purpose
This command processes Shopware 6 configuration XML files and translates translatable text elements to specified target languages. It supports translating:
<title>elements<label>elements<helpText>elements<resetOption>elements
Prerequisites
Before using this command, ensure:
- DeepL API key is configured as
DEEPL_FREE_API_KEYenvironment variable - The XML file exists and is valid
- Source and target language codes are properly formatted (e.g.,
de-DE,cs-CZ,en-GB)
Usage
bin/console topdata:machine-translations:translate-config-xml <file> --from=<source> --to=<target1> [--to=<target2> ...] [options]
Arguments
| Argument | Required | Description |
|---|---|---|
file | Yes | Path to the XML file to translate |
Options
| Option | Short | Required | Description |
|---|---|---|---|
--from | -f | Yes | Source language code (e.g., de-DE) |
--to | -t | Yes | Target language code(s). Can be specified multiple times (e.g., --to=cs-CZ --to=sk-SK) |
--force | - | No | Force translation even if translation already exists for target language |
--no-backup | - | No | Do not create a backup of the original file |
Examples
Basic Translation
Translate a German configuration file to Czech:
bin/console topdata:machine-translations:translate-config-xml config.xml --from=de-DE --to=cs-CZ
Multiple Target Languages
Translate to multiple languages at once:
bin/console topdata:machine-translations:translate-config-xml config.xml --from=de-DE --to=cs-CZ --to=sk-SK --to=en-GB
Force Overwrite Existing Translations
Overwrite existing translations for specified languages:
bin/console topdata:machine-translations:translate-config-xml config.xml --from=de-DE --to=cs-CZ --force
Skip Backup Creation
Translate without creating a backup file:
bin/console topdata:machine-translations:translate-config-xml config.xml --from=de-DE --to=cs-CZ --no-backup
Behavior Details
Backup Creation
By default, the command creates a backup of the original file before making changes. The backup file follows the pattern:
<filename>.backup.YYYY-MM-DD_HH-MM-SS
Translation Logic
- Source Text Detection: The command first looks for child
<text>elements with the specified source language (--from). If none found, it uses the parent element’s text content. - Existing Translation Check: Before translating, it checks if a translation already exists for the target language. Existing translations are skipped unless
--forceis used. - Translation Storage: Translations are added as new
<text lang="target-code">child elements within the parent element.
Error Handling
The command will fail with appropriate error messages for:
- Missing DEEPL_FREE_API_KEY environment variable
- Non-existent XML file
- Invalid XML format
- Failed backup creation
- Failed file save operations
Output
The command provides detailed progress information:
- Number of translatable nodes found
- Processing status for each target language
- Number of translations added per language
- Backup file location (when created)
- Success/failure status
XML Structure Requirements
The command expects XML files with the following structure for translatable elements:
<config>
<title>
<text lang="de-DE">German Title</text>
</title>
<label>
<text lang="de-DE">German Label</text>
</label>
<helpText>
<text lang="de-DE">German help text</text>
</helpText>
</config>
After translation, the structure will include additional <text> elements:
<config>
<title>
<text lang="de-DE">German Title</text>
<text lang="cs-CZ">Czech Title</text>
</title>
</config>
Snippet JSON Translation Command
The topdata:machine-translations:translate-snippets-json command translates Shopware plugin snippet JSON files (src/Resources/snippet/*.json) with DeepL. It supports one plugin or all plugins in a plugins root directory.
Purpose
Use this command to generate or update locale snippet files from a source locale file while preserving snippet structure and existing translations (unless --force is used).
Prerequisites
- DeepL API key is configured as
DEEPL_FREE_API_KEY - Source snippet file exists, e.g.
de-DE.json - Plugin snippet path follows
src/Resources/snippet/
Usage
bin/console topdata:machine-translations:translate-snippets-json [--plugin=<name> ...|--all-plugins] --from=<source-locale> --to=<target-locale> [--to=<target-locale> ...] [options]
Options
| Option | Short | Required | Description |
|---|---|---|---|
--plugin | -p | Yes* | Plugin technical name. Repeatable and comma-separated values are supported |
--all-plugins | - | Yes* | Process all plugin directories in --plugins-root |
--plugins-root | - | No | Root directory containing plugins (default: /www/custom/plugins) |
--from | -f | Yes | Source locale file name without extension, e.g. de-DE |
--to | -t | Yes | Target locale(s), repeatable |
--force | - | No | Overwrite existing non-empty target translations |
--dry-run | - | No | Preview processing without writing files |
--no-backup | - | No | Skip backup creation for existing target files |
--skip-empty | - | No | Skip translating empty source strings |
* Exactly one selection mode is required: use either --plugin or --all-plugins.
Examples
Translate One Plugin
bin/console topdata:machine-translations:translate-snippets-json --plugin=SwagBasicExample --from=de-DE --to=en-GB
Translate One Plugin to Multiple Locales
bin/console topdata:machine-translations:translate-snippets-json --plugin=SwagBasicExample --from=de-DE --to=en-GB --to=cs-CZ
Dry-Run All Plugins
bin/console topdata:machine-translations:translate-snippets-json --all-plugins --from=de-DE --to=en-GB --dry-run
Force Overwrite Existing Values
bin/console topdata:machine-translations:translate-snippets-json --plugin=MyPlugin --from=de-DE --to=en-GB --force
Behavior Details
- Source file:
<plugin>/src/Resources/snippet/<from>.json - Target files:
<plugin>/src/Resources/snippet/<to>.json - Existing non-empty target values are kept by default
- Nested JSON key structure is preserved recursively
- Backups are created for existing target files unless
--no-backupis set - If source snippet file is missing, the plugin is skipped and listed in summary
Exit Behavior
- Returns
SUCCESSwhen at least one plugin was processed successfully - Returns
FAILUREwhen all plugin jobs fail or are skipped
General Questions
Q: Where are backups stored?
Backups are created in /tmp/database-backups by default. This is temporary storage - move backups to persistent storage for production use.
Q: How do I translate multiple tables?
Use multiple —table options:
bin/console topdata:translate --table=table1 --table=table2
API Key Issues
Q: “DEEPL_FREE_API_KEY is missing” error
- Verify the key is set in your environment
- For CLI usage, prepend commands with
DEEPL_FREE_API_KEY=your-key - Ensure no typos in the key
Q: Difference between Free and Pro API keys?
- Free keys:
api-free.deepl.com - Pro keys:
api.deepl.comUpdate the API URL inDeeplTranslator.phpfor Pro accounts
Language Support
Q: Which language codes are supported?
Use 2-letter codes (de, en) or 4-letter codes (de-DE, en-GB). The plugin automatically converts to 2-letter format for DeepL API.
Q: Why are some columns not translated?
We skip columns:
- Ending with
_idor_config - Containing timestamps
- With existing translations
Troubleshooting
Q: “Backup file was not created” error
- Verify mysqldump is installed
- Check directory permissions for
/tmp - Ensure sufficient disk space
Q: Translations not appearing in Shopware
- Clear Shopware cache
- Verify language IDs exist in
languagetable - Check translation table relationships