Локализация в Laravel 10.x: Мультиязычные Приложения

Введение
Определение строк перевода
- Использование коротких ключей
- Использование строк перевода в качестве ключей
Получение строк перевода
- Замена параметров в строках перевода
- Множественное число
Переопределение языковых файлов пакета

Введение

Примечание По умолчанию структура приложения Laravel не включает в себя каталог lang. Если вы хотите настроить языковые файлы Laravel, вы можете опубликовать их с помощью команды Artisan lang:publish.

Функции локализации 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

Настройка локали

Язык по умолчанию для вашего приложения хранится в файле конфигурации config/app.php в опции конфигурации 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);
 
    // ...
});

Вы можете настроить "язык замены", который будет использоваться, когда активный язык не содержит заданной строки перевода. Как и язык по умолчанию, язык замены также настраивается в файле конфигурации config/app.php:

'fallback_locale' => 'en',

Определение текущей локали

Вы можете использовать методы currentLocale и isLocale фасада App для определения текущего языка или проверки, является ли язык заданным значением:

use Illuminate\Support\Facades\App;
 
$locale = App::currentLocale();
 
if (App::isLocale('en')) {
    // ...
}

Язык множественного числа

Вы можете указать "множитель" Laravel, который используется Eloquent и другими частями фреймворка для преобразования единственных строк во множественные строки, чтобы использовать язык, отличный от английского. Это можно сделать, вызвав метод useLanguage внутри метода boot одного из сервис-провайдеров вашего приложения. В настоящее время поддерживаемые языки множителя: french, norwegian-bokmal, portuguese, spanish и turkish:

use Illuminate\Support\Pluralizer;
 
/**
 * Загрузка любых служб приложения.
 */
public function boot(): void
{
    Pluralizer::useLanguage('spanish');
 
    // ...
}

Внимание Если вы настраиваете язык множителя, вы должны явно определить имена таблиц вашей модели Eloquent.

Определение строк перевода

Использование коротких ключей

Обычно строки перевода хранятся в файлах в каталоге lang. Внутри этого каталога должен быть подкаталог для каждого языка, поддерживаемого вашим приложением. Этот метод Laravel использует для управления строками перевода для встроенных функций 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".

Использование строк перевода в качестве ключей

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

По этой причине 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 для получения строки для заданного "count". В этом примере, поскольку count больше единицы, возвращается форма множественного числа строки перевода:

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. Внутри этого файла вы должны определить только строки перевода, которые вы хотите переопределить. Любые строки перевода, которые вы не переопределяете, по-прежнему будут загружены из оригинальных файлов языка пакета.