.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "PO4A-GETTEXTIZE 1p" .TH PO4A-GETTEXTIZE 1p "2020-08-19" "Инструменты Po4a" "Инструменты Po4a" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "НАЗВАНИЕ" .IX Header "НАЗВАНИЕ" po4a\-gettextize \- преобразует оригинальный файл (и его перевод) в PO\-файл .SH "СИНТАКСИС" .IX Header "СИНТАКСИС" \&\fBpo4a\-gettextize\fR \fB\-f\fR \fIформат\fR \fB\-m\fR \fIмастер_документ.doc\fR [\fB\-l\fR \&\fI\s-1XX\s0.doc\fR] \fB\-p\fR \fI\s-1XX\s0.po\fR .PP (\fI\s-1XX\s0.po\fR является выходным файлом, всё остальное является входными параметрами) .SH "ОПИСАНИЕ" .IX Header "ОПИСАНИЕ" po4a (\s-1PO\s0 for anything, \s-1PO\s0 для всего) упрощает поддержку переводов документации, используя обычные инструменты gettext. Основная идея po4a состоит в том, что оно отделяет перевод содержимого от структуры документа. Пошаговое вводное руководство по работе с данным проектом можно посмотреть на странице \fBpo4a\fR\|(7). .PP Сценарий \fBpo4a\-gettextize\fR отвечает за преобразование файлов документации в PO\-файлы. Он понадобится вам только для того, чтобы начать ваш проект перевода с помощью po4a, в дальнейшем вам не нужно будет его использовать. .PP If you start from scratch, \fBpo4a\-gettextize\fR will extract the translatable strings from the documentation and write a \s-1POT\s0 file. If you provide a previously existing translated file with the \fB\-l\fR flag, \fBpo4a\-gettextize\fR will try to use the translations that it contains in the produced \s-1PO\s0 file. This process remains tedious and manual, as explained in Section \&'Converting a manual translation to po4a' below. .PP Если мастер\-документ содержит не\-ASCII символы, то созданный PO\-файл будет в кодировке \s-1UTF\-8.\s0 В противном случае (если мастер\-документ полностью в кодировке \s-1ASCII\s0), созданный PO\-файл будет использовать кодировку переводимого входного документа или \s-1UTF\-8,\s0 если переведённый документ не задан. .SH "ПАРАМЕТРЫ" .IX Header "ПАРАМЕТРЫ" .IP "\fB\-f\fR, \fB\-\-format\fR" 4 .IX Item "-f, --format" Формат документации которой вы хотите обработать. Используйте параметр \&\fB\-\-help\-format\fR, чтобы просмотреть список доступных форматов. .IP "\fB\-m\fR, \fB\-\-master\fR" 4 .IX Item "-m, --master" Файл содержащий мастер\-документ для перевода. Вы можете использовать этот параметр несколько раз, если вы хотите создать один PO\-файл сразу для нескольких документов. .IP "\fB\-M\fR, \fB\-\-master\-charset\fR" 4 .IX Item "-M, --master-charset" Кодировка файла, содержащаяся в документе для перевода. .IP "\fB\-l\fR, \fB\-\-localized\fR" 4 .IX Item "-l, --localized" Файл, содержащий локализованный (переведённый) документ. Если вы указали несколько мастер\-файлов, может возникнуть необходимость предоставить несколько файлов локализации, указав данный параметр несколько раз. .IP "\fB\-L\fR, \fB\-\-localized\-charset\fR" 4 .IX Item "-L, --localized-charset" Кодировка файла, содержащего переведённый документ. .IP "\fB\-p\fR, \fB\-\-po\fR" 4 .IX Item "-p, --po" Файл в который будет записан каталог сообщений. Если не задан, то каталог сообщений будет записан в стандартный вывод. .IP "\fB\-o\fR, \fB\-\-option\fR" 4 .IX Item "-o, --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'. .IP "\fB\-h\fR, \fB\-\-help\fR" 4 .IX Item "-h, --help" Отобразить короткую справку. .IP "\fB\-\-help\-format\fR" 4 .IX Item "--help-format" Выводит список поддерживаемых po4a форматов. .IP "\fB\-V\fR, \fB\-\-version\fR" 4 .IX Item "-V, --version" Отобразить версию и завершить работу сценария. .IP "\fB\-v\fR, \fB\-\-verbose\fR" 4 .IX Item "-v, --verbose" Увеличить количество выводимой пояснительной информации. .IP "\fB\-d\fR, \fB\-\-debug\fR" 4 .IX Item "-d, --debug" Вывод отладочной информации. .IP "\fB\-\-msgid\-bugs\-address\fR \fIemail@address\fR" 4 .IX Item "--msgid-bugs-address email@address" Установить адрес для сообщений об ошибках в msgid. По умолчанию, созданные POT\-файлы не имеют поля Report-Msgid-Bugs-To. .IP "\fB\-\-copyright\-holder\fR \fIстрока\fR" 4 .IX Item "--copyright-holder строка" Указать владельца авторских прав в заголовке \s-1POT\s0 файла. Значение по умолчанию: «Free Software Foundation, Inc.» .IP "\fB\-\-package\-name\fR \fIстрока\fR" 4 .IX Item "--package-name строка" Указать имя пакета в заголовке POT\-файла. Значение по умолчанию: «PACKAGE». .IP "\fB\-\-package\-version\fR \fIстрока\fR" 4 .IX Item "--package-version строка" Указать версию пакета в заголовке POT\-файла. Значение по умолчанию: «VERSION». .SS "Преобразование уже существующего перевода в po4a" .IX Subsection "Преобразование уже существующего перевода в po4a" \&\fBpo4a\-gettextize\fR попытается извлечь содержимое заданного переведённого файла и использовать его в качестве msgstr в созданном PO\-файле. Имейте в виду, что этот процесс крайне хрупкий: предполагается что N\-ая строка переведённого файла является переводом N\-ой строки исходного. Естественно, это не будет работать, если у обоих файлов не абсолютно идентичная структура. .PP Внутренне, каждый парсер po4a возвращает синтаксический тип для каждой извлечённой строки. Это и помогает определить рассинхрон файлов во время геттекстизации. Например, если у файлов будет следующая структура, очень маловероятно, что 4\-я строка в переводе (типа «глава») является переводом 4\-й строки в оригинале (типа «параграф»). Скорее в оригинал был добавлен новый параграф или два параграфа оригинала были объединены в переводе. .PP .Vb 1 \& Оригинал Перевод \& \& глава глава \& параграф параграф \& параграф параграф \& параграф глава \& глава параграф \& параграф параграф .Ve .PP \&\fBpo4a\-gettextize\fR 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. .PP 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 \fIfuzzy\fR 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. .PP 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 \fImaster.doc\fR that was used for the translation, and only update the \s-1PO\s0 file against the latest master file once the gettextization was successful. .PP Если вам повезёт и структура обоих документов идеально совпадает, то создание корректного PO\-файла займёт всего несколько секунд. В противном случае вы вскоре поймёте, почему у этого процесса такое уродливое название :). Но помните, что эта грязная работёнка — это та цена, которую придётся заплатить за то, чтобы пользоваться удобствами po4a в дальнейшем. Как только вы завершите процесс преобразования, синхронизация между мастер\-документом и переводами станет полностью автоматической. .PP Даже когда что\-то идёт не так, зачастую сделать геттекстизацию всё равно быстрее, чем переводить всё заново. Например, я смог геттекстизировать существующий французский перевод всей документации Perl всего за один день, даже несмотря на то, что структура многих документов была рассинхронизирована. И это были более чем два мегабайта исходного текста (2 миллиона символов): новый перевод с нуля занял бы несколько месяцев. .SS "Hints and tricks for the gettextization process" .IX Subsection "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 \fBdiff\fR\|(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?). .PP Когда это случается, вся фишка сводится к тому, чтобы совместить выравнивание этих проклятых файловых структур, редактируя их вручную. \fBpo4a\-gettextize\fR довольно подробно описывает, что пошло не так. Он выдаст вам строки, которые не совпадают, их местоположение в документах и тип каждой из них. Кроме того, созданный к моменту сбоя PO\-файл будет сбрасываться в \fIgettextization.failed.po\fR. .PP Here are some other tricks to help you in this tedious process: .IP "\(bu" 4 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 \fBpo4a\fR\|(7)). .IP "\(bu" 4 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 \&\s-1PO\s0 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 \s-1PO\s0 file to start with. .IP "\(bu" 4 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 \s-1PO\s0 file with the document. .IP "\(bu" 4 Если вы как\-либо меняете структуру документа в переводе и это кажется вам оправданным, то, скорее всего, вам следует связаться по этому поводу с его автором. О проблемах оригинального документа нужно сообщать автору оригинального документа. Если вы исправляете их только в своём переводе, то вы исправляете их только для части сообщества. И кроме того, это невозможно при использовании po4a ;) .IP "\(bu" 4 Иногда содержимое абзацев совпадает, но не их типы. То, как именно разрешить эту ситуацию, зависит от формата. В \s-1POD\s0 и man это зачастую происходит из\-за того, что один из них начинается с пробела, а другой — нет. Для этих форматов в таком абзаце (начинающемся с пробела) запрещён перенос строк и, таким образом, он рассматривается, как имеющий другой тип. Просто удалите пробел и всё будет в порядке. Это также может быть вызвано, например, опечаткой в имени тега в \s-1XML.\s0 .Sp Аналогично, два абзаца могут слиться в один в \s-1POD,\s0 когда разделяющая их строка содержит пробелы или когда между \fB=item\fR и содержимым элемента нет пустой строки. .IP "\(bu" 4 Иногда сообщения о рассинхронизации кажутся странными так как перевод привязан не к тома абзац оригинала. Это признак того, что проблема где\-то выше не была обнаружена. Ищите истинную точку рассинхронизации, исследуя содержимое \fIgettextization.failed.po\fR и исправьте проблему в этом месте. .IP "\(bu" 4 В некоторых неблагоприятных обстоятельствах, у вас может появиться ощущение, что po4a съедает некоторые части текста, либо оригинала, либо перевода. \fIgettextization.failed.po\fR указывает на то, что оба файла были сопоставлены правильно вплоть до абзаца N. Но затем происходит (неудачная) попытка сопоставить абзац N+1 оригинального файла не с абзацем N+1 перевода, как следовало бы, а с абзацем N+2. Так, как будто бы, абзац N+1, который вы видите в переводе, просто испарился бы. .Sp Эта печальная ситуация возникает, когда один и тот же абзац повторяется в документе несколько раз. В этом случае новая запись в PO\-файле не создаётся, а к уже существующей добавляется новая сноска. .Sp 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. .Sp Напротив, если один и тот же абзац встречается дважды в оригинальном документе, но переводится не в точности одинаково в разных случаях, у вас создаётся впечатление, будто один из параграфов оригинала просто пропадает. Чтобы исправить проблему, просто скопируйте выберете лучший вариант перевода и скопируйте его вместо второго в переведённом документе. .IP "\(bu" 4 As a final note, do not be too surprised if the first synchronization of your \s-1PO\s0 file takes a long time. This is because most of the msgid of the \s-1PO\s0 file resulting from the gettextization don't match exactly any element of the \s-1POT\s0 file built from the recent master files. This forces gettext to search for the closest one using a costly string proximity algorithm. .Sp For example, the first \fBpo4a\-updatepo\fR of the Perl documentation's French translation (5.5 \s-1MB PO\s0 file) took about 48 hours (yes, two days) while the subsequent ones only take a dozen of seconds. .SH "СМОТРИТЕ ТАКЖЕ" .IX Header "СМОТРИТЕ ТАКЖЕ" \&\fBpo4a\fR\|(1), \fBpo4a\-normalize\fR\|(1), \fBpo4a\-translate\fR\|(1), \fBpo4a\-updatepo\fR\|(1), \&\fBpo4a\fR\|(7). .SH "АВТОРЫ" .IX Header "АВТОРЫ" .Vb 3 \& Денис Барбье (Denis Barbier) \& Николя Франсуа (Nicolas François) \& Мартин Кенсон (Martin Quinson) (mquinson#debian.org) .Ve .SH "АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИИ" .IX Header "АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИИ" Copyright 2002\-2020 by \s-1SPI,\s0 inc. .PP Данная программа является свободным программным обеспечением; вы можете распространять и/или изменять её на условиях Универсальной общественной лицензии (\s-1GPL\s0) \s-1GNU\s0 (см. файл \s-1COPYING\s0).