FFCMS Wiki

Официальная документация разработчика и администратора

Инструменты пользователя

Инструменты сайта


i18n

Интернализация (i18n)

FFCMS поддерживает один из современных алгоритмов локализации сайтов для различных языков. При помощи методов алгоритма интернализации вы можете быстро разработать те или иные представления и сообщения, отображаемые на сайте на различных языках.

Стандартные файлы интернализации

Все файлы с переводами хранятся в директории /I18n/ в зависимости от используемого интерфейса и языка перевода. К примеру, переводы используемые в рамках интерфейса Front для языка ru и запросом к контроллеру User должны быть расположены в /I18n/Front/ru/User.php.

Все стандартные интернализации загружаются автоматически при вызове одноименного контроллера, как показано выше в примере. Переводы содержащиеся в Default.php загружаются всегда, вместе с переводами для текущего контроллера.

В файлах интернализации переводы хранятся в формате массива вида ключ ⇒ значение, где в виде ключа используется оригинальный текст (на английском языке), а в качестве значения - перевод для текущей языковой локали. Пример файла интернализации для русского языка:

<?php
return [
    'Hello world' => 'Привет мир',
    'Hello %name%' => 'Привет, %name%'
]

Использование в шаблонах, моделях, контроллерах

Переводы, хранящиеся в файлах интернализации предназначены для использования в теле представлений, контроллеров и моделей. Наиболее часто переводы используются в представлениях, для отображения текстового содержимого шаблона на различных языках. Реже, переводы могут использоваться в контроллерах, для отображения коротких уведомлений, нотификаций, ответов json api и других сообщений пользователю. Еще реже переводы будут использоваться в теле моделей, если они применяются правильно и реализуют только бизнес логику приложения.

Для использования переводов в шаблонах и контроллерах существует специальный сокращенный синтаксис. Перевод может быть отображен при помощи функции:

echo __('Source text');

Рассмотрим пример контроллера, в котором рендерится отображение представления:

class Demo extends FrontController
{
    public function actionIndex()
    {
        return $this->view->render('demo/index');
    }
}

В свою очередь, шаблон default/demo/index.php содержит следующую разметку:

<h1><?= __('Hello guest!') ?></h1>
<hr />
<p><?= __('Your ip is: %ip%. Glad to see you!', ['ip' => App::$Request->getClientIp()) ?></p>

Как вы заметили, в данном шаблоне дважды используется выше описанная функция отображения интернализации. Для данного контроллера, Demo, в рамках интерфейса Front для языка ru автоматически будет использоваться файл интернализации: /I18n/Front/ru/Demo.php. Для отображения русского перевода данный файл должен содержать:

<?php
 
return [
    'Hello guest!' => 'Привет, гость!',
    'Your ip is: %ip%. Glad to see you!' => 'Твой ip: %ip%. Рады видеть тебя!'
];

Как вы заметили, первый вызов лишь переводит одну строку в другую (английский ⇒ русский), а второй вызов содержит в себе обработку динамического параметра %ip%. Параметрические запросы будут рассмотрены ниже.

Кроме сокращенного синтаксиса вызова, рассмотренного выше, существует и вариант расширенного вызова функции интернализации. Расширенный вызов доступен черед единую точку доступа App:

echo App::$Translate->get('Index', 'text', $params);

При использовании расширенного синтаксиса у вас будет возможность указать используемый файл индекса перевода вручную. Таким образом можно использовать индексы интернализации не принадлежащее текущему контроллеру. Если обратиться к примеру выше вы можете использовать переводы, к примеру, из файла /I18n/Front/ru/OtherDemo.php:

<?= App::$Translate->get('OtherDemo', 'Other text to translate') ?>

Синтаксис параметрических переводов

Система интернализации в ffcms поддерживает параметризацию языковых строк. Выше было показано, что языковая строка может содержать некоторые параметры в файле интернализации:

return [
    'String contains %var1% and %var2%' => 'Строка содержит %var1% и %var2%'
];

В данном примере в строке перевода содержится 2 параметра: var1 и var2. Параметры обрамлены с обеих сторон символом %. В дальнейшем вы сможете назначить значения данным параметрам при вызове метода отображения перевода:

<?= __('String contains %var1% and %var2%', [
    'var1' => 'Variable#1',
    'var2' => 'Variable#2'
]) ?>

Строка перевода может содержать бесконечное множество параметров. В случае, если параметр не передан в массиве аргументов он примет значение null.

Расширенный вызов интернализаций

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

При использовании системы интернализации для текстовых вставок разрабатываемого вами шаблона, чтобы не загромождать глобальные файлы переводов, расположенные в /I18n/* можно расположить файлы интернализации внутри вашего шаблона. К примеру, чтобы глобально загрузить файл интернализаций для вашего шаблона для языка ru необходимо использовать файл: /Apps/View/Front/ваш_шаблон/I18n/ru.php с синтаксисом, аналогичным стандартным файлам интернализации.

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

$text = App::$Translate->get('Index', 'text', $params);

в противном случае, модель может некорректно распознать индекс интернализации при инициации из разных контроллеров.

В качестве параметров при вызове метода интернализации может быть передан в том числе html синтаксис. Такой подход не является лучшей практикой, однако бывает крайне необходим. Пример:

<?= __('Hello, %name%', ['name' => '<b>bob</b>']) ?>

Индекс (файл) интернализации не всегда может быть загружен, в случае реализации пакетов расширений по средствам composer. В таком случае вам необходимо будет принудительно выгрузить какой-либо сторонний файл интернализации. Допустим, что у нас имеется файл интернализации в директории /some/dir/ru/translate.php и нам необходимо его загрузить для всех представлений, вызываемых из контроллера Demo. Сделать это можно при помощи вызова метода App::$Translate→append():

use Ffcms\Core\App;
 
class Demo extens FrontAppController
{
    public function before()
    {
        $file = root . '/some/dir/' . App::$Request->getLanguage() . '/translate.php';
        if (App::$Request->getLanguage() !== 'en' && File::exist($file)) {
            App::$Translate->append($file);
        } 
    }
}

если эта интернализация должна быть применена для всех приложений сайта, можно использовать крючек на загрузочном методе static boot().

i18n.txt · Последние изменения: 2017/01/02 16:00 (внешнее изменение)