Функционал локализации Laravel предоставляют удобный способ извлечения строк разных языков, что позволяет легко поддерживать мультиязычность интерфейса вашего приложения.
Laravel предлагает два способа управления строками перевода. Во-первых, языковые строки могут храниться в файлах в каталоге lang. В этом каталоге могут быть подкаталоги для каждого языка, поддерживаемого приложением. Это подход, который Laravel использует для управления строками перевода собственного функционала, например сообщений об ошибках валидации:
/lang
/en
messages.php
/es
messages.php
Или строки перевода могут быть определены в файлах JSON, которые помещаются в каталог lang. При таком подходе каждый язык, поддерживаемый вашим приложением, будет иметь соответствующий файл JSON в этом каталоге. Этот подход рекомендуется для приложений с большим количеством переводимых строк:
/lang
en.json
es.json
Мы обсудим каждый подход по управлению строками перевода в этой документации.
Язык по умолчанию для вашего приложения хранится в параметре locale конфигурационного файла config/app.php. Вы можете изменить это значение в соответствии с потребностями вашего приложения.
Вы можете изменить язык по умолчанию для одного HTTP-запроса во время выполнения, используя метод setLocale фасада App:
use Illuminate\Support\Facades\App;
Route::get('/greeting/{locale}', function ($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;
/**
* Загрузка любых служб приложения.
*
* @return void
*/
public function boot()
{
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.
Для приложений с большим количеством переводимых строк определение каждой строки с помощью «короткого ключа» может сбивать с толку при обращении к ключам в ваших шаблонах, и постоянно изобретать ключи для каждой строки перевода, поддерживаемой вашим приложением, затруднительно.
По этой причине Laravel предлагает определение строк перевода с использованием переводимой строки в качестве ключа «по умолчанию». Файлы перевода, которые используют строки перевода в качестве ключей, хранятся как файлы JSON в каталоге lang. Например, если ваше приложение имеет испанский перевод, то вы должны создать файл lang/es.json:
{
"I love programming.": "Me encanta programar."
}Вы не должны определять строковые ключи перевода, которые конфликтуют с именами файлов перевода. Например, перевод __('Action') для языка NL при условии существования файла nl/action.php и отсутствии файла nl.json приведет к тому, что переводчик Laravel вернет содержимое всего файла 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
Плюрализация – сложная задача, поскольку разные языки имеют множество сложных правил плюрализации; однако 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. В этом файле вы должны определять только те строки перевода, которые хотите переопределить. Любые строки перевода, которые вы не меняете, все равно будут загружены из исходных языковых файлов пакета.