НАЗВАНИЕ

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

           = item -k --keep-temps

           Keep the temporary master and localized POT files built before merging. This can be
           useful to understand why these files get desynchronized, leading to gettextization
           problems

       -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 и
           исправьте проблему в этом месте.

       •   In some case, po4a adds a space at the end of either the original or the translated
           strings. This is because every string must be deduplicated during the gettextize
           process. Imagine that a string appearing several times unmodified in the original, but
           is translated in differing way, or that different paragraphs are translated in the
           exact same way.

           Without deduplication, such case would break the gettexization algorithm, as it is a
           simple one to one pairing between the msgids of both the master and the localized
           files. Since one of the PO files would miss an entry (that would be reported as
           duplicate, with two references), the pairing would fail.

           Since po4a uses the entry type ("title" or "plain paragraph", etc) to detect whether
           the parsing streams got desynchronized, similar issues could occur if two identical
           entries (same content but differing type) of the master file are translated in the
           exact same way in the localized file. po4a would detect a fake desyncronization in
           such case.

           In most cases, the extra space added by po4a to deduplicate the strings has no impact
           on the formatting. Strings are fuzzied anyway, and msgmerge will probably match the
           strings accordingly afterward.

       •   В качестве последнего замечания, не удивляйтесь, если первая синхронизация вашего
           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).