README

Most Laravel “translatable” packages force you to either convert your translatable attributes into a JSON column on the same table (for storing all strings on one place), or requires you to create and maintain a dedicated {model}_translations table for each model.

Both approaches work, but they either bloat your base table with JSON logic or force you to manage a growing number of nearly identical tables.

rat.md/laravel-translatable takes a different path — inspired by OctoberCMS — by using a single, shared translations table for all your models.

Features

Support for MySQL, MariaDB, PostgreSQL, SQlite and MongoDB (Driver-aware querying and sorting).
One polymorphic translations table for everything — no extra migrations per model.
Keep your default language clean in the model’s own columns, exactly where it belongs.
Transparent reads and writes through the model’s attributes, with automatic fallback.

Requirements

PHP ≥ 8.2
Laravel ≥ 11
SQLite ≥ 3.35 | MySQL ≥ 8.0 | MariaDB ≥ 10.6 | PostgreSQL ≥ 13.22
Only required for MongoDB driver (experimental):
- MongoDB ≥ v7.0 (may work with ≥ v5.0 too)
- mongodb/laravel-mongodb ≥ 5.0

Installation

Install the package via composer:

composer require rat.md/laravel-translatable

Publish and run the migrations using:

php artisan vendor:publish --tag="laravel-translatable-migrations"
php artisan migrate

Publish the configuration file with:

php artisan vendor:publish --tag="laravel-translatable-config"

Usage

Preparing your models

Simply add the Translatable trait to your Eloquent models and declare which attributes should support translations. Array-Like attributes must be declared either in your $casts or in the package-native $translatableArrayAttributes model property.

use Rat\Translatable\Concerns\Translatable;

class Post extends Model
{
    use Translatable;

    protected $fillable = ['title', 'content', 'tags'];
    protected $translatable = ['title', 'content', 'tags'];
    protected $casts = [
        'tags' => 'array'
    ];
}

Setting translations

Set translations in known / familiar ways.

// Mass assignment
Post::create([
    'title' => [
        'en' => 'Hello World',
        'de' => 'Hallo Welt',
    ]
]);

// Manual assignment
$post = new Post;
$post->title = 'Hello World';
$post->setTranslation('de', 'title', 'Hallo Welt');
$post->save();

// Manual assignment using withLocale()
$post = new Post;
$post->title = 'Hello World';
$post->withLocale('de', function ($model) {
    $model->title = 'Hallo Welt';
});

Retrieving translations

Access translations directly, use helpers, or switch the application/model locale.

$post = Post::first();

// Direct access based on app()->getLocale()
echo $post->title;
app()->setLocale('de');
echo $post->title;

// Manual access
echo $post->getTranslation('de', 'title');
echo $post->getTranslations('de')['title'];

// Access by mutating model locale
$post->locale('de');
echo $post->title;

// Access by cloning model with desired locale
echo $post->in('de')->title;

// Access by using withLocale()
$post->withLocale('de', function ($model) {
    echo $model->title;
});

Querying by locale

Query, filter, and sort your models by translated values across different locales.

Note

orderByLocale() is not yet supported for the MongoDB driver. We are actively exploring a clean and efficient implementation. For now, this scope works only with SQL drivers.

Post::whereLocale('de', 'title', 'Hallo Welt')->get();
Post::query()->whereLocale('de', 'title', 'Hallo Welt')->get();

Post::whereHasLocale('de')->get();
Post::whereMissingLocale('de')->get(); // or "whereDoesntHaveLocale"

Post::orderByLocale('de', 'title', 'ASC')->get();

Testing

./vendor/bin/pest

Changelog

Please see CHANGELOG for more information on what has changed recently.

rat.md / laravel-translatable

Maintainers

Details