Поддержка файлов локализации с помощью Transifex

#1. Введение

Начиная с версии Cotonti 0.9.13 языковые файлы движка совместимы со стандартами сервиса переводов Transifex, ознакомится с проектом и присоединиться к международной команде переводчиков можно здесь:

https://www.transifex.com/projects/p/cotonti/

Для начала работы с сервисом переводов, желательно изучить документацию — Transifex Help Pages (на английском языке). В этой статье будут освещены только особенности касающиеся работы с файлами Cotonti.

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

Кроме онлайн перевода есть возможность скачать набор файлов к себе на диск. О наборе инструментов для «офлайн» перевода далее и пойдет речь.

#2. Настройка инструментов переводчика

Все файлы могут быть отредактированы онлайн, тем не менее т.к. Cotonti содержит множество отдельных языковых файлов, для перевода, возможно, будет удобнее скопировать их к себе на диск и использовать свой любимый редактор. Для этого Transifex предоставляет специальную программу работающую с командной строкой — Client tool (далее утилита `tx`).

Внимание! Т.к. часть утилит для автоматизации перевода поставляется в виде скриптов на языке Python, то вам, возможно, потребуется установленный в системе интерпретатор Python (для unix систем он обычно установлен по умолчанию). Скачать его можно здесь: http://python.org/download/. Если вы работаете под ОС Windows, то вам будет полезным настроить команды быстрого вызова — см. инструкцию (на англ. языке).

После этого вы можете установить программу 'tx' (см. английскую инструкцию).

Для облегчения работы по переводу мы подготовили набор утилит для манипуляций с языковыми файлами, скачать которые можно здесь: https://github.com/trustmaster/cotlang. Это набор скриптов на Python, запускаемых из командной строки.

#3. Получение рабочей копии

Сервис Transifex работает по аналогии с репозиториями git, поэтому первое что необходимо сделать это получить рабочую копию.

Примечание: все последующие команды подразумевают использование командной строки.

Создайте для работы новый каталог (для примера назовем его 'cot-lang') и перейдите в него, введя в командной строке:

cd cot-lang

Теперь надо инициализировать в этом каталоге репозиторий Transifex командой:

tx init

После этого надо импортировать файл конфигурации. Выполняем:

tx set --auto-remote  https://www.transifex.com/projects/p/cotonti/

Для правильного сопоставления файлов локализации Transifex и языковых файлов Cotonti, откройте файл '.tx/config', созданный предыдущей командой и замените его содержимое актуальными настройками для Cotonti из файла:

https://raw.github.com/trustmaster/cotlang/master/tx.config

Замечание для продвинутых пользователей: подобный файл конфигурации может быть создан скриптом 'cotlangtx.py', указав  путь к каталогу с исходными файлами Cotonti:

python cotlangtx.py ~/htdocs/cotonti

Теперь пора скопировать языковые файлы в рабочий каталог:

tx pull -a

Отлично. Теперь у вас есть структура каталогов в расположенными в них языковыми файлами.

#4. Делаем текущую локализацию совместимой с Transifex

Если файлы вашей локализации были установлены с версией младше 0.9.13, вам необходимо провести их обновление для соответствия форматам используемым в Transifex. Для этого в наборе утилит cotlang есть скрипт под именем 'cotlangfix.py'. Он автоматизирует 95% работы по изменению файлов. Запускается он следующим образом:

python cotlangfix.py путь/к/исходным/файлам

Он выводит информацию о процессе конвертации на экран. Он так же сообщит о том какие строки должны быть исправлены самостоятельно. Ниже несколько примеров.

#4.1. Многострочные записи

Transifex не поддерживает записи разбитые на несколько строк. Поэтому их надо объединить в одну строку. Если перенос строк необходим внутри записи, используйте двойные кавычки и символ \n внутри строки. Не забудьте при замене одинарных кавычек на двойные экранировать символы '$', чтобы они выглядели так '\$'.
Пример, строку:

$L['multiline_example'] = 'это пример
%1$s многострочной
записи';

Придется заменить на:

$L['multiline_example'] = "это пример\n%1\$s многострочной\nзаписи";

#4.2. Массивы записей

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

$L['cfg_array_params'] = array(
	'Foo',
	'Bar'
);

или в таком виде:

