Локализация

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

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

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

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

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

Файлы локализации 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 "Имя"

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

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

Множественные формы перевода позволяют легко отображать в приложении слова в нужной форме, например: 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-файла выполните следующую команду в терминале командной строки:

Пример

php wa-system/locale/locale.php myapp

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

php wa-system/locale/locale.php [APP_ID]/plugins/[PLUGIN_ID]

Пример

php wa-system/locale/locale.php myapp/plugins/some

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

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

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

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

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

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

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

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