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
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