PO4A-GETTEXTIZE(1p)

НАЗВАНИЕ
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 отвечает за преобразование файлов документации в PO-файлы. Он понадобится вам только для того, чтобы начать ваш проект перевода с помощью po4a, в дальнейшем вам не нужно будет его использовать.

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

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

ПАРАМЕТРЫ

-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 форматов.

-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 попытается извлечь содержимое заданного переведённого файла и использовать его в качестве msgstr в созданном PO-файле. Имейте в виду, что этот процесс крайне хрупкий: предполагается что N-ая строка переведённого файла является переводом N-ой строки исходного. Естественно, это не будет работать, если у обоих файлов не абсолютно идентичная структура.

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

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

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

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

Even when the document is successfully processed, undetected disparities and silent errors are still possible. That is why any translation associated automatically by po4a-gettextize is marked as fuzzy to require an manual inspection by humans. One has to check that each retrieved msgstr is actually the translation of the associated msgid, and not the string before or after.

As you can see, the key here is to have the exact same structure in the translated document and in the original one. The best is to do the gettextization on the exact version of master.doc that was used for the translation, and only update the PO file against the latest master file once the gettextization was successful.

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

Даже когда что-то идёт не так, зачастую сделать геттекстизацию всё равно быстрее, чем переводить всё заново. Например, я смог геттекстизировать существующий французский перевод всей документации Perl всего за один день, даже несмотря на то, что структура многих документов была рассинхронизирована. И это были более чем два мегабайта исходного текста (2 миллиона символов): новый перевод с нуля занял бы несколько месяцев.

  Hints and tricks for the gettextization process
The gettextization stops as soon as a desynchronization is detected. In theory, it should probably be possible resynchronize the gettextization later in the documents using e.g. the same algorithm than the diff(1) utility. But a manual intervention would still be mandatory to manually match the elements that couldn't be automatically matched, explaining why automatic resynchronization is not implemented (yet?).

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

Here are some other tricks to help you in this tedious process:

•   Remove all extra content of the translations, such as the section giving credits to the translators. You can add them back in po4a afterward, using an addenda (see po4a(7)).

•   If you need to edit the files to align their structures, you should prefer editing the translation if possible. Indeed, if the changes to the original are too intrusive, the old and new versions will not be matched during the PO update, and the corresponding translation will be dumped anyway. But do not hesitate to also edit the original document if required: the important thing is to get a first PO file to start with.

•   Do not hesitate to kill any original content that would not exist in the translated version. This content will be automatically reintroduced afterward, when synchronizing the PO file with the document.

•   Если вы как-либо меняете структуру документа в переводе и это кажется вам оправданным, то, скорее всего, вам следует связаться по этому поводу с его автором. О проблемах оригинального документа нужно сообщать автору оригинального документа. Если вы исправляете их только в своём переводе, то вы исправляете их только для части сообщества. И кроме того, это невозможно при использовании po4a ;)

•   Иногда содержимое абзацев совпадает, но не их типы. То, как именно разрешить эту ситуацию, зависит от формата. В POD и man это зачастую происходит из-за того, что один из них начинается с пробела, а другой — нет. Для этих форматов в таком абзаце (начинающемся с пробела) запрещён перенос строк и, таким образом, он рассматривается, как имеющий другой тип. Просто удалите пробел и всё будет в порядке. Это также может быть вызвано, например, опечаткой в имени тега в XML.

    Аналогично, два абзаца могут слиться в один в POD, когда разделяющая их строка содержит пробелы или когда между =item и содержимым элемента нет пустой строки.

•   Иногда сообщения о рассинхронизации кажутся странными так как перевод привязан не к тома абзац оригинала. Это признак того, что проблема где-то выше не была обнаружена. Ищите истинную точку рассинхронизации, исследуя содержимое gettextization.failed.po и исправьте проблему в этом месте.

•   В некоторых неблагоприятных обстоятельствах, у вас может появиться ощущение, что po4a съедает некоторые части текста, либо оригинала, либо перевода. gettextization.failed.po указывает на то, что оба файла были сопоставлены правильно вплоть до абзаца N. Но затем происходит (неудачная) попытка сопоставить абзац N+1 оригинального файла не с абзацем N+1 перевода, как следовало бы, а с абзацем N+2. Так, как будто бы, абзац N+1, который вы видите в переводе, просто испарился бы.

    Эта печальная ситуация возникает, когда один и тот же абзац повторяется в документе несколько раз. В этом случае новая запись в PO-файле не создаётся, а к уже существующей добавляется новая сноска.

    So, the previous situation occurs when two similar but different paragraphs are translated in the exact same way. This will apparently remove a paragraph of the translation. To fix the problem, it is sufficient to slightly alter one of the translations in the document. You can also prefer to kill the second paragraph in the original document.

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

•   As a final note, do not be too surprised if the first synchronization of your PO file takes a long time. This is because most of the msgid of the PO file resulting from the gettextization don't match exactly any element of the POT file built from the recent master files. This forces gettext to search for the closest one using a costly string proximity algorithm.

    For example, the first po4a-updatepo of the Perl documentation's French translation (5.5 MB PO file) took about 48 hours (yes, two days) while the subsequent ones only take a dozen of seconds.

СМОТРИТЕ ТАКЖЕ
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)

АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИИ
Copyright 2002-2020 by SPI, inc.

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