Skip to main content

Laravel i18n: täielik internatsionaliseerimise ja lokaliseerimise juhend

Esimesest lokaadifailist tootmiskeskkonnani: seadista Laravel'i tõlkesüsteem, töötle mitmusevorme, paranda JSON-i varulokaadi viga ja lisa piirkondlike variantide jaoks nutikad varulokaadiahelad.

1

Mõista Laravel'i tõlkesüsteemi

Laravel sisaldab tõlkesüsteemi, mis toetab kaht failivormingut: PHP-massiive ja JSON-i. PHP-failid kasutavad funktsioonide järgi korraldatud pesastatud võtmeid (auth.failed, validation.required). JSON-failid kasutavad lähtestringi võtmena, mis on lihtsam, kuid ei toeta pesastamist.

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'i tõlkesüsteem asub kataloogis lang/ (Laravel 9+) või resources/lang/ (Laravel 8 ja varasemad). Raamistik tuvastab kataloogi automaatselt. Kui mõlemad on olemas, eelistatakse lang/ kataloogi.
2

Määra lokaadiseaded

Määra rakenduse vaike- ja varulokaat failis config/app.php. Varulokaati kasutatakse, kui aktiivsest lokaadist puudub tõlkevõti. Seadista rakenduse toetatud lokaadid ja lisa middleware kasutaja eelistatud lokaadi tuvastamiseks ning määramiseks.

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

Kasuta tõlkefunktsioone

Laravel pakub stringide tõlkimiseks kolme viisi: abifunktsioon __() (soovitatud), funktsioon trans() ja Blade'i direktiiv @lang. Kõik kolm võtavad vastu tõlkevõtme ning valikulised asendusparameetrid. Kasuta __() PHP-koodis ja Blade'i mallides ning @langi Blade'is, kui HTML-i pole vaja varjestada.

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',
    ],
];
Uues koodis eelista trans() asemel __(). __() töötab nii PHP- kui ka JSON-tõlkefailidega, trans() ainult PHP-failidega. Direktiiv @lang vastab Blade'i mallides avaldisele { __() }, kuid veidi puhtama süntaksiga.
4

Töötle mitmusevorme

Laravel kasutab mitmusevormide jaoks püstkriipsuga eraldatud süntaksit. Lihtsaim vorm on 'apples' => 'There is one apple|There are many apples'. Selgesõnaliste vahemike jaoks kasuta 'apples' => '{0} No apples|{1} One apple|[2,*] :count apples'. Abifunktsioon trans_choice() või Str::plural() valib koguse põhjal õige vormi.

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"
}
Laravel'i sisseehitatud mitmusekäsitlus haldab enamikus keeltes õigesti ainult lihtsaid one/other-reegleid. Keerukate mitmusevormidega keeltes (araabia keeles kuus, vene keeles neli, poola keeles kolm) tuleb määrata kõik vajalikud CLDR-i mitmusekategooriad. Ilma nendeta näevad kasutajad grammatiliselt vigast teksti.
5

Lisa varulokaadiahelad

Laravel'i sisseehitatud varu liigub ainult aktiivsest lokaadist fallback_locale'ile, vahepealset sammu pole. Puuduva võtmega pt-BR kasutaja näeb täiesti sobiva pt-PT tõlke asemel inglise keelt. laravel-locale-chain parandab selle, süvaühendades laadimise ajal seadistatava varulokaadiahela tõlked.

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

Automatiseeri tõlked

Kui Laravel i18n-i seadistus on valmis, tõlgi lokaadifailid tehisintellektiga. Suuna tehisintellekti abiline lähtekeele failile või kasuta CI/CD-konveieris i18n Agent'i CLI-d. Toetatud on nii PHP- kui ka JSON-tõlkefailid.

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
Tõlgi järk-järgult — kui lisad uusi võtmeid, tõlgi kõigi failide uuesti loomise asemel ainult diff. Nii säilivad inimeste ülevaadatud tõlked ja väldid tarbetuid muudatusi.

Levinud komistuskivid

Jäigalt kodeeritud ainsuse või mitmuse loogika

Tingimus $count == 1 ? 'item' : 'items' rikub tõlked keeltes, kus 0 on ainsus (prantsuse), kus on vähemalt kolm mitmusevormi (vene, poola) või kuus vormi (araabia). Kasuta alati Laravel'i mitmusesüntaksit ja määra kõik vajalikud vormid.

JSON-tõlked ei taandu varulokaadile

Laravel'i fallback_locale töötab ainult PHP-tõlkefailidega. JSON-tõlked kasutavad lähtestringi võtmena, seega tagastab puuduv tõlge varulokaadist otsimise asemel võtme ehk ingliskeelse teksti. See tähendab, et JSON-tõlgetel pole päris varulokaati. Paranda see laravel-locale-chain'iga.

PHP ja JSON-i segamine prioriteeti mõistmata

Kui sama võti on nii PHP- kui ka JSON-failis, on PHP prioriteetsem. See võib põhjustada segadust, kus JSON-faili värskendamine ei mõju, sest PHP-fail varjutab seda. Vali iga funktsiooni nimeruumi jaoks üks vorming ja ole järjepidev.

Proovi i18n Agent'i kohe

Kukuta tõlkefail siia

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

või klõpsa faili valimiseks

Sihtkeeled

Registreerumine pole vajalikKohene hinnang

Laravel i18n-i KKK