Локалізація · Laravel

Вступ

Примітка За замовчуванням скелет застосунку Laravel не містить теки lang. Якщо ви хочете налаштувати мовні файли Laravel під себе, опублікуйте їх Artisan-командою lang:publish.

Засоби локалізації Laravel дають зручний спосіб отримувати рядки різними мовами, тож підтримати кілька мов у застосунку нескладно.

Laravel пропонує два способи керувати рядками перекладу. Перший: мовні рядки зберігаються у файлах усередині теки lang. Усередині цієї теки можуть бути підтеки для кожної мови, яку підтримує застосунок. Саме так Laravel керує рядками перекладу для вбудованих можливостей фреймворку, як-от повідомлення про помилки валідації:

/lang
    /en
        messages.php
    /es
        messages.php

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

/lang
    en.json
    es.json

Обидва підходи до керування рядками перекладу розглянуто в цій документації.

Публікація мовних файлів

За замовчуванням скелет застосунку Laravel не містить теки lang. Якщо ви хочете змінити мовні файли Laravel або створити власні, згенеруйте теку lang Artisan-командою lang:publish. Команда lang:publish створить теку lang у вашому застосунку й опублікує стандартний набір мовних файлів, які використовує Laravel:

php artisan lang:publish

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

Мова застосунку за замовчуванням зберігається у файлі конфігурації config/app.php в опції locale, яку зазвичай задають через змінну середовища APP_LOCALE. Ви можете змінити це значення відповідно до потреб вашого застосунку.

Також можна налаштувати «резервну мову» (fallback language), яку буде використано, коли основна мова не містить потрібного рядка перекладу. Як і мова за замовчуванням, резервна мова налаштовується у файлі конфігурації config/app.php, а її значення зазвичай задається змінною середовища APP_FALLBACK_LOCALE.

Змінити мову за замовчуванням для окремого HTTP-запиту під час виконання можна методом setLocale фасаду App:

use Illuminate\Support\Facades\App;

Route::get('/greeting/{locale}', function (string $locale) {
    if (! in_array($locale, ['en', 'es', 'fr'])) {
        abort(400);
    }

    App::setLocale($locale);

    // ...
});

Визначення поточної локалі

Методи currentLocale та isLocale фасаду App дозволяють дізнатися поточну локаль або перевірити, чи вона має задане значення:

use Illuminate\Support\Facades\App;

$locale = App::currentLocale();

if (App::isLocale('en')) {
    // ...
}

Мова для множини

Ви можете вказати «плюралізатору» (pluralizer) Laravel, який Eloquent та інші частини фреймворку використовують для перетворення рядків з однини в множину, працювати з мовою, відмінною від англійської. Для цього викличте метод useLanguage у методі boot одного з сервіс-провайдерів вашого застосунку. Наразі плюралізатор підтримує такі мови: french, norwegian-bokmal, portuguese, spanish і turkish:

use Illuminate\Support\Pluralizer;

/**
 * Ініціалізація сервісів застосунку.
 */
public function boot(): void
{
    Pluralizer::useLanguage('spanish');

    // ...
}

Увага Якщо ви змінюєте мову плюралізатора, вам слід явно визначити назви таблиць для ваших моделей Eloquent.

Визначення рядків перекладу

Використання коротких ключів

Зазвичай рядки перекладу зберігаються у файлах усередині теки lang. У цій теці має бути підтека для кожної мови, яку підтримує застосунок. Саме так Laravel керує рядками перекладу для вбудованих можливостей фреймворку, як-от повідомлення про помилки валідації:

/lang
    /en
        messages.php
    /es
        messages.php

Усі мовні файли повертають масив рядків із ключами. Наприклад:

<?php

// lang/en/messages.php

return [
    'welcome' => 'Welcome to our application!',
];

Увага Для мов, які різняться за територією, теки слід називати згідно з ISO 15897. Наприклад, для британської англійської треба використовувати «en_GB», а не «en-gb».

Використання рядків перекладу як ключів

У застосунках із великою кількістю рядків для перекладу визначення кожного рядка через «короткий ключ» швидко заплутує: у представленнях (view) незрозуміло, на що саме посилається ключ, а вигадувати нові ключі для кожного рядка перекладу втомливо.

Тому Laravel також підтримує визначення рядків перекладу, де ключем виступає «типовий» переклад самого рядка. Мовні файли, що використовують рядки перекладу як ключі, зберігаються у форматі JSON у теці lang. Наприклад, якщо ваш застосунок має іспанський переклад, створіть файл lang/es.json:

{
    "I love programming.": "Me encanta programar."
}

Конфлікти ключа та файлу

Не варто визначати ключі рядків перекладу, що конфліктують з іменами інших файлів перекладу. Наприклад, переклад __('Action') для локалі «NL» за умови, що файл nl/action.php існує, а файлу nl.json немає, призведе до того, що транслятор поверне весь вміст nl/action.php.

