Artisan Translator Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require artryazanov/artisan-translator
   

   Publish the config file:

   php artisan vendor:publish --provider="ArtisanTranslator\ArtisanTranslatorServiceProvider" --tag="config"
   

2. Configuration Edit config/artisan-translator.php to set:

   • google_api_key (for Gemini AI translation)
   • source_language (default: en)
   • target_languages (e.g., ['fr', 'es'])
   • blade_paths (directories to scan for Blade templates)

3. First Use Case Extract and translate strings from Blade files:

   php artisan artisan-translator:extract
   php artisan artisan-translator:translate
   

   This generates/update resources/lang/{locale}/messages.php with translated keys.

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline Add to phpunit.xml or GitHub Actions:

   <phpunit>
       <listeners>
           <listener class="ArtisanTranslator\Tests\TranslationListener" file="vendor/artisan-translator/src/Tests/TranslationListener.php"/>
       </listeners>
   </phpunit>
   

   Run before merging to enforce translation updates:

   php artisan artisan-translator:check
   

2. On-Demand Translation Use the translate command interactively:

   php artisan artisan-translator:translate --key="validation.required" --locale="fr"
   

3. Blade Template Hooks Add @translate directives in Blade:

   <p>@translate('welcome.message')</p>
   

   The package auto-detects these during extraction.

4. Dynamic Language Switching Override target_languages in runtime config:

   config(['artisan-translator.target_languages' => ['de']]);
   

Gotchas and Tips

Pitfalls

• Google API Quotas: Monitor Gemini API usage to avoid rate limits. Cache translations locally:

  config(['artisan-translator.cache_translations' => true]);
  

• Blade Caching: Clear Blade cache after translations:

  php artisan view:clear
  

• Key Conflicts: Avoid duplicate keys (e.g., home.welcome vs home.welcome.title). Use nested arrays:

  'home' => [
      'welcome' => [
          'title' => 'Bonjour',
      ],
  ],
  

Debugging

• Dry Run: Test extraction without writing files:

  php artisan artisan-translator:extract --dry-run
  

• Verbose Output: Log skipped keys:

  php artisan artisan-translator:translate --verbose
  

• Custom Extractors: Extend ArtisanTranslator\Extractor\ExtractorInterface for non-Blade files (e.g., JS):

  class CustomExtractor implements ExtractorInterface {
      public function extract($file) { /* ... */ }
  }
  

Extension Points

• Custom Translators: Replace Gemini with DeepL or Linguee:

  config(['artisan-translator.translator' => \App\Services\CustomTranslator::class]);
  

• Post-Translation Hooks: Listen to translation.generated events:

  event(new TranslationGenerated($key, $locale, $translation));
  

• Excluded Directories: Skip vendor or test templates:

  config(['artisan-translator.ignore_paths' => ['vendor/*', 'tests/*']]);