Statamic Translate Lang Files Laravel Package

Getting Started

Minimal Steps

1. Install the package:

   composer require bit-mx/statamic-translate-lang-files
   php artisan statamic-translate-lang-files:install
   

2. Assign permissions to roles in Statamic CP:
   • access translation-manager utility
   • edit translation manager
   • sync translation manager
3. Access the utility via the Statamic Control Panel under "Utilities" (or navigate directly to /cp/translate-lang-files).

First Use Case

Edit a translation key for a specific locale:

1. Navigate to the Translation Manager utility.
2. Select a locale (e.g., es) and translation group (e.g., auth.php).
3. Locate the key you want to edit (e.g., failed).
4. Modify the value in the UI and click Save.
5. Verify the change in resources/lang/es/auth.php.

Implementation Patterns

Workflows

1. In-Place Translation Editing

• Pattern: Use the CP utility to edit translations directly.
• Workflow:

  sequenceDiagram
    participant User
    participant CP
    participant Package
    participant LangFiles
  
    User->>CP: Navigate to Translation Manager
    CP->>Package: Fetch locales/groups
    Package->>LangFiles: Read `lang/{locale}/*.php`
    User->>CP: Edit key/value
    CP->>Package: Save changes
    Package->>LangFiles: Write to disk
    Package->>CP: Refresh cache (if enabled)
  

• Tip: Use the search bar to quickly locate keys.

2. Syncing Missing Keys

• Pattern: Automate translation sync from a reference locale (e.g., en).
• Workflow:
  1. Select a target locale (e.g., fr).
  2. Click Sync Missing Keys and choose en as the reference.
  3. Review and save changes.
• Code Hook: Extend sync logic via events:

  // In EventServiceProvider
  protected $listen = [
      'translate-lang-files::syncing' => [
          YourSyncListener::class,
      ],
  ];
  

3. Cache Management

• Pattern: Configure cache invalidation post-save.
• Config:

  // config/statamic-translate-lang-files.php
  'features' => [
      'refresh_caches' => true,
      'invalidate_opcache' => env('APP_ENV') === 'production',
  ],
  

• Manual Refresh: Run:

  php artisan cache:clear
  php artisan config:clear
  

4. Git Integration (Optional)

• Pattern: Auto-commit changes to Git.
• Config:

  'git' => [
      'auto_commit' => true,
      'commit_message' => 'Update translations',
  ],
  

• Workflow: Changes to lang/ files trigger a Git commit.

Integration Tips

1. Customizing the UI

• Override the Blade view:

  php artisan vendor:publish --tag=statamic-translate-lang-files-views
  

• Modify resources/views/vendor/statamic-translate-lang-files/....

2. Extending Sync Logic

• Add custom sync rules via a service provider:

  public function boot()
  {
      event('translate-lang-files::syncing', function ($locale, $referenceLocale) {
          // Custom logic (e.g., skip certain keys)
          return ['key1' => 'value1'];
      });
  }
  

3. CLI Automation

• Sync all locales from en:

  php artisan translate-lang-files:sync --reference=en --locales=es,fr,de
  

4. Testing

• Use the package’s test suite as a reference:

  composer test
  

• Mock the CP utility in tests:

  $this->actingAs($user)
       ->get('/cp/translate-lang-files')
       ->assertSee('Translation Manager');
  

Gotchas and Tips

Pitfalls

1. Permission Issues:

   • Symptom: Utility not appearing in CP.
   • Fix: Ensure roles have the required permissions (edit translation manager).
   • Debug: Check statamic:permissions table or run:

     php artisan statamic:permissions:list
     

2. Cache Stale Data:

   • Symptom: Changes not reflecting in the UI.
   • Fix: Clear caches:

     php artisan cache:clear
     php artisan view:clear
     

   • Tip: Disable refresh_caches in config if debugging:

     'features' => ['refresh_caches' => false],
     

3. OPcache Conflicts:

   • Symptom: Translations not updating despite file changes.
   • Fix: Disable invalidate_opcache temporarily:

     'features' => ['invalidate_opcache' => false],
     

   • Workaround: Restart PHP-FPM or use:

     php artisan opcache:restart
     

4. Git Auto-Commit Failures:

   • Symptom: Commits not working silently.
   • Fix: Verify Git config and permissions:

     git config --global user.email "you@example.com"
     git config --global user.name "Your Name"
     

   • Debug: Check logs in storage/logs/laravel.log.

5. Locale/Group Discovery:

   • Symptom: Missing locales/groups in the UI.
   • Fix: Ensure lang/ files follow the expected structure:

     resources/lang/
     ├── en/
     │   ├── auth.php
     │   └── validation.php
     └── es/
         └── auth.php
     

   • Tip: Use the CLI to regenerate metadata:

     php artisan translate-lang-files:generate
     

Debugging Tips

• Log Translation Events: Add to config/statamic-translate-lang-files.php:

  'debug' => [
      'log_events' => true,
  ],
  

  Check logs in storage/logs/laravel.log for sync/save events.

• Validate File Permissions: Ensure storage/framework/ and resources/lang/ are writable:

  chmod -R 775 resources/lang/
  chmod -R 775 storage/framework/
  

• Test with a Fresh Install: Clone the project and test the package in isolation to rule out conflicts.

Extension Points

1. Custom Translation Sources: Override the TranslateLangFilesService to support non-PHP files (e.g., JSON):

   // app/Providers/TranslateLangFilesServiceProvider.php
   public function register()
   {
       $this->app->bind('translate-lang-files', function () {
           return new CustomTranslateLangFilesService();
       });
   }
   

2. Pre/Post-Save Hooks: Listen for events to add custom logic:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       'translate-lang-files::saving' => [
           CustomTranslationValidator::class,
       ],
       'translate-lang-files::saved' => [
           CustomTranslationLogger::class,
       ],
   ];
   

3. Bulk Operations: Extend the sync command to handle bulk updates:

   // app/Console/Commands/SyncTranslations.php
   public function handle()
   {
       $locales = ['es', 'fr', 'de'];
       foreach ($locales as $locale) {
           $this->call('translate-lang-files:sync', [
               '--reference' => 'en',
               '--locale' => $locale,
           ]);
       }
   }
   

Configuration Quirks

• Reference Locale:

  • Must exist in lang/ (e.g., en/auth.php).
  • Sync will fail if the reference locale is missing keys.

• File Encoding:

  • Ensure lang/ files use UTF-8 encoding to avoid character issues.

• Reserved Keys:

  • Avoid overriding Laravel’s core keys (e.g., auth.failed) unless intentional.

Performance Considerations

• Large Projects:

  • Disable invalidate_opcache for projects with >100MB lang/ files.
  • Use database-backed translations for scalability:

    'features' => [
        'use_database' => true, // Custom extension
    ],
    

• Concurrent Edits:

  • Implement file locking for multi-user environments:

    // app/Services/CustomTranslateLangFilesService.php
    public function save($locale, $group, $data)
    {
        if (!file_exists(storage_path("locks/{$locale}-{$group}.lock"))) {
            file_put_contents(storage_path("locks/{$locale}-{$group}.lock"), '');
            // Save logic here
            unlink(storage_path("locks/{$locale}-{$group}.lock