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: translate a single .po file to German:

./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:

  "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 and skip non-essential entries. 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, e.g., to add custom post-processing or fallback handling.

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

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 — see PR #26 and #31.

• .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 — note PR #22 and #30 clarify behavior.

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