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

Даже когда документ успешно обработан, все еще возможны необнаруженные несоответствия и неявные ошибки. Поэтому любой перевод, автоматически ассоциированный po4a-gettextize, помечается как fuzzy, чтобы потребовать ручной проверки человеком. Необходимо проверить, что каждый полученный msgstr является переводом соответствующего msgid, а не строкой до или после него.

Как видите, ключевым моментом здесь является точное совпадение структуры в переведенном документе и в оригинале. Лучше всего выполнять gettextization на той версии master.doc, которая использовалась для перевода, и обновлять PO-файл по последнему мастер-файлу только после успешной gettextization.

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

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

  Подсказки и хитрости для процесса gettextization
Gettextization прекращается, как только обнаруживается десинхронизация. Теоретически, вероятно, должна быть возможность повторной синхронизации gettextization в более поздних документах, используя, например, тот же алгоритм, что используется в утилите diff(1). Но ручное вмешательство все равно будет обязательным для ручного сопоставления элементов, которые не могут быть сопоставлены автоматически, что объясняет, почему автоматическая ресинхронизация не реализована (пока?).

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

Вот еще несколько приемов, которые помогут вам в этом утомительном процессе:

•   Удалите все лишнее содержимое переводов, например, раздел с кредитами переводчикам. Вы можете добавить их обратно в po4a позже, используя addenda (см. po4a(7)).

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

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

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

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

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

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

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

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

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

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

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

    Например, первый po4a-updatepo французского перевода документации Perl (файл PO размером 5,5 МБ) занял около 48 часов (да, два дня), в то время как последующие занимают лишь десятки секунд.

СМОТРИТЕ ТАКЖЕ
po4a(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7).

АВТОРЫ
 Denis Barbier <barbier@linuxfr.org>
 Nicolas Francois <nicolas.francois@centraliens.net>
 Martin Quinson (mquinson#debian.org)

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

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