Localizzazione

Come gestire le stringhe tradotte in file PHP e JSON usando la funzionalità multilingua di Laravel.

​

Cos’è la localizzazione

La localizzazione di Laravel offre un meccanismo comodo per ottenere stringhe tradotte in più lingue. La usi per supportare più lingue nella tua applicazione.

Ci sono due modi per gestire le stringhe di traduzione.

Modalità	Caratteristiche
File PHP	Array chiave-valore in lang/it/messages.php. Adatto per organizzare i messaggi per funzionalità (es. errori di validazione)
File JSON	Stringhe definite come chiave in lang/it.json. Consigliato per applicazioni con molte traduzioni

Le applicazioni Laravel predefinite non includono la directory lang. Per personalizzare pubblicala con lang:publish.

php artisan lang:publish

​

Impostazione della locale

​

Locale predefinita

La lingua predefinita si imposta in locale di config/app.php. Di norma usi la variabile d’ambiente APP_LOCALE in .env.

// config/app.php
'locale' => env('APP_LOCALE', 'en'),
'fallback_locale' => env('APP_FALLBACK_LOCALE', 'en'),

# .env
APP_LOCALE=it
APP_FALLBACK_LOCALE=en

fallback_locale è la lingua di fallback quando la stringa non esiste nella lingua richiesta.

​

Cambio di locale a runtime

Con il metodo setLocale() della facade App cambi la locale per una singola richiesta.

use Illuminate\Support\Facades\App;

Route::get('/greeting/{locale}', function (string $locale) {
    if (! in_array($locale, ['en', 'it', 'fr'])) {
        abort(400);
    }

    App::setLocale($locale);

    // ...
});

​

Verificare la locale corrente

use Illuminate\Support\Facades\App;

$locale = App::currentLocale();

if (App::isLocale('it')) {
    // Se è italiano
}

​

Creazione dei file di traduzione

​

Formato file PHP

Crea file PHP nella directory lang/{codice}/. Restituiscono un array associativo chiave-valore.

/lang
    /en
        messages.php
    /it
        messages.php

<?php

// lang/it/messages.php

return [
    'welcome' => 'Benvenuto nell\'applicazione!',
    'goodbye' => 'A presto!',
];

Per le lingue con varianti regionali usa i codici ISO 15897. Ad esempio inglese britannico è en_GB, non en-gb.

​

Formato JSON

Con molte stringhe da tradurre è consigliato il JSON. Crea file JSON con il nome della lingua in lang/.

/lang
    en.json
    it.json

Le stringhe predefinite (di norma in inglese) diventano le chiavi.

{
    "Welcome to our application!": "Benvenuto nell'applicazione!",
    "I love programming.": "Adoro programmare.",
    "Logout": "Esci",
    "Dashboard": "Cruscotto"
}

Nel formato JSON, il testo inglese è la chiave: la visualizzazione predefinita in inglese funziona automaticamente. Nelle lingue senza file di traduzione viene mostrata la chiave stessa (l’originale).

​

Quando usare PHP o JSON

Quando conviene il formato PHP

• Quando vuoi organizzare per funzionalità (es. messaggi di validazione)
• Quando sovrascrivi traduzioni integrate di Laravel (validation.php, auth.php, ecc.)
• Quando serve una gestione gerarchica delle chiavi

// lang/it/validation.php
return [
    'required' => 'Il campo :attribute è obbligatorio.',
    'email' => 'Il campo :attribute deve essere un\'email valida.',
];

Quando conviene JSON

• Molte stringhe di UI, chiavi laboriose da pensare
• Vuoi scrivere l’inglese direttamente nei template e tradurre solo le altre lingue
• Internazionalizzazione aggiunta a posteriori

