Skip to main content

i18n en Laravel: guía completa de internacionalización y localización

Del primer archivo de configuración regional a producción: configure el sistema de traducción de Laravel, gestione la pluralización, corrija el error de respaldo de JSON y añada cadenas inteligentes de respaldo para variantes regionales.

1

Comprender el sistema de traducción de Laravel

Laravel incluye un sistema de traducción compatible con dos formatos: matrices PHP y JSON. Los archivos PHP usan claves anidadas organizadas por funcionalidad —auth.failed o validation.required—. JSON utiliza la cadena de origen como clave, algo más sencillo pero sin anidamiento.

Terminal
composer create-project laravel/laravel my-app
cd my-app

# Laravel includes i18n out of the box
# No extra packages needed for basic usage
El sistema reside en lang/ —Laravel 9 o posterior— o resources/lang/ —Laravel 8 y anteriores—. El framework detecta automáticamente el directorio. Si existen ambos, lang/ tiene prioridad.
2

Configurar los ajustes regionales

Defina la configuración regional predeterminada y la de respaldo de la aplicación en config/app.php. Esta última se utiliza cuando falta una clave en la configuración regional activa. Configure las configuraciones regionales admitidas y añada middleware para detectar y definir la preferida del usuario.

config/app.php
// config/app.php
return [
    'locale' => 'en',            // Default locale
    'fallback_locale' => 'en',   // Fallback when key is missing
    'faker_locale' => 'en_US',

    // Available locales (for your language switcher)
    'available_locales' => ['en', 'de', 'ja', 'es', 'fr', 'pt-BR'],
];
app/Http/Middleware/SetLocale.php
// app/Http/Middleware/SetLocale.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class SetLocale
{
    public function handle(Request $request, Closure $next)
    {
        $locale = $request->segment(1); // e.g. /de/about

        if (in_array($locale, config('app.available_locales'))) {
            app()->setLocale($locale);
        }

        return $next($request);
    }
}
3

Utilizar funciones de traducción

Laravel ofrece tres formas: la función auxiliar __() —recomendada—, trans() y la directiva Blade @lang. Las tres aceptan la clave y parámetros de sustitución opcionales. Utilice __() en código PHP y plantillas Blade, y @lang en Blade cuando no necesite escapar HTML.

lang/en/messages.php
// lang/en/messages.php
return [
    'welcome' => 'Welcome to our application',
    'greeting' => 'Hello, :name!',
    'nav' => [
        'home' => 'Home',
        'about' => 'About',
        'settings' => 'Settings',
    ],
];

// lang/de/messages.php
return [
    'welcome' => 'Willkommen in unserer Anwendung',
    'greeting' => 'Hallo, :name!',
    'nav' => [
        'home' => 'Startseite',
        'about' => 'Über uns',
        'settings' => 'Einstellungen',
    ],
];
Prefiera __() a trans() en código nuevo. __() funciona con archivos PHP y JSON, mientras trans() solo funciona con PHP. La directiva @lang equivale a {'{ __() }'} en plantillas Blade, pero ofrece una sintaxis algo más limpia.
4

Gestionar la pluralización

Laravel separa las formas plurales con barras verticales. La forma más sencilla es 'apples' => 'There is one apple|There are many apples'. Para intervalos explícitos: 'apples' => '{0} No apples|{1} One apple|[2,*] :count apples'. trans_choice() o Str::plural() selecciona la forma según el número.

lang/en.json
// lang/en.json
{
    "Welcome back!": "Welcome back!",
    "You have :count new notifications": "You have :count new notifications",
    "Copyright :year :company": "Copyright :year :company"
}

// lang/de.json
{
    "Welcome back!": "Willkommen zurück!",
    "You have :count new notifications": "Sie haben :count neue Benachrichtigungen",
    "Copyright :year :company": "Copyright :year :company"
}
La pluralización integrada solo gestiona bien reglas simples one/other en la mayoría de los idiomas. En otros complejos —árabe, 6 formas; ruso, 4; polaco, 3— debe definir todas las categorías CLDR. Sin ellas, los usuarios ven texto gramaticalmente incorrecto.
5

Añadir cadenas de respaldo de configuración regional

El respaldo integrado de Laravel solo va de la región activa a fallback_locale, sin pasos intermedios. Un usuario pt-BR con una clave ausente ve inglés en vez de pt-PT. laravel-locale-chain lo corrige combinando en profundidad traducciones de una cadena configurable durante la carga.

resources/views/example.blade.php
{{-- Simple translation --}}
<h1>{{ __('messages.welcome') }}</h1>

{{-- With variables --}}
<p>{{ __('messages.greeting', ['name' => $user->name]) }}</p>

{{-- Using @lang directive --}}
<h2>@lang('messages.nav.home')</h2>

{{-- JSON translations (use the string itself as key) --}}
<p>{{ __('Welcome back!') }}</p>

{{-- Pluralization --}}
{{ trans_choice('{0} No items|{1} One item|[2,*] :count items', $count) }}

{{-- Inside Blade components --}}
<x-button>{{ __('messages.nav.settings') }}</x-button>
6

Automatizar traducciones

Cuando complete la configuración, traduzca sus archivos de configuración regional con IA. Indique a su asistente el archivo de origen o utilice la CLI de i18n Agent en CI/CD. Se admiten PHP y JSON.

config/locale-chain.php
// Install locale chain package
composer require i18n-agent/laravel-locale-chain

// config/locale-chain.php
return [
    'chains' => [
        'pt-BR' => ['pt-BR', 'pt', 'en'],
        'zh-Hant-TW' => ['zh-Hant-TW', 'zh-Hant', 'zh', 'en'],
        'es-419' => ['es-419', 'es', 'en'],
    ],
];

// In AppServiceProvider::boot()
use I18nAgent\LocaleChain\LocaleChainServiceProvider;

// The package automatically deep-merges translations
// across the chain: pt-BR -> pt -> en
Traduzca de forma incremental: cuando añada claves nuevas, traduzca solo las diferencias en vez de volver a generar todo. Así conserva las traducciones revisadas por personas y evita cambios innecesarios.

Errores habituales

Lógica de singular y plural codificada directamente

Escribir $count == 1 ? 'item' : 'items' en vez de utilizar trans_choice() falla en idiomas donde 0 es singular —francés—, hay 3 o más formas —ruso y polaco— o existen 6 —árabe—. Utilice siempre la sintaxis de Laravel y defina todas las formas.

Las traducciones JSON no usan la configuración regional de respaldo

fallback_locale de Laravel solo funciona con PHP. JSON utiliza la cadena de origen como clave, así que una traducción ausente devuelve la propia clave —texto inglés— en vez de buscar en otra región. Por tanto, no existe un respaldo real. Utilice laravel-locale-chain para corregirlo.

Mezclar PHP y JSON sin comprender la prioridad

Cuando existe la misma clave en PHP y JSON, PHP tiene prioridad. Esto puede resultar confuso: actualizar JSON no surte efecto porque PHP lo oculta. Elija un formato por espacio funcional y manténgalo.

Pruebe i18n Agent ahora

Arrastre y suelte aquí su archivo de traducción

JSON, YAML, PO, XML, CSV, Markdown, Properties

o haga clic para seleccionar

Idiomas de destino

No es necesario registrarsePresupuesto al instante

Preguntas frecuentes sobre i18n en Laravel