Getting Started

First Steps

Installation Requires Laravel 10+ and PHP 8.1+. Install via Composer:

composer require flobbos/laravel-translatable-db

Publish the config and migrations:

php artisan vendor:publish --provider="Flobbos\LaravelTranslatable\LaravelTranslatableServiceProvider"
php artisan migrate

Basic Model Setup Extend your model with Flobbos\LaravelTranslatable\Translatable trait and define translatable fields in $translatable:

use Flobbos\LaravelTranslatable\Translatable;

class Post extends Model
{
    use Translatable;

    protected $translatable = ['title', 'content'];
}

First Usage Create a post with translations:

$post = Post::create([
    'title' => 'English Title',
    'content' => 'English Content',
]);

$post->translate('es', [
    'title' => 'Título en Español',
    'content' => 'Contenido en Español',
]);

Retrieving Translations Fetch a translation by locale:

$post->getTranslation('es')->title; // "Título en Español"

Or use the localize() helper:

$post->localize('es')->title; // Same result

Implementation Patterns

Common Workflows

Dynamic Translation Handling Use translatable() to dynamically add/remove translatable fields:
```
$model->translatable(['new_field']); // Add
$model->translatable(null); // Reset
```

Locale Fallbacks Configure fallbacks in config/translatable.php (now with stricter defaults):

'fallback_locale' => 'en',
'fallbacks' => [
    'es' => 'en',
    'fr' => 'en',
],

Then fetch translations with fallback:

$post->localize('es')->title; // Falls back to 'en' if 'es' missing

Scopes for Localized Queries Use the translated() scope to filter by translations:
```
Post::translated('title', 'like', '%English%')->get();
```
API Responses Note: to_array_always_loads_translations is now false by default. Explicitly eager-load translations:
```
return Post::withTranslations()->get();
```

Form Requests Validate and bind translations in form requests:

public function rules()
{
    return [
        'title' => 'required',
        'translations.es.title' => 'required',
    ];
}

public function prepareForValidation()
{
    $this->merge([
        'translations' => json_decode($this->input('translations'), true),
    ]);
}

Integration Tips

Laravel Scout: Override toSearchableArray() to include translations.
Nova/Livewire: Use withTranslations() in queries for admin panels.
Validation: Use translatable.* rules for nested validation.

Middleware: Breaking Change: middleware_default is now false. Manually add middleware if needed:

Route::middleware(['translatable'])->group(function () {
    // Routes requiring translation middleware
});

Gotchas and Tips

Pitfalls

Migration Conflicts

If manually creating translations table, ensure it matches the package’s schema:

Schema::create('translations', function (Blueprint $table) {
    $table->id();
    $table->string('locale')->index();
    $table->json('attributes');
    $table->foreignId('translatable_id')->constrained()->onDelete('cascade');
    $table->unique(['translatable_id', 'locale']);
});

Mass Assignment Risks
- Always whitelist translatable fields in $fillable or use $guarded.
- Example:
```
protected $fillable = ['title', 'content'];
```
Locale-Specific Queries
- Avoid querying translations directly. Use the provided scopes instead.
JSON Field Limitations
- The attributes column uses JSON, which may cause issues with very large translations. Consider splitting into separate columns if needed.
Model Events
- Translations trigger savingTranslation, savedTranslation, etc. Listen carefully to avoid infinite loops:
```
$model->setAttribute('title', 'New Title');
$model->save(); // Triggers translation events
```
Middleware Defaults
- Breaking Change: Middleware is no longer enabled by default. Explicitly add it to routes or models:
```
class Post extends Model
{
    use Translatable;

    protected $middleware = ['translatable'];
}
```

Debugging Tips

Check for Missing Translations Use hasTranslation('es') to verify:

if (!$post->hasTranslation('es')) {
    // Handle missing translation
}

Inspect Raw Translations Dump the translations relationship:
```
dd($post->translations);
```
Enable Query Logging Temporarily enable debug mode in config/translatable.php:
```
'debug' => true,
```
Clear Cached Compiled Views If translations aren’t updating, run:
```
php artisan view:clear
```

Extension Points

Custom Storage Override getTranslationsTable() in your model:

protected function getTranslationsTable()
{
    return 'custom_translations';
}

Custom Attribute Handling Extend the trait to modify how attributes are stored:

use Flobbos\LaravelTranslatable\Translatable as BaseTranslatable;

trait CustomTranslatable
{
    use BaseTranslatable;

    protected function getTranslatableAttributes()
    {
        return array_merge($this->$translatable, ['custom_field']);
    }
}

Add Scopes Extend the query builder in your model:

public function scopeActiveTranslations($query)
{
    return $query->whereHas('translations', function ($q) {
        $q->where('locale', app()->getLocale());
    });
}

Custom Serialization Override toArray() or toJson() to format translations:

public function toArray()
{
    return array_merge(parent::toArray(), [
        'translations' => $this->translations->pluck('attributes', 'locale'),
    ]);
}

Non-ID Primary Keys Fixed in 2.0.0: Ensure foreign key detection works for non-id primary keys by explicitly defining:
```
public function getTranslatableKey()
{
    return $this->uuid; // If using UUID as primary key
}
```

Performance Considerations

Eager Loading: Always use withTranslations() when fetching models with translations.
Indexing: Ensure locale and translatable_id are indexed in the translations table.

Batch Updates: Use updateTranslations() for bulk updates:

$posts->each->updateTranslations('es', ['title' => 'Updated']);

Explicit Translation Loading: Breaking Change: Translations are no longer loaded by default in toArray(). Use withTranslations() or explicitly load them:
```
$post->load('translations');
```

Laravel Translatable Db Laravel Package