$L['cfg_array2_params'] = array(
	'foo' => 'Foo',
	'bar' => 'Bar'
);

Их тоже надо преобразовать в простые строки. Массивы «склеиваются» с помощью знака ',', а ассоциативные массивы собираются в таком виде: 'key1: value1, key2: value2'. Таким образом строки представленные выше преобразуются в следующий вид

$L['cfg_array_params'] = 'Foo, Bar';

и 

$L['cfg_array2_params'] = 'foo: Foo, bar: Bar';

#5. Загрузка языковых файлов на Transifex

Перед загрузкой файлов с переводом на новый язык, убедитесь, что запись для этого языка создана и отображается в проекте Cotonti на сайте Transifex. Если этого языка еще нет в проекте, то войдите на сервис под своей учетной записью (регистрация здесь) и запросите добавление нового языка в проект Cotonti. Мы получим ваш запрос и оперативно создадим запись для новой локализации.

В наборе утилит cotlang есть скрипт под названием 'cotlangcp.py'. Он позволяет упростить операции по копированию набора языковых файлов из одной папки в другую, сохраняя при этом структуру каталогов. Используйте его следующим образом:

python cotlangcp.py путь/к/исходным/файлам путь/к/целевому/каталогу

Кроме этого можно копировать файлы только для определенного языка, например 'nl' (для обозначения используется 2-х буквенный код принятый в Cotonti):

python cotlangcp.py путь/к/исходным/файлам путь/к/целевому/каталогу -l nl

Например, если вы используете текущую 'nl' локализацию, файлы которой находятся в каталоге '~/htdocs/cotonti' и вы хотите скопировать её в каталог репозитория '~/cot-lang', используйте cotlangcp.py следующим образом:

python cotlangcp.py ~/htdocs/cotonti ~/cot-lang -l nl

Теперь, когда у вас есть новые файлы для языка вы можете отправить их на сервер Transifex:

tx push -t -l nl

Замените код 'nl' на код вашего языка.

После этого языковые записи попадут на сервер и будут доступны на страницах проекта https://www.transifex.com/projects/p/cotonti/.

#6. Обновление локальной копии файлов

Языковые файлы периодически обновляются. Какие-то строки могут быть добавлены, какие-то удалены. Если вы используете веб-интерфейс Transifex для перевода проблем возникнуть не должно — все изменения видны, просто найти записи без перевода. Более того при редактировании онлайн доступны такие инструменты как Translation Memory и автоматический перевод при помощи сервиса Google.
Тем не менее, вам может потребоваться получить актуальную версию локальной копии языковых файлов для редактирования в привычном редакторе. Сделать это не сложно, с помощью командной строки и все тех же утилит.

Перед внесением любых изменений в файлы лучше всегда обновить локальные копии свежими версиями с сервера:

tx pull

Для получения всех файлов, включая новые используйте команду:

tx pull -a

Теперь вы можете редактировать файлы прямо в текущих каталогах. Или можете скопировать ваш вариант локализации из другой папки, например так:

python cotlangcp.py ~/htdocs/cotonti ~/cot-lang -l nl

Эта команда скопирует языковые файлы голландской локали ('nl')из каталога ~/htdocs/cotonti в каталог ~/cot-lang. Здесь предполагается что каталог ~/cot-lang это каталог вашего Transifex репозитория, а  ~/htdocs/cotonti путь где вы храните последние версии файлов с голландской локализацией.

И наоборот, вы всегда можете скопировать последние версии файлов из репозитория Transifex в каталог с файлами вашего сайта на Cotonti:

python cotlangcp.py ~/cot-lang ~/htdocs/cotonti -l nl

Когда процесс редактирования файлов в локальной копии закончен надо отправить изменения на сервер Transifex:

tx push -t -l nl

Замените код 'nl' на соответствующий вашему языку.

#7. Полезные советы

Всегда скачивайте последнюю версию (Pull) перед изменением и заливкой на сервер(push).

Это правило многим должно быть знакомо по работе с Git, однако Tx это не Git, и надо быть более осторожным. Рекомендуем выполнять команда в следующем порядке:

tx pull -a # получаем последнюю версию с сайта
cotlangcp.py # редактируем или заменяем часть файлов
tx push -t # выгружаем изменения обратно на сервер