Skip to main content

Laravel i18n: täydellinen kansainvälistämis- ja lokalisointiopas

Ensimmäisestä kieliversiotiedostosta tuotantoon: määritä Laravel:in käännösjärjestelmä, käsittele monikkomuodot, korjaa JSON-varakielivirhe ja lisää älykkäät varakieliketjut alueellisille muodoille.

1

Ymmärrä Laravel:in käännösjärjestelmä

Laravel sisältää kaksi tiedostomuotoa tukevan käännösjärjestelmän: PHP-taulukot ja JSON. PHP-tiedostot käyttävät ominaisuuksittain järjestettyjä sisäkkäisiä avaimia (auth.failed, validation.required). JSON-tiedostot käyttävät lähdemerkkijonoa avaimena, mikä on yksinkertaisempaa mutta ei tue sisäkkäisyyttä.

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:in käännösjärjestelmä on lang/-hakemistossa (Laravel 9+) tai resources/lang/-hakemistossa (Laravel 8 ja vanhemmat). Ohjelmistokehys tunnistaa hakemiston automaattisesti. Jos molemmat ovat olemassa, lang/ on etusijalla.
2

Määritä kieliversioasetukset

Aseta sovelluksesi oletus- ja varakieliversiot config/app.php-tiedostossa. Varakieliversiota käytetään, kun aktiivisesta kieliversiosta puuttuu käännösavain. Määritä sovelluksesi tuetut kieliversiot ja lisää middleware tunnistamaan ja asettamaan käyttäjän ensisijainen kieliversio.

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

Käytä käännösfunktioita

Laravel tarjoaa kolme tapaa merkkijonojen kääntämiseen: __()-apufunktio (suositus), trans()-funktio ja @lang-Blade-direktiivi. Kaikki kolme vastaanottavat käännösavaimen ja valinnaiset korvausparametrit. Käytä __()-funktiota PHP-koodissa ja Blade-malleissa sekä @lang-direktiiviä Bladessa, kun HTML:ää ei tarvitse koodata.

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',
    ],
];
Suosi uudessa koodissa __()-funktiota trans()-funktion sijaan. __() toimii sekä PHP- että JSON-käännöstiedostojen kanssa, mutta trans() vain PHP-tiedostojen kanssa. @lang-direktiivi vastaa Blade-mallien { __() }-lauseketta hieman selkeämmällä syntaksilla.
4

Käsittele monikkomuodot

Laravel käyttää monikkomuotoihin pystyviivalla erotettua syntaksia. Yksinkertaisin muoto on 'apples' => 'There is one apple|There are many apples'. Käytä eksplisiittisiin alueisiin muotoa 'apples' => '{0} No apples|{1} One apple|[2,*] :count apples'. trans_choice()-apufunktio tai Str::plural() valitsee määrän perusteella oikean muodon.

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:in sisäänrakennettu monikkomuotojen käsittely käsittelee useimmissa kielissä oikein vain yksinkertaiset one/other-säännöt. Monimutkaisia monikkomuotoja käyttävissä kielissä (arabiassa kuusi, venäjässä neljä, puolassa kolme) on määritettävä kaikki tarvittavat CLDR-monikkoluokat. Ilman niitä käyttäjät näkevät kieliopillisesti virheellistä tekstiä.
5

Lisää varakieliketjut

Laravel:in sisäänrakennettu varakieli siirtyy vain aktiivisesta kieliversiosta fallback_locale-arvoon ilman välivaihetta. Puuttuvan avaimen kohtaava pt-BR-käyttäjä näkee täysin käyttökelpoisen pt-PT-käännöksen sijaan englannin. laravel-locale-chain korjaa tämän syväyhdistämällä määritettävän varakieliketjun käännökset latauksen aikana.

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

Automatisoi käännökset

Kun Laravel i18n on otettu käyttöön, käännä kieliversiotiedostosi tekoälyllä. Osoita tekoälyavustajasi lähdekielen tiedostoon tai käytä i18n Agent:in CLI:tä CI/CD-putkessasi. Sekä PHP- että JSON-käännöstiedostoja tuetaan.

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
Käännä vaiheittain — kun lisäät uusia avaimia, käännä vain diff äläkä luo kaikkia tiedostoja uudelleen. Näin ihmisten tarkistamat käännökset säilyvät ja tarpeettomat muutokset vältetään.

Tavalliset sudenkuopat

Kovakoodattu yksikkö- tai monikkologiikka

Ehto $count == 1 ? 'item' : 'items' rikkoo käännökset, jos kieli käsittelee 0:n yksikkönä (ranska), käyttää vähintään kolmea monikkomuotoa (venäjä, puola) tai kuutta muotoa (arabia). Käytä aina Laravel:in monikkosyntaksia ja määritä kaikki tarvittavat muodot.

JSON-käännökset eivät siirry varakieleen

Laravel:in fallback_locale toimii vain PHP-käännöstiedostoille. JSON-käännökset käyttävät lähdemerkkijonoa avaimena, joten puuttuva käännös palauttaa itse avaimen eli englanninkielisen tekstin eikä etsi varakieliversiosta. JSON-käännöksillä ei siis ole oikeaa varakieliversiota. Korjaa tämä laravel-locale-chain:illa.

PHP:n ja JSON:in sekoittaminen ymmärtämättä etusijajärjestystä

Kun sama avain on sekä PHP- että JSON-tiedostossa, PHP on etusijalla. Tämä voi aiheuttaa hämmentävän tilanteen, jossa JSON-tiedoston päivittäminen ei vaikuta, koska PHP-tiedosto peittää sen. Valitse ominaisuuden nimiavaruutta kohden yksi muoto ja käytä sitä johdonmukaisesti.

Kokeile i18n Agent:ia nyt

Pudota käännöstiedostosi tähän

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

tai valitse napsauttamalla

Kohdekielet

Rekisteröitymistä ei tarvitaVälitön arvio

Usein kysyttyä Laravel i18n:stä