Фремворк Limb

Эта страница только для чтения. Вы можете посмотреть её исходный текст, но не можете его изменить. Сообщите администратору, если считаете, что это неправильно.
===== Добавление локализации в свой проект =====

1) В проекте создаем директорию i18n/translations

2) Копируем в нее файлы *.ts из пакетов, в которые предполагается вносить изменения, касающиеся локализации (validation.en_US.ts, validation.ru_RU.ts, cms.en_US.ts, cms.ru_RU.ts)

3) Создаем файлы (НАЗВАНИЕ_ПРОЕКТА.ru_RU.ts, НАЗВАНИЕ_ПРОЕКТА.en_US.ts) со следующим содержанием:

''<?xml version="1.0" encoding="utf-8"?>
<TS>
  <context>
  </context>
</TS>''

4) Выполняем команду (обновление словарей):

 limb i18n ut

5) Очищаем кэш, обновляем страницу




===== Локализация =====

1) В PHP коде

lmb_i18n("Hello {arg}", array('arg' => 'Bob'), "domain")

2) В шаблоне

{$"Search query"|i18n:"project_name"}


===== Изменения в пакете i18n (перенесено с форума) =====

1) Изменился способ хранения Qt словарей, теперь эти словари хранятся в директории i18n/translations и имеют вид $domain.$locale.ts, например, validation.en_US.ts. Больше нет такого понятия как "оригинальный" словарь, по-умолчанию просто используется default.en_US.ts.

2) Больше нет понятия "контекста" для словарей вида /foo/bar, теперь есть более общее понятие "домена"(понятие домена взято из терминологии gettext). Вообще это сделано для того, чтобы обобщить работу с разного вида словарями(см.ниже), хотя пока есть только Qt поддержка.

Домен состоит из одного слова, и, например, для Qt словарей указывает на то, как будет выглядеть название словаря. Так, домен "foo" и текущая локаль "en_US" для Qt словарей замапятся на файл i18/translations/foo.en_US.ts.

3) Больше нет функции tr(..), ей на смену пришла функция __($txt) с двумя опциональными аргументами. Вот ее возможное использование:

a) __("Hello") - используется домент по-умолчанию "default"
b) __("Hello", "domain") - явно используется домен "domain"
c) __("Hello {arg}", array('arg' => 'Bob')) - параметры + домент по-умолчанию "default"
d) __("Hello {arg}", array('arg' => 'Bob'), "domain") - параметры + домент "domain"

Update: вместо функции __() теперь используется lmb_i18n()

4) Для себя мы делаем следующее соглашение(чисто условное): Limb3 пакет содержит переводы в домене, совпадающем с ним по названию. Например, validation словарь должен находиться в пакете VALIDATION. Сейчас это соглашение не выполняется, например, для WEB_APP пакета, но это будет исправлено.

5) Домен по-умолчанию - "default". Подразумевается, что словари из этого домена будут использоваться в конечном приложении. В пакетах Limb3, мы опять же уславливаемся, не должно быть непереведенных строк в данном домене.

6) Поиск словарей Qt происходит следующим образом: a) вначале поиск происходит в приложении b) затем поиск происходит по пакетам Limb3. Вообще за это отвечает константа:

@define('LIMB_TRANSLATIONS_INCLUDE_PATH', 'i18n/translations;limb/*/i18n/translations');

Таким образом в приложении можно будет оверрайдить Limb3 словари, хотя большого смысла в этом я не вижу.

7) Фильтр i18n для шаблонов остался тем же, однако пока он находится в WEB_APP, но будет перенесен в пакет I18N, т.к на самом деле его место там. Это ничего не должно сломать.

8 ) Теоретически можно будет иметь любое количество реализаций хранилищ(backend) для словарей, пока же реально есть только реализация хранения в Qt формате.

Самое главное, чтобы хранилище реализовывало интерфейс:

Code:
view plainprint?

   1. interface lmbDictionaryBackend  
   2. {  
   3.   //сохраняет словарь в хранилище  
   4.   function save($locale, $domain, $dictionary);  
   5.   //загружает и возвращает словарь из хранилища  
   6.   function load($locale, $domain);  
   7.   //загружает массив всех словарей из хранилища для всех доменов и локалей в виде  
   8.   //array('en_US' => array('bar' => $d1, 'foo' => $d2), 'ru_RU' => (...))  
   9.   function loadAll();   
  10. }  

interface lmbDictionaryBackend { //сохраняет словарь в хранилище function save($locale, $domain, $dictionary); //загружает и возвращает словарь из хранилища function load($locale, $domain); //загружает массив всех словарей из хранилища для всех доменов и локалей в виде //array('en_US' => array('bar' => $d1, 'foo' => $d2), 'ru_RU' => (...)) function loadAll(); }

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

9) Была добавлена CLI команда для обновления словарей, пока она в сыром виде. Команде будет передаваться, a) какой тип хранилища использовать в данный момент b) директория с исходными файлами. Куда именно физически записывать найденные строки передаваться в команду не будет, теперь это полностью в ответственности хранилища.

