Localizzazione

• Introduzione
• Definire le stringhe di traduzione
• Recuperare le stringhe di traduzione
• Sovrascrivere i File di Lingua del Package

Introduzione

Per impostazione predefinita, lo scheletro dell’applicazione Laravel non include la directory lang. Se desideri personalizzare i file di lingua di Laravel, puoi pubblicarli tramite il comando Artisan lang:publish.

Le funzionalità di localizzazione di Laravel offrono un modo semplice per ottenere stringhe in diverse lingue, permettendo di supportare facilmente più lingue all’interno della tua applicazione.

Laravel fornisce due modi per gestire le stringhe di traduzione. Prima di tutto, le stringhe di lingua possono essere salvate in file all’interno della directory lang dell’applicazione. In questa directory, possono esserci sottodirectory per ogni lingua supportata dall’applicazione. Questo è l’approccio che Laravel utilizza per gestire le stringhe di traduzione per funzionalità integrate di Laravel come i messaggi di errore di validazione:

    /lang
        /en
            messages.php
        /es
            messages.php

Oppure, le stringhe di traduzione possono essere definite all’interno di file JSON posti nella directory lang. Seguendo questo approccio, ogni lingua supportata dalla tua applicazione avrà un file JSON corrispondente in questa directory. Questo metodo è consigliato per applicazioni che hanno un gran numero di stringhe traducibili:

    /lang
        en.json
        es.json

Discuteremo ciascun approccio per la gestione delle stringhe di traduzione in questa documentazione.

Pubblicazione dei File delle Lingue

Di default, lo scheletro dell’applicazione Laravel non include la directory lang. Se vuoi personalizzare i file delle lingue di Laravel o crearne di tuoi, devi creare la directory lang usando il comando Artisan lang:publish. Il comando lang:publish creerà la directory lang nella tua applicazione e pubblicherà il set predefinito di file linguistici usati da Laravel:

php artisan lang:publish

Configurare la Lingua

La lingua predefinita per la tua applicazione è memorizzata nell’opzione locale del file di configurazione config/app.php, solitamente impostata usando la variabile d’ambiente APP_LOCALE. Puoi modificare questo valore per adattarlo alle esigenze della tua applicazione.

Puoi anche configurare una "lingua di fallback", che verrà utilizzata quando la lingua predefinita non contiene una determinata stringa di traduzione. Come la lingua predefinita, anche la lingua di fallback è configurata nel file config/app.php e il suo valore è tipicamente impostato usando la variabile d’ambiente APP_FALLBACK_LOCALE.

Puoi modificare la lingua predefinita per una singola richiesta HTTP durante l’esecuzione utilizzando il metodo setLocale fornito dalla facade App:

use Illuminate\Support\Facades\App;

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

    App::setLocale($locale);

    // ...
});

Determinare la Lingua Corrente

Puoi usare i metodi currentLocale e isLocale sulla facade App per determinare la lingua corrente o verificare se la lingua è un determinato valore:

use Illuminate\Support\Facades\App;

$locale = App::currentLocale();

if (App::isLocale('en')) {
    // ...
}

Lingua per la Pluralizzazione

Puoi istruire il "pluralizer" di Laravel, utilizzato da Eloquent e da altre parti del framework per convertire stringhe singolari in plurali, a usare una lingua diversa dall’inglese. Questo può essere fatto invocando il metodo useLanguage all’interno del metodo boot di uno dei service provider della tua applicazione. Le lingue attualmente supportate dal pluralizer sono: french, norwegian-bokmal, portuguese, spanish e turkish:

    use Illuminate\Support\Pluralizer;

/**
 * Bootstrap di tutti i servizi dell'applicazione.
 */
public function boot(): void
{
    Pluralizer::useLanguage('spanish');

    // ...
}

Se personalizzi la lingua del pluralizer, dovresti definire esplicitamente i nomi delle tabelle del tuo modello Eloquent.

Definire le stringhe di traduzione

Utilizzo delle Chiavi Brevi

Generalmente, le stringhe di traduzione sono memorizzate in file all’interno della directory lang. All’interno di questa directory, dovrebbe esserci una sottocartella per ogni lingua supportata dalla tua applicazione. Questo è l’approccio che Laravel utilizza per gestire le stringhe di traduzione per le funzionalità integrate di Laravel, come i messaggi di errore di validazione:

    /lang
        /en
            messages.php
        /es
            messages.php

Tutti i file di lingua restituiscono un array di stringhe associate a chiavi. Ad esempio:

    <?php

    // lang/en/messages.php

    return [
        'welcome' => 'Welcome to our application!',
    ];

Per le lingue che differiscono per territorio, dovresti nominare le cartelle delle lingue secondo la ISO 15897. Ad esempio, "en_GB" dovrebbe essere usato per l’inglese britannico anziché "en-gb".

Utilizzo delle stringhe di traduzione come chiavi

Per applicazioni con un gran numero di stringhe traducibili, definire ogni stringa con una "chiave breve" può diventare confuso quando si fa riferimento alle chiavi nelle tue viste ed è scomodo inventare continuamente chiavi per ogni stringa di traduzione supportata dalla tua applicazione.

Per questo motivo, Laravel fornisce anche il supporto per definire le stringhe di traduzione utilizzando la traduzione "predefinita" della stringa come chiave. I file di lingua che utilizzano le stringhe di traduzione come chiavi sono memorizzati come file JSON nella directory lang. Ad esempio, se la tua applicazione ha una traduzione in spagnolo, dovresti creare un file lang/es.json:

{
    "I love programming.": "Me encanta programar."
}

Conflitti Chiave/File

