Skip to main content

Laravel i18n: повний посібник з інтернаціоналізації та локалізації

Від першого файлу локалі до розгортання у виробничому середовищі: налаштуйте систему перекладу Laravel, опрацюйте множину, виправте проблему резервної локалі для JSON і додайте розумні ланцюжки резервних локалей для регіональних варіантів.

1

Як працює система перекладу Laravel

Laravel має вбудовану систему перекладу, яка підтримує два формати файлів: масиви PHP і JSON. Файли PHP використовують вкладені ключі, упорядковані за функціональністю (auth.failed, validation.required). У файлах JSON ключем слугує вихідний рядок: це простіше, але вкладеність не підтримується.

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 використовує каталог lang/ у Laravel 9+ або resources/lang/ у Laravel 8 і попередніх версіях. Фреймворк автоматично визначає каталог. Якщо існують обидва, lang/ має пріоритет.
2

Налаштування локалі

Укажіть локаль за замовчуванням і резервну локаль Вашого застосунку у config/app.php. Резервна локаль використовується, коли в активній локалі немає ключа перекладу. Налаштуйте підтримувані локалі свого застосунку й додайте middleware для визначення та встановлення бажаної локалі користувача.

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

Використання функцій перекладу

Laravel надає три способи перекладу рядків: допоміжну функцію __(), яку рекомендовано використовувати, функцію trans() і директиву Blade @lang. Усі три приймають ключ перекладу та необов’язкові параметри заміни. Використовуйте __() у коді PHP і шаблонах Blade, а @lang — у Blade, коли не потрібно екранувати 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',
    ],
];
У новому коді віддавайте перевагу __() перед trans(). __() працює і з файлами перекладу PHP, і з JSON, тоді як trans() працює лише з файлами PHP. Директива @lang еквівалентна {'{ __() }'} у шаблонах Blade, але має дещо лаконічніший синтаксис.
4

Опрацювання множини

Laravel використовує розділений вертикальною рискою синтаксис форм множини. Найпростіший варіант: 'apples' => 'There is one apple|There are many apples'. Для явних діапазонів використовуйте 'apples' => '{0} No apples|{1} One apple|[2,*] :count apples'. Допоміжна функція trans_choice() або Str::plural() вибирає правильну форму відповідно до кількості.

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 правильно опрацьовує переважно лише прості правила one/other для більшості мов. Для мов зі складними формами множини — в арабській їх 6, у російській 4, а в польській 3 — потрібно визначити всі необхідні категорії множини CLDR. Інакше користувачі бачитимуть граматично неправильний текст.
5

Додавання ланцюжків резервних локалей

Вбудований резервний механізм Laravel переходить лише від активної локалі до fallback_locale — проміжного етапу немає. Якщо для користувача pt-BR відсутній ключ, він побачить англійський текст замість цілком придатного перекладу pt-PT. laravel-locale-chain розв’язує цю проблему, глибоко об’єднуючи переклади з налаштовуваного ланцюжка резервних локалей під час завантаження.

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

Автоматизація перекладу

Після завершення налаштування i18n у Laravel перекладіть свої файли локалей за допомогою ШІ. Укажіть своєму асистенту на основі ШІ файл вихідної локалі або використовуйте CLI i18n Agent у своєму pipeline CI/CD. Підтримуються файли перекладу як PHP, так і 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
Перекладайте поступово: додаючи нові ключі, перекладайте лише diff, а не створюйте всі файли заново. Так Ви збережете перевірені фахівцями переклади та уникнете зайвих змін.

Поширені помилки

Жорстко закодована логіка однини та множини

Вираз $count == 1 ? 'item' : 'items' замість trans_choice() не працює для мов, у яких 0 вважається одниною (французька), є 3+ форми множини (російська, польська) або 6 форм (арабська). Завжди використовуйте синтаксис множини Laravel і визначайте всі необхідні форми.

Для перекладів JSON не застосовується резервна локаль

Параметр Laravel fallback_locale працює лише для файлів перекладу PHP. Переклади JSON використовують вихідний рядок як ключ, тому за відсутності перекладу повертається сам ключ, тобто англійський текст, а не значення з резервної локалі. Отже, переклади JSON не мають справжнього механізму резервної локалі. Виправити це можна за допомогою laravel-locale-chain.

Поєднання PHP і JSON без урахування пріоритету

Коли той самий ключ є і у файлах PHP, і у файлах JSON, пріоритет має PHP. Це може спричинити незрозумілу поведінку: оновлення файлу JSON не дає результату, оскільки значення з файлу PHP його перекриває. Виберіть один формат для кожного простору імен функціональності та дотримуйтеся його.

Спробуйте i18n Agent зараз

Перетягніть сюди файл для перекладу

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

або натисніть, щоб вибрати

Цільові мови

Реєстрація не потрібнаМиттєвий розрахунок

Запитання про Laravel i18n