Локализация

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

#Введение

Возможности локализации 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. Вы можете изменить это значение в соответствии с требованиями вашего приложения.

Вы можете изменить язык по умолчанию для одного 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);

    // ...
});

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

'fallback_locale' => 'en',

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

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

use Illuminate\Support\Facades\App;

$locale = App::currentLocale();

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

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

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

use Illuminate\Support\Pluralizer;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Pluralizer::useLanguage('spanish');

    // ...
}

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

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

Обычно строки перевода хранятся в файлах внутри директории lang. В этой директории должна быть поддиректория для каждого языка, поддерживаемого вашим приложением. Такой подход используется Laravel для управления строками перевода встроенных функций, например, сообщений об ошибках валидации:

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

Все языковые файлы возвращают массив с ключами и строками. Например:

<?php

// lang/en/messages.php

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

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

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

По этой причине 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;

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