4.12. Локализация

• 1. Введение
  • 1.1. Публикация языковых файлов
  • 1.2. Настройка локали
  • 1.3. Язык множественного числа
• 2. Определение строк перевода
  • 2.1. Использование коротких ключей
  • 2.2. Использование строк перевода в качестве ключей
• 3. Получение строк перевода
  • 3.1. Замена параметров в строках перевода
  • Pluralization
• Overriding Package Language Files

1. Введение

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

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

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

Или же строки перевода могут быть определены в JSON-файлах, размещённых в директории lang. При использовании этого подхода для каждого языка, поддерживаемого вашим приложением, в этой директории должен быть соответствующий JSON-файл. Этот подход рекомендуется для приложений с большим количеством переводимых строк:

/lang
    en.json
    es.json

В этой документации мы рассмотрим каждый из подходов к управлению строками перевода.

1.1. Публикация языковых файлов

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

php artisan lang:publish

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

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

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

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

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

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

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

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

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

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

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

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

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

<?php
 
// lang/en/messages.php
 
return [
    'welcome' => 'Welcome to our application!',
];

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

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

По этой причине Laravel также поддерживает определение строк перевода с использованием "значения по умолчанию" строки в качестве ключа. Языковые файлы, которые используют строки перевода в качестве ключей, хранятся в виде JSON-файлов в директории lang. Например, если в вашем приложении есть перевод на испанский язык, вам следует создать файл lang/es.json:

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

Конфликты ключей и файлов

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

3. Получение строк перевода

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

echo __('messages.welcome');

Если указанная строка перевода не существует, функция __ вернёт ключ строки перевода. Таким образом, в приведённом выше примере функция __ вернёт messages.welcome, если строка перевода отсутствует.

Если вы используете строки перевода по умолчанию в качестве ключей перевода, вам следует передать значение перевода по умолчанию в функцию __;

echo __('I love programming.');

Если строка перевода снова не будет найдена, функция __ вернёт переданный ей ключ строки перевода.

Если вы используете шаблонизатор Blade, вы можете использовать синтаксис вывода {{ }} для отображения строки перевода:

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

3.1. Замена параметров в строках перевода

При необходимости вы можете определить плейсхолдеры в своих строках перевода. Все плейсхолдеры начинаются с префикса :. Например, вы можете определить приветственное сообщение с плейсхолдером для имени:

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

Чтобы заменить плейсхолдеры при получении строки перевода, вы можете передать массив замен в качестве второго аргумента функции __: