Skip to content

Latest commit

 

History

History
100 lines (61 loc) · 11.7 KB

i18n.md

File metadata and controls

100 lines (61 loc) · 11.7 KB

Пакет I18N — интернационализация и работа с мультибайтным контентом.

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

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

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

  3. Поиск словарей Qt происходит следующим образом:

    • вначале поиск происходит в приложении
    • затем поиск происходит по пакетам Limb3

Вообще за это отвечает константа:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  10. В связи с последними изменениями в 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(..), которая может на данный момент использоваться так:

    lmb_i18n(«Hello») — используется домент по-умолчанию «default» lmb_i18n(«Hello», «domain») — явно используется домен «domain» lmb_i18n(«Hello {arg}», array('arg' ⇒ 'Bob')) — параметры + домент по-умолчанию «default» mb_i18n(«Hello {arg}», array('arg' ⇒ 'Bob'), «domain») — параметры + домент «domain»

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

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

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

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

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

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