Skip to main content

Laravel i18n: Kompletní průvodce internacionalizací a lokalizací

Od prvního souboru locale po produkci: nakonfigurujte překladový systém Laravelu, vyřešte pluralizaci, opravte JSON fallback bug a přidejte chytré fallback řetězce locale pro regionální varianty.

1

Pochopit překladový systém Laravelu

Laravel obsahuje vestavěný překladový systém, který podporuje dva formáty souborů: PHP pole a JSON. Soubory PHP používají vnořené klíče uspořádané podle funkcí (auth.failed, validation.required). Soubory JSON používají jako klíč zdrojový řetězec, což je jednodušší, ale nepodporuje vnořování.

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
Překladový systém Laravelu je v adresáři lang/ (Laravel 9+) nebo resources/lang/ (Laravel 8 a starší). Framework adresář automaticky detekuje. Pokud existují oba, přednost má lang/.
2

Nakonfigurovat nastavení locale

V config/app.php nastavte výchozí locale aplikace a fallback locale. Fallback locale se použije, když v aktivním locale chybí překladový klíč. Nakonfigurujte pro aplikaci podporovaná locale a přidejte middleware, který rozpozná a nastaví uživatelem preferované locale.

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žívat překladové funkce

Laravel nabízí tři způsoby, jak překládat řetězce: pomocnou funkci __() (doporučeno), funkci trans() a direktivu @lang v Blade. Všechny tři přijímají překladový klíč a volitelné parametry pro nahrazení. V PHP kódu i v Blade šablonách používejte __() a v Blade používejte @lang tam, kde nepotřebujete escapovat 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 novém kódu preferujte __() před trans(). __() funguje s překladovými soubory PHP i JSON, zatímco trans() funguje jen se soubory PHP. Direktiva @lang je ekvivalentní {'{ __() }'} v Blade šablonách, ale má o něco čistší syntaxi.
4

Zpracovat pluralizaci

Laravel používá pro tvary množného čísla syntaxi oddělenou svislítkem. Nejjednodušší tvar je 'apples' => 'There is one apple|There are many apples'. Pro explicitní rozsahy použijte 'apples' => '{0} No apples|{1} One apple|[2,*] :count apples'. Pomocníci trans_choice() nebo Str::plural() vyberou správný tvar podle 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"
}
Vestavěná pluralizace v Laravelu správně pokrývá pro většinu jazyků jen jednoduchá pravidla one/other. Pro jazyky se složitými tvary množného čísla (arabština má 6, ruština 4, polština 3) musíte definovat všechny požadované kategorie plurálu podle CLDR. Jinak se uživatelům budou zobrazovat gramaticky nesprávné texty.
5

Přidat fallback řetězce locale

Vestavěný fallback v Laravelu jde pouze z aktivního locale na fallback_locale — neexistuje žádný mezikrok. Uživatel pt-BR s chybějícím klíčem uvidí angličtinu místo zcela použitelného překladu pt-PT. laravel-locale-chain to řeší tak, že při načtení provede deep-merge překladů z konfigurovatelného fallback řetězce.

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

Automatizovat překlady

S dokončeným i18n nastavením v Laravelu překládejte soubory locale pomocí AI. Nasměrujte svého AI asistenta na zdrojový soubor locale nebo použijte i18n Agent CLI ve Vašem CI/CD pipeline. Podporované jsou překladové soubory v PHP i 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
Překládejte postupně — když přidáte nové klíče, přeložte jen diff místo regenerování všech souborů. Zachováte tak překlady zkontrolované člověkem a vyhnete se zbytečným změnám.

Běžná úskalí

Natvrdo zakódovaná logika singuláru/plurálu

Psát $count == 1 ? 'item' : 'items' místo použití trans_choice() selhává u jazyků, kde je 0 singulár (francouzština), kde existují 3+ tvary plurálu (ruština, polština) nebo kde je tvarů 6 (arabština). Vždy používejte pluralizační syntaxi Laravelu a definujte všechny požadované tvary.

JSON překlady nepoužívají fallback

fallback_locale v Laravelu funguje pouze pro PHP překladové soubory. JSON překlady používají zdrojový řetězec jako klíč, takže při chybějícím překladu vrátí samotný klíč (anglický text) místo toho, aby hledaly ve fallback locale. To znamená, že JSON překlady nemají skutečný locale fallback. K nápravě použijte laravel-locale-chain.

Míchání PHP a JSON bez pochopení priority

Když stejný klíč existuje v PHP i JSON souborech, přednost má PHP. To může vést k matoucímu chování, kdy úprava JSON souboru nemá žádný efekt, protože jej PHP soubor přebije. Vyberte jeden formát pro daný feature namespace a držte se ho.

Vyzkoušejte i18n Agent nyní

Sem přetáhněte svůj překladový soubor

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

nebo klikněte a vyberte soubor

Cílové jazyky

Bez registraceOkamžitý odhad

FAQ k i18n v Laravelu