README

A Laravel package that provides easy multi-language (i18n) support for Eloquent models. It automatically manages translations by separating translatable columns into dedicated translation tables, allowing you to store and retrieve model data in multiple languages seamlessly.

Features

• Automatic Translation Table Management - Translatable columns are automatically moved to a separate {table}_translations table
• Eloquent Integration - Use the HasTranslations trait for automatic translation joins and locale-aware queries
• Schema Builder - Extended schema builder (TranslatableSchema) for creating and modifying translatable tables
• Artisan Commands - Generate migrations, cache translatable columns, and manage translations via CLI
• Multi-Locale Support - Save translations for multiple locales at once
• Performance Caching - Cache translatable columns to avoid database queries
• Laravel 12 Compatible - Built for modern Laravel applications

Requirements

• PHP 8.2+
• Laravel 12.0+

Installation

Install the package via Composer:

composer require initiumlv/laravel-translatable

Publish the configuration file (optional):

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

Configuration

The configuration file config/translatable.php contains the following options:

return [
    // How to handle missing translations: 'strict', 'nullable', or 'fallback'
    'missing_translation_strategy' => 'strict',

    // Path where translatable column cache will be stored
    'cache_path' => 'bootstrap/cache/translatable.php',

    // Automatically regenerate cache after running migrations
    'auto_cache_after_migrate' => true,

    // Suffix used for translation tables (default: _translations)
    'table_suffix' => '_translations',

    // System columns to exclude when detecting translatable columns
    'system_columns' => ['id', 'locale'],
];

Missing Translation Strategies

The missing_translation_strategy option controls how the package handles records without translations in the current locale:

Usage

Creating Translatable Tables

Use the TranslatableSchema facade in your migrations to create tables with translatable columns:

<?php

use Illuminate\Database\Migrations\Migration;
use Initium\LaravelTranslatable\Components\Database\Blueprint;
use Initium\LaravelTranslatable\Facades\TranslatableSchema;

return new class extends Migration
{
    public function up(): void
    {
        TranslatableSchema::create('products', function (Blueprint $table) {
            $table->id();

            // Non-translatable columns (stay in main table)
            $table->decimal('price', 10, 2)->default(0);
            $table->boolean('is_active')->default(true);
            $table->integer('sort_order')->default(0);

            // Translatable columns (moved to products_translations table)
            $table->string('name')->translatable();
            $table->text('description')->nullable()->translatable();

            $table->timestamps();
        });
    }

    public function down(): void
    {
        TranslatableSchema::dropIfExists('products');
    }
};

This creates two tables:

products table:

product_translations table:

Adding the Trait to Your Model

Add the HasTranslations trait to your Eloquent model:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Initium\LaravelTranslatable\Components\Database\Concerns\HasTranslations;

class Product extends Model
{
    use HasTranslations;

    protected $guarded = [];
}

Saving Translations

Save with Current Locale

// Uses app()->getLocale() by default
$product = new Product();
$product->price = 99.99;
$product->is_active = true;
$product->name = 'English Product Name';
$product->description = 'English description';
$product->save();

Save with Specific Locale

$product = new Product();
$product->price = 49.99;
$product->name = 'Latvian Product Name';
$product->description = 'Latvian description';
$product->save(locale: 'lv');

Save Multiple Translations at Once

$product = new Product();
$product->price = 99.99;
$product->save();

$product->saveTranslations([
    'en' => ['name' => 'English Name', 'description' => 'English description'],
    'lv' => ['name' => 'Latvian Name', 'description' => 'Latvian description'],
    'de' => ['name' => 'German Name', 'description' => 'German description'],
]);

Retrieving Translations

The HasTranslations trait automatically joins the translation table and filters by the current locale:

// Set the application locale
app()->setLocale('en');

// Get product with English translations
$product = Product::find(1);
echo $product->name; // "English Name"
echo $product->description; // "English description"

// Switch locale
app()->setLocale('lv');

// Get product with Latvian translations
$product = Product::find(1);
echo $product->name; // "Latvian Name"

Query Without Translation Scope

To retrieve records without the automatic translation join:

// Get all products regardless of translation availability
$products = Product::withoutTranslations()->get();

Modifying Translatable Tables

Add New Translatable Columns

TranslatableSchema::table('products', function (Blueprint $table) {
    $table->string('subtitle')->nullable()->translatable();
});

Modify Existing Translatable Columns

TranslatableSchema::table('products', function (Blueprint $table) {
    $table->text('description')->nullable()->translatable()->change();
});

Drop Translatable Columns

TranslatableSchema::table('products', function (Blueprint $table) {
    $table->dropTranslatable('subtitle');
});

Supported Column Types

The following column types can be made translatable:

Text Types:

Numeric Types:

Other Types:

All column modifiers work as expected:

$table->string('name', 100)->nullable()->default('Untitled')->translatable();
$table->decimal('local_price', 10, 2)->translatable(); // Price that varies by locale
$table->boolean('is_available')->default(true)->translatable(); // Availability per locale

Artisan Commands

Generate Translatable Migration

# Create a new translatable table
php artisan make:translatable-migration create_products_table --create=products

# Modify an existing translatable table
php artisan make:translatable-migration add_subtitle_to_products_table --table=products

# Auto-detect table name from migration name
php artisan make:translatable-migration create_categories_table

Cache Translatable Columns

Generate a PHP cache file of translatable columns for improved performance:

php artisan translatable:cache

This scans your database for all *_translations tables and creates a cache file mapping tables to their translatable columns.

Clear Cache

Remove the translatable columns cache:

php artisan translatable:clear

API Reference

TranslatableSchema Facade

Blueprint Methods

HasTranslations Trait Methods

How It Works

1. Column Separation: When you call ->translatable() on a column definition, it's marked for separation from the main table.

2. Automatic Table Creation: The TranslatableSchemaBuilder automatically creates a {table}_translations table with the translatable columns, a foreign key reference, and a locale column.

3. Global Scope: The TranslationScope is automatically applied to models using HasTranslations, joining the translation table and filtering by the current application locale.

4. Atomic Saves: Translation data is saved within database transactions to ensure data consistency.

5. Pending Queue: Translation attribute changes are queued before saving to avoid race conditions when setting multiple translatable attributes.

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Kristians Jaunzems
• All Contributors

License

The MIT License (MIT). Please see License File for more information.