Translation Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cavernbay/translation-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       CavernBay\TranslationBundle\CavernBayTranslationBundle::class => ['all' => true],
   ];
   

2. First Export Generate a CSV for all translations (English as reference):

   php bin/console cavernbay:translation:export --reference-locale=en --output=translations.csv
   

   Key flags:

   • --reference-locale: Base locale for comparison (e.g., en).
   • --filter-bundle: Limit to specific bundles (e.g., AppBundle).
   • --filter-domain: Limit to domains (e.g., messages).

3. First Import After translators update translations.csv, import back:

   php bin/console cavernbay:translation:import translations.csv
   

   Verify with:

   php bin/console debug:translation
   

Implementation Patterns

Workflow Integration

1. Translation Lifecycle

   • Export → Send to translators (CSV/Excel-friendly).
   • Translate → Use tools like Poedit or Google Sheets.
   • Import → Merge updates into translations/ directory.
   • Validate → Check for missing/duplicate keys post-import.

2. Domain-Specific Exports Export only frontend messages (domain: messages):

   php bin/console cavernbay:translation:export \
     --reference-locale=en \
     --filter-domain=messages \
     --output=frontend_translations.csv
   

3. Vendor Bundle Support Include translations from installed bundles (e.g., FOSUserBundle):

   php bin/console cavernbay:translation:export --include-vendors
   

4. Automated CI Pipeline Add to composer.json scripts:

   "scripts": {
       "post-update-cmd": [
           "php bin/console cavernbay:translation:export --reference-locale=en --output=translations.csv"
       ]
   }
   

   Trigger on composer update to keep CSV in sync.

5. Fallback Locale Handling Configure fallback in config/packages/translation.yaml:

   framework:
       default_locale: en
       translator:
           fallbacks:
               - en
   

   CBTB respects this during exports/imports.

Gotchas and Tips

Pitfalls

1. CSV Format Sensitivity

   • Tab-separated: CBTB expects \t (not commas). Use --delimiter if needed:

     php bin/console cavernbay:translation:export --delimiter=,
     

   • Encoding: Save CSV as UTF-8 (translators may corrupt it with BOM).

2. Locale Mismatches

   • If --reference-locale doesn’t exist, the command fails. Pre-create locales in translations/:

     mkdir -p translations/fr
     touch translations/fr/messages.yaml
     

3. Vendor Overwrites Importing vendor translations replaces existing files. Backup first:

   cp -r translations/ translations_backup/
   

4. YAML vs. CSV Conflicts

   • CBTB converts YAML to CSV during export, but imports back to YAML.
   • If CSV has malformed YAML (e.g., unescaped colons), imports fail. Validate with:

     php bin/console cavernbay:translation:validate translations.csv
     

5. Symfony 6+ Quirks

   • Autowiring: Ensure CavernBayTranslationBundle is loaded before FrameworkBundle.
   • Debug Mode: Some commands fail in dev if translations are missing. Use --no-debug:

     php bin/console cavernbay:translation:import translations.csv --no-debug
     

Debugging Tips

1. Dry Run Imports Preview changes without writing files:

   php bin/console cavernbay:translation:import translations.csv --dry-run
   

2. Log Missing Keys Check for untranslated entries:

   php bin/console cavernbay:translation:check --locale=fr
   

3. Custom Exporters Extend the exporter to add metadata (e.g., context):

   // src/Command/CustomTranslationExporter.php
   use CavernBay\TranslationBundle\Command\ExportTranslationCommand;
   use Symfony\Component\Console\Input\InputInterface;
   
   class CustomTranslationExporter extends ExportTranslationCommand {
       protected function configure() {
           $this->setName('app:custom-export');
       }
   
       protected function execute(InputInterface $input, OutputInterface $output) {
           $this->addMetadataToCsv(); // Custom logic
           parent::execute($input, $output);
       }
   }
   

4. Git Ignore Add to .gitignore to avoid committing generated CSVs:

   /translations.csv
   /*.csv
   

5. Performance For large projects, export in chunks by bundle:

   find src -name "*.php" | xargs grep -l "__" | cut -d'/' -f2 | sort | uniq | while read bundle; do
       php bin/console cavernbay:translation:export --filter-bundle=$bundle --output=$bundle.csv
   done