Laravel Translatable Laravel Package

Getting Started

1. Install the package via Composer: composer require spatie/laravel-translatable
2. Add the HasTranslations trait to any Eloquent model and define a $translatable array listing the attributes that should support translations
3. Ensure the translatable columns use the json database type (or text as fallback); migration example: $table->json('name')
4. Start using intuitive syntax: $model->name = 'Hello'; or $model->setTranslation('name', 'fr', 'Bonjour');
5. Check the official docs for deeper configuration—especially the "Installation & Setup" and "Basic Usage" sections

Implementation Patterns

• Use setTranslation() for explicit control over locale assignment; use magic property access ($model->title) when working with the current app locale
• Store translations in JSON columns and access nested keys via dot-notation in $translatable (e.g., 'meta->description') for structured data
• Leverage scoped query helpers (whereLocale(), whereLocales(), whereJsonContainsLocale()) to filter models by locale or value—crucial for SEO and multilingual admin interfaces
• Use forgetTranslation() and forgetAllTranslations() to handle partial or full locale removal cleanly, especially during content cleanup workflows
• In factories, use the built-in translations() helper to generate seeded translations efficiently:

  'title' => $this->translations(['en', 'nl'], ['English', 'Dutch'])
  

Gotchas and Tips

• Locale fallback behavior is critical: By default, missing translations return empty strings—configure fallback logic in a service provider via Translatable::fallback() to avoid silent UI gaps
• Avoid modifying $translatable dynamically; it’s cached internally—define it as a static array property
• When querying with whereJsonContainsLocale(), ensure your DB supports JSON (MySQL ≥5.7 / PostgreSQL / MariaDB ≥10.2.3); otherwise, queries may fail or be slow
• The TranslationHasBeenSetEvent fires on every setTranslation() call—useful for logging or syncing to external services, but be cautious of N+1 behavior in bulk operations
• Caching pitfall: Avoid caching Eloquent models with translations across locales unless you invalidate per-locale—consider caching only the current locale translation with explicit cache keys like news.{$id}.{$locale}