Локализация

Вступление

Функции локализации Laravel обеспечивают удобный способ получения строк на различных языках, позволяя легко поддерживать несколько языков в приложении. Языковые строки хранятся в файлах в каталоге resources/lang. Внутри этого каталога должен быть подкаталог для каждого языка, поддерживаемого приложением:

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

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

<?php

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

Для языков, различающихся по территории, следует называть языковые каталоги в соответствии с ISO 15897. Например, для британского английского языка следует использовать "en_GB", а не "en-gb".

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

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

Route::get('welcome/{locale}', function ($locale) {
    if (! in_array($locale, ['en', 'es', 'fr'])) {
        abort(400);
    }

    App::setLocale($locale);

    //
});

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

'fallback_locale' => 'en',

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

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

$locale = App::getLocale();

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

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

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

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

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

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

<?php

// resources/lang/en/messages.php

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

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

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

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

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

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

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

echo __('messages.welcome');

echo __('I love programming.');

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

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

@lang('messages.welcome')

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

Директива @lang не экранирует вывод. При использовании этой директивы вы несете полную ответственность за экранирование собственных выходных данных.

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

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

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

Для замены плейсхолдеров при получении строки перевода передайте массив замен в качестве второго аргумента в функцию __:

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

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

'welcome' => 'Welcome, :NAME', // Welcome, DAYLE
'goodbye' => 'Goodbye, :Name', // Goodbye, Dayle

Плюрализация

Плюрализация — это сложная проблема, так как разные языки имеют множество сложных правил для множественного числа. Используя символ "|", можно различать единственную и множественную формы строк:

'apples' => 'There is one apple|There are many apples',

Можно создавать более сложные правила множественного числа, которые задают строки перевода для множества числовых диапазонов:

'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',

Переопределение языковых файлов пакета

Некоторые пакеты могут поставляться с собственными языковыми файлами. Вместо того, чтобы изменять основные файлы пакета, чтобы подкорректировать эти строки, вы можете переопределить их, поместив файлы в каталог resources/lang/vendor/{package}/{locale}.

Так, например, если вам нужно переопределить строки английского перевода в messages.php для пакета с именем skyrim/hearthfire, вы должны поместить языковой файл в resources/lang/vendor/hearthfire/en/messages.php. В этом файле вы должны определить только те строки перевода, которые вы хотите переопределить. Любые строки перевода, которые вы не переопределите, будут загружены из оригинальных языковых файлов пакета.