Skip to main content

Laravel i18n: kompletny przewodnik po internacjonalizacji i lokalizacji

Od pierwszego pliku językowego po produkcję: skonfiguruj system tłumaczeń Laravela, obsłuż liczbę mnogą, napraw błąd wartości rezerwowej JSON i dodaj inteligentne łańcuchy rezerwowe dla wariantów regionalnych.

1

Poznaj system tłumaczeń Laravela

Laravel zawiera wbudowany system tłumaczeń obsługujący dwa formaty plików: tablice PHP oraz JSON. Pliki PHP używają zagnieżdżonych kluczy uporządkowanych według funkcji (auth.failed, validation.required). Pliki JSON używają tekstu źródłowego jako klucza, co jest prostsze, ale nie obsługuje zagnieżdżeń.

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
System tłumaczeń Laravela znajduje się w katalogu lang/ (Laravel 9+) lub resources/lang/ (Laravel 8 i starsze). Framework automatycznie wykrywa katalog. Jeśli istnieją oba, lang/ ma pierwszeństwo.
2

Skonfiguruj ustawienia językowe

Ustaw domyślny język aplikacji i język rezerwowy w config/app.php. Język rezerwowy jest używany, gdy w aktywnym języku brakuje klucza tłumaczenia. Skonfiguruj obsługiwane języki aplikacji i dodaj middleware wykrywający oraz ustawiający preferowany język użytkownika.

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

Używaj funkcji tłumaczeniowych

Laravel udostępnia trzy sposoby tłumaczenia tekstów: funkcję pomocniczą __() (zalecaną), funkcję trans() oraz dyrektywę Blade @lang. Wszystkie przyjmują klucz tłumaczenia i opcjonalne parametry zastępcze. Używaj __() w kodzie PHP i szablonach Blade, a @lang w Blade, gdy nie trzeba kodować 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',
    ],
];
W nowym kodzie wybieraj __() zamiast trans(). __() działa zarówno z plikami tłumaczeń PHP, jak i JSON, podczas gdy trans() obsługuje tylko pliki PHP. Dyrektywa @lang jest odpowiednikiem {'{ __() }'} w szablonach Blade, ale ma nieco prostszą składnię.
4

Obsłuż liczbę mnogą

Laravel używa składni form liczby mnogiej rozdzielonych pionową kreską. Najprostsza forma to 'apples' => 'There is one apple|There are many apples'. Dla jawnych zakresów użyj 'apples' => '{0} No apples|{1} One apple|[2,*] :count apples'. Funkcja pomocnicza trans_choice() lub Str::plural() wybiera właściwą formę na podstawie liczby.

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"
}
Wbudowana obsługa liczby mnogiej Laravela poprawnie rozpoznaje głównie proste reguły one/other. W językach ze złożonymi formami (arabski ma 6, rosyjski 4, a polski 3) trzeba zdefiniować wszystkie wymagane kategorie CLDR. Bez nich użytkownicy widzą tekst niepoprawny gramatycznie.
5

Dodaj łańcuchy rezerwowe

Wbudowany mechanizm rezerwowy Laravela przechodzi tylko z aktywnego języka do fallback_locale — bez etapu pośredniego. Użytkownik pt-BR z brakującym kluczem widzi angielski zamiast w pełni poprawnego tłumaczenia pt-PT. laravel-locale-chain rozwiązuje ten problem, głęboko scalając tłumaczenia z konfigurowalnego łańcucha rezerwowego podczas wczytywania.

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

Zautomatyzuj tłumaczenia

Po skonfigurowaniu i18n w Laravelu tłumacz pliki językowe za pomocą AI. Wskaż asystentowi AI plik języka źródłowego albo użyj CLI i18n Agent w pipeline CI/CD. Obsługiwane są pliki tłumaczeń 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
Tłumacz przyrostowo — po dodaniu nowych kluczy przetłumacz tylko różnicę zamiast ponownie generować wszystkie pliki. Pozwala to zachować tłumaczenia sprawdzone przez człowieka i uniknąć niepotrzebnych zmian.

Typowe pułapki

Logika liczby pojedynczej i mnogiej zapisana na stałe

Zapis $count == 1 ? 'item' : 'items' zamiast trans_choice() nie działa w językach, w których 0 jest liczbą pojedynczą (francuski), występują co najmniej 3 formy liczby mnogiej (rosyjski, polski) albo istnieje 6 form (arabski). Zawsze używaj składni liczby mnogiej Laravela i definiuj wszystkie wymagane formy.

Tłumaczenia JSON nie używają języka rezerwowego

fallback_locale Laravela działa tylko z plikami tłumaczeń PHP. Tłumaczenia JSON używają tekstu źródłowego jako klucza, dlatego brak tłumaczenia zwraca sam klucz (angielski tekst), zamiast szukać go w języku rezerwowym. Oznacza to, że tłumaczenia JSON nie mają prawdziwego mechanizmu rezerwowego. Użyj laravel-locale-chain, aby to naprawić.

Łączenie PHP i JSON bez znajomości pierwszeństwa

Gdy ten sam klucz istnieje w plikach PHP i JSON, pierwszeństwo ma PHP. Może to powodować mylące zachowanie, gdy aktualizacja pliku JSON nie przynosi efektu, ponieważ przesłania go plik PHP. Wybierz jeden format dla każdej przestrzeni nazw funkcji i używaj go konsekwentnie.

Wypróbuj i18n Agent

Upuść tutaj plik tłumaczenia

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

lub kliknij, aby go wybrać

Języki docelowe

Rejestracja nie jest wymaganaNatychmiastowa wycena

Najczęstsze pytania o Laravel i18n