Translation Laravel Package

Getting Started

Start inside a Laravel app — this package is not meant to be installed standalone (it’s a subtree split of laravel/framework). First steps:

1. Place translation files in resources/lang/{locale}/{group}.php (e.g., resources/lang/en/validation.php).
2. Use __('validation.required') or trans('validation.required') in Blade, controllers, or services.
3. Set locale dynamically via app()->setLocale('es') (often in middleware or user preferences).
   ➡️ Begin with Laravel’s official localization docs — this package is the engine, not the frontend API.

Implementation Patterns

• Grouping: Split translations by context (e.g., auth.php, admin/dashboard.php) — keeps files lean and scannable.
• Placeholders: Use :variable syntax ('welcome' => 'Hello, :name') and pass replacements: __('greeting.welcome', ['name' => 'Alex']).
• Pluralization:

  // Explicit rules
  'comments' => '{0} No comments|[1,*] :count comments',
  // Simple Countable (Laravel auto-selects form based on :count)
  'apples' => 'There are :count apples',
  

  Resolve with trans_choice('apples', $count, ['count' => $count]).
• Fallback handling: Configure config('app.fallback_locale') to avoid broken UI (e.g., 'fallback' => 'en').
• Vendor overrides: Place lang/vendor/{package}/{locale}/{file}.php to patch package translations (e.g., Filament, Spatie packages).
  Most developers interact via the __() helper or Lang facade — direct Translator class usage is rare.

Gotchas and Tips

• No standalone install: This is not a standalone package — avoid composer require illuminate/translation. Use laravel/framework instead.
• Format consistency: Don’t mix php and json translation files per group (e.g., lang/en/auth.php + lang/en/auth.json → undefined behavior). Choose one format.
• Locale casing: en-US ≠ en-us by default. Normalize in middleware:

  app()->setLocale(Str::lower(str_replace('_', '-', $locale)));
  

• Debugging missing keys: In debug mode (APP_DEBUG=true), missing keys render as ???key.name??? — makes gaps obvious.
• Caching: Run php artisan translation:export (Laravel 11+) to cache all translations for production speed.
• Runtime performance: Avoid repeated Lang::get() in loops — fetch entire group once (Lang::get('messages')) or pre-load used keys.
• Extensibility: Extend Translator + TranslationLoader to power translations from database, APIs, or CMS (e.g., Laravel’s Lang facade accepts custom loader via Lang::extend()).