Laravel Translation Loader Laravel Package

Getting Started

Start by installing the package via Composer and replacing Laravel’s built-in TranslationServiceProvider with Spatie\TranslationLoader\TranslationServiceProvider in config/app.php. Then publish and run the migration to create the language_lines table. After that, create a sample translation using the LanguageLine model:

use Spatie\TranslationLoader\LanguageLine;

LanguageLine::create([
    'group' => 'auth',
    'key' => 'failed',
    'text' => [
        'en' => 'These credentials do not match our records.',
        'es' => 'Estas credenciales no coinciden con nuestros registros.',
    ],
]);

You can immediately use it with the familiar __() helper — no code changes needed:

__('auth.failed'); // → "These credentials do not match our records."
app()->setLocale('es');
__('auth.failed'); // → "Estas credenciales no coinciden con nuestros registros."

Implementation Patterns

• Hybrid Storage Strategy: Keep static, rarely changed keys in language files (lang/en/auth.php), and use the database for dynamic content (e.g., CMS-managed pages, user-generated labels). Database translations override file-based ones.
• Admin UI Integration: Build a simple CRUD interface using LanguageLine for content managers to add/edit translations. Cache the results with LanguageLine::flushGroupCache('validation') after bulk updates.
• Custom Loaders: Implement a new loader (e.g., YamlTranslationLoader) that implements the TranslationLoader interface and register it in translation_loaders config to pull translations from external sources like YAML files or remote APIs.
• JSON Translations: For complex nested messages (e.g., messages.errors.*), store them in a single row with group = '*' and keys like messages.errors.required — the loader treats them like nested arrays.

Gotchas and Tips

• Performance: Each __() call may query the DB unless caching is enabled. Since this package replaces Laravel’s translation loader, consider enabling Laravel’s built-in config caching (config:cache) — though note that the DB loader itself doesn’t cache by default. You may need to implement custom caching in your loader or wrap LanguageLine::getForLocale() in a cache block.
• Group/key collision: If a translation exists in both DB and files with matching group.key, the DB wins. To debug, use app('translation.loader') to inspect which loaders return what.
• Null vs empty string: Prior to v2.1.5, missing translations returned ''. Now they return null, so be mindful in views — use {{ __(...) ?? 'fallback' }}.
• Migration compatibility: If you customize the table name via config('translation-loader.model')’s table property, ensure your migrations reference the same (v2.7.3+ fixes hardcoded table name issues).
• Extensibility hook: The model config option lets you extend LanguageLine (e.g., add status or updated_by fields), but you must ensure it implements the same structure and is mutable via create()/update().
• Lumen caveat: Publishing assets doesn’t work out-of-the-box — manually copy migration and config from the vendor package.