Локализация

Содержание...

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

Локализация приложений

Для отображения перевода строки слово на языке пользователя нужно в коде использовать следующие конструкции:

  • в PHP-файлах: _w('слово')
  • в шаблонах Smarty: [`слово`]

Если перевод строки слово не будет найден, система отобразит текст слово без перевода.

Файлы локализации gettext, содержащие переводы строк интерфейса на различные языки, необходимо размещать в файловой структуре приложения по следующему правилу: wa-apps/[APP_ID]/locale/[ЛОКАЛЬ]/LC_MESSAGES/[APP_ID].po. Например, файл с переводом строк на русский язык для приложения с идентификатором blog должен располагаться по адресу wa-apps/blog/locale/ru_RU/LC_MESSAGES/blog.po.

Файл с расширением имени .po — это текстовый файл специального формата, содержащий перевод строк для конкретной языковой локали. Для подключения перевода из .po-файла, его необходимо скомпилировать в файл с расширением .mo, например, с помощью программы poEdit.

Пример содержимого .po-файла с переводом строк на русский язык:

msgid ""
msgstr ""
"Project-Id-Version: Guestbook\n"
"POT-Creation-Date: \n"
"PO-Revision-Date: 2011-04-27 10:30+0300\n"
"Last-Translator: \n"
"Language-Team: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=3; plural=((((n%10)==1)&&((n%100)!=11))?(0):(((((n%10)>=2)&&
((n%10)<=4))&&(((n%100)<10)||((n%100)>=20)))?(1):2));\n"
"X-Poedit-Language: Russian\n"
"X-Poedit-Country: Russian Federation\n"
"X-Poedit-SourceCharset: utf-8\n"
"X-Poedit-Basepath: .\n"
"X-Poedit-SearchPath-0: .\n"
"X-Poedit-SearchPath-1: .\n"

msgid "Name"
msgstr "Имя"

msgid "Message"
msgstr "Сообщение"

msgid "post"
msgid_plural "posts"
msgstr[0] "запись"
msgstr[1] "записи"
msgstr[2] "записей"

Пары «ключ—перевод»

Ключ и его перевод представлены в .po-файле двумя последовательными строками следующего вида:

msgid "Name"
msgstr "Имя"
  • msgid — это ключ строки локализации, который используется в коде приложения (PHP или Smarty)
  • msgstr — перевод строки

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

Множественные формы строк локализации

Множественные формы перевода позволяют легко отображать в приложении слова в нужной форме, например: 21 запись, 22 записи, 25 записей.

Следующая строка в заголовках .po-файла указывает, что в русском языке есть три множественные формы (как в примере выше) и задаёт формулу, по которой определяется нужная форма слова для любого целого числа:

"Plural-Forms: nplurals=3; plural=((((n%10)==1)&&((n%100)!=11))?(0):(((((n%10)>=2)&&
((n%10)<=4))&&(((n%100)<10)||((n%100)>=20)))?(1):2));\n"

Пример перевода множественной формы в .po-файле:

msgid "post"
msgid_plural "posts"
msgstr[0] "запись"
msgstr[1] "записи"
msgstr[2] "записей"

Для получения нужной формы слова в PHP-коде нужно использовать следующую конструкцию:

// вернёт значение запись, записи либо записей в зависимости от значения $n согласно формуле в .po-файле
_w('post', 'posts', $n);

Аналогичная конструкция для шаблонов Smarty:

{_w('post', 'posts', $n)}

Обратите внимание на отличие этой конструкций от синтаксиса перевода обычных (немножественных) форм, используемых в Smarty. Для немножественных переводов рекомендуется использовать в шаблонах Smarty конструкцию вида [`строка`].

Функция _w() умеет также автоматически заменять в переводе подстроку %d на значение $n средствами PHP-функции sprintf, например:

_w('%d file', '%d files', 21); // 21 файл
_w('%d file', '%d files', 22); // 22 файла
_w('%d file', '%d files', 25); // 25 файлов

Автоматическая сборка .po-файла

Фреймворк позволяет автоматически выполнять анализ всего кода приложения, собирать используемые в нём ключи локализации и дописывать отсутствующие ключи в .po-файл. Если сам .po-файл отсутствует, то он создается автоматически. Для запуска скрипта автоматической сборки .po-файла выполните следующую команду в терминале командной строки:

  • UNIX/Linux/FreeBSD:

    php wa.php locale [app_id]
  • Windows:

    php.exe wa.php locale [app_id]
Пример
php wa.php locale myapp

