Skip to main content

i18n di Laravel: guida completa all'internazionalizzazione e alla localizzazione

Dal primo file di lingua alla produzione: configuri il sistema di traduzione di Laravel, gestisca i plurali, corregga il bug del fallback JSON e aggiunga catene di fallback intelligenti per le varianti regionali.

1

Comprendere il sistema di traduzione di Laravel

Laravel include un sistema di traduzione integrato che supporta due formati di file: array PHP e JSON. I file PHP usano chiavi annidate organizzate per funzionalità (auth.failed, validation.required). I file JSON usano la stringa di origine come chiave, una soluzione più semplice che però non supporta l'annidamento.

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
Il sistema di traduzione di Laravel si trova nella directory lang/ (Laravel 9 e versioni successive) o resources/lang/ (Laravel 8 e versioni precedenti). Il framework rileva automaticamente la directory. Se esistono entrambe, lang/ ha la precedenza.
2

Configurare le impostazioni della lingua

Imposti in config/app.php le lingue predefinita e di fallback dell'applicazione. Quella di fallback viene usata quando manca una chiave di traduzione nella lingua attiva. Configuri le lingue supportate dall'applicazione e aggiunga un middleware per rilevare e impostare quella preferita dall'utente.

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

Usare le funzioni di traduzione

Laravel offre tre modi per tradurre le stringhe: la funzione helper __() (consigliata), la funzione trans() e la direttiva Blade @lang. Tutte accettano la chiave di traduzione e parametri di sostituzione facoltativi. Usi __() nel codice PHP e nei modelli Blade e @lang in Blade quando non serve applicare l'escape 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',
    ],
];
Nel nuovo codice, preferisca __() a trans(). __() funziona sia con i file di traduzione PHP sia con quelli JSON, mentre trans() funziona soltanto con i file PHP. La direttiva @lang equivale a {'{ __() }'} nei modelli Blade, ma presenta una sintassi leggermente più ordinata.
4

Gestire i plurali

Laravel usa una sintassi con forme plurali separate da barre verticali. La forma più semplice è 'apples' => 'There is one apple|There are many apples'. Per gli intervalli espliciti, usi 'apples' => '{0} No apples|{1} One apple|[2,*] :count apples'. La funzione helper trans_choice() o Str::plural() seleziona la forma corretta in base al conteggio.

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 gestione dei plurali integrata in Laravel tratta correttamente soltanto le semplici regole one/other per la maggior parte delle lingue. Per le lingue con forme complesse, come arabo con 6 forme, russo con 4 e polacco con 3, deve definire tutte le categorie del plurale CLDR richieste. Senza di esse, gli utenti vedono testo grammaticalmente errato.
5

Aggiungere catene di fallback

Il fallback integrato di Laravel passa soltanto dalla lingua attiva a fallback_locale, senza passaggi intermedi. Un utente pt-BR con una chiave mancante vede l'inglese anziché la traduzione pt-PT perfettamente valida. laravel-locale-chain risolve il problema unendo ricorsivamente le traduzioni di una catena di fallback configurabile al momento del caricamento.

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

Automatizzare le traduzioni

Dopo aver completato la configurazione i18n di Laravel, traduca i file di lingua con l'IA. Indichi all'assistente IA il file della lingua di origine oppure usi la CLI di i18n Agent nella pipeline CI/CD. Sono supportati sia i file di traduzione PHP sia quelli 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
Traduca in modo incrementale: quando aggiunge nuove chiavi, traduca soltanto il diff anziché rigenerare tutti i file. In questo modo preserva le traduzioni revisionate da persone ed evita modifiche superflue.

Problemi comuni

Logica singolare/plurale codificata direttamente

Scrivere $count == 1 ? 'item' : 'items' anziché usare trans_choice() non funziona nelle lingue in cui 0 è singolare (francese), esistono 3 o più forme plurali (russo, polacco) oppure vi sono 6 forme (arabo). Usi sempre la sintassi plurale di Laravel e definisca tutte le forme richieste.

Le traduzioni JSON non applicano il fallback

fallback_locale di Laravel funziona soltanto con i file di traduzione PHP. Le traduzioni JSON usano la stringa di origine come chiave, quindi una traduzione mancante restituisce la chiave stessa, ossia il testo inglese, anziché cercare nella lingua di fallback. Ciò significa che le traduzioni JSON non hanno un vero fallback linguistico. Usi laravel-locale-chain per correggere il problema.

Combinare PHP e JSON senza comprenderne la precedenza

Quando la stessa chiave esiste sia nei file PHP sia in quelli JSON, PHP ha la precedenza. Può verificarsi un comportamento poco chiaro in cui l'aggiornamento del file JSON non produce effetti perché il file PHP lo sostituisce. Scelga un formato per ogni spazio dei nomi delle funzionalità e lo usi in modo coerente.

Provi subito i18n Agent

Trascinare qui il file di traduzione

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

oppure fare clic per selezionarlo

Lingue di destinazione

Nessuna registrazione richiestaPreventivo immediato

Domande frequenti sull'i18n di Laravel