Search by

hibasabouh / laravel-model-translations

hibasabouh

Database-driven model translations for Laravel using separate translation tables.

Package info

github.com/hibasabouh/laravel-model-translations

pkg:composer/hibasabouh/laravel-model-translations

Statistics

Installs: 8

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.3.0 2026-11-17 14:09 UTC

This package is auto-updated.

Last update: 2026-11-17 14:10:30 UTC


README

Latest Version on Packagist Total Downloads License: MIT Tests PHP

A clean, database-driven approach to model translations in Laravel. Store translations in separate normalized tables and access them with elegant, locale-aware magic accessors.

Why This Package?

Unlike JSON-based translation approaches, this package:

✅ Relational structure — Translations live in proper normalized tables
✅ Query support — Filter models by translated content with whereTranslation()
✅ Indexing & constraints — Add database indexes and unique constraints per locale
✅ Scalability — Handles large datasets better than JSON columns
✅ Clean models — Keeps base model focused, translations separated

If you prefer structured, relational translation tables over JSON columns, this package is for you.

Requirements

Laravel PHP
10.x ^8.1
11.x ^8.2
12.x ^8.2
13.x ^8.3

Quick Start

1. Install

composer require hibasabouh/laravel-model-translations

2. Add the trait & define $translatable

use HibaSabouh\ModelTranslations\Traits\HasTranslations;

class Product extends Model
{
    use HasTranslations;

    protected array $translatable = ['name', 'description'];
}

3. Create translation table

Schema::create('product_translations', function (Blueprint $table) {
    $table->id();
    $table->foreignId('product_id')->constrained()->cascadeOnDelete();
    $table->string('lang', 10);
    $table->string('name');
    $table->text('description')->nullable();
    $table->timestamps();
    
    $table->unique(['product_id', 'lang']);
});

4. Create & access translations

Product::createWithTranslations([
    'sku' => 'LAPTOP-001',
    'name' => ['en' => 'Laptop', 'fr' => 'Ordinateur'],
]);

app()->setLocale('fr');
echo $product->name; // "Ordinateur"

Done!

Features

  • 🌍 Locale-aware accessors — $model->name automatically returns the current locale's value
  • 🔄 Fallback strategies — Choose between null, app fallback, or first available translation
  • 🔍 Query scopes — whereTranslation(), whereAnyTranslation() for filtering and orderByTranslation() for sorting by translated content
  • 💾 Transactional CRUD — All operations wrapped in database transactions
  • 🎯 Convention over configuration — Auto-resolves translation model names
  • ⚡ Eager loading — Configurable auto-eager-loading via global scope
  • 🛠️ Artisan command — Scaffold translated models with a single command

Installation

composer require hibasabouh/laravel-model-translations

Publish Configuration

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

This creates config/translatable.php:

return [
    'auto_load' => true,  // Eager load translations globally
    'fallback'  => 'app', // Fallback strategy: null, 'app', or 'first'
];

Artisan Command

The package ships with a translations:make-model command that scaffolds everything you need in one step: the main model, the translation model (in the Translations sub-namespace), and optionally a migration and resource controller.

Basic Usage

php artisan translations:make-model Product

This creates:

  • app/Models/Product.php — with HasTranslations trait and $translatable property pre-configured
  • app/Models/Translations/ProductTranslation.php — with $fillable set to ['product_id', 'lang']

Options

Option Description
--m Create migrations for both the main model and its translation table
--r Create a resource controller for the main model
--mr Create both migration and resource controller
# With migration
php artisan translations:make-model Product --m

# With resource controller
php artisan translations:make-model Product --r

# With both
php artisan translations:make-model Product --mr

What Gets Generated

When --m is used, the translation migration is pre-filled with the expected structure:

Schema::create('product_translations', function (Blueprint $table) {
    $table->id();
    $table->foreignId('product_id')
        ->constrained()
        ->cascadeOnDelete();

    $table->string('lang');
    $table->timestamps();
});

You only need to add your translatable columns (e.g. name, description) — the foreign key, lang, and timestamps are already there.

The main model is set up with the trait and empty stubs ready to fill:

use HibaSabouh\ModelTranslations\Traits\HasTranslations;

class Product extends Model
{
    use HasTranslations;

    protected $fillable = [];

    protected $translatable = [];
}

The translation model has $fillable bootstrapped with the foreign key and locale columns:

class ProductTranslation extends Model
{
    protected $fillable = [
        'product_id',
        'lang',
    ];
}

After running the command, add your translatable column names to both the migration and the $fillable / $translatable arrays.

Setup Guide

1. Migration: Create Translation Table

For each translatable model, create a corresponding {model}_translations table:

Schema::create('product_translations', function (Blueprint $table) {
    $table->id();
    $table->foreignId('product_id')->constrained()->cascadeOnDelete();
    $table->string('lang', 10);
    $table->string('name');
    $table->text('description')->nullable();
    $table->timestamps();
    
    $table->unique(['product_id', 'lang']); // One translation per locale
    $table->index('lang'); // Optional: speed up locale-specific queries
});

2. Translation Model

Create a translation model in the Translations sub-namespace:

namespace App\Models\Translations;

use Illuminate\Database\Eloquent\Model;

class ProductTranslation extends Model
{
    protected $fillable = ['product_id', 'lang', 'name', 'description'];
}

Convention: A App\Models\Product model resolves to App\Models\Translations\ProductTranslation.

3. Add Trait to Main Model

namespace App\Models;

