.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" 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 1p" .TH PO4A 1p "2020-12-09" "Инструменты 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 \- обновление PO\-файлов и переведённой документации за один проход .SH "СИНТАКСИС" .IX Header "СИНТАКСИС" \&\fBpo4a\fR [\fIпараметры\fR] \fIфайл_настроек\fR .SH "ОПИСАНИЕ" .IX Header "ОПИСАНИЕ" po4a (\s-1PO\s0 for anything, \s-1PO\s0 для всего) упрощает поддержку переводов документации, используя обычные инструменты gettext. Основная идея po4a состоит в том, что оно отделяет перевод содержимого от структуры документа. Пошаговое вводное руководство по работе с данным проектом можно посмотреть на странице \fBpo4a\fR\|(7). .PP Если вы запускаете программу \fBpo4a\fR в первый раз, когда у вас есть только файл настроек и сами документы, которые вы собираетесь переводить (называемые мастер\-документами), то она создаёт POT\-файл (также называемый «шаблон перевода»), который содержит все переводимые строки документа в формате, который облегчает труд переводчиков. .PP Такие POT\-файлы можно переводить с помощью специальных редакторов, как, например, \fB\s-1GNOME\s0 Translation Editor\fR, \fBLokalize\fR из \s-1KDE\s0 или \fBpoedit\fR, или же процесс их перевода можно интегрировать в онлайн\-платформу локализации, как \fBweblate\fR или \fBpootle\fR. Результат перевода — это набор PO\-файлов; по одному для каждого языка. .PP Если вы запускаете программу \fBpo4a\fR, когда у вас есть и мастер\-документ, и PO\-файлы, то она создаёт переведённые документы, вставляя содержимое переводов (из PO\-файлов) в структуру оригинального мастер\-документа. .PP Если мастер\-документы будут изменены в процессе работы, po4a обновит \s-1PO\s0 и POT\-файлы в соответствии с изменениями, дабы переводчики без проблем заметили эти изменения и обновили свои переводы. В зависимости от ваших настроек, po4a или отбросит частично переведённые документы, или создаст документ, сочетая текст на Английском (для новых или изменённых абзацев) и на целевом языке перевода (для абзацев уже присутствующих в PO\-файле). .PP По умолчанию переведённые документы создаются, когда переведено, как минимум, 80% содержимого (см. описание параметра \fI\-\-keep\fR ниже). Если вы будете отбрасывать весь перевод в случае, когда он завершён не на все 100%, то это будет обескураживающим фактором для переводчиков; с другой стороны, вы можете вызвать у конечных пользователей затруднения, предоставляя им «переводы», которые слишком далеки от завершения. .SS "Наглядный обзор" .IX Subsection "Наглядный обзор" .Vb 11 \& мастер\-документ \-\-\-\-\-+\-\-\-\-\-\-\-\-\->\-\-\-\-\-\-\-\->\-\-\-\-\-\-\-\-+ \& (создание документа) | | \& V (выполнение po4a) >\-\-+\-\-> переводы \& | | | \& существующие PO\-файлы \->\-> обновлённые PO\-файлы \->\-+ | \& ^ | | \& | V | \& +\-\-\-\-\-\-\-\-\-\-<\-\-\-\-\-\-\-\-\-<\-\-\-\-\-\-\-+ ^ \& (ручной перевод) | \& | \& дополнение \-\->\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ .Ve .PP Мастер\-документы создаются авторами, пишущими документацию. Любые изменения po4a автоматически отображает в PO\-файлах, которые затем обновляются переводчиками. Все изменения в PO\-файлах (как сделанные po4a, так и вручную) автоматически отображаются в переведённых документах. Вы можете сымитировать это поведение с помощью сценариев \fBpo4a\-updatepo\fR\|(1) и \&\fBpo4a\-translate\fR\|(1), вызывая их из make\-файлов, но это монотонное и докучливое занятие (см. \fBpo4a\fR\|(7)). Настоятельно рекомендуется, вместо этого использовать программу \fBpo4a\fR. .SH "ПАРАМЕТРЫ" .IX Header "ПАРАМЕТРЫ" .IP "\fB\-k\fR, \fB\-\-keep\fR" 4 .IX Item "-k, --keep" Минимальное пороговое значение, в процентах, для сохранения (например, для записи) результирующего файла (по умолчанию: 80). То есть, по умолчанию, для того чтобы файл был записан, необходимо перевести как минимум 80%. .IP "\fB\-h\fR, \fB\-\-help\fR" 4 .IX Item "-h, --help" Отобразить короткую справку. .IP "\fB\-M\fR, \fB\-\-master\-charset\fR" 4 .IX Item "-M, --master-charset" Кодировка файлов переводимых документов. Обратите внимание, что все мастер\-документы должны использовать одну и ту же кодировку. .IP "\fB\-L\fR, \fB\-\-localized\-charset\fR" 4 .IX Item "-L, --localized-charset" Кодировка файлов локализованных документов. Обратите внимание, что все переведённые документы должны использовать одну и ту же кодировку. .IP "\fB\-A\fR, \fB\-\-addendum\-charset\fR" 4 .IX Item "-A, --addendum-charset" Кодировка дополнений. Обратите внимание, что все дополнения должны иметь одну и ту же кодировку. .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\-q\fR, \fB\-\-quiet\fR" 4 .IX Item "-q, --quiet" Уменьшить количество выводимой пояснительной информации. .IP "\fB\-d\fR, \fB\-\-debug\fR" 4 .IX Item "-d, --debug" Вывод отладочной информации. .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\-f\fR, \fB\-\-force\fR" 4 .IX Item "-f, --force" Всегда создавать \s-1POT\s0 и PO\-файлы, даже если \fBpo4a\fR считает, что это не требуется. .Sp Поведение по умолчанию (когда параметр \fB\-\-force\fR не установлен) следующее: .RS 4 .Sp .RS 4 Если POT\-файл уже существует, он создаётся повторно, если мастер\-документ или файл настроек был недавно изменён (и если не задан параметр \&\fB\-\-no\-update\fR). POT\-файл также записывается во временный документ и \fBpo4a\fR проверяет, что изменения действительно необходимы. .Sp Кроме того, перевод обновляется (regenerated) только если его мастер\-документ, PO\-файл, один из его дополнений или файл настроек были недавно обновлены. Чтобы избежать попыток обновления переводов, которые не преодолели порогового значения (см. \fB\-\-keep\fR), можно создать файл с расширением \fI.po4a\-stamp\fR (см. \fB\-\-stamp\fR). .RE .RE .RS 4 .Sp Если мастер\-документ включает файлы, вам необходимо использовать флаг \&\fB\-\-force\fR, потому что время изменения включённых файлов не принимается во внимание. .Sp PO\-файлы всегда обновляются из POT\-файлов с помощью \fBmsgmerge \-U\fR. .RE .IP "\fB\-\-stamp\fR" 4 .IX Item "--stamp" Указывает \fBpo4a\fR создать файлы\-заглушки, если перевод не создаётся, поскольку он не преодолел порогового значения. Эти файлы будут называться также как и переведённый документ, с расширением \fI.po4a\-stamp\fR. .Sp Примечание: Параметр активирует только создание \fI.po4a\-stamp\fR файлов. Файлы\-заглушки используются всегда если они существуют, и удаляются при выполнении \fB\-\-rm\-translations\fR или когда файл полностью переведён. .IP "\fB\-\-no\-translations\fR" 4 .IX Item "--no-translations" Не регенерировать переведённые документы, только обновлять \s-1POT\s0 и PO\-файлы. .IP "\fB\-\-no\-update\fR" 4 .IX Item "--no-update" Не менять \s-1POT\s0 и PO\-файлы, только обновить переводы. .IP "\fB\-\-keep\-translations\fR" 4 .IX Item "--keep-translations" Не удалять файлы перевода даже если перевод не соответствует пороговому значению, заданному \fB\-\-keep\fR. Этот параметр указывает po4a не создавать новые переведённые файлы с недостаточным количеством переведённого материала, а сохранять старые переводы, которые находятся в упадке из\-за изменений в мастер\-документах. .Sp ПРЕДУПРЕЖДЕНИЕ: этот флаг изменяет поведение po4a достаточно радикальным образом: ваши переведённые файлы не будут обновляться вообще, пока перевод не улучшится. Используйте этот ключ только если вам больше по нраву поставлять устаревшую, но переведённою документацию, нежели только точную, но непереведённую. .IP "\fB\-\-rm\-translations\fR" 4 .IX Item "--rm-translations" Удалить переведённые файлы (подразумевает \fB\-\-no\-translations\fR). .IP "\fB\-\-no\-backups\fR" 4 .IX Item "--no-backups" Этот флаг ничего не делает начиная с 0.41 и может быть удалён в последующих версиях. .IP "\fB\-\-rm\-backups\fR" 4 .IX Item "--rm-backups" Этот флаг ничего не делает начиная с 0.41 и может быть удалён в последующих версиях. .IP "\fB\-\-translate\-only\fR \fIпереводимый\-файл\fR" 4 .IX Item "--translate-only переводимый-файл" Перевести только указанный файл. Это может быть полезно, чтобы ускорить обработку, когда конфигурационный файл содержит значительное количество файлов. Заметим, что этот параметр не обновляет \s-1PO\s0 и POT\-файлы. Этот параметр может быть указан несколько раз. .IP "\fB\-\-variable\fR \fIпеременная\fR\fB=\fR\fIзначение\fR" 4 .IX Item "--variable переменная=значение" Определяет переменную которая будет использоваться в файле настроек \&\fBpo4a\fR. Каждое появление \fI$(переменная)\fR будет замещено на \&\fIзначение\fR. Данный параметр можно использовать несколько раз. .IP "\fB\-\-srcdir\fR \fIИСХОДНЫЙ_КАТАЛОГ\fR" 4 .IX Item "--srcdir ИСХОДНЫЙ_КАТАЛОГ" Задаёт базовый каталог для всех входных документов, указанных в файле настроек \fBpo4a\fR. .Sp If both \fIdestdir\fR and \fIsrcdir\fR are specified, input files are searched in the following directories, in order: \fIdestdir\fR, the current directory and \&\fIsrcdir\fR. Output files are written to \fIdestdir\fR if specified, or to the current directory. .IP "\fB\-\-destdir\fR \fIКАТАЛОГ_НАЗНАЧЕНИЯ\fR" 4 .IX Item "--destdir КАТАЛОГ_НАЗНАЧЕНИЯ" Задаёт базовый каталог для всех выходных документов, указанных в файле настроек \fBpo4a\fR (см. описание \fB\-\-srcdir\fR выше). .SS "Параметры, изменяющие заголовок POT\-файла" .IX Subsection "Параметры, изменяющие заголовок POT-файла" .IP "\fB\-\-porefs\fR \fIтип\fR" 4 .IX Item "--porefs тип" Задаёт формат сносок в комментариях PO\-файла. Аргумент l<тип> может быть одним из: \fBnever\fR — не выводить никаких сносок, \fBnoline\fR — не выводить номера строк (точнее, все номера строк будут заменены на 1), \fBcounter\fR — заменяет номера строк инкрементным счётчиком и \fBfull\fR — включает полноценные сноски (по умолчанию: \fBfull\fR). .IP "\fB\-\-wrap\-po\fR \fBno\fR|\fBnewlines\fR|\fIчисло\fR (по умолчанию: 76)" 4 .IX Item "--wrap-po no|newlines|число (по умолчанию: 76)" Задаёт, как должны переносится строки в PO\-файле. С помощью этого параметра можно выбрать или чтобы в файлах были удобно расставлены переносы строк, хотя это и может привести к конфликтам в git, или чтобы файлы больше подходили для автоматической обработки, хотя это и снизит удобство чтения оных людьми. .Sp Исторически, gettext переносил строки в PO\-файлах на 77\-м столбце по косметическим соображениям. Этот параметр задаёт поведение po4a. Если в нём указано число, po4a будет переносить строки в PO\-файле после данного столбца и после символов перевода строки в содержимом. Если указано \fBnewlines\fR, то po4a будет разделять msgid и msgstr на строки только в местах перевода строк в самом их содержимом. Если же указано \fBno\fR, то po4a вообще не будет переносить строки в PO\-файле. Строки комментариев со ссылками на местоположение строки в исходном документе всегда разбиваются на строки по усмотрению инструментов gettext, которые используются внутри po4a. .Sp Замечание: этот параметр ни как не влияет на то, как будут расставлены переносы строк внутри самих msgid и msgstr, т.е. на то, как переносы строк будут добавляться к их содержимому. .IP "\fB\-\-master\-language\fR" 4 .IX Item "--master-language" Язык файлов переводимых документов. Обратите внимание, что все мастер\-документы должны быть на одном языке. .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 "Параметры, изменяющие PO\-файлы" .IX Subsection "Параметры, изменяющие PO-файлы" .IP "\fB\-\-msgmerge\-opt\fR \fIпараметры\fR" 4 .IX Item "--msgmerge-opt параметры" Дополнительные параметры для \fBmsgmerge\fR(1). .Sp Примечание: \fB\f(CB$lang\fB\fR будет заменён на текущий язык. .IP "\fB\-\-no\-previous\fR" 4 .IX Item "--no-previous" Данный параметр удаляет параметр \fB\-\-previous\fR из настроек \fBmsgmerge\fR. Это позволяет использовать версии \fBgettext\fR ниже 0.16. .IP "\fB\-\-previous\fR" 4 .IX Item "--previous" Данный параметр добавляет \fB\-\-previous\fR к параметрам, передаваемым \&\fBmsgmerge\fR. Для жтого требуется \fBgettext\fR версии 0.16 или выше; он активирован по умолчанию. .SH "ФАЙЛ НАСТРОЕК" .IX Header "ФАЙЛ НАСТРОЕК" po4a ожидает, что в качестве аргумента ему будет передан файл настроек. Этот файл должен содержать следующие данные: .IP "\(bu" 4 Путь к PO\-файлам и список языков, доступных в проекте; .IP "\(bu" 4 Опционально, некоторые глобальные параметры и, так называемые, псевдонимы настроек (configuration aliases), которые можно использовать в качестве шаблонов для настройки отдельных мастер\-файлов; .IP "\(bu" 4 Список всех мастер\-файлов, которые нужно переводить, и специфические параметры для оных. .PP Каждая строка файла должна содержать директиву, заключённую в квадратные скобки, и её параметры. Комментарии начинаются с символа «#» и продолжаются до конца строки. Конец строки может быть экранирован (с помощью обратного слеша \f(CW\*(C`\e\*(C'\fR), в таком случае комментарий может быть растянут на несколько строк. .PP Some full examples are presented on this page, while other examples can be found in the \f(CW\*(C`t/cfg\*(C'\fR directory of the source distribution. .SS "Поиск \s-1POT\s0 и PO\-файлов" .IX Subsection "Поиск POT и PO-файлов" The simplest solution is to explicitly give the path to \s-1POT\s0 and \s-1PO\s0 files, as follows: .PP .Vb 1 \& [po4a_paths] man/po/project.pot ru:man/po/ru.po fr:man/po/fr.po .Ve .PP Это задаст пути к POT\-файлу, а также к русскому и французскому PO\-файлам. .PP The same information can be written as follows to reduce the risk of copy/paste errors: .PP .Vb 2 \& [po4a_langs] fr ru \& [po4a_paths] man/po/project.pot $lang:man/po/$lang.po .Ve .PP Вместо \f(CW$lang\fR будет автоматически подставлен, код языка из списка, что уменьшает риск ошибок, вызванных копированием/вставкой при добавлении нового языка. .PP You can further compact the same information by only providing the path to the directory containing your translation project, as follows. .PP .Vb 1 \& [po_directory] man/po/ .Ve .PP The provided directory must contain a set of \s-1PO\s0 files, each named \fI\s-1XX\s0.po\fR with \f(CW\*(C`XX\*(C'\fR the \s-1ISO 639\-1\s0 of the language used in this file. The directory must also contain a single \s-1POT\s0 file, with the \f(CW\*(C`.pot\*(C'\fR file extension. For the first run, this file can be empty but it must exist (po4a cannot guess the name to use before the extension). .PP Note that you must choose only one between \f(CW\*(C`po_directory\*(C'\fR and \&\f(CW\*(C`po4a_paths\*(C'\fR. The first one (\f(CW\*(C`po_directory\*(C'\fR) is more compact, further reduces the risk of copy/paste error, but forces you to use the expected project structure and file names. The second one (\f(CW\*(C`po4a_paths\*(C'\fR), is more explicit, probably more readable, and advised when you setup your first project with po4a. .PP \fIЦентрализованные или раздельные PO\-файлы?\fR .IX Subsection "Централизованные или раздельные PO-файлы?" .PP By default, po4a produces one single \s-1PO\s0 file per target language, containing the whole content of your translation project. As your project grows, the size of these files may become problematic. When using weblate, it is possible to specify priorities for each translation segment (i.e., msgid) so that the important ones get translated first. Still, some translation teams prefer to split the content in several files. .PP Чтобы использовать отдельный PO\-файл для каждого мастер\-файла, просто добавьте \f(CW$master\fR в имя своего PO\-файла в директиве \f(CW\*(C`[po4a_paths]\*(C'\fR: .PP .Vb 1 \& [po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po .Ve .PP Если возникают конфликты из\-за того, что у нескольких файлов одинаковые имена, то имя мастер\-файла может быть задано добавлением параметра \&\f(CW\*(C`master:file=\*(C'\fR\fIимя\fR: .PP .Vb 4 \& [po4a_langs] de fr ru \& [po4a_paths] l10n/po/$master.pot $lang:l10n/po/$master.$lang.po \& [type: xml] foo/gui.xml $lang:foo/gui.$lang.xml master:file=foo\-gui \& [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml master:file=bar\-gui .Ve .PP В раздельном режиме \fBpo4a\fR создаёт временный сборник всех переводов во время обновления PO\-файлов, чтобы объединить перевод одинаковых строк из различных PO\-файлов. Если два PO\-файла имеют различные переводы для одной и той же строки, \fBpo4a\fR пометит данные переводы как неточные и добавит оба варианта в каждый PO\-файл, содержащий эту строку. Затем, когда переводчик снимет пометку «неточно» хотя бы в одном PO\-файле, перевод данной строки будет обновлён во всех PO\-файлах автоматически. .SS "Задание документов для перевода" .IX Subsection "Задание документов для перевода" Вы также должны перечислить список документов, которые следует переводить. Для каждого мастер\-файла нужно указать, какой использовать парсер формата, местоположение, куда записывать переведённые документы, а также, по необходимости, некоторые дополнительные параметры, например: .PP .Vb 5 \& [type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \e \& ru:doc/ru/mein_kram.sgml \& [type: man] script fr:doc/fr/script.1 ru:doc/ru/script.1 \& [type: docbook] doc/script.xml fr:doc/fr/script.xml \e \& ru:doc/ru/script.xml .Ve .PP Но, опять же, такие тяжеловесные конструкции сложно читать и изменять, например, когда нужно добавить новый язык. Намного проще будет реорганизовать всё это с помощью шаблонов с \f(CW$lang\fR: .PP .Vb 3 \& [type: sgml] doc/my_stuff.sgml $lang:doc/$lang/my_stuff.sgml \& [type: man] script.1 $lang:po/$lang/script.1 \& [type: docbook] doc/script.xml $lang:doc/$lang/script.xml .Ve .SS "Задание параметров" .IX Subsection "Задание параметров" Есть два вида параметров: \fIпараметры po4a\fR, которые задают значения по умолчанию для параметров командной строки самого po4a, и \fIпараметры форматов\fR, которые изменяют поведение парсера конкретного формата. \fIПараметром po4a\fR будет являться, например, если вы зададите в своём файле настроек, что значение по умолчанию параметра командной строки \&\fB\-\-keep\fR будет 50% вместо 80%. \fIПараметры форматов\fR описаны на справочной странице каждого отдельного модуля парсера конкретного формата, например \&\fBLocale::Po4a::Xml\fR\|(3pm). Вы, например, можете передать \fBnostrip\fR парсеру \&\s-1XML,\s0 чтобы он не убирал пробелы у извлекаемых им строк. .PP Вы можете передать эти параметры для конкретного мастер\-файла или даже для перевода файла на конкретный язык, используя \f(CW\*(C`opt:\*(C'\fR и \f(CW\*(C`opt_XX:\*(C'\fR для языка \&\f(CW\*(C`XX\*(C'\fR. В примере ниже, параметр \fBnostrip\fR передаётся парсеру \s-1XML\s0 (для всех языков), а порог завершения перевода будет уменьшен до 0% только для французского (чтобы он никогда не отбрасывался). .PP .Vb 1 \& [type:xml] toto.xml $lang:toto.$lang.xml opt:"\-o nostrip" opt_fr:"\-\-keep 0" .Ve .PP В любом случае, такие настройки должны находится в конце строки. Имена файлов должны идти вначале, затем дополнение, если есть (см. ниже), и только затем параметры. Группировка разных частей строки параметров не очень важна, ибо внутри себя po4a просто соединяет их все в одну строку. Следующие варианты абсолютно эквивалентны: .PP .Vb 3 \& [type:xml] toto.xml $lang:toto.$lang.xml opt:"\-\-keep 20" opt:"\-o nostrip" opt_fr:"\-\-keep 0" \& [type:xml] toto.xml $lang:toto.$lang.xml opt:"\-\-keep 20 \-o nostrip" opt_fr:"\-\-keep 0" \& [type:xml] toto.xml $lang:toto.$lang.xml opt:\-\-keep opt:20 opt:\-o opt:nostrip opt_fr:\-\-keep opt_fr:0 .Ve .PP Заметьте, что параметры, специфичные для отдельных языков не используются во время создания POT\-файла. Например, невозможно передать \fBnostrip\fR парсеру только для французского перевода, так как тот же самый POT\-файл используется для обновления всех языков. Так что специфичными для языка могут быть только те параметры, которые используются во время создания перевода, как параметр \&\f(CW\*(C`\-\-keep\*(C'\fR. .PP \fIНастройка псевдонимов (aliases)\fR .IX Subsection "Настройка псевдонимов (aliases)" .PP Наилучшим способом передать одинаковые параметры различным файлам будет определить псевдоним (alias) типа, как это показано ниже. В примере \f(CW\*(C`\-\-keep 0\*(C'\fR передаётся всех документов на итальянский с помощью типа \f(CW\*(C`test\*(C'\fR, который является расширением типа \f(CW\*(C`man\*(C'\fR: .PP .Vb 2 \& [po4a_alias:test] man opt_it:"\-\-keep 0" \& [type: test] man/page.1 $lang:man/$lang/page.1 .Ve .PP Вы также можете расширить существующий тип, использовав то же самое имя для псевдонима. Это не будет считаться ошибкой рекурсивного определения: .PP .Vb 2 \& [po4a_alias:man] man opt_it:"\-\-keep 0" \& [type: man] man/page.1 $lang:man/$lang/page.1 .Ve .PP \fIГлобальные параметры по умолчанию\fR .IX Subsection "Глобальные параметры по умолчанию" .PP Вы также можете использовать строки с директивой \f(CW\*(C`[options]\*(C'\fR, чтобы определить параметры, которые должны использоваться для всех файлов, независимо от их типа. .PP .Vb 1 \& [options] \-\-keep 20 \-\-option nostrip .Ve .PP Как и параметры командной строки, параметры передаваемые в файле настроек можно сокращать: .PP .Vb 1 \& [options] \-k 20 \-o nostrip .Ve .PP \fIПриоритет параметров\fR .IX Subsection "Приоритет параметров" .PP Параметры из каждого источника соединяются в одну строку, что гарантирует, что значения по умолчанию могут быть переопределены более специфическими параметрами. Порядок приоритетов следующий: .IP "\(bu" 4 Директивы \f(CW\*(C`[options]\*(C'\fR задают значения по умолчанию, которые могут быть переопределены любым другим источником. .IP "\(bu" 4 Затем идут псевдонимы типов.При этом настройки, специфичные для конкретных языков переопределяют те что применяются ко всем языкам. .IP "\(bu" 4 Настройки, специфичные для конкретного мастер\-файла переопределяют и настройки по умолчанию и те что заданы в псевдонимах типов. В данном случае настройки, специфичные для языков, также переопределяют общие. .IP "\(bu" 4 Наконец, параметры, переданные в командной строке переопределяют любые параметры из файла настройки. .PP \fIПример\fR .IX Subsection "Пример" .PP Пример, показывающий, как следует экранировать пробелы и кавычки: .PP .Vb 1 \& [po_directory] man/po/ \& \& [options] \-\-master\-charset UTF\-8 \& \& [po4a_alias:man] man opt:"\-o \e"mdoc=NAME,SEE ALSO\e"" \& [type:man] t\-05\-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \e \& opt:"\-k 75" opt_it:"\-L UTF\-8" opt_fr:\-\-verbose .Ve .SS "Дополнение (addendum): добавление дополнительного содержимого в перевод" .IX Subsection "Дополнение (addendum): добавление дополнительного содержимого в перевод" Если вы хотите добавить дополнительный раздел в перевод, например отдать дань уважения переводчику, тогда вам нужно указать дополнение, при определении мастер\-документа. Подробности о синтаксисе файлов\-дополнений можно получить на справочной странице \fBpo4a\fR\|(7). .PP .Vb 2 \& [type: pod] script fr:doc/fr/script.1 \e \& add_fr:doc/l10n/script.fr.add .Ve .PP Вы также можете использовать шаблоны языков: .PP .Vb 2 \& [type: pod] script $lang:doc/$lang/script.1 \e \& add_$lang:doc/l10n/script.$lang.add .Ve .PP Если дополнение не получается применить, то весь перевод отбрасывается. .PP \fIМодификаторы объявления дополнений\fR .IX Subsection "Модификаторы объявления дополнений" .PP Модификаторы дополнений могут делать файл настройки проще, когда не все языки имеют дополнение или когда список дополнений меняется от языка к языку. Модификатор — это один символ, стоящий перед именем файла. .IP "\fB?\fR" 2 .IX Item "?" Использовать файл \fIпуть_к_дополнению\fR, если этот файл существует, в противном случае — ничего не делать. .IP "\fB@\fR" 2 .IX Item "@" \&\fIпуть_к_дополнению\fR является не обычным дополнением, а файлом содержащим список дополнений, по одному в каждой строке. Каждое такое дополнение также могут предварять свои модификаторы. .IP "\fB!\fR" 2 .IX Item "!" \&\fIпуть_к_дополнению\fR отбрасывается, он не загружается и не будет загружаться никакими будущими определениями дополнений. .PP Например, чтобы включить дополнение для любого языка, для которого оно существует можно сделать следующее (если дополнение не существует, то сообщение об ошибке не будет выдано): .PP .Vb 1 \& [type: pod] script $lang:doc/$lang/script.1 add_$lang:?doc/l10n/script.$lang.add .Ve .PP Следующий пример задаёт список дополнений для каждого языка: .PP .Vb 1 \& [type: pod] script $lang:doc/$lang/script.1 add_$lang:@doc/l10n/script.$lang.add .Ve .SS "Фильтрация переведённых строк" .IX Subsection "Фильтрация переведённых строк" Иногда, вам хочется скрыть некоторые строки от переводчиков. Для этого вы можете задать параметр \f(CW\*(C`pot_in\*(C'\fR в определении мастер\-файла, дабы указать имя файла, из которого следует извлекать строки для создания POT\-файла для перевода вместо настоящего мастер\-файла. Например: .PP .Vb 3 \& [type:docbook] book.xml \e \& pot_in:book\-filtered.xml \e \& $lang:book.$lang.xml .Ve .PP С такими настройками строки для перевода будут извлекаться из \&\fIbook\-filtered.xml\fR (который должен быть создан до вызова \fBpo4a\fR), а переведённые документы будут собираться на основе \fIbook.xml\fR. В результате, все строки, которые есть только в \fIbook.xml\fR, но не в \fIbook\-filtered.xml\fR не будут включены в PO\-файлы, что предотвратит возможность того, что переводчики переведут что\-то, что не должно быть переведено. Таким образом, эти строки останутся без изменений во время создания переведённых документов. Это, конечно, снижает фактический уровень готовности перевода, так что вам придётся снизить значение параметра \f(CW\*(C`\-\-keep\*(C'\fR, дабы документ всё равно создавался. .SS "ПРИМЕР ФАЙЛА НАСТРОЕК" .IX Subsection "ПРИМЕР ФАЙЛА НАСТРОЕК" \&\s-1TODO:\s0 Этот раздел действительно полезен? .PP Предположим, что вы сопровождаете программу \fBfoo\fR, у которой есть man\-страница \fIman/foo.1\fR, которая изначально поддерживается только на английском. Теперь вы как upstream или downstream сопровождающий хотите создать и поддерживать перевод. Сначала вам надо создать POT\-файл, который вы позже отправите переводчикам, с помощью \fBpo4a\-gettextize\fR\|(1). .PP Так что в нашем случае мы бы выполнили .PP .Vb 1 \& cd man && po4a\-gettextize \-f man \-m foo.1 \-p foo.pot .Ve .PP Затем вы, вероятно, отправите этот файл в соответствующие группы перевода или предложите его для скачивания на своём web\-сайте. .PP Теперь, предположим, вы получили три перевода перед выпуском новой версии вашего пакета: \fIde.po\fR (включая файл дополнений \fIde.add\fR), \fIsv.po\fR и \&\fIpt.po\fR. Поскольку вы не хотите менять свой \fIMakefile\fR всякий раз, когда вым присылают новый перевод, вы можете воспользоваться \fBpo4a\fR с соответствующим файлом конфигурации. Давайте назовём его \fIpo4a.cfg\fR. В нашем примере он будет иметь следующий вид: .PP .Vb 1 \& [po_directory] man/po4a/po/ \& \& [type: man] man/foo.1 $lang:man/translated/$lang/foo.1 \e \& add_$lang:?man/po4a/add_$lang/$lang.add opt:"\-k 80" .Ve .PP В этом примере мы предположим, что ваши генерируемые переведённые man\-страницы (а также все PO\-файлы и файлы дополнений) должны хранится в \&\fIman/translated/$lang/\fR (и соответственно в \fIman/po4a/po/\fR и \&\fIman/po4a/add_$lang/\fR). В нашем примере каталог \fIman/po4a/po/\fR будет содержать: \fIde.po\fR, \fIpt.po\fR и \fIsv.po\fR, а каталог \fIman/po4a/add_de/\fR будет содержать \fIde.add\fR. .PP Отметим, использование модификатора \fB?\fR т.к. только с немецким переводом (\fIde.po\fR)вам прислали файл дополнений. .PP Чтобы фактически собрать переводы man\-страниц, вам осталось бы (только один раз!) добавить следующую строку к цели \fBbuild\fR соответствующего \&\fIMakefile\fR\-а: .PP .Vb 1 \& po4a po4a.cfg .Ve .PP Как только это сделано, вам более не нужно менять \fIMakefile\fR, когда готовы новые переводы, то есть если французская команда присылает вам \fIfr.po\fR и \&\fIfr.add\fR, то вы просто кладёте их соответственно в \fIman/po4a/po/\fR и \&\fIman/po4a/add_fr/\fR и во время следующей сборки французский перевод автоматически создаётся в \fIman/translated/fr/\fR. .PP Заметьте, что вам по\-прежнему нужна подходящая цель, чтобы устанавливать локализованные man\-страницы вместе с Английскими. .PP В заключении, если вы не храните сгенерированные файлы в вашей системе контроля версий, вам также понадобится строка в вашей цели \fBclean\fR: \-rm \-rf man/translated .SH "СМОТРИТЕ ТАКЖЕ" .IX Header "СМОТРИТЕ ТАКЖЕ" \&\fBpo4a\-gettextize\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).