Potrans Laravel Package

Technical Evaluation

Architecture Fit

• Limited Laravel Integration: Designed as a standalone CLI tool (Symfony Console-based), not a Laravel service provider or facade. No native Laravel translation system (Lang facade, config/translation.php) integration.
• Gettext-Focused: Optimized for .po/.pot/.mo files, not Laravel’s JSON/array-based translations. Requires manual sync between Laravel’s resources/lang and Gettext files.
• API-Driven Workflow: Externalizes translation logic to Google/DeepL APIs, bypassing Laravel’s built-in translation caching (e.g., cache.forget('translations')).

Integration Feasibility

• Symfony Version Conflict: Requires symfony/console:^7.0|^8.0; Laravel 10+ uses Symfony 6.4. High risk of breaking Laravel core if forced to upgrade.
• No Laravel Hooks: Lacks event listeners (e.g., translated, translation.failed) or service container binding for Laravel’s translation pipeline.
• Manual File Management: Requires manual handling of .po/.mo files in resources/lang or a custom directory, with no automatic sync to Laravel’s translation loader.

Technical Risk

• Dependency Isolation: No Laravel-specific tests or CI checks. Risk of hidden conflicts with Laravel’s symfony/process, symfony/console (v6.x), or laravel/framework.
• API Key Management: Relies on .env files in the working directory, not Laravel’s config/services.php or .env auto-loading. Security risk if keys are exposed in CI/CD.
• Caching Quirks: Cache directory (~/.potrans) may conflict with Laravel’s storage/framework/cache. No built-in invalidation for Laravel’s translation cache.
• PHP 8.3+ Compatibility: While the package supports PHP 8.5, Laravel’s ecosystem (e.g., older packages) may lag behind, causing runtime issues.

Key Questions

1. Translation Sync Strategy:

   • How will .po/.mo files map to Laravel’s resources/lang structure? Will you use a custom loader (e.g., GettextLoader) or manual file watches?
   • How will you handle conflicts between Laravel’s translation cache and potrans’s cached API responses?

2. CI/CD Pipeline:

   • Where will potrans commands run (pre-commit, build, or deploy)? How will you trigger them without manual intervention?
   • How will you manage API key rotation/secrets in CI (e.g., GitHub Actions, GitLab CI)?

3. Fallback Mechanisms:

   • What’s the plan for API failures (rate limits, outages)? Will you implement retries or fallback to a local cache?
   • How will you handle unsupported languages or edge cases (e.g., RTL languages, plural forms)?

4. Performance:

   • Will potrans run in parallel for multiple languages, or sequentially? How will this impact build times?
   • How will you monitor API costs (e.g., DeepL/Google quotas) and avoid surprises?

5. Maintenance:

   • Who will own updates to potrans (e.g., Symfony 8.x migration)? Will you fork or submit PRs upstream?
   • How will you handle breaking changes (e.g., API deprecations, new Laravel versions)?

Integration Approach

Stack Fit

• Laravel + Gettext Hybrid:

  • Use potrans for externalized translations (e.g., vendor docs, third-party strings) stored in .po files, while keeping Laravel’s resources/lang for app-specific translations.
  • Integrate with Laravel’s AppServiceProvider to auto-load .mo files via a custom GettextLoader (extend Illuminate\Translation\LoaderInterface).
  • Example:

    // app/Providers/AppServiceProvider.php
    public function register()
    {
        $loader = new GettextLoader(base_path('resources/lang'));
        $this->app->singleton('translation.loader', fn() => $loader);
    }
    

• CI/CD Pipeline:

  • Pre-commit: Run potrans to update .po files from source code (via xgettext).
  • Build Phase: Translate .po → .mo using potrans + Google/DeepL.
  • Deploy Phase: Sync .mo files to storage/lang or a CDN.
  • Example GitHub Actions workflow:

    jobs:
      translate:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - run: composer install
          - run: ./vendor/bin/potrans google resources/lang/messages.pot resources/lang --lang=de --force
          - run: msgfmt resources/lang/de/messages.po -o resources/lang/de/messages.mo
    

Migration Path

1. Phase 1: Pilot Project

   • Isolate a non-critical module (e.g., admin dashboard) and migrate its translations to .po files.
   • Use potrans in a local dev script before committing to CI.
   • Test with Laravel’s php artisan translate:load (custom command) to verify .mo loading.

2. Phase 2: CI/CD Integration

   • Add potrans to composer.json scripts:

     "scripts": {
       "translate:all": "potrans google resources/lang/messages.pot resources/lang --langs=\"de,fr,es\" --force"
     }
     

   • Use Laravel’s Artisan::call() to trigger translations from a custom command:

     // app/Console/Commands/TranslateCommand.php
     public function handle()
     {
         $exitCode = Artisan::call('potrans:google', [
           'source' => 'resources/lang/messages.pot',
           'target' => 'resources/lang',
           '--langs' => 'de,fr',
           '--force' => true,
         ]);
         if ($exitCode !== 0) throw new \RuntimeException('Translation failed');
     }
     

3. Phase 3: Full Adoption

   • Replace Laravel’s lang files with .po/.mo for all languages.
   • Deprecate old JSON/array translations via a migration script that converts resources/lang/*.php to .po files.

Compatibility

• Symfony Conflict Workaround:

  • Use a separate Composer project for potrans (e.g., vendor/bin/potrans in a monorepo) to avoid Symfony version clashes.
  • Alternatively, downgrade potrans to v0.0.9 (last Symfony 6.x-compatible release) and pin dependencies:

    composer require om/potrans:0.0.9 --dev
    composer require symfony/console:^6.4
    

  • Risk: May miss bug fixes (e.g., PHP 8.3+ support).

• Laravel Translation Loader:

  • Implement a custom loader to bridge .mo files with Laravel’s Translator:

    class GettextLoader implements LoaderInterface {
        public function load($locale, $group, $namespace = null)
        {
            $path = resource_path("lang/{$locale}/{$group}.mo");
            if (!file_exists($path)) return [];
            $translations = gettext_translations($path);
            return array_map(fn($t) => $t['translation'], $translations);
        }
    }
    

Sequencing

1. Prerequisites:

   • Ensure gettext PHP extension is enabled (php -m | grep gettext).
   • Set up API keys in .env or CI secrets:

     DEEPL_API_KEY=your_key_here
     GOOGLE_TRANSLATE_API_KEY=your_key_here
     

2. Initial Setup:

   • Generate .pot template from source code:

     xgettext --default-domain=messages --directory=app --output=resources/lang/messages.pot
     

   • Initialize .po files for target languages:

     msginit --locale=de --input=resources/lang/messages.pot --output-file=resources/lang/de/LC_MESSAGES/messages.po
     

3. Translation Workflow:

   • Develop: Use Laravel’s lang files for active development.
   • Build: Run potrans to update .po files from source:

     ./vendor/bin/potrans google resources/lang/messages.pot resources/lang --lang=de --force
     

   • Deploy: Compile .mo files and sync to production:

     msgfmt resources/lang/de/LC_MESSAGES/messages.po -o resources/lang/de/LC_MESSAGES/messages.mo
     

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor potrans for Symfony 8.x migrations. Plan to fork or patch if Laravel’s Symfony 6.x support ends.
  • Update gettext PHP extension and `msg