Skip to main content

Laravel i18n: cjelovit vodič za internacionalizaciju i lokalizaciju

Od prve datoteke lokalnih postavki do produkcije: postavite Laravelov sustav prijevoda, obradite množinu, riješite pogrešku zamjene za JSON i dodajte pametne zamjenske lance za regionalne inačice.

1

Upoznajte Laravelov sustav prijevoda

Laravel sadržava ugrađeni sustav prijevoda koji podržava dva formata datoteka: PHP polja i JSON. PHP datoteke rabe ugniježđene ključeve organizirane prema značajkama (auth.failed, validation.required). JSON datoteke rabe izvorni tekst kao ključ, što je jednostavnije, ali ne podržava ugniježđivanje.

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
Laravelov sustav prijevoda nalazi se u direktoriju lang/ (Laravel 9+) ili resources/lang/ (Laravel 8 i stariji). Razvojni okvir automatski prepoznaje direktorij. Ako postoje oba, prednost ima lang/.
2

Konfiguriranje lokalnih postavki

U config/app.php postavite zadane i zamjenske lokalne postavke aplikacije. Zamjenske se postavke rabe kada ključ prijevoda nedostaje u aktivnima. Odredite podržane lokalne postavke aplikacije i dodajte posrednički softver koji prepoznaje i postavlja korisnikove željene postavke.

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

Uporaba funkcija za prijevod

Laravel nudi tri načina prevođenja nizova: pomoćnu funkciju __() (preporučeno), funkciju trans() i Bladeovu direktivu @lang. Sve prihvaćaju ključ prijevoda i neobavezne zamjenske parametre. __() rabite u PHP kodu i Blade predlošcima, a @lang u Bladeu kada HTML ne treba kodirati.

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',
    ],
];
U novom kodu odaberite __() umjesto trans(). __() radi s PHP i JSON datotekama prijevoda, dok trans() radi samo s PHP datotekama. Direktiva @lang odgovara izrazu {'{ __() }'} u Blade predlošcima, ali ima nešto pregledniju sintaksu.
4

Obradite množinu

Laravel rabi sintaksu množinskih oblika odvojenih okomitom crtom. Najjednostavniji je oblik 'apples' => 'There is one apple|There are many apples'. Za izričite raspone rabite 'apples' => '{0} No apples|{1} One apple|[2,*] :count apples'. Pomoćna funkcija trans_choice() ili Str::plural() odabire ispravan oblik prema broju.

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"
}
Laravelova ugrađena množina za većinu jezika ispravno obrađuje samo jednostavna pravila one/other. Za jezike sa složenijim oblicima, poput arapskoga sa 6, ruskoga s 4 i poljskoga s 3, morate definirati sve potrebne kategorije množine CLDR. Bez njih će korisnici vidjeti gramatički neispravan tekst.
5

Dodavanje lanaca zamjenskih lokalnih postavki

Laravelova ugrađena zamjena prelazi samo s aktivnih lokalnih postavki na fallback_locale, bez međukoraka. Korisnik s postavkom pt-BR kojem nedostaje ključ vidi engleski umjesto valjanoga prijevoda za pt-PT. laravel-locale-chain to rješava dubinskim objedinjavanjem prijevoda iz prilagodljivog zamjenskog lanca tijekom učitavanja.

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

Automatiziranje prijevoda

Nakon što postavite Laravelov i18n sustav, prevedite datoteke lokalnih postavki uz pomoć AI-ja. Usmjerite AI pomoćnika na datoteku izvornog jezika ili rabite i18n Agent CLI u CI/CD pipelineu. Podržane su PHP i JSON datoteke prijevoda.

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
Prevodite postupno: kada dodate nove ključeve, prevedite samo razliku umjesto da ponovno stvarate sve datoteke. Tako čuvate prijevode koje su pregledali ljudi i izbjegavate nepotrebne izmjene.

Uobičajene zamke

Izravno zapisana logika jednine i množine

Izraz $count == 1 ? 'item' : 'items' umjesto funkcije trans_choice() ne radi za jezike u kojima je 0 jednina (francuski), koji imaju više od 3 množinska oblika (ruski, poljski) ili 6 oblika (arapski). Uvijek rabite Laravelovu sintaksu množine i definirajte sve potrebne oblike.

JSON prijevodi ne prelaze na zamjenske lokalne postavke

Laravelov fallback_locale radi samo s PHP datotekama prijevoda. JSON prijevodi rabe izvorni tekst kao ključ, pa se za prijevod koji nedostaje vraća sam ključ (engleski tekst) umjesto pretraživanja zamjenskih lokalnih postavki. JSON prijevodi zato nemaju stvaran zamjenski jezik. To riješite paketom laravel-locale-chain.

Kombiniranje PHP i JSON formata bez razumijevanja prioriteta

Kada isti ključ postoji u PHP i JSON datoteci, prednost ima PHP. To može uzrokovati zbunjujuće ponašanje u kojem ažuriranje JSON datoteke nema učinka jer je PHP datoteka zasjenjuje. Za svaki prostor imena značajke odaberite jedan format i dosljedno ga se držite.

Isprobajte i18n Agent odmah

Povucite datoteku za prijevod ovdje

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

ili kliknite za odabir

Ciljni jezici

Registracija nije potrebnaProcjena odmah

Česta pitanja o Laravelovu i18n sustavu