PO4A-GETTEXTIZE.1P

Section: User Contributed Perl Documentation (1)
Updated: 2024-06-17
Index Return to Main Contents

НАЗВАНИЕ

po4a-gettextize - преобразует исходный файл (и его перевод) в PO-файл

КРАТКОЕ СОДЕРЖАНИЕ

po4a-gettextize -f формат -m мастер_документ.doc -l XX.doc -p XX.po

(XX.po является выходным файлом, все остальные являются входными параметрами)

ОПИСАНИЕ

po4a (PO for anything, PO для всего) упрощает поддержку переводов документации, используя обычные инструменты gettext. Основная идея po4a состоит в том, что оно отделяет перевод содержимого от структуры документа. Пошаговое вводное руководство по работе с данным проектом можно посмотреть на странице po4a(7).

Скрипт po4a-gettextize поможет вам преобразовать уже существующие переводы для использования их в рабочем процессе, основанном на po4a. Это необходимо сделать только один раз, чтобы во время интеграции po4a уже проделанная работа по переводу не пропала впустую; это не нужно будет делать регулярно при работе над вашим проектом. Этот нудный процесс описан во всех подробностях в главе «Преобразование уже существующего перевода в po4a» ниже.

Вы должны задать как мастер-файл (т.е. исходный документ на английском), так и уже существующий переведённый файл (т.е. предыдущая попытка перевода, выполненная без использования po4a). Если вы задали больше одного мастер-файла или файла с переводом, то они будут использованы последовательно, но учтите, что, скорей всего, проще будет геттекстизировать каждую страницу или главу отдельно, а затем слить их вместе в один PO-файл с помощью msgmerge. Но это на ваше усмотрение.

Если мастер-документ содержит не-ASCII символы, то созданный PO-файл будет в кодировке UTF-8. В противном случае, если мастер-документ полностью в кодировке ASCII, то созданный PO-файл будет использовать кодировку переводимого входного документа.

ПАРАМЕТРЫ

-f, --format: Формат документации которой вы хотите обработать. Используйте параметр --help-format, чтобы просмотреть список доступных форматов.
-m, --master: Файл содержащий мастер-документ для перевода. Вы можете использовать этот параметр несколько раз, если вы хотите создать один PO-файл сразу для нескольких документов.
-M, --master-charset: Кодировка файла, содержащаяся в документе для перевода.
-l, --localized: Файл, содержащий локализованный (переведённый) документ. Если вы указали несколько мастер-файлов, может возникнуть необходимость предоставить несколько файлов локализации, указав данный параметр несколько раз.
-L, --localized-charset: Кодировка файла, содержащего переведённый документ.
-p, --po: Файл в который будет записан каталог сообщений. Если не задан, то каталог сообщений будет записан в стандартный вывод.
-o, --option: Дополнительные параметры, передаваемые модулю формата. См. описание возможных параметров и их значений в документации каждого конкретного модуля. Например, вы можете указать '-o tablecells' парсеру AsciiDoc, в то время как парсер text принимал бы '-o tabs=split'.
-h, --help: Отобразить короткую справку.
--help-format: Выводит список поддерживаемых po4a форматов.
-k --keep-temps: Не удалять временные POT-файлы для мастер-документа и перевода, которые создаются перед их сшивкой. Это может быть полезно, чтобы понять, почему некоторые файлы рассинхронизированы (что приводит к проблемам с геттекстизацией).
-V, --version: Отобразить версию и завершить работу сценария.
-v, --verbose: Увеличить количество выводимой пояснительной информации.
-d, --debug: Вывод отладочной информации.
--msgid-bugs-address email@address: Установить адрес для сообщений об ошибках в msgid. По умолчанию, созданные POT-файлы не имеют поля Report-Msgid-Bugs-To.
--copyright-holder строка: Указать владельца авторских прав в заголовке POT файла. Значение по умолчанию: «Free Software Foundation, Inc.»
--package-name строка: Указать имя пакета в заголовке POT-файла. Значение по умолчанию: «PACKAGE».
--package-version строка: Указать версию пакета в заголовке POT-файла. Значение по умолчанию: «VERSION».

Преобразование уже существующего перевода в po4a

po4a-gettextize синхронизирует мастер-файла с его переведённой версией, извлекая их содержимое в PO-файл. Содержимое мастер-файла даёт msgid, а содержимое переведённого — msgstr. Этот процесс в некоторой степени хрупок: предполагается что N-ый строка, извлечённая из переведённого файла является переводом N-ой строки исходного.

Геттекстизация пройдёт легче, если вы сможете заполучить в точности ту версию исходного документа, которая использовалась для перевода. Хотя даже в этом случае вам, возможно, придётся немного поиграться и с мастер-документом, и с его переведённой версией, чтобы выравнять их структуры, например, в ситуации, когда они были изменены изначальным переводчиком.