Non dovresti definire chiavi di stringhe di traduzione che confliggono con altri nomi di file di traduzione. Ad esempio, tradurre __('Action') per la locale "NL" mentre esiste un file nl/action.php ma non esiste un file nl.json farà sì che il traduttore restituisca l’intero contenuto di nl/action.php.

Recuperare le stringhe di traduzione

Puoi recuperare le stringhe di traduzione dai tuoi file di lingua usando la funzione helper __. Se utilizzi "chiavi brevi" per definire le tue stringhe di traduzione, dovresti passare il file che contiene la chiave e la chiave stessa alla funzione __ usando la sintassi a "punto". Per esempio, recuperiamo la stringa di traduzione welcome dal file di lingua lang/en/messages.php:

    echo __('messages.welcome');

Se la stringa di traduzione specificata non esiste, la funzione __ restituirà la chiave della stringa di traduzione. Quindi, usando l’esempio sopra, la funzione __ restituirebbe messages.welcome se la stringa di traduzione non esiste.

Se utilizzi le stringhe di traduzione predefinite come chiavi di traduzione, dovresti passare la traduzione predefinita della tua stringa alla funzione __:

    echo __('I love programming.');

Anche in questo caso, se la stringa di traduzione non esiste, la funzione __ restituirà la chiave della stringa di traduzione che le è stata fornita.

Se usi il motore di templating Blade, puoi usare la sintassi di echo {{ }} per mostrare la stringa di traduzione:

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

Sostituire Parametri nelle Stringhe di Traduzione

Se desideri, puoi definire dei segnaposto nelle tue stringhe di traduzione. Tutti i segnaposto iniziano con :. Per esempio, puoi definire un messaggio di benvenuto con un segnaposto per il nome:

    'welcome' => 'Welcome, :name',

Per sostituire i segnaposto quando recuperi una stringa di traduzione, puoi passare un array di sostituzioni come secondo argomento alla funzione __:

    echo __('messages.welcome', ['name' => 'dayle']);

Se il tuo segnaposto è tutto in maiuscolo, o solo la prima lettera è maiuscola, il valore tradotto sarà capitalizzato di conseguenza:

    'welcome' => 'Welcome, :NAME', // Welcome, DAYLE
    'goodbye' => 'Goodbye, :Name', // Goodbye, Dayle

Formattazione della Sostituzione di Oggetti

Se provi a fornire un oggetto come segnaposto per una traduzione, verrà invocato il metodo __toString dell’oggetto. Il metodo __toString è uno dei "metodi magici" integrati di PHP. Tuttavia, a volte potresti non avere il controllo sul metodo __toString di una determinata classe, come quando la classe con cui stai interagendo appartiene a una libreria di terze parti.

In questi casi, Laravel ti permette di registrare un gestore di formattazione personalizzato per quel particolare tipo di oggetto. Per fare ciò, dovresti invocare il metodo stringable del traduttore. Il metodo stringable accetta una closure, che dovrebbe specificare il tipo di oggetto di cui è responsabile la formattazione. Tipicamente, il metodo stringable dovrebbe essere invocato all’interno del metodo boot della classe AppServiceProvider della tua applicazione:

use Illuminate\Support\Facades\Lang;
use Money\Money;

/**
 * Avvia qualsiasi servizio dell'applicazione.
 */
public function boot(): void
{
    Lang::stringable(function (Money $money) {
        return $money->formatTo('en_GB');
    });
}

Pluralizzazione

La pluralizzazione è un problema complesso, poiché diverse lingue hanno una varietà di regole intricate; tuttavia, Laravel può aiutarti a tradurre le stringhe in modo diverso in base alle regole di pluralizzazione che definisci. Utilizzando il carattere |, puoi distinguere le forme singolari e plurali di una stringa:

    'apples' => 'C\'è una mela|Ci sono molte mele',

Naturalmente, la pluralizzazione è supportata anche quando si utilizzano stringhe di traduzione come chiavi:

{
    "There is one apple|There are many apples": "Hay una manzana|Hay muchas manzanas"
}

Puoi anche creare regole di pluralizzazione più complesse che specificano stringhe di traduzione per diverse gamme di valori:

    'apples' => '{0} Non ce n\'sono|[1,19] Ce ne sono alcune|[20,*] Ce ne sono molte',

Dopo aver definito una stringa di traduzione con opzioni di pluralizzazione, puoi usare la funzione trans_choice per recuperare la forma corretta in base al "conteggio". In questo esempio, poiché il conteggio è maggiore di uno, viene restituita la forma plurale della stringa di traduzione:

    echo trans_choice('messages.apples', 10);

Puoi anche definire attributi segnaposto nelle stringhe di pluralizzazione. Questi segnaposto possono essere sostituiti passando un array come terzo argomento alla funzione trans_choice:

    'minutes_ago' => '{1} :value minuto fa|[2,*] :value minuti fa',

    echo trans_choice('time.minutes_ago', 5, ['value' => 5]);

Se desideri visualizzare il valore intero passato alla funzione trans_choice, puoi utilizzare il segnaposto integrato :count:

    'apples' => '{0} Non ce n\'sono|{1} C\'è una mela|[2,*] Ce ne sono :count',

Sovrascrivere i File di Lingua del Package

Alcuni package includono i propri file di lingua. Invece di modificare i file principali del package per cambiare queste linee, puoi sovrascriverli posizionando i file nella directory lang/vendor/{package}/{locale}.

Ad esempio, se devi sovrascrivere le stringhe di traduzione in inglese in messages.php per un package chiamato skyrim/hearthfire, dovresti posizionare un file di lingua in: lang/vendor/hearthfire/en/messages.php. In questo file, devi definire solo le stringhe di traduzione che vuoi sovrascrivere. Le stringhe di traduzione che non sovrascrivi verranno caricate dai file di lingua originali del package.