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

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

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

Использование ключей локализации других приложений

Если в вашем продукте (приложении, плагине или виджете) нужно использовать перевод, заданный в файлах локализации другого приложения, вызывайте функцию _wd(), как показано в примере:

_wd('other_app_id', 'Some string key');
// Пример для приложения Shop-Script
// _wd('shop', 'Orders');

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

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