Подписывайтесь на наш Telegram канал и будьте в курсе всех событий.
Будьте в курсе последних новостей!
Будьте в курсе последних новостей!

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

Введение

Функционал локализации 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. В этом файле вы должны определять только те строки перевода, которые хотите переопределить. Любые строки перевода, которые вы не меняете, все равно будут загружены из исходных языковых файлов пакета.