Laravel Translation Manager Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require barryvdh/laravel-translation-manager
   php artisan vendor:publish --provider="Barryvdh\TranslationManager\TranslationManagerServiceProvider" --tag="migrations"
   php artisan migrate
   

   Publish config and views (if needed):

   php artisan vendor:publish --provider="Barryvdh\TranslationManager\TranslationManagerServiceProvider" --tag="config"
   php artisan vendor:publish --provider="Barryvdh\TranslationManager\TranslationManagerServiceProvider" --tag="views"
   

2. First Use Case: Access the translation manager UI at /translation-manager (or your configured route). Log in as an admin to edit translations directly in the browser.

3. Key Files:

   • config/translation-manager.php: Core configuration (e.g., locales, default locale, file paths).
   • resources/views/vendor/translation-manager/: Override default UI templates here.
   • database/migrations/: Check for custom translation tables if extending functionality.

Implementation Patterns

Core Workflows

1. Editing Translations:

   • Use the UI to edit translations for all supported locales.
   • Group translations by key (e.g., auth.login, validation.required) for consistency.
   • Bulk Actions: Update multiple keys/locales at once via the UI.

2. Locale Management:

   • Define locales in config/translation-manager.php:

     'locales' => [
         'en' => 'English',
         'es' => 'Spanish',
         'fr' => 'French',
     ],
     

   • Add/remove locales dynamically via the UI or migrations.

3. Integration with Language Switcher:

   • Sync with laravel-localization or custom middleware:

     use Barryvdh\TranslationManager\Middleware\SetLocaleFromCookie;
     
     Route::middleware([SetLocaleFromCookie::class])->group(function () {
         // Your routes
     });
     

4. Translation Files Sync:

   • Export translations to .json/.php files:

     php artisan translation-manager:export
     

   • Import from files:

     php artisan translation-manager:import
     

5. API Access (Optional):

   • Use the TranslationManager facade to fetch translations programmatically:

     use Barryvdh\TranslationManager\Facades\TranslationManager;
     
     $translations = TranslationManager::get('en', 'auth.*');
     

Advanced Patterns

1. Custom Storage:

   • Extend the TranslationManager to use a custom storage backend (e.g., S3, database-specific tables):

     // app/Providers/TranslationManagerServiceProvider.php
     $this->app->bind('translation-manager.storage', function () {
         return new CustomStorage();
     });
     

2. Translation Events:

   • Listen for translation updates:

     TranslationManager::setEventDispatcher($app);
     event(new TranslationUpdated('en', 'auth.login'));
     

3. Validation Rules:

   • Add custom validation to translation keys/values via service providers:

     TranslationManager::extend('validation', function ($key, $value, $locale) {
         return Str::contains($value, 'admin') ? 'invalid' : null;
     });
     

4. Multi-Tenant Translations:

   • Scope translations by tenant using middleware or model observers:

     TranslationManager::setCurrentTenant($tenantId);
     

Gotchas and Tips

Common Pitfalls

1. File Permissions:

   • Ensure the storage/app/translation-manager directory is writable:

     chmod -R 775 storage/app/translation-manager
     

   • Fix: Verify storage_path() permissions in config/translation-manager.php.

2. Locale Fallbacks:

   • If a translation is missing in the requested locale, Laravel falls back to the default. Override this in config/translation-manager.php:

     'fallback_locale' => 'en',
     'fallback_when_empty' => true,
     

3. Caching Issues:

   • Clear translation cache after manual edits:

     php artisan translation-manager:clear-cache
     

   • Tip: Disable caching during development:

     'cache' => env('APP_ENV') !== 'local',
     

4. Key Conflicts:

   • Avoid duplicate keys across locales. Use the UI’s "Find" feature to check for conflicts.

5. Middleware Order:

   • Place SetLocaleFromCookie before ShareErrorsFromSession to ensure locale is set early:

     $middlewareGroups['web'] = [
         // ...
         Barryvdh\TranslationManager\Middleware\SetLocaleFromCookie::class,
         // ...
     ];
     

Debugging Tips

1. Log Translation Updates:

   • Enable logging in config/translation-manager.php:

     'log_updates' => true,
     

   • Check storage/logs/laravel.log for update events.

2. Check Database:

   • Verify translations exist in translation_manager_translations:

     SELECT * FROM translation_manager_translations WHERE locale = 'es' AND key LIKE 'auth.%';
     

3. Disable JavaScript Errors:

   • If the UI fails silently, check browser console for JS errors (e.g., missing CSRF token).

4. Test Locale Switching:

   • Manually set the locale cookie to test:

     curl -H "Cookie: locale=es" http://your-app.test/translation-manager
     

Extension Points

1. Custom UI Components:

   • Override Blade templates in resources/views/vendor/translation-manager/.
   • Example: Extend the edit form to include a "translation memory" search.

2. API Endpoints:

   • Add custom routes for programmatic access:

     Route::get('/api/translations/{locale}', [TranslationController::class, 'index']);
     

3. Translation Groups:

   • Use the group config option to organize translations:

     'groups' => [
         'auth' => ['auth.*'],
         'validation' => ['validation.*'],
     ],
     

   • Render groups in the UI via custom views.

4. Webhooks:

   • Trigger external actions (e.g., Slack notifications) on translation updates:

     TranslationManager::onUpdate(function ($locale, $key, $value) {
         // Send webhook
     });
     

5. Localization Tools:

   • Integrate with tools like Crowdin or Transifex by extending the TranslationManager to sync with their APIs.