Potrans Laravel Package

Getting Started

Start by installing the package globally or locally via Composer:

composer require --dev om/potrans

Or install globally:

composer global require om/potrans

After installation, run ./vendor/bin/potrans list to see available commands. The two primary entry points are:

• potrans google — for Google Cloud Translate API
• potrans deepl — for DeepL API

Before using either, configure your API key via environment variables (GOOGLE_TRANSLATE_API_KEY or DEEPL_API_KEY) or pass via --apikey= flag. A .env file is automatically loaded from the current directory.

First practical use (v1.0.2+): Translate a single .po file to German, now with improved HTML entity handling:

./vendor/bin/potrans google ./locale/messages.po ./locale --lang=de

Implementation Patterns

• CI/CD Integration: Wrap potrans commands in Composer scripts or CI pipelines to auto-update translations after new POT file generation. Example composer.json script (unchanged):

  "scripts": {
    "translate:de": "potrans google ./locale/messages.pot ./locale --lang=de"
  }
  

• Language Hygiene: Leverage --only (write only PO files, skip MO) and --ignore="^#, fuzzy$" to preserve manual edits. Useful for preserving fuzzy flags and avoiding overwriting human-reviewed content.

• Source Mapping via POT Files: When working with evolving source strings, generate and maintain .pot templates first:

  xgettext -o ./locale/messages.pot ./src/**/*.php
  ./vendor/bin/potrans google ./locale/messages.pot ./locale --lang=fr
  

• Custom Translators: Extend translation logic by pointing --translator= to a class implementing \Potrans\Translator\TranslatorInterface. Note: v1.0.2 fixes object instantiation issues in PoTranslator methods (#41).

• Caching Strategy: potrans caches translations in ~/.potrans/cache/. In CI, clear cache before runs or use --no-cache flag to avoid stale translations.

• PHP 8.3+ Compatibility: v1.0.2+ officially supports PHP 8.3 and 8.5. Ensure your environment matches (tested via GitHub Actions CI).

Gotchas and Tips

• Language Code Mapping: Google and DeepL use different codes for some languages (e.g., zh-CN, zh-TW). potrans auto-maps, but verify with --debug to confirm resolution.

• .env Loading: The tool only loads .env from the working directory, not nested or parent paths. Set working directory explicitly in scripts.

• Cache Invalidation: If source strings change but translations stay cached, use --force (not --all) to bypass cache.

• MO File Overwrite Risk: By default, MO files are regenerated. Use --only to generate only .po files during review, then later regenerate MOs.

• Debugging API Calls: Add --debug to surface HTTP status and raw responses. Especially useful when DeepL returns 403 (invalid key) or Google quota errors.

• Symfony/Console Compatibility: v1.0+ requires Symfony 7 or 8 — ensure dev environment matches (e.g., symfony/console:^7.0), or downgrade to older release for legacy Symfony.

• PO File Encoding: Ensure all input POs are UTF-8 encoded. Non-UTF-8 files can cause silent failures or garbled translations — use msgconv -f UTF-8 before translation if needed.

• DeepL Error Handling (v1.0.2+): Non-recoverable DeepL exceptions (e.g., API failures) are no longer silently swallowed (#40). Use --debug to diagnose issues.

• HTML Entities in Translations (v1.0.2+): The package now properly decodes htmlentities() in translations (#39). If your source strings contain encoded entities (e.g., &), translations will be cleaner.

• PHP 8.3/8.5 Compatibility: Test thoroughly in PHP 8.3+ environments. The package now includes CI checks for these versions (#41).