Download the PHP package zaber-dev/laravel-localization without Composer

Laravel Localization

Supports: Laravel 11, 12 & 13+ • PHP 8.2+ • Database

Application-level multilingual content management and provider-agnostic translation orchestration for Laravel.

Manage localizations using stateful entity lifecycles, attribute-level content fingerprinting, AI-ready translation pipelines, Scout-compatible search indexing, and transparent Eloquent model proxies — all through a clean, expressive API.

Language is an application concern, not just a presentation concern. Modern applications generate content with AI, send translations to human editors for review, publish across multi-region clusters, and need to know exactly which attributes became outdated when source models change.

Quick Example

Common Use Cases

Laravel Localization is ideal for:

• AI-Ready Translation Pipelines: Dispatch structured localization requests containing only the attributes that require translation, allowing your application to connect OpenAI, Anthropic, DeepL, or custom translation services.
• Multilingual SaaS & E-Commerce: Manage translated product titles, descriptions, and SEO metadata with draft/published state control.
• Content Review Workflows: Transition translations through Draft → Generated → NeedsReview → Approved → Published states.
• Stale Translation Auditing: Identify exactly which localized attributes require re-translation after source model updates.
• Scout-Compatible Search Indexing: Flatten localized attributes into searchable fields for Scout-compatible engines such as Meilisearch, Typesense, and Algolia.

Why not Spatie Laravel Translatable or Raw JSON Columns?

Spatie's package is excellent for simple string storage. However, enterprise applications require lifecycle awareness, AI pipeline integration, and granular staleness detection.

Features

• Transparent Model Proxy ⭐: Access localized attributes as if they were standard model properties ($post->title or $post->localize('fr')->title).
• Attribute-Level Content Fingerprinting ⭐: Tracks individual content fingerprints for each translatable field. When you update the title, only the title is marked stale — preventing expensive AI re-generation of unchanged content.
• Stateful Localization Lifecycles: Manage translation approval using formal state machine transitions (Draft, Generated, NeedsReview, Approved, Published).
• AI Batching & Metadata: Dispatch batch translation events (LocalizationRequested) while recording provider names, AI model versions, token counts, and cost telemetry.
• Enterprise Fallback Chains: Define granular fallback paths per locale (e.g., fr-CA -> fr -> en).
• Laravel Scout Search Integration: Flatten all active translations into indexed search fields via toLocalizedSearchArray().
• Artisan CLI Diagnostics: Audit un-translated models and stale localizations straight from your terminal.

Documentation

• Installation
• Configuration
• Usage Guide
• LEARN.md

Installation

Install the package via Composer:

Publish the configuration file and database migrations:

Run database migrations to create the localizations table:

Configuration

The configuration file config/localization.php allows you to set default locales, database table names, and fallback chains:

Usage Guide

1. Preparing Eloquent Models

Implement Localizable contract and add the HasLocalizations trait to any Eloquent model:

2. Transparent Model Proxy

Accessing translatable attributes automatically inspects the active application locale (app()->getLocale()). If a translation payload exists, it is returned transparently:

3. Reading DTOs (LocalizationInfo)

To inspect metadata, state, or completion metrics, retrieve the strongly-typed LocalizationInfo Data Transfer Object:

4. Attribute-Level Content Fingerprinting & Stale Detection

Laravel Localization calculates a content fingerprint (MD5 hash) for each translatable attribute when localizations are saved. When the source model changes, only modified fields are flagged:

5. Storing Translations & AI Metadata

Store translation payloads manually or through automated background jobs, passing rich execution telemetry:

6. AI Batching & Generation Pipelines

Trigger batch translation pipelines across multiple models and locales:

Listen to LocalizationRequested events in your application listener:

7. Stateful Lifecycle Workflows

Transition translations through formal publication stages:

8. Querying & Scopes

Query models based on translation presence, missing locales, or lifecycle states:

9. Laravel Scout Search Indexing

Flatten all localized content for full-text search indexing engines:

Produces indexed fields like title_fr, content_fr, title_de, content_de.

10. CLI Diagnostics Commands

Audit missing and stale translations directly from Artisan:

Testing

Run the test suite using PHPUnit:

License

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