Lang Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require laravel-lang/lang --dev
   

   Add the package to your composer.json under require-dev to avoid bloating production builds.

2. Publish Assets:

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

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

3. Update config/app.php: Add the package's service provider to the providers array:

   LaravelLang\Lang\LangServiceProvider::class,
   

4. First Use Case: Use the translations in your Blade templates or PHP code:

   @lang('vendor.laravel-lang::auth.passwords.reset')
   

   Or in PHP:

   __('vendor.laravel-lang::auth.passwords.reset');
   

Implementation Patterns

Core Workflows

1. Namespace Handling:

   • All translations are prefixed with vendor.laravel-lang:: to avoid conflicts.
   • Example: vendor.laravel-lang::validation.attributes.name for validation messages.

2. Integration with Laravel Breeze/Jetstream:

   • The package includes translations for common auth flows (login, registration, password reset).
   • Example:

     @lang('vendor.laravel-lang::auth.login')
     

3. Validation Messages:

   • Extend Laravel’s validation rules with localized messages:

     $rules = ['email' => 'required|email'];
     $messages = [
         'email.required' => __('vendor.laravel-lang::validation.required', ['attribute' => 'Email']),
     ];
     

4. Dynamic Language Switching:

   • Use middleware to set the locale dynamically:

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

5. Customizing Translations:

   • Override specific translations by creating matching files in resources/lang/{locale}/vendor/laravel-lang/.
   • Example: Override auth.login in resources/lang/fr/vendor/laravel-lang/auth.php:

     return [
         'login' => 'Connexion',
     ];
     

Advanced Patterns

1. Partial Overrides:

   • Merge only specific language files instead of all:

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

     Then manually edit the files you need.

2. Localization for Pagination:

   • Use the package’s pagination translations:

     {{ $users->appends(request()->query())->links('vendor.laravel-lang::pagination.default') }}
     

3. Testing Localizations:

   • Mock translations in tests:

     $this->app->setLocale('fr');
     $this->withoutExceptionHandling();
     

4. Custom Language Files:

   • Add new languages by extending the package or contributing to the repo.

Gotchas and Tips

Pitfalls

1. Namespace Conflicts:

   • Avoid naming your custom language files vendor.laravel-lang to prevent overwrites during updates.
   • Use a unique prefix (e.g., app.laravel-lang) for custom overrides.

2. Missing Translations:

   • Some languages (e.g., zu, uz_Cyrl) have partial translations. Check the status page before relying on them.
   • Example: zu (Zulu) has 19 missing entries; use fallback locales if needed:

     __('vendor.laravel-lang::auth.login', [], 'en'); // Fallback to English
     

3. Performance:

   • Publishing all 126 languages increases bundle size. Only publish the ones you need:

     php artisan vendor:publish --provider="LaravelLang\Lang\LangServiceProvider" --tag=lang --langs="fr,es,de"
     

4. Validation Quirks:

   • The encoding validation rule may have inconsistencies (e.g., az, fr, vi languages). Override these in your custom files:

     'validation' => [
         'attributes' => [
             'encoding' => 'kódolás',
         ],
         'custom' => [
             'encoding' => [
                 'encoding' => 'A :attribute megnévezett kódolásban kell lennie.',
             ],
         ],
     ],
     

5. Jetstream/Breeze Compatibility:

   • Some auth flows (e.g., Verify your email address) may have missing translations in certain languages (e.g., fr, az). Test thoroughly.

Debugging Tips

1. Check Loaded Translations:

   dd(__path('vendor.laravel-lang::auth.login'));
   

   This helps verify if the translation is loaded or falling back to English.

2. Clear Compiled Views: If translations aren’t updating, clear the view cache:

   php artisan view:clear
   

3. Locale-Specific Issues:

   • Use php artisan lang:list to list available locales.
   • Force a locale in tests or development:

     app()->setLocale('fr');
     

4. Contributing Fixes:

   • Report missing translations via the GitHub repo or contribute directly by following the CONTRIBUTING guide.

Extension Points

1. Custom Language Files:

   • Add new languages by extending the package or forking the repo. Example structure:

     resources/lang/vendor/laravel-lang/custom/
     ├── custom.php
     └── validation.php
     

2. Dynamic Language Loading:

   • Load translations on-demand using Laravel’s FileLoader:

     $loader = app('translator')->getLoader();
     $loader->addNamespace('laravel-lang', resource_path('lang/vendor/laravel-lang'));
     

3. API Localization:

   • Pass the Accept-Language header in API requests and use middleware to set the locale:

     public function handle($request, Closure $next) {
         $locale = substr($request->header('Accept-Language'), 0, 2);
         app()->setLocale($locale);
         return $next($request);
     }
     

4. Fallback Logic:

   • Configure fallback locales in config/app.php:

     'fallback_locales' => ['en', 'fr'],