10) Поменялись названия локалей, они стали более полными(более стандартные), вместо 'ru', теперь используется 'ru_RU', вместо 'en' - 'en_US'. Были еще локали 'de', 'fr', 'ar' - однако в связи с тем, что это неподтвержденные локали(т.е толком ими не пользовались), я их временно удалил, подождем пока появятся люди, которые взялись бы за их поддержку. Функционал локалей еще будет очень активно причесываться...

11) Методы setLocale()/getLocale() для lmbI18NTools поменяли свое предназначение, теперь это сеттер/геттер для кода локали, не объекта, т.е ставить текущую локаль надо теперь так setLocale('ru_RU'). 'en_US' лоаль стоит по-умолчанию. Для получения именно объекта локали используется теперь метод тулкита getLocaleObject(). 


12) В тулкит I18N пакета был добавлен метод getLocaleObject($locale=null), который мапит переданную локаль на объект локали, если локаль не передается используется текущая локаль, т.е установленная при помощи setLocale().

13) В тулкит I18N пакета был добавлен метод addLocaleObject($obj, $locale = null), этот позволяет зарегистрировать объект локали, чтобы тот использовался при вызове getLocaleObject(..). Данный метод полезен для тестирования.

14) Теперь все параметры конструктора lmbLocale стали опциональными, т.е можно просто инстанциировать пустой объект локали. Опять же полезно для тестирования.

15) Добавлен крайне эксперементальный функционал по обновлению словарей из исходников приложения. Это CLI команда I18nCliCmd, варианты использования в консоли:

$ limb i18n update-translations /src/path #процедура обновление
$ limb i18n test-update-translations /src/path #dry-run режим

I18nCliCmd показал, что пока пользоваться новыми средствами CLI пакета довольно неудобно, не хватает некоторых вещей. Но об этом в другом посте. 

16) Добавлена укороченная команда по обновлению словарей:
limb i18n ut == limb i18n update-translations

17) функция __(..) заменена на lmb_i18n(..), да выглядит неуклюже, зато не будет конфликтов. В качестве хорошей новости - фильтр в шаблоне называется схожим образом.

18) В связи с последними изменениями в CLI пакете получилось сделать команду по обновлению чуть более удобной. Теперь test-update-translations больше нет, просто надо использовать опцию -t|--test, т.е:

limb i18n ut -t

или более длинный вариант :

limb i18n update-translations -t

Еще добавил вменяемую помощь:

limb i18n help

===== Работа с пакетом =====

1) Всегда предполагается, что пакет имеет только один файл с переводами и этот файл имеет схожее с пакетом название. Например, validation.ru_RU.ts, validation.en_US.ts и проч.

2) Файлы с переводами ищутся в файловой системе по путям, перечисленным в константе LIMB_TRANSLATIONS_INCLUDE_PATH, которая по-умолчанию равна:
@define('LIMB_TRANSLATIONS_INCLUDE_PATH', 'i18n/translations;limb/*/i18n/translations');

3) Для перевода фразы используется функция lmb_i18n(..), которая может на данный момент использоваться так:

a) lmb_i18n("Hello") - используется домент по-умолчанию "default"
b) lmb_i18n("Hello", "domain") - явно используется домен "domain"
c) lmb_i18n("Hello {arg}", array('arg' => 'Bob')) - параметры + домент по-умолчанию "default"
d) lmb_i18n("Hello {arg}", array('arg' => 'Bob'), "domain") - параметры + домент "domain"

Здесь стоит сделать замечание: мы используем соглашение о том, что домен - это и есть название пакета. Для конечного приложения возможно имеет смысл использовать 'default' домен, таким образом, получится немного сократить написание lmb_i18n функции.

Также надо понимать, что lmb_i18n использует текущую локаль, которая может быть установлена через $toolkit(например, $toolkit->setLocale('ru_RU'), по-умолчанию используется en_US);

4) Я уже выше говорил про локали, но еще раз подытожу. Пакет i18n также вводит понятие локали, которая позволяет хранить определенные интернациональные настройки. Локали расположены в пакете i18n, в директории i18n/locale. Однако пути до локалей не жестко зашиты, а ищутся подобно файлам переводов, только теперь уже при помощи константы LIMB_LOCALE_INCLUDE_PATH, которая по-умолчанию равна:
@define('LIMB_LOCALE_INCLUDE_PATH', 'i18n/locale;limb/i18n/i18n/locale');

Соотв-но локали также ищутся по include_path, поэтому можно безболезненно добавлять свои, или оверрайдить стандартные.

Также существует понятие текущей локали, которая хранится в $toolkit. Текущая локаль влияет на работу функции lmb_i18n

5) Для обновления словарей используется консольная утилита limb i18n(предполагается, что limb утилита настроена). В двух словах как эта штука работает: вызывается "limb i18n" в корневой директории пакета(приложение тоже считается пакетом) и после этого происходит анализ PHP и html файлов на предмет новых фраз, если таковые были найдены то обновляются словари в директории i18n/translations текущего пакета.