
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 НАЗВАНИЕ

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

=head1 СИНТАКСИС

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

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

=head1 ОПИСАНИЕ

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

Сценарий B<po4a-gettextize> отвечает за преобразование файлов документации в PO-файлы. Он понадобится вам только для того, чтобы начать ваш проект перевода с помощью po4a, в дальнейшем вам не нужно будет его использовать.

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

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

=head1 ПАРАМЕТРЫ

=over 4

=item B<-f>, B<--format>

Формат документации которой вы хотите обработать. Используйте параметр B<--help-format>, чтобы просмотреть список доступных форматов.

=item B<-m>, B<--master>

Файл содержащий мастер-документ для перевода. Вы можете использовать этот параметр несколько раз, если вы хотите создать один PO-файл сразу для нескольких документов.

=item B<-M>, B<--master-charset>

Кодировка файла, содержащаяся в документе для перевода.

=item B<-l>, B<--localized>

Файл, содержащий локализованный (переведённый) документ. Если вы указали несколько мастер-файлов, может возникнуть необходимость предоставить несколько файлов локализации, указав данный параметр несколько раз.

=item B<-L>, B<--localized-charset>

Кодировка файла, содержащего переведённый документ.

=item B<-p>, B<--po>

Файл в который будет записан каталог сообщений. Если не задан, то каталог сообщений будет записан в стандартный вывод.

=item B<-o>, B<--option>

Дополнительные параметры, передаваемые модулю формата. См. описание возможных параметров и их значений в документации каждого конкретного модуля. Например, вы можете указать '-o tablecells' парсеру AsciiDoc, в то время как парсер text принимал бы '-o tabs=split'.

=item B<-h>, B<--help>

Отобразить короткую справку.

=item B<--help-format>

Выводит список поддерживаемых po4a форматов.

=item B<-V>, B<--version>

Отобразить версию и завершить работу сценария.

=item B<-v>, B<--verbose>

Увеличить количество выводимой пояснительной информации.

=item B<-d>, B<--debug>

Вывод отладочной информации.

=item B<--msgid-bugs-address> I<email@address>

Установить адрес для сообщений об ошибках в msgid. По умолчанию, созданные POT-файлы не имеют поля Report-Msgid-Bugs-To.

=item B<--copyright-holder> I<строка>

Указать владельца авторских прав в заголовке POT файла. Значение по умолчанию: «Free Software Foundation, Inc.»

=item B<--package-name> I<строка>

Указать имя пакета в заголовке POT-файла. Значение по умолчанию: «PACKAGE».

=item B<--package-version> I<строка>

Указать версию пакета в заголовке POT-файла. Значение по умолчанию: «VERSION».

=back

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=over 

=item 

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

=item 

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

=item 

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

=item 

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

=item 

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

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

=item 

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

=item 

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

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

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

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

=item 

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

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

=back

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

L<po4a(1)>, L<po4a-normalize(1)>, L<po4a-translate(1)>, L<po4a-updatepo(1)>, L<po4a(7)>.

=head1 АВТОРЫ

 Denis Barbier <barbier@linuxfr.org>
 Nicolas Francois <nicolas.francois@centraliens.net>
 Martin Quinson (mquinson#debian.org)

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

Copyright 2002-2020 by SPI, inc.

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

