Topdata Topdata Docs

TopdataMachineTranslationsSW6 v1.1.0

This is an older version of the manual. Show the latest version

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

  1. Install Plugin
bin/console plugin:refresh
bin/console plugin:install --activate TopdataMachineTranslationsSW6
  1. 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 [...]
  1. Verify Installation
bin/console topdata:translate --list-languages

Post-Installation

  • Backup directory: /tmp/database-backups (configurable via plugin settings)
  • First-run recommendation: Use --table option 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-XX or xx

--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 _id or _config
    • created_at/updated_at timestamps
  • 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

  1. Verify the key is set in your environment
  2. For CLI usage, prepend commands with DEEPL_FREE_API_KEY=your-key
  3. Ensure no typos in the key

Q: Difference between Free and Pro API keys?

  • Free keys: api-free.deepl.com
  • Pro keys: api.deepl.com Update the API URL in DeeplTranslator.php for 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 _id or _config
  • Containing timestamps
  • With existing translations

Troubleshooting

Q: “Backup file was not created” error

  1. Verify mysqldump is installed
  2. Check directory permissions for /tmp
  3. Ensure sufficient disk space

Q: Translations not appearing in Shopware

  1. Clear Shopware cache
  2. Verify language IDs exist in language table
  3. Check translation table relationships