Внутренне, каждый парсер po4a возвращает синтаксический тип для каждой извлечённой строки. Это и помогает определить рассинхрон файлов во время геттекстизации. Например, в ситуации приведённой ниже очень маловероятно, что 4-я строка в переводе (типа «глава») является переводом 4-й строки в оригинале (типа «параграф»). Скорее в оригинал был добавлен новый параграф или два параграфа оригинала были объединены в переводе.

    Оригинал           Перевод

  глава              глава
    параграф           параграф
    параграф           параграф
    параграф         глава
  глава                параграф
    параграф           параграф

po4a-gettextize будет выдавать подробные диагностические сообщения о любых расхождениях в структуре файлов. Кода такое произойдёт, вам придётся вручную отредактировать эти файлы: добавить какие-то суррогатные параграфы или удалить что-то то там то тут, дабы исправить найденные несоответствия так, чтобы структура обоих файлов в точности совпадала. Несколько трюков, как это сделать так, чтобы сохранить как можно большую часть уже готового перевода, приведены ниже.

Если вам повезёт и структура обоих документов идеально совпадает, то создание корректного PO-файла займёт всего несколько секунд. В противном случае вы вскоре поймёте, почему у этого процесса такое уродливое название :). Но даже в таком случае, геттекстизация будет быстрее, чем переводить всё с нуля. Например, я геттекстизировал Французский перевод всей документации Perl за один день, несмотря на то, что у меня возникло много проблем с синхронизацией. Учитывая объём (2Mb оригинального текста), перевод всего этого с нуля не сохраняя предыдущие наработки занял бы несколько месяцев. К тому же, эта грязная работёнка — это та цена, которую придётся заплатить за то, чтобы пользоваться удобствами po4a в дальнейшем. Как только вы завершите процесс преобразования, синхронизация между мастер-документом и переводами станет полностью автоматической.

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

Подсказки и хитрости для процесса gettextization

Как только в файлах обнаруживается рассинхронизация, процесс гетекстизации останавливается. Когда это происходит, вам придётся вручную отредактировать файлы так, чтобы их структуры снова стали выравненными. po4a-gettextize довольно подробно описывает, что пошло не так. Он выдаст вам строки, которые не совпадают, их местоположение в документах и тип каждой из них. Кроме того, созданный до момента этого сбоя PO-файл будет сбрасываться в gettextization.failed.po.

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

•: Удалите все лишнее содержимое из переводов, например, раздел с благодарностями переводчикам. С po4a подобные разделы должны добавляться в виде аддендумов (addendum, см. po4a(7)).
•: Когда вы редактируете файлы, чтобы выравнять их структуры, то, по-возможности, лучше редактировать перевод. Действительно, если изменения в оригинале будут слишком навязчивыми, старая и новая версии не будут корректно сопоставлены при первом запуске po4a после геттекстизации (см. ниже). Любые переводы, которым нет соответствий в оригинале всё равно придётся выбросить. Тем не менее, в некоторых ситуациях, когда иначе продолжить геттекстизацию не получается, иногда будет легче всё же внести правку и в исходный документ; даже если это и означает, что один из абзацев перевода будет отброшен. Главное на этом этапе — получить первый PO-файл, с которого можно начать дальнейшую работу.
•: Не стесняйтесь удалять какой-либо текст в оригинале, которого нет в переведённой версии. В дальнейшем всё это содержимое будет восстановлено при синхронизации PO-файла с документом.
•: Если вы считаете, что ваши изменения структуры документа в переводе оправданы, то, скорее всего, вам следует связаться по этому поводу с его автором. О проблемах оригинального документа нужно сообщать автору оригинального документа. Если вы исправляете их только в своём переводе, то вы исправляете эти проблемы только для части сообщества. И кроме того, это невозможно при использовании po4a ;). Однако, с этим, наверное, лучше будет повременить до окончания конвертации проекта для работы с po4a.
•: Иногда содержимое абзацев совпадает, но не их типы. То, как именно разрешить эту ситуацию, зависит от формата. В POD и man это зачастую происходит из-за того, что один из них начинается с пробела, а другой — нет. Для этих форматов в таком абзаце (начинающемся с пробела) запрещён перенос строк и, таким образом, он рассматривается, как имеющий другой тип. Просто удалите пробел и всё будет в порядке. Это также может быть вызвано, например, опечаткой в имени тега в XML.
Аналогично, два абзаца могут слиться в один в POD, когда разделяющая их строка содержит пробелы или когда между =item и содержимым элемента нет пустой строки.
•: Иногда сообщения о рассинхронизации кажутся странными так как перевод привязывается не к тому абзацу оригинала. Это признак того, что проблема где-то выше не была обнаружена. Ищите истинную точку рассинхронизации, исследуя содержимое файла gettextization.failed.po, созданного после неудачной геттекстизации, и исправьте проблему там.
•: Другой класс проблем может возникать из-за дубликатов строк (когда одна и таже строка встречается в файле несколько раз) в оригинале или переводе. Дубликаты строк объединяются в PO-файле в одну с несколькими сносками. Это является проблемой для алгоритма геттекстизации, так как он просто попарно берёт msgid полученные из мастер-файла и из перевода. Однако, считается, что относительно новые версии po4a могут корректно обрабатывать дубликаты строк, так что вам следует сообщать о любых оставшихся проблемах, с которыми вы столкнётесь.

