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

Введение

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

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

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

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

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

/lang
    en.json
    es.json

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

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

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

php artisan lang:publish

Конфигурирование языка по умолчанию

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

Вы можете изменить язык по умолчанию для одного 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);

    // ...
});

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

/**
 * Загрузка сервисов приложения.
 */
public function boot(): void
{
    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 автоматически вызывает метод __toString этого объекта. Метод __toString является одним из встроенных “магических” методов в PHP. Однако бывают случаи, когда у вас нет контроля над методом __toString определенного класса, особенно если это класс сторонней библиотеки.

В таких ситуациях Laravel предоставляет возможность зарегистрировать пользовательский обработчик форматирования для конкретного типа объекта. Для этого используется метод stringable фасада Lang. Метод stringable принимает замыкание, которое должно указать тип объекта, для которого выполняется форматирование. Обычно вызов метода stringable выполняется в методе boot класса AppServiceProvider вашего приложения:

use Illuminate\Support\Facades\Lang;
use Money\Money;

/**
 * Настройка служб приложения.
 */
public function boot(): void
{
    Lang::stringable(function (Money $money) {
        return $money->formatTo('en_GB');
    });
}

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

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