Skip to main content

Laravel i18n: ghid complet de internaționalizare și localizare

De la primul fișier de limbă până în producție: configurați sistemul de traducere Laravel, gestionați pluralizarea, remediați eroarea mecanismului de rezervă pentru JSON și adăugați lanțuri inteligente de rezervă pentru setările regionale.

1

Înțelegeți sistemul de traducere Laravel

Laravel include un sistem de traducere care acceptă două formate de fișiere: tablouri PHP și JSON. Fișierele PHP folosesc chei imbricate, organizate după funcționalitate (auth.failed, validation.required). Fișierele JSON folosesc șirul-sursă drept cheie, ceea ce este mai simplu, dar nu permite imbricarea.

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
Sistemul de traducere Laravel se află în directorul lang/ (Laravel 9+) sau resources/lang/ (Laravel 8 și versiunile anterioare). Cadrul de lucru detectează automat directorul. Dacă există ambele, lang/ are prioritate.
2

Configurați setările de limbă

Setați limba implicită și limba de rezervă a aplicației în config/app.php. Limba de rezervă este folosită când o cheie de traducere lipsește din limba activă. Configurați limbile acceptate de aplicație și adăugați middleware pentru a detecta și seta limba preferată a utilizatorului.

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

Folosiți funcțiile de traducere

Laravel oferă trei modalități de a traduce șiruri: funcția ajutătoare __() (recomandată), funcția trans() și directiva Blade @lang. Toate trei acceptă cheia de traducere și parametri opționali de înlocuire. Folosiți __() în codul PHP și în șabloanele Blade, iar @lang în Blade când nu este necesară codificarea caracterelor speciale 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',
    ],
];
În codul nou, preferați __() în locul trans(). __() funcționează atât cu fișiere de traducere PHP, cât și JSON, în timp ce trans() funcționează numai cu fișiere PHP. Directiva @lang este echivalentă cu {'{ __() }'} în șabloanele Blade, dar are o sintaxă ceva mai clară.
4

Gestionați pluralizarea

Laravel folosește o sintaxă cu forme de plural separate prin bară verticală. Cea mai simplă formă este 'apples' => 'There is one apple|There are many apples'. Pentru intervale explicite, folosiți 'apples' => '{0} No apples|{1} One apple|[2,*] :count apples'. Funcția ajutătoare trans_choice() sau Str::plural() selectează forma corectă în funcție de număr.

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"
}
Pluralizarea încorporată în Laravel gestionează corect numai regulile simple one/other pentru majoritatea limbilor. Pentru limbile cu forme complexe de plural (araba are 6, rusa are 4, iar polona are 3), trebuie să definiți toate categoriile de plural CLDR necesare. În caz contrar, utilizatorii vor vedea texte incorecte gramatical.
5

Adăugați lanțuri de rezervă pentru setările regionale

Mecanismul de rezervă încorporat în Laravel trece doar de la limba activă la fallback_locale, fără o etapă intermediară. Un utilizator pt-BR căruia îi lipsește o cheie vede textul în engleză în locul traducerii perfect valabile în pt-PT. laravel-locale-chain remediază problema prin îmbinarea profundă, la încărcare, a traducerilor dintr-un lanț de rezervă configurabil.

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

Automatizați traducerile

După configurarea Laravel i18n, traduceți fișierele de limbă cu ajutorul IA. Indicați-i asistentului IA fișierul limbii-sursă sau folosiți interfața CLI i18n Agent în fluxul CI/CD. Sunt acceptate atât fișierele de traducere PHP, cât și cele 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
Traduceți incremental: când adăugați chei noi, traduceți doar diferențele, fără a regenera toate fișierele. Astfel păstrați traducerile verificate de oameni și evitați modificările inutile.

Capcane frecvente

Logică singular/plural scrisă direct în cod

Scrierea expresiei $count == 1 ? 'item' : 'items' în locul folosirii trans_choice() nu funcționează pentru limbile în care 0 este singular (franceză), există cel puțin 3 forme de plural (rusă, polonă) sau există 6 forme (arabă). Folosiți întotdeauna sintaxa de plural Laravel și definiți toate formele necesare.

Traducerile JSON nu folosesc limba de rezervă

fallback_locale din Laravel funcționează numai pentru fișierele de traducere PHP. Traducerile JSON folosesc șirul-sursă drept cheie, astfel că o traducere lipsă returnează însăși cheia (textul în engleză), în loc să caute în limba de rezervă. Prin urmare, traducerile JSON nu au un mecanism real de rezervă. Folosiți laravel-locale-chain pentru a remedia problema.

Combinarea PHP și JSON fără a înțelege ordinea de prioritate

Când aceeași cheie există atât în fișierele PHP, cât și în cele JSON, PHP are prioritate. Acest lucru poate produce un comportament derutant: actualizarea fișierului JSON nu are efect deoarece fișierul PHP îl suprascrie. Alegeți câte un singur format pentru fiecare spațiu de nume al funcționalității și folosiți-l consecvent.

Încercați acum i18n Agent

Plasați aici fișierul de traducere

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

sau faceți clic pentru a-l selecta

Limbi țintă

Nu este necesară înregistrareaEstimare instantanee

Întrebări frecvente despre Laravel i18n