Skip to main content

I18n de Laravel: guia completa d’internacionalització i localització

Des del primer fitxer de configuració regional fins a producció: configuri el sistema de traducció de Laravel, gestioni la pluralització, corregeixi l’error de reserva de JSON i afegeixi cadenes intel·ligents de configuracions regionals de reserva per a les variants regionals.

1

Entendre el sistema de traducció de Laravel

Laravel inclou un sistema de traducció integrat que admet dos formats de fitxer: matrius PHP i JSON. Els fitxers PHP utilitzen claus imbricades organitzades per funcionalitat (auth.failed, validation.required). Els fitxers JSON utilitzen la cadena d’origen com a clau; és més senzill, però no admet l’imbricació.

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 de traducció de Laravel es troba al directori lang/ (Laravel 9 o posterior) o resources/lang/ (Laravel 8 o anterior). El framework detecta el directori automàticament. Si tots dos existeixen, lang/ té prioritat.
2

Configurar els paràmetres de configuració regional

Defineixi la configuració regional predeterminada de l’aplicació i la de reserva a config/app.php. La configuració regional de reserva s’utilitza quan falta una clau de traducció a la configuració regional activa. Configuri les configuracions regionals admeses per l’aplicació i afegeixi programari intermedi que detecti i estableixi la configuració regional preferida de l’usuari.

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

Utilitzar les funcions de traducció

Laravel ofereix tres maneres de traduir cadenes: la funció auxiliar __() (recomanada), la funció trans() i la directiva @lang de Blade. Totes tres accepten la clau de traducció i paràmetres de substitució opcionals. Utilitzi __() al codi PHP i a les plantilles Blade i @lang a Blade quan no calgui escapar l’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',
    ],
];
En codi nou, prefereixi __() a trans(). __() funciona tant amb fitxers de traducció PHP com JSON, mentre que trans() només funciona amb fitxers PHP. La directiva @lang equival a {'{ __() }'} a les plantilles Blade, però té una sintaxi una mica més neta.
4

Gestionar la pluralització

Laravel utilitza una sintaxi de formes plurals separades per barres verticals. La forma més senzilla és 'apples' => 'There is one apple|There are many apples'. Per indicar intervals explícits, utilitzi 'apples' => '{0} No apples|{1} One apple|[2,*] :count apples'. La funció auxiliar trans_choice() o Str::plural() selecciona la forma correcta segons la quantitat.

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 pluralització integrada de Laravel només gestiona correctament les regles senzilles de singular i plural per a la majoria d’idiomes. Per als idiomes amb formes plurals complexes (l’àrab en té 6, el rus 4 i el polonès 3), ha de definir totes les categories de plural CLDR necessàries. Si no ho faci, els usuaris veuran textos gramaticalment incorrectes.
5

Afegir cadenes de configuracions regionals de reserva

El mecanisme de reserva integrat de Laravel només passa de la configuració regional activa a fallback_locale; no hi ha cap pas intermedi. Un usuari de pt-BR que trobi una clau absent veurà el text en anglès en lloc de la traducció de pt-PT perfectament vàlida. laravel-locale-chain ho corregeix fusionant en profunditat les traduccions d’una cadena de reserva configurable durant la càrrega.

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

Automatitzar les traduccions

Un cop completada la configuració d’i18n de Laravel, tradueixi els fitxers de configuració regional mitjançant IA. Indiqui a l’assistent d’IA el fitxer de configuració regional d’origen o utilitzi la CLI d’i18n Agent al procés de CI/CD. S’admeten tant els fitxers de traducció PHP com els 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
Tradueixi incrementalment: quan afegeixi claus noves, tradueixi només les diferències en lloc de regenerar tots els fitxers. Així conservarà les traduccions revisades per persones i evitarà canvis innecessaris.

Errors habituals

Lògica de singular i plural escrita directament al codi

Escriure $count == 1 ? 'item' : 'items' en lloc d’utilitzar trans_choice() falla en idiomes en què 0 és singular (francès), en què hi ha 3 formes plurals o més (rus i polonès) o en què n’hi ha 6 (àrab). Utilitzi sempre la sintaxi de plural de Laravel i defineixi totes les formes necessàries.

Les traduccions JSON no recorren a la configuració regional de reserva

El fallback_locale de Laravel només funciona amb fitxers de traducció PHP. Les traduccions JSON utilitzen la cadena d’origen com a clau, de manera que, si falta una traducció, es retorna la mateixa clau (el text en anglès) en lloc de cercar-la a la configuració regional de reserva. Per tant, les traduccions JSON no tenen cap mecanisme real de configuració regional de reserva. Utilitzi laravel-locale-chain per corregir-ho.

Combinar PHP i JSON sense entendre’n la prioritat

Quan la mateixa clau existeix tant als fitxers PHP com als JSON, PHP té prioritat. Això pot provocar un comportament desconcertant en què actualitzar el fitxer JSON no té cap efecte perquè el fitxer PHP l’oculta. Triï un únic format per cada espai de noms funcional i mantingui'l.

Provar i18n Agent ara

Arrossegar aquí el fitxer de traducció

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

o fer clic per explorar

Idiomes de destinació

No cal registrePressupost instantani

Preguntes freqüents sobre l’i18n de Laravel