use HibaSabouh\ModelTranslations\Traits\HasTranslations;
use Illuminate\Database\Eloquent\Model;

class Product extends Model
{
    use HasTranslations;

    protected $fillable = ['sku', 'price', 'stock'];
    
    protected array $translatable = ['name', 'description'];
}

Usage

Creating Models

Pass translatable attributes as arrays keyed by locale:

Product::createWithTranslations([
    'sku'   => 'LAPTOP-001',
    'price' => 999,
    'name'  => [
        'en' => 'Gaming Laptop',
        'fr' => 'Ordinateur Portable de Jeu',
        'ar' => 'حاسوب محمول للألعاب',
    ],
    'description' => [
        'en' => 'High-performance laptop for gaming',
        'fr' => 'Ordinateur haute performance pour les jeux',
    ],
]);

Updating Models

$product->updateWithTranslations([
    'price' => 899, // Update base attribute
    'name'  => [
        'en' => 'Gaming Laptop Pro', // Update existing
        'de' => 'Gaming-Laptop',      // Add new locale
    ],
]);

// Untouched translations ('fr', 'ar') remain unchanged

Reading Translations

Locale-aware accessor:

app()->setLocale('fr');
echo $product->name; // "Ordinateur Portable de Jeu"

All translations at once:

$product->name_translations;
// ['en' => 'Gaming Laptop', 'fr' => 'Ordinateur Portable de Jeu', 'ar' => '...']

Direct relationship access:

$product->translations; // Collection of all ProductTranslation records
$product->translations()->where('lang', 'en')->first();

Querying by Translation

Current locale (default):

app()->setLocale('en');
Product::whereTranslation('name', 'like', '%Laptop%')->get();

Specific locale:

Product::whereTranslation('name', '=', 'Ordinateur', 'fr')->get();

Any locale:

Product::whereAnyTranslation('name', 'like', '%Laptop%')->get();

Chaining with OR:

Product::where('price', '<', 1000)
    ->whereTranslation('name', 'like', '%Pro%')
    ->orWhereAnyTranslation('description', 'like', '%gaming%')
    ->get();

Sorting by Translation

Product::orderByTranslation('name')->get();               // current locale, ascending
Product::orderByTranslation('name', 'desc')->get();       // descending
Product::orderByTranslationDesc('name')->get();           // same as above
Product::orderByTranslation('name', 'asc', 'fr')->get();  // a specific locale

// Works with other scopes, pagination and relations
$category->products()
    ->whereTranslation('name', 'like', '%Pro%')
    ->orderByTranslation('name')
    ->paginate(20);

Missing translations follow the same fallback strategy as the accessors:

fallback Sort key when the locale is missing
null NULL
'app' The app.fallback_locale value
'first' The first translation (by id)

Sorting uses subqueries rather than a join, so selected columns and row counts are not affected. Rows with no usable translation sort as NULL, which comes first in ascending order on MySQL and SQLite and last on PostgreSQL. For large tables, keep the unique(['{model}_id', 'lang']) index from the setup guide.

Advanced Usage

First or Create

Product::firstOrCreateWithTranslations(
    ['sku' => 'LAPTOP-001'], // Match condition
    [
        'price' => 999,
        'name'  => ['en' => 'Laptop', 'fr' => 'Ordinateur'],
    ]
);

// If match found: returns existing model (translations untouched)
// If no match: creates new model with translations

Update or Create

Product::updateOrCreateWithTranslations(
    ['sku' => 'LAPTOP-001'], // Match condition
    [
        'price' => 899,
        'name'  => ['en' => 'Gaming Laptop'],
    ]
);

// If match found: updates model AND translations
// If no match: creates new model with translations

Custom Translation Model

Override the convention by defining $translationModel:

class Product extends Model
{
    use HasTranslations;

    protected string $translationModel = \App\Models\CustomProductTranslation::class;
    protected array $translatable = ['name'];
}

Configuration

Edit config/translatable.php:

return [
    'auto_load' => true,  // Eager load translations on every query
    'fallback'  => 'app', // Fallback strategy when translation missing
];

Fallback Strategies

Strategy Behavior
null Returns null when translation missing
'app' Falls back to config('app.fallback_locale')
'first' Falls back to first available translation

Example:

config(['translatable.fallback' => 'app']);
config(['app.fallback_locale' => 'en']);

app()->setLocale('de'); // German not available
echo $product->name; // Falls back to English

Auto-Loading Translations

When auto_load is true, all queries automatically eager load the translations relationship via a global scope. Disable for manual control:

config(['translatable.auto_load' => false]);

Product::with('translations')->get(); // Manual eager loading

Validation & Error Handling

Missing $translatable Property

If a model uses the trait but doesn't define $translatable:

MissingTranslatablePropertyException: App\Models\Product must define a $translatable property.

Invalid Translation Format

Translatable attributes must be arrays:

// ❌ Invalid
Product::createWithTranslations(['name' => 'Laptop']);

// ✅ Valid
Product::createWithTranslations(['name' => ['en' => 'Laptop']]);

Throws InvalidTranslationFormatException with a clear message:

The 'name' attribute must be an array of translations in the format: ['locale' => 'value'].

Testing

composer test

Changelog

See CHANGELOG.md for release history.

Contributing

Contributions are welcome! Please:

  1. Fork the repo
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

The MIT License (MIT). See LICENSE for details.

Credits

  • Hiba Sabouh — GitHub
  • All contributors

Support