Skip to main content

Laravel i18n: kompletná príručka internacionalizácie a lokalizácie

Od prvého lokalizačného súboru po produkciu: nakonfigurujte prekladový systém Laravel, spracujte tvary množného čísla, opravte chybu náhrady JSON a pridajte inteligentné reťazce náhradných lokalizácií pre regionálne varianty.

1

Pochopte prekladový systém Laravel

Laravel obsahuje vstavaný prekladový systém, ktorý podporuje dva formáty súborov: polia PHP a JSON. Súbory PHP používajú vnorené kľúče usporiadané podľa funkcií (auth.failed, validation.required). Súbory JSON používajú ako kľúč zdrojový reťazec, čo je jednoduchšie, ale nepodporuje vnorovanie.

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
Prekladový systém Laravel sa nachádza v adresári lang/ (Laravel 9+) alebo resources/lang/ (Laravel 8 a starší). Framework adresár rozpozná automaticky. Ak existujú oba, prednosť má lang/.
2

Nakonfigurujte nastavenia lokalizácie

V config/app.php nastavte predvolenú a náhradnú lokalizáciu aplikácie. Náhradná lokalizácia sa použije, keď v aktívnej lokalizácii chýba prekladový kľúč. Nakonfigurujte podporované lokalizácie aplikácie a pridajte middleware na rozpoznanie a nastavenie preferovanej lokalizácie používateľa.

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

Používajte prekladové funkcie

Laravel ponúka tri spôsoby prekladu reťazcov: pomocnú funkciu __() (odporúčaná), funkciu trans() a direktívu Blade @lang. Všetky tri prijímajú prekladový kľúč a voliteľné náhradné parametre. __() používajte v kóde PHP a šablónach Blade a @lang v Blade, keď nepotrebujete kódovať 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',
    ],
];
V novom kóde uprednostnite __() pred trans(). __() funguje s prekladovými súbormi PHP aj JSON, zatiaľ čo trans() iba so súbormi PHP. Direktíva @lang zodpovedá {'{ __() }'} v šablónach Blade, ale má o niečo čistejšiu syntax.
4

Spracujte tvary množného čísla

Laravel používa syntax tvarov množného čísla oddelených zvislou čiarou. Najjednoduchší tvar je 'apples' => 'There is one apple|There are many apples'. Pre explicitné rozsahy použite 'apples' => '{0} No apples|{1} One apple|[2,*] :count apples'. Pomocná funkcia trans_choice() alebo Str::plural() vyberie správny tvar podľa počtu.

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"
}
Vstavané množné číslo Laravel správne spracúva vo väčšine jazykov iba jednoduché pravidlá one/other. Pri jazykoch so zložitými tvarmi (arabčina ich má 6, ruština 4 a poľština 3) musíte definovať všetky potrebné kategórie CLDR. Bez nich používatelia uvidia gramaticky nesprávny text.
5

Pridajte reťazce náhradných lokalizácií

Vstavaná náhrada Laravel prechádza iba z aktívnej lokalizácie na fallback_locale – bez medzikroku. Používateľ pt-BR s chýbajúcim kľúčom uvidí angličtinu namiesto úplne vhodného prekladu pt-PT. laravel-locale-chain to rieši hĺbkovým zlúčením prekladov z konfigurovateľného reťazca náhrad pri načítaní.

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

Automatizujte preklady

Po dokončení nastavenia Laravel i18n preložte lokalizačné súbory pomocou AI. Zadajte svojmu asistentovi AI zdrojový lokalizačný súbor alebo použite CLI i18n Agent vo svojej pipeline CI/CD. Podporované sú prekladové súbory PHP aj 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
Prekladajte prírastkovo – po pridaní nových kľúčov preložte iba rozdiel namiesto opätovného generovania všetkých súborov. Zachováte tak preklady skontrolované človekom a vyhnete sa zbytočným zmenám.

Bežné nástrahy

Pevne zapísaná logika jednotného a množného čísla

Zápis $count == 1 ? 'item' : 'items' namiesto trans_choice() zlyháva v jazykoch, kde je 0 jednotné číslo (francúzština), existujú viac ako 3 tvary množného čísla (ruština, poľština) alebo 6 tvarov (arabčina). Vždy používajte syntax množného čísla Laravel a definujte všetky potrebné tvary.

Preklady JSON nepoužívajú náhradu

fallback_locale v Laravel funguje iba pre prekladové súbory PHP. Preklady JSON používajú zdrojový reťazec ako kľúč, takže chýbajúci preklad vráti samotný kľúč (anglický text) namiesto hľadania v náhradnej lokalizácii. Preklady JSON preto nemajú skutočnú náhradnú lokalizáciu. Opravte to pomocou laravel-locale-chain.

Kombinovanie PHP a JSON bez pochopenia priority

Keď rovnaký kľúč existuje v súboroch PHP aj JSON, prednosť má PHP. Môže to viesť k mätúcemu správaniu, keď aktualizácia súboru JSON nemá účinok, pretože ho zatieňuje súbor PHP. Pre každý menný priestor funkcie vyberte jeden formát a používajte ho konzistentne.

Vyskúšajte i18n Agent teraz

Potiahnite súbor na preklad sem

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

alebo kliknite a vyberte súbor

Cieľové jazyky

Bez registrácieOkamžitý odhad

Časté otázky k Laravel i18n