Skip to content
Laravel
Icon

ПРЕДУПРЕЖДЕНИЕ Вы просматриваете документацию к старой версии Laravel. Рассмотрите возможность обновления Вашего проекта до Laravel 9.x.

Локализация

Введение

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

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

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

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

<?php
 
// resources/lang/en/messages.php
 
return [
    'welcome' => 'Welcome to our application!',
];

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