Lang Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel-lang/lang
   

   Add the package to your composer.json under require-dev if using for development/testing.

2. Publish Language Files:

   php artisan vendor:publish --provider="LaravelLang\Lang\LangServiceProvider" --tag=lang
   

   This publishes all language files to resources/lang/vendor/laravel-lang.

3. First Use Case:

   • Localization: Use the published translations in your Blade views or PHP code:

     __('vendor.lang-key'); // Access translations via the 'vendor' namespace
     

   • Validation Messages: Override default validation messages for a specific language by extending the published files.

Implementation Patterns

Core Workflows

1. Language Overrides:

   • Extend existing translations by creating a new language file in resources/lang/{locale}/auth.php (or any other namespace) and copy the relevant keys from vendor/lang/{locale}/auth.php.
   • Example:

     // resources/lang/id/auth.php
     return [
         'failed' => 'Kredensial tidak valid. Silakan coba lagi.',
     ];
     

2. Dynamic Language Switching:

   • Use middleware to set the locale dynamically:

     // app/Http/Middleware/SetLocale.php
     public function handle($request, Closure $next) {
         app()->setLocale($request->header('Accept-Language') ?? config('app.locale'));
         return $next($request);
     }
     

   • Register the middleware in app/Http/Kernel.php.

3. Integration with Laravel Breeze/Jetstream:

   • Replace default language files in resources/lang/vendor/laravel-jetstream with the published translations from laravel-lang/lang.

4. Validation Language:

   • Extend validation messages by copying keys from vendor/lang/{locale}/validation.php to resources/lang/{locale}/validation.php and customizing them.

Advanced Patterns

1. Partial Language Loading:

   • Use config(['app.fallback_locale' => 'en']) to ensure English fallback if a translation is missing.
   • Load only required language files for performance:

     $translator = app('translator');
     $translator->load('id', ['auth' => require resource_path('lang/vendor/laravel-lang/id/auth.php')]);
     

2. Custom Language Packs:

   • Create a custom language pack by extending the LaravelLang\Lang\LangServiceProvider and overriding the boot() method to load additional files.

3. Testing Localizations:

   • Use Lang::setLocale() in tests to switch languages:

     use LaravelLang\Lang\Facades\Lang;
     
     public function test_localization() {
         Lang::setLocale('id');
         $this->assertEquals('Kredensial tidak valid.', __('auth.failed'));
     }
     

Gotchas and Tips

Common Pitfalls

1. Missing Translations:

   • The package includes 128 languages, but some may have partial translations (e.g., uz_Cyrl missing country names like "Fiji").
   • Fix: Check the status page for missing keys and contribute or override them manually.

2. Namespace Conflicts:

   • Translations are published under the vendor namespace (__('vendor.lang-key')).
   • Tip: Use config(['app.fallback_locales' => ['en', 'vendor']]) to ensure fallback works correctly.

3. Caching Issues:

   • Clear the view and config caches after publishing new translations:

     php artisan view:clear
     php artisan config:clear
     

4. Jetstream/Breeze Overrides:

   • If using Laravel Jetstream/Breeze, do not override their default language files directly. Instead, extend the laravel-lang translations and ensure your custom files load after the vendor files.

Debugging Tips

1. Check Loaded Languages:

   dd(app('translator')->getLoader()->getLoadedLocales());
   

   Verify your language is loaded.

2. Fallback Debugging:

   • Enable debug mode to see fallback chains:

     config(['app.debug' => true]);
     

   • Check the translator facade logs for missing keys.

3. Partial Translations:

   • If a language has missing keys (e.g., validation.encoding), override them in your project’s language files:

     // resources/lang/vi/validation.php
     'encoding' => 'Trường :attribute phải được mã hóa bằng :encoding.',
     

Extension Points

1. Custom Language Files:

   • Add new languages by extending the LangServiceProvider:

     // app/Providers/LangServiceProvider.php
     namespace App\Providers;
     
     use LaravelLang\Lang\LangServiceProvider as BaseLangServiceProvider;
     
     class LangServiceProvider extends BaseLangServiceProvider {
         protected $additionalLanguages = ['jv' => 'resources/lang/vendor/laravel-lang/jv'];
     }
     

2. Dynamic Language Loading:

   • Load languages on demand (e.g., for API responses):

     $translator->load('id', ['custom' => ['key' => 'Custom value']]);
     

3. Contributing Missing Translations:

   • Submit missing translations via GitHub Issues or contribute directly to the repo.

4. Performance Optimization:

   • Use Lang::load() sparingly in production. Pre-load languages during bootstrapping:

     // app/Providers/AppServiceProvider.php
     public function boot() {
         Lang::load('id');
         Lang::load('vi');
     }