Локалізація

• Вступ
  • Публікація мовних файлів
  • Налаштування локалі
  • Мовна Плюралізація
• Визначення рядків перекладу
  • Використання коротких ключів
  • Використання рядків перекладу як ключів
• Отримання рядків перекладу
  • Заміна параметрів у рядках перекладу
  • Плюралізація
• Перевизначення мовних файлів пакета

Вступ

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

Laravel надає два способи керування рядками перекладу. По-перше, мовні рядки можуть зберігатися у файлах в директорії lang застосунку. У цій директорії можуть бути піддиректорії для кожної мови, яку підтримує застосунок. Це підхід, який Laravel використовує для керування рядками перекладу для вбудованих функцій 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

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

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

Ви також можете налаштувати "резервну мову", яка буде використовуватися, коли мова за замовчуванням не містить певного рядка перекладу. Як і мова за замовчуванням, резервна мова також налаштовується у конфігураційному файлі 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 одного з сервіс-провайдерів вашого застосунку. На даний момент "pluralizer" підтримує такі мови: french, norwegian-bokmal, portuguese, spanish та turkish:

use Illuminate\Support\Pluralizer;
 
/**
 * Ініціалізувати будь-які сервіси застосунку.
 */
public function boot(): void
{
    Pluralizer::useLanguage('spanish');
 
    // ...
}

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

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

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

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

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

<?php
 
// lang/en/messages.php
 
return [
    'welcome' => 'Ласкаво просимо до нашого застосунку!',
];

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

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

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

{
    "I love programming.": "Я люблю програмування."
}

Ключові / Файлові Конфлікти

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

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

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

echo __('messages.welcome');

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

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

echo __('Я люблю програмування.');

Знову ж таки, якщо рядок перекладу не існує, функція __ поверне ключ рядка перекладу, який їй було надано.

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

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

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

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

'welcome' => 'Привіт, :name',

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

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

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

'welcome' => 'Привіт, :NAME', // Привіт, DAYLE
'goodbye' => 'Бувай, :Name', // Бувай, 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": "Є одне яблуко | Є багато яблук"
}

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

'apples' => '{0} Немає жодного|[1,19] Є кілька|[20,*] Є багато',

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

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

Ви також можете визначити атрибути-заповнювачі в рядках множини. Ці заповнювачі можуть бути замінені шляхом передачі масиву як третього аргументу у функцію trans_choice:

'minutes_ago' => '{1} :value хвилину тому|[2,*] :value хвилини тому',
 
echo trans_choice('time.minutes_ago', 5, ['value' => 5]);

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

'apples' => '{0} Немає|{1} Є один|[2,*] Є така кількість:count',

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

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

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