{{-- Scrivi l'inglese direttamente in Blade --}}
{{ __('Welcome to our application!') }}

​

Recupero delle traduzioni

​

Helper __()

Il modo più usato. In formato PHP usa nomefile.chiave.

// Formato PHP: chiave 'welcome' in lang/it/messages.php
echo __('messages.welcome');
// => Benvenuto nell'applicazione!

// Formato JSON: usa direttamente il testo originale come chiave
echo __('I love programming.');
// => Adoro programmare.

Se la stringa non esiste viene restituita la chiave stessa.

echo __('messages.not_exists');
// => messages.not_exists

​

Uso in Blade

Nei template Blade usa {{ __() }}.

{{-- Formato PHP --}}
<h1>{{ __('messages.welcome') }}</h1>

{{-- Formato JSON --}}
<button>{{ __('Logout') }}</button>

{{-- Direttiva @lang (deprecata, mantenuta per compatibilità) --}}
@lang('messages.welcome')

La direttiva @lang è deprecata. Oggi si consiglia {{ __() }}.

​

Placeholder

Puoi inserire nei testi tradotti dei placeholder :nome.

// lang/it/messages.php
return [
    'welcome' => 'Benvenuto, :name!',
    'greet'   => 'Ciao, :Name!',  // Prima lettera maiuscola
    'shout'   => 'EHI :NAME!',    // Tutto maiuscolo
];

Passa un array di sostituzioni come secondo argomento a __().

echo __('messages.welcome', ['name' => 'Mario']);
// => Benvenuto, Mario!

echo __('messages.greet', ['name' => 'mario']);
// => Ciao, Mario!

echo __('messages.shout', ['name' => 'mario']);
// => EHI MARIO!

Anche in Blade:

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

​

Plurale

Le regole del plurale variano per lingua. Con | puoi separare singolare e plurale.

​

Plurale di base

// lang/it/messages.php
return [
    'apples' => 'C\'è una mela|Ci sono molte mele',
];

Anche in JSON:

{
    "There is one apple|There are many apples": "C'è una mela|Ci sono molte mele"
}

Usa trans_choice() passando la quantità.

echo trans_choice('messages.apples', 1);
// => C'è una mela

echo trans_choice('messages.apples', 5);
// => Ci sono molte mele

​

Plurale con range

Puoi indicare intervalli.

'apples' => '{0} Nessuna mela|[1,19] Alcune mele|[20,*] Tante mele',

echo trans_choice('messages.apples', 0);
// => Nessuna mela

echo trans_choice('messages.apples', 10);
// => Alcune mele

echo trans_choice('messages.apples', 50);
// => Tante mele

​

Placeholder nei plurali

Usa :count per mostrare la quantità. Passa altri valori come terzo argomento.

// lang/it/messages.php
return [
    'minutes_ago' => '{1} :value minuto fa|[2,*] :value minuti fa',
    'items'       => 'Ci sono :count elementi',
];

echo trans_choice('messages.minutes_ago', 5, ['value' => 5]);
// => 5 minuti fa

echo trans_choice('messages.items', 3);
// => Ci sono 3 elementi

​

Sovrascrivere i file di traduzione dei pacchetti

Se un pacchetto di terze parti ha propri file di traduzione, puoi sovrascriverlo posizionando file con lo stesso nome in lang/vendor/{nome-pacchetto}/{codice}/.

Ad esempio per personalizzare i messaggi inglesi di skyrim/hearthfire:

lang/
└── vendor/
    └── hearthfire/
        └── en/
            └── messages.php

// lang/vendor/hearthfire/en/messages.php
return [
    'welcome' => 'Messaggio personalizzato',
    // Definisci solo le chiavi che vuoi sovrascrivere. Le altre restano dal file originale.
];

​

Esempio pratico: middleware di switch italiano/inglese

Middleware che imposta la locale in base a sessione, preferenze utente o URL.

1. Crea il middleware

   php artisan make:middleware SetLocale
   
2. Implementa il middleware

   <?php
   
   namespace App\Http\Middleware;
   
   use Closure;
   use Illuminate\Http\Request;
   use Illuminate\Support\Facades\App;
   use Symfony\Component\HttpFoundation\Response;
   
   class SetLocale
   {
       public function handle(Request $request, Closure $next): Response
       {
           // Elenco delle locale supportate
           $supportedLocales = ['it', 'en'];
   
           // Se in sessione c'è una locale, usala
           $locale = $request->session()->get('locale');
   
           // Altrimenti usa Accept-Language del browser
           if (! $locale) {
               $browserLocale = substr($request->getPreferredLanguage($supportedLocales) ?? 'it', 0, 2);
               $locale = in_array($browserLocale, $supportedLocales) ? $browserLocale : 'it';
           }
   
           App::setLocale($locale);
   
           return $next($request);
       }
   }
   
3. Registra il middleware

   Registralo in bootstrap/app.php.

   use App\Http\Middleware\SetLocale;
   
   ->withMiddleware(function (Middleware $middleware) {
       $middleware->append(SetLocale::class);
   })
   
4. Aggiungi la route di switch

   // routes/web.php
   Route::post('/locale/{locale}', function (string $locale) {
       if (! in_array($locale, ['it', 'en'])) {
           abort(400);
       }
   
       session(['locale' => $locale]);
   
       return back();
   })->name('locale.switch');
   
5. Aggiungi i pulsanti nella vista Blade

   <div>
       <form method="POST" action="{{ route('locale.switch', 'it') }}">
           @csrf
           <button type="submit">Italiano</button>
       </form>
   
       <form method="POST" action="{{ route('locale.switch', 'en') }}">
           @csrf
           <button type="submit">English</button>
       </form>
   </div>
   

​

Esempio di struttura dei file di traduzione

lang/
├── it.json          # JSON (UI)
├── en.json
├── it/
│   └── validation.php   # PHP (validazione)
└── en/
    └── validation.php

// lang/it.json
{
    "Dashboard": "Cruscotto",
    "Login": "Accedi",
    "Logout": "Esci",
    "Welcome, :name!": "Benvenuto, :name!",
    "Save": "Salva",
    "Cancel": "Annulla",
    "Are you sure?": "Sei sicuro?"
}

{{-- resources/views/layouts/app.blade.php --}}
<nav>
    <a href="{{ route('dashboard') }}">{{ __('Dashboard') }}</a>
    <span>{{ __('Welcome, :name!', ['name' => auth()->user()->name]) }}</span>

    <form method="POST" action="{{ route('logout') }}">
        @csrf
        <button type="submit">{{ __('Logout') }}</button>
    </form>
</nav>

​

Riepilogo

Come definire le traduzioni

Modalità	File	Esempio di chiave	Recupero
File PHP	lang/it/messages.php	'welcome' => '...'	__('messages.welcome')
JSON	lang/it.json	"Welcome": "..."	__('Welcome')

Funzioni e facade utili

Funzione/metodo	Uso
__('key')	Helper per stringhe tradotte
trans('key')	Equivalente di __()
trans_choice('key', $count)	Traduzione al plurale
App::setLocale('it')	Cambia locale per richiesta
App::currentLocale()	Locale corrente
App::isLocale('it')	Verifica la locale

Uso in Blade

{{-- Base --}}
{{ __('messages.welcome') }}

{{-- Con placeholder --}}
{{ __('messages.welcome', ['name' => $user->name]) }}

{{-- Plurale --}}
{{ trans_choice('messages.apples', $count) }}