Автоматическая сборка .po-файлов плагинов, виджетов и тем дизайна выполняется аналогично:

php wa.php locale [app_id]/plugins/[plugin_id]
php wa.php locale [app_id]/widgets/[widget_id]
php wa.php locale [app_id]/themes/[theme_id]
Примеры
php wa.php locale someapp/plugins/myplugin
php wa.php locale someapp/widgets/mywidget
php wa.php locale someapp/themes/mytheme

Сборка файлов локализации в режиме отладки

Сборщик файлов локализации умеет добавлять в .po-файл комментарии с путями к тем файлам продукта, в которых были найдены ключи локализации.

Пример
#: /wa-apps/myapp/templates/actions/info.html:38
msgid "Company"
msgstr ""

Такой комментарий показывает, что ключ локализации был найден сборщиком на 38-й строке указанного файла. Если вы сомневаетесь, как лучше перевести строку локализации, можно подсмотреть логику файла, в котором она используется.

Чтобы добавить в .po-файл такие комментарии, запустите команду сборщика с параметром --debug.

Пример
php wa.php locale myapp --debug

После перевода строк в .po-файле снова запустите сборщик локализации — без ключа --debug. Вызов сборщика без дополнительного ключа удалит из .po-файла лишние комментарии и уменьшит размер файла, который должен быть включён в дистрибутив продукта.

Локализация плагинов приложений

Для локализации плагинов с помощью собственных файлов локализации в PHP-коде вместо функции _w() следует использовать функцию _wp().

Файлы локализации плагинов приложений, так же как и для приложений, должны размещаться в locale/[ЛОКАЛЬ]/LC_MESSAGES/ (в поддиректории плагина) и именоваться по правилу [app_id]_[plugin_id].po и [app_id]_[plugin_id].mo. Например, .po-файл локализации для русского языка некоторого плагина с идентификатором some приложения shop должен находиться по адресу wa-apps/shop/plugins/some/locale/ru_RU/LC_MESSAGES/shop_some.po (.mo-файл должен находиться в этой же директории).

Локализация тем дизайна

Темы дизайна поддерживают 2 способа локализации текстовых строк:

  • в файле-манифесте theme.xml;
  • с использованием gettext.

Локализация темы дизайна в манифесте theme.xml

Такой способ локализации традиционно использовался в темах дизайна. Для локализации темы дизайна этим способом нужно добавить в корневой XML-элемент манифеста вложенный элемент <locales></locales> по следующему примеру:

<locales>
    <locale>
        <msgid>String key</msgid>
        <msgstr locale="ru_RU">Перевод строки</msgstr>
    </locale>
    <locale>
        <msgid>Another string key</msgid>
        <msgstr locale="ru_RU">Перевод другой строки</msgstr>
    </locale>
</locales>

Ключи локализации в шаблонах темы дизайна нужно указывать в виде

[`String key`]

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

Локализация темы дизайна с использованием gettext

Файлы локализации темы дизайна при использовании gettext размещаются в директориях вида wa-apps/[app_id]/themes/[theme_id]/locale/[locale_id]/LC_MESSAGES/[app_id]_[theme_id].po. Для быстрого создания файлов локализации удобно использовать команду автоматического сборщика.

При использовании этого способа ключи локализации в единственном числе нужно указывать в шаблонах точно так же:

[`String key`]

А формы множественного числа в шаблоны дизайна нужно добавлять в формате

{_wp('%d product', '%d products', $n)}

Локализация системных плагинов

В именах файлов локализации системных плагинов, размещаемых в директории wa-plugins/, в качестве префикса имени следует использовать идентификаторы payment_, shipping_, sms_ — в зависимости от имени поддиректории, в которой размещается системный плагин. Пример .po-файла локализации для русского языка некоторого платежного плагина с идентификатором some: wa-plugins/payment/some/locale/ru_RU/LC_MESSAGES/payment_some.po

Чтобы подключить строки локализации системного плагина в его исходном коде, используйте публичный метод _w() базового класса waSystemPlugin, как показано ниже:

  • В PHP-коде

    $this->_w('name')
  • В HTML-шаблонах

    {$p->_w('name')}

Разработка продукта, предназначенного для использования только на одном языке

Если ваш продукт (приложение или плагин) гарантированно предназначен для использования только на одном языке, использовать механизм локализации нет необходимости. В таком случае все строки локализации пишите в исходном коде продукта непосредственно на том языке, на котором им будут пользоваться. Конструкции _w(), _wp() и [``] в этом случае использовать не нужно.