Проверка файлов, созданных po4a-gettextize

Любой файл, созданный po4a-gettextize, должен подлежать тщательной ручной проверке, даже если выполнение завершается успешно. Вам следует просмотреть PO-файл и убедиться, что msgid и msgstr действительно соответствуют друг другу. На данном этапе пока нет необходимости проверять полную корректность перевода, поскольку все записи и так помечаются как «неточные» (fuzzy). Вам надо только проверить, нет ли очевидных проблем с соответствием переводов исходным строкам, поскольку те переводы которые окажутся сопоставлены не своим строкам, будут попросту удалены на последующих этапах в то время, как вам, вероятно, хотелось бы их сохранить.

К счастью, для данной задачи не обязательно овладевать целевым языком в полной мере, ибо вам нужно будет только распознавать похожие элементы в msgid и соответствующем ему msgstr. Например я, как человек говорящий по-французски, по-английски и немного по-немецки, могу произвести подобную проверку, по крайней мере, для всех европейских языков не смотра на то, что я не могу выговорить ни слова на большинстве из них. Иногда мне удаётся обнаружить проблемы с сопоставлением и в языках с не-латинской письменностью. В этих случаях можно обращать внимание на длину строк, структуру фраз (совпадает ли количество вопросительных знаков?) и другие подсказки, но проверку подобных языков я предпочитаю оставлять на кого-то другого.

Если вы обнаружите несоответствия, то отредактируйте исходный файл или перевод также, как если бы po4a-gettextize сообщил об ошибке, и попробуйте снова. Как только у вас получится сносный PO-файл для уже существующего перевода, сохраните его резервную копию и отложите в сторону до тех пор, пока вы не настроите po4a так, чтобы она корректно обрабатывала ваш проект.

Запуск po4a в первый раз

Самый простой способ подготовить po4a к работе — создать файл настроек po4a.conf и дальше пользоваться интегрированной утилитой po4a (po4a-updatepo и po4a-translate устарели). Более подробно это описано в раздел «ФАЙЛ НАСТРОЕК» в po4a(1).

При первом запуске po4a текущая версия мастер-документов будет использоваться для обновления PO-файлов, содержащих старые переводы, которые вы вытащили во время геттекстизации. Это может занять довольно длительное время, поскольку многие msgid после геттекстизации могут в некоторой степени отличаться от тех, что в POT-файле, созданном из последних мастер-файлов. Это приводит к тому, что gettext вынужден искать ближайшие соответствия, используя дорогостоящие алгоритмы приближённого сопоставления строк. Например, первый подобный запуск для французского перевода документации Perl (PO-файл размером 5,5 МБ) занял около 48 часов (да, два дня), а последующие — всего несколько секунд.

Переход к повседневной работе с переводами

После этого первого запуска PO-файлы готовы к проверке переводчиками. После работы po4a-gettextization все записи в PO-файле были помечены как неточные (fuzzy), что вынудит переводчиков проверять их тщательно, прежде чем использовать. Переводчики должны проверить каждую запись, чтобы убедиться, что сохранённый перевод действительно соответствует текущему исходному тексту, по-необходимости обновить перевод и удалить пометку «неточный».

Как только достаточное количество переводов будут проверены (будут сняты пометки о «неточный»), po4a начнёт создавать переведённые файлы на их основе, и вы будете готовы полностью интегрировать данный рабочий процесс в свою повседневную деятельность. Некоторые проекты полагаются на такие сервисы, как, например, weblate для координации взаимодействия между переводчиками и сопровождающими проекта, но это уже выходит за рамки описания работы с po4a.

СМОТРИТЕ ТАКЖЕ

po4a(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7).

АВТОРЫ

 Денис Барбье (Denis Barbier) <barbier@linuxfr.org>
 Николя Франсуа (Nicolas François) <nicolas.francois@centraliens.net>
 Мартин Кенсон (Martin Quinson) (mquinson#debian.org)

АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИИ

Данная программа является свободным программным обеспечением; вы можете распространять и/или изменять её на условиях Универсальной общественной лицензии (GPL) GNU v2.0 или новее (см. файл COPYING).