Laravel Go Translate Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require codebuglab/laravel-go-translate
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Codebuglab\LaravelGoTranslate\GoTranslateServiceProvider"
   

2. First Use Case: Translate a Laravel resource (e.g., resources/views):

   php artisan translate:resource en es resources/views
   

   Replace en (source language) and es (target language) with your desired language codes.

3. Where to Look First:

   • Artisan Commands: Check php artisan for available commands (translate:resource, translate:vendor, translate:folder, translate:file).
   • Config File: Located at config/laravel-go-translate.php (if published). Adjust settings like google_api_key (if needed) or default languages.
   • Service Provider: Codebuglab\LaravelGoTranslate\GoTranslateServiceProvider registers commands and binds the translator service.

Implementation Patterns

Usage Patterns

1. Translating Laravel Resources: Use the translate:resource command to translate views, languages, or other resource files. Example:

   php artisan translate:resource en fr resources/lang
   

   • Workflow: Run the command in a development environment, review translations, and commit the generated files (e.g., resources/lang/fr/*.php).

2. Translating Vendor Files: Translate third-party packages (e.g., Blade templates in vendor):

   php artisan translate:vendor en de vendor/package-name
   

   • Caution: Only translate vendor files if you’re comfortable overriding them (consider forking the package instead).

3. Translating Folders/Files:

   • Folder:

     php artisan translate:folder en ja /path/to/folder
     

   • File:

     php artisan translate:file en zh resources/views/welcome.blade.php
     

   • Use Case: Translate specific files (e.g., Blade templates, config files) or entire directories (e.g., config/).

4. Integration with Workflows:

   • CI/CD: Add commands to a post-install or post-deploy script to auto-translate resources during deployment (e.g., for multilingual sites).
   • Localization Pipeline:
     1. Develop in English (en).
     2. Run translate:resource en es resources/lang to generate Spanish translations.
     3. Manually review and refine translations in resources/lang/es/.

5. Customizing Translations:

   • Use the --extension option to specify file extensions (e.g., --extension=php,blade):

     php artisan translate:folder en fr resources/views --extension=blade
     

   • Post-Translation: Override auto-generated translations in language files (e.g., resources/lang/es/messages.php).

Integration Tips

1. Environment-Specific Config:

   • Disable translations in production by wrapping commands in environment checks (e.g., if (app()->environment('local'))).
   • Example in composer.json:

     "scripts": {
       "post-install-cmd": [
         "@php artisan translate:resource en es resources/lang"
       ]
     }
     

     Add this only to dev dependencies or use a script like npm run dev && php artisan translate:resource ....

2. Handling Dynamic Content:

   • For dynamic content (e.g., user-generated text), use this package to pre-translate static strings, then handle dynamic content via Laravel’s localization features (e.g., __('key')).

3. Combining with Other Packages:

   • Use with spatie/laravel-translatable for database-localized models:

     // After translating resources/lang, ensure your models use the same keys.
     $model->title = __('translated.key');
     

4. Testing:

   • Mock the translator service in tests to avoid API calls:

     $this->app->instance('google-translate', Mockery::mock());
     

Gotchas and Tips

Pitfalls

1. Google API Limitations:

   • The package uses Google Translate’s free tier, which has quotas. Avoid translating large files repeatedly.
   • Error: If you hit limits, you’ll see Google_Service_Exception. Solution: Add a google_api_key to config/laravel-go-translate.php or wait.

2. File Overwrites:

   • Commands overwrite target files by default. Backup or use --dry-run first:

     php artisan translate:file en fr file.blade.php --dry-run
     

   • Tip: Review diffs before committing:

     git diff resources/lang/es/
     

3. Unsupported File Types:

   • The package targets .php, .blade.php, and text-based files. Binary files (e.g., .png) or non-text files (e.g., .json with non-string values) may break.
   • Fix: Exclude unsupported files with --extension or pre-process files.

4. Language Code Mismatches:

   • Ensure target language codes (e.g., es for Spanish) match Google’s supported languages. Invalid codes (e.g., spa) will fail silently or return poor results.

5. Vendor File Risks:

   • Translating vendor files can cause conflicts during composer update. Best Practice: Fork the package and translate the forked version.

Debugging

1. Command Output:

   • Use -v (verbose) flag to debug:

     php artisan translate:resource en fr resources/lang -v
     

   • Look for errors like Failed to translate file X or Unsupported extension.

2. Logging:

   • Enable Laravel logging to track API calls:

     // config/logging.php
     'default' => 'single',
     'channels' => [
         'single' => [
             'driver' => 'single',
             'path' => storage_path('logs/translate.log'),
             'level' => 'debug',
         ],
     ],
     

3. API Key Issues:

   • If using a custom google_api_key, ensure it has the Cloud Translation API enabled and billing set up (even for free tier).

Tips

1. Exclude Files: Use .gitignore-style patterns to skip files (e.g., node_modules, vendor):

   php artisan translate:folder en fr resources/views --exclude="node_modules,*.min.js"
   

2. Batch Processing: For large projects, translate incrementally:

   # Step 1: Translate views
   php artisan translate:folder en fr resources/views
   
   # Step 2: Translate language files
   php artisan translate:resource en fr resources/lang
   

3. Custom Translator: Extend the package by binding a custom translator in the service provider:

   $this->app->bind('google-translate', function () {
       return new CustomGoogleTranslator();
   });
   

4. Performance:

   • Cache translations locally to avoid repeated API calls:

     // config/laravel-go-translate.php
     'cache_translations' => true,
     'cache_ttl' => 3600, // 1 hour
     

5. Fallback Languages: Configure fallback languages in config/laravel-go-translate.php:

   'fallback_languages' => [
       'es' => 'en', // Fallback to English for Spanish
   ],
   

6. Post-Translation Hooks: Use Laravel’s translated event to process files after translation:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       'translated' => [
           'App\Listeners\PostTranslateListener',
       ],
   ];