Локализация интерфейса

Введение

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

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

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

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

/resources
    /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')) {
    //
}

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

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

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

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

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

<?php

// resources/lang/en/messages.php

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

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

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

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

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

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

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

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

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

Вы можете получить строки перевода из ваших языковых файлов с помощью глобального помощника __. Если вы используете «короткие ключи» для определения ваших строк перевода, то вы должны передать файл, содержащий ключ, и сам ключ в функцию __, используя «точечную нотацию». Например, давайте извлечем строку перевода welcome из языкового файла resources/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',

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

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

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