Отримання рядків перекладу

Отримувати рядки перекладу з мовних файлів можна функцією-хелпером __. Якщо ви визначаєте рядки перекладу через «короткі ключі», передайте у функцію __ файл, що містить ключ, і сам ключ, використовуючи «крапкову» нотацію. Наприклад, отримаємо рядок перекладу welcome із мовного файлу lang/en/messages.php:

echo __('messages.welcome');

Якщо вказаного рядка перекладу не існує, функція __ поверне ключ рядка перекладу. Тобто в прикладі вище функція __ поверне messages.welcome, якщо рядка перекладу немає.

Якщо ви використовуєте типові рядки перекладу як ключі, передавайте у функцію __ типовий переклад вашого рядка:

echo __('I love programming.');

І знову: якщо рядка перекладу не існує, функція __ поверне переданий їй ключ рядка перекладу.

Якщо ви користуєтеся шаблонізатором Blade, для виведення рядка перекладу можна застосувати синтаксис {{ }}:

{{ __('messages.welcome') }}

Заміна параметрів у рядках перекладу

За бажання в рядках перекладу можна визначати плейсхолдери. Усі плейсхолдери починаються з :. Наприклад, можна визначити привітання з плейсхолдером імені:

'welcome' => 'Welcome, :name',

Щоб замінити плейсхолдери під час отримання рядка перекладу, передайте масив замін другим аргументом функції __:

echo __('messages.welcome', ['name' => 'dayle']);

Якщо плейсхолдер записаний повністю великими літерами або лише з великої першої літери, перекладене значення буде відформатовано відповідно:

'welcome' => 'Welcome, :NAME', // Welcome, DAYLE
'goodbye' => 'Goodbye, :Name', // Goodbye, Dayle

Форматування підстановки обʼєктів

Якщо ви спробуєте передати обʼєкт як плейсхолдер перекладу, буде викликано метод __toString цього обʼєкта. Метод __toString - один із вбудованих «магічних методів» PHP. Втім, іноді ви не контролюєте метод __toString певного класу, наприклад коли клас, з яким ви працюєте, належить сторонній бібліотеці.

У таких випадках Laravel дозволяє зареєструвати власний обробник форматування для конкретного типу обʼєктів. Для цього викличте метод stringable транслятора. Метод stringable приймає замикання, у якому слід вказати тип обʼєкта, за форматування якого воно відповідає. Зазвичай метод stringable викликають у методі boot класу AppServiceProvider вашого застосунку:

use Illuminate\Support\Facades\Lang;
use Money\Money;

/**
 * Ініціалізація сервісів застосунку.
 */
public function boot(): void
{
    Lang::stringable(function (Money $money) {
        return $money->formatTo('en_GB');
    });
}

Множина

Утворення множини - складна задача, бо різні мови мають розмаїті й непрості правила; однак Laravel допоможе перекладати рядки по-різному залежно від правил, які ви визначите. За допомогою символу | можна розділити форму однини й множини рядка:

'apples' => 'There is one apple|There are many apples',

Звісно, множина підтримується й тоді, коли ви використовуєте рядки перекладу як ключі:

{
    "There is one apple|There are many apples": "Hay una manzana|Hay muchas manzanas"
}

Можна створювати й складніші правила множини, які задають рядки перекладу для кількох діапазонів значень:

'apples' => '{0} There are none|[1,19] There are some|[20,*] There are many',

Визначивши рядок перекладу з варіантами множини, ви можете скористатися функцією trans_choice, щоб отримати рядок для заданої «кількості». У цьому прикладі кількість більша за одиницю, тож повертається форма множини:

echo trans_choice('messages.apples', 10);

У рядках із множиною також можна визначати плейсхолдери-атрибути. Замінити їх можна, передавши масив третім аргументом функції trans_choice:

'minutes_ago' => '{1} :value minute ago|[2,*] :value minutes ago',

echo trans_choice('time.minutes_ago', 5, ['value' => 5]);

Якщо потрібно вивести ціле число, передане у функцію trans_choice, скористайтеся вбудованим плейсхолдером :count:

'apples' => '{0} There are none|{1} There is one|[2,*] There are :count',

Перевизначення мовних файлів пакета

Деякі пакети постачаються з власними мовними файлами. Замість того щоб правити основні файли пакета заради зміни цих рядків, ви можете перевизначити їх, розмістивши файли в теці lang/vendor/{package}/{locale}.

Наприклад, якщо потрібно перевизначити англійські рядки перекладу у файлі messages.php для пакета skyrim/hearthfire, розмістіть мовний файл за шляхом: lang/vendor/hearthfire/en/messages.php. У цьому файлі слід визначити лише ті рядки перекладу, які ви хочете перевизначити. Усі рядки, які ви не перевизначили, як і раніше завантажуватимуться з оригінальних мовних файлів пакета.