Skip to main content

Laravel i18n: pilnīgs internacionalizācijas un lokalizācijas ceļvedis

No pirmā lokāles faila līdz produkcijai: konfigurējiet Laravel tulkošanas sistēmu, apstrādājiet daudzskaitli, novērsiet JSON atkāpšanās kļūdu un pievienojiet viedas lokāļu atkāpšanās ķēdes reģionālajiem variantiem.

1

Izprotiet Laravel tulkošanas sistēmu

Laravel ietver iebūvētu tulkošanas sistēmu, kas atbalsta divus failu formātus: PHP masīvus un JSON. PHP faili izmanto ligzdotas atslēgas, kas sakārtotas pēc funkcijas (auth.failed, validation.required). JSON faili izmanto avota virkni kā atslēgu — tas ir vienkāršāk, bet neatbalsta ligzdošanu.

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 tulkošanas sistēma atrodas direktorijā lang/ (Laravel 9 un jaunākās versijās) vai resources/lang/ (Laravel 8 un agrākās versijās). Ietvars direktoriju nosaka automātiski. Ja pastāv abas, priekšroka ir lang/.
2

Konfigurējiet lokāles iestatījumus

Failā config/app.php iestatiet lietotnes noklusējuma lokāli un atkāpšanās lokāli. Atkāpšanās lokāle tiek izmantota, ja aktīvajā lokālē trūkst tulkojuma atslēgas. Konfigurējiet lietotnes atbalstītās lokāles un pievienojiet starpprogrammatūru, lai noteiktu un iestatītu lietotāja vēlamo lokāli.

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

Izmantojiet tulkošanas funkcijas

Laravel piedāvā trīs virkņu tulkošanas veidus: palīgfunkciju __() (ieteicams), funkciju trans() un Blade direktīvu @lang. Visi trīs pieņem tulkojuma atslēgu un neobligātus aizstāšanas parametrus. PHP kodā un Blade veidnēs izmantojiet __(), bet @lang — Blade veidnēs, ja nav jāatveido HTML speciālās rakstzīmes.

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',
    ],
];
Jaunā kodā dodiet priekšroku __(), nevis trans(). __() darbojas gan ar PHP, gan JSON tulkojumu failiem, bet trans() — tikai ar PHP failiem. @lang direktīva Blade veidnēs ir līdzvērtīga {'{ __() }'}, taču tai ir nedaudz vienkāršāka sintakse.
4

Apstrādājiet daudzskaitli

Laravel daudzskaitļa formām izmanto ar vertikālo svītru atdalītu sintaksi. Vienkāršākā forma ir 'apples' => 'There is one apple|There are many apples'. Konkrētiem diapazoniem izmantojiet 'apples' => '{0} No apples|{1} One apple|[2,*] :count apples'. Palīgfunkcija trans_choice() vai Str::plural() atlasa pareizo formu atbilstoši skaitam.

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 iebūvētā daudzskaitļa apstrāde vairumam valodu pareizi apstrādā tikai vienkāršas one/other kārtulas. Valodām ar sarežģītām daudzskaitļa formām (arābu valodai ir 6, krievu — 4, poļu — 3) jādefinē visas nepieciešamās CLDR daudzskaitļa kategorijas. Pretējā gadījumā lietotāji redzēs gramatiski nepareizu tekstu.
5

Pievienot lokalizāciju atkāpšanās ķēdes

Laravel iebūvētā atkāpšanās pāriet tikai no aktīvās lokāles uz fallback_locale — starpposma nav. Ja pt-BR lietotājam trūkst atslēgas, viņš redz angļu valodu, nevis pilnīgi derīgo pt-PT tulkojumu. laravel-locale-chain to novērš, ielādes laikā dziļi sapludinot tulkojumus no konfigurējamas atkāpšanās ķēdes.

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

Automatizēt tulkošanu

Kad Laravel i18n iestatīšana ir pabeigta, tulkojiet lokāļu failus ar MI. Norādiet MI asistentam avota lokāles failu vai izmantojiet i18n Agent CLI savā CI/CD konveijerā. Tiek atbalstīti gan PHP, gan JSON tulkojumu faili.

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
Tulkojiet pakāpeniski — pievienojot jaunas atslēgas, tulkojiet tikai izmaiņas, nevis no jauna ģenerējiet visus failus. Tas saglabā cilvēku pārskatītos tulkojumus un novērš nevajadzīgas izmaiņas.

Biežākās kļūdas

Kodā ierakstīta vienskaitļa un daudzskaitļa loģika

Rakstot $count == 1 ? 'item' : 'items' un neizmantojot trans_choice(), risinājums nedarbojas valodās, kur 0 ir vienskaitlis (franču), ir 3 vai vairāk daudzskaitļa formu (krievu, poļu) vai 6 formas (arābu). Vienmēr izmantojiet Laravel daudzskaitļa sintaksi un definējiet visas nepieciešamās formas.

JSON tulkojumiem nenotiek atkāpšanās

Laravel fallback_locale darbojas tikai PHP tulkojumu failiem. JSON tulkojumos avota virkne tiek izmantota kā atslēga, tāpēc trūkstošs tulkojums atgriež pašu atslēgu (angļu tekstu), nevis meklē atkāpšanās lokālē. Tas nozīmē, ka JSON tulkojumiem nav īstas lokāles atkāpšanās. Izmantojiet laravel-locale-chain, lai to novērstu.

PHP un JSON jaukšana, neizprotot prioritāti

Ja viena un tā pati atslēga ir gan PHP, gan JSON failos, priekšroka ir PHP. Tas var radīt mulsinošu situāciju, kad JSON faila atjaunināšana neko nemaina, jo PHP fails to aizēno. Katrai funkcijas nosaukumvietai izvēlieties vienu formātu un konsekventi to izmantojiet.

Izmēģiniet i18n Agent tūlīt

Nometiet tulkošanas failu šeit

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

vai noklikšķiniet, lai izvēlētos

Mērķa valodas

Reģistrācija nav vajadzīgaTūlītēja tāme

Laravel i18n bieži uzdotie jautājumi