Skip to main content

Laravel i18n: išsamus internacionalizavimo ir lokalizavimo vadovas

Nuo pirmojo lokalės failo iki gamybinės aplinkos: sukonfigūruokite Laravel vertimo sistemą, tvarkykite daugiskaitą, ištaisykite JSON atsarginio parinkimo klaidą ir pridėkite išmanias lokalių atsarginio parinkimo grandines regioniniams variantams.

1

Supraskite Laravel vertimo sistemą

Laravel turi integruotą vertimo sistemą, palaikančią du failų formatus: PHP masyvus ir JSON. PHP failuose naudojami įdėtiniai raktai, suskirstyti pagal funkciją (auth.failed, validation.required). JSON failuose šaltinio eilutė naudojama kaip raktas – tai paprasčiau, tačiau nepalaiko įdėjimo.

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
Laravel vertimo sistema yra lang/ kataloge (Laravel 9 ir naujesnėse versijose) arba resources/lang/ kataloge (Laravel 8 ir senesnėse versijose). Sistema katalogą aptinka automatiškai. Jei yra abu, pirmenybė teikiama lang/.
2

Sukonfigūruokite lokalės nustatymus

Nustatykite numatytąją ir atsarginę programos lokalę faile config/app.php. Atsarginė lokalė naudojama, kai aktyvioje lokalėje trūksta vertimo rakto. Sukonfigūruokite programos palaikomas lokales ir pridėkite tarpinę programinę įrangą, kuri aptiktų ir nustatytų naudotojo pageidaujamą lokalę.

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

Naudokite vertimo funkcijas

Laravel siūlo tris eilučių vertimo būdus: pagalbinę funkciją __() (rekomenduojama), funkciją trans() ir Blade direktyvą @lang. Visi trys priima vertimo raktą ir pasirinktinius keitimo parametrus. PHP kode ir Blade šablonuose naudokite __(), o @lang – Blade šablonuose, kai nereikia keisti HTML specialiųjų simbolių.

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',
    ],
];
Naujame kode rinkitės __(), o ne trans(). __() veikia su PHP ir JSON vertimo failais, o trans() – tik su PHP failais. @lang direktyva Blade šablonuose atitinka {'{ __() }'}, tačiau jos sintaksė šiek tiek aiškesnė.
4

Tvarkykite daugiskaitą

Laravel naudoja vertikaliuoju brūkšniu atskirtą daugiskaitos formų sintaksę. Paprasčiausia forma: 'apples' => 'There is one apple|There are many apples'. Aiškiems intervalams naudokite 'apples' => '{0} No apples|{1} One apple|[2,*] :count apples'. Pagalbinė funkcija trans_choice() arba Str::plural() parenka tinkamą formą pagal skaičių.

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"
}
Integruotas Laravel daugiskaitos formų parinkimas daugumai kalbų tinkamai apdoroja tik paprastas one/other taisykles. Kalboms su sudėtingomis daugiskaitos formomis (arabų kalba turi 6, rusų – 4, lenkų – 3) turite apibrėžti visas reikalingas CLDR daugiskaitos kategorijas. Priešingu atveju naudotojai matys gramatiškai netaisyklingą tekstą.
5

Pridėti atsarginių lokalių grandines

Integruotas Laravel atsarginis parinkimas pereina tik nuo aktyvios lokalės prie fallback_locale – tarpinio žingsnio nėra. Jei pt-BR naudotojui trūksta rakto, jis mato anglų kalbą, o ne puikiai tinkamą pt-PT vertimą. laravel-locale-chain tai ištaiso įkėlimo metu giliai suliedama vertimus iš konfigūruojamos atsarginio parinkimo grandinės.

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

Automatizuoti vertimus

Baigę konfigūruoti Laravel i18n, išverskite lokalės failus naudodami DI. Nurodykite DI asistentui šaltinio lokalės failą arba naudokite i18n Agent CLI savo CI/CD konvejeryje. Palaikomi PHP ir JSON vertimo failai.

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
Verskite palaipsniui – pridėję naujų raktų, išverskite tik skirtumą, užuot iš naujo generavę visus failus. Taip išsaugosite žmonių peržiūrėtus vertimus ir išvengsite nereikalingų pakeitimų.

Dažnos klaidos

Kode įrašyta vienaskaitos ir daugiskaitos logika

Naudojant $count == 1 ? 'item' : 'items' vietoje trans_choice(), sprendimas neveikia kalbose, kur 0 yra vienaskaita (prancūzų), yra 3 ar daugiau daugiskaitos formų (rusų, lenkų) arba 6 formos (arabų). Visada naudokite Laravel daugiskaitos sintaksę ir apibrėžkite visas reikalingas formas.

JSON vertimams netaikomas atsarginis parinkimas

Laravel fallback_locale veikia tik PHP vertimo failams. JSON vertimuose šaltinio eilutė naudojama kaip raktas, todėl trūkstamas vertimas grąžina patį raktą (anglišką tekstą), užuot ieškojęs atsarginėje lokalėje. Vadinasi, JSON vertimai neturi tikro lokalės atsarginio parinkimo. Ištaisykite tai naudodami laravel-locale-chain.

PHP ir JSON maišymas nesuprantant pirmumo

Kai tas pats raktas yra ir PHP, ir JSON failuose, pirmenybė teikiama PHP. Dėl to gali kilti paini situacija: JSON failo atnaujinimas neturi jokio poveikio, nes jį užgožia PHP failas. Kiekvienai funkcijos vardų sričiai pasirinkite vieną formatą ir nuosekliai jį naudokite.

Išbandykite i18n Agent dabar

Nuvilkite vertimo failą čia

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

arba spustelėkite norėdami pasirinkti

Tikslinės kalbos

Registruotis nereikiaMomentinis įvertis

Laravel i18n DUK