Topdata Topdata Docs

TopdataMachineTranslationsSW6

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

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

ArgumentRequiredDescription
fileYesPath to the XML file to translate

Options

OptionShortRequiredDescription
--from-fYesSource language code (e.g., de-DE)
--to-tYesTarget language code(s). Can be specified multiple times (e.g., --to=cs-CZ --to=sk-SK)
--force-NoForce translation even if translation already exists for target language
--no-backup-NoDo 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

  1. 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.
  2. Existing Translation Check: Before translating, it checks if a translation already exists for the target language. Existing translations are skipped unless --force is used.
  3. 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

OptionShortRequiredDescription
--plugin-pYes*Plugin technical name. Repeatable and comma-separated values are supported
--all-plugins-Yes*Process all plugin directories in --plugins-root
--plugins-root-NoRoot directory containing plugins (default: /www/custom/plugins)
--from-fYesSource locale file name without extension, e.g. de-DE
--to-tYesTarget locale(s), repeatable
--force-NoOverwrite existing non-empty target translations
--dry-run-NoPreview processing without writing files
--no-backup-NoSkip backup creation for existing target files
--skip-empty-NoSkip 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-backup is set
  • If source snippet file is missing, the plugin is skipped and listed in summary

Exit Behavior

  • Returns SUCCESS when at least one plugin was processed successfully
  • Returns FAILURE when 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

  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