Локализация

Во фреймворке имеется встроенная поддержка мультиязычных веб-приложений. Механизм локализации использует 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-system/locale/locale.php {APP_ID}

• Windows:

  php.exe wa-system/locale/locale.php {APP_ID}

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