
        *****************************************************
        *           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, в дальнейшем вам не нужно будет его использовать.

If you start from scratch, B<po4a-gettextize> will extract the translatable
strings from the documentation and write a POT file. If you provide a
previously existing translated file with the B<-l> flag, B<po4a-gettextize>
will try to use the translations that it contains in the produced PO
file. This process remains tedious and manual, as explained in Section
'Converting a manual translation to po4a' below.

Если мастер-документ содержит не-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>

Extra option(s) to pass to the format plugin. See the documentation of each
plugin for more information about the valid options and their meanings. For
example, you could pass '-o tablecells' to the AsciiDoc parser, while the
text parser would accept '-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> will verbosely diagnose any detected structure
desynchronization. When this happens, you should manually edit the files
(this probably requires that you have some notions of the target
language). You must add fake paragraphs or remove some content in one of the
documents (or both) to fix the reported disparities, until the structure of
both documents perfectly match. Some tricks are given in the next section.

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 I<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 F<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
миллиона символов): новый перевод с нуля занял бы несколько месяцев.

=head2 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 L<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?).

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

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

=over 

=item 

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 L<po4a(7)>).

=item 

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.

=item 

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.

=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-файле не создаётся,
а к уже существующей добавляется новая сноска.

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.

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

=item 

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 B<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.

=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 François) <nicolas.francois@centraliens.net>
 Мартин Кенсон (Martin Quinson) (mquinson#debian.org)

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

Copyright 2002-2020 by SPI, inc.

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

