.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" 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 7" .TH PO4A 7 "2023-01-03" "Инструменты 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 \- платформа для перевода документации и других материалов .SH "Введение" .IX Header "Введение" Ниже приводится дополнение на любом языке, но только если оно существует. Если дополнение не существует, об ошибке не сообщается. .PP Этот документ служит введением в проект po4a, ориентированным на потенциальных пользователей, рассматривающих возможность использования этого инструмента, и на любознательных, желающих понять, почему все происходит именно так, как происходит. .SH "Почему именно po4a?" .IX Header "Почему именно po4a?" Философия свободного программного обеспечения (ПО) состоит в том, чтобы сделать технологии по\-настоящему доступными всем. Но лицензирование — это не единственное, о чём стоит задуматься: непереведённое свободное ПО бесполезно для неанглоговорящих пользователей. И нам предстоит ещё кое\-какая работа, чтобы сделать его доступным по\-настоящему для всех. .PP Эта ситуация хорошо понятна большинству проектов, и все сейчас убеждены в необходимости переводить все. Тем не менее, фактические переводы представляют собой огромную работу многих людей, которая осложняется небольшими техническими трудностями. .PP К счастью, у ПО с открытым исходным кодом достаточно хорошие переводы, которые удобно поддерживать благодаря инструментам из пакета gettext. Они извлекают строки для перевода из программ, и предоставляют их переводчикам в единообразном формате (называемом PO\-файлы, или translation catalogs, каталоги переводов).Целая экосистема различных инструментов выросла вокруг оных, дабы помочь переводчикам собственно переводить эти PO\-файлы. Результат их работы затем используется библиотекой gettext во время исполнения программы, чтобы отображать переведённые сообщения пользователю. .PP Что касается документации, то здесь ситуация все еще несколько неутешительна. Поначалу перевод документации может показаться проще, чем перевод программы, поскольку кажется, что нужно просто скопировать исходный файл документации и начать переводить содержимое. Однако, когда в исходную документацию вносятся изменения, отслеживание этих изменений быстро превращается в кошмар для переводчиков. Если выполнять эту задачу вручную, она становится неприятной и чреватой ошибками. .PP Устаревшие переводы часто хуже, чем отсутствие перевода вообще. Конечные пользователи могут быть обмануты документацией, описывающей старое поведение программы. Более того, они не могут напрямую взаимодействовать с сопровождающими, поскольку те не говорят по\-английски. Кроме того, сопровождающий не может устранить проблему, поскольку не знает всех языков, на которые переведена документация. Эти трудности, часто вызванные плохим инструментарием, могут подорвать мотивацию добровольных переводчиков, что еще больше усугубляет проблему. .PP \&\fBЦель проекта po4a \- облегчить работу переводчиков документации\fR. В частности, он делает переводы документации \fIподдерживаемыми\fR. .PP Идея заключается в повторном использовании и адаптации подхода gettext к этой области. Как и в gettext, тексты извлекаются из оригинальных мест и представляются переводчикам в виде каталогов переводов \s-1PO.\s0 Переводчики могут использовать классические инструменты gettext для контроля за выполнением работы, сотрудничества и организации команд. po4a затем вставляет переводы непосредственно в структуру документации для создания переведенных исходных файлов, которые можно обрабатывать и распространять так же, как и английские файлы. Любой абзац, который не переведен, остается на английском языке в итоговом документе, гарантируя, что конечные пользователи никогда не увидят в документации устаревший перевод. .PP Это автоматизирует большую часть тяжелой работы по обслуживанию перевода. Обнаружить абзацы, нуждающиеся в обновлении, становится очень просто, а процесс полностью автоматизирован, когда элементы перестраиваются без дополнительных изменений. Конкретная проверка также может быть использована для снижения вероятности ошибок форматирования, которые приведут к поломке документа. .PP Полный список достоинств и недостатков этого подхода перечислен в разделе «\fBЧасто задаваемые вопросы\fR» ниже в этом документе. .SS "Поддерживаемые форматы" .IX Subsection "Поддерживаемые форматы" На данный момент этот подход был успешно воплощён для нескольких форматов: .IP "man (зрелый парсер)" 4 .IX Item "man (зрелый парсер)" Старый добрый формат man\-страниц, который используют так много программ. Поддержка po4a приходится здесь очень кстати, ибо этот формат в некоторой степени сложен, и не особо дружелюбен к новичкам. .Sp Модуль \fBLocale::Po4a::Man\fR\|(3pm) также поддерживает формат mdoc, используемый в \s-1BSD\s0 man pages (они также довольно распространены в Linux). .IP "AsciiDoc (зрелый парсер)" 4 .IX Item "AsciiDoc (зрелый парсер)" Этот формат представляет собой легкий формат разметки, предназначенный для облегчения составления документации. Например, он используется для документирования системы git. Эти manpages переведены с помощью po4a. .Sp Подробнее см. в разделе Locale::Po4a::AsciiDoc. .IP "pod (зрелый парсер)" 4 .IX Item "pod (зрелый парсер)" Это формат встроенной документации языка Perl (Perl Online Documentation). Сам язык и его расширения документируются с помощью этого формата, а также и большинство существующих сценариев perl. Это делает проще поддержать документацию близкой к исходному коду, так как они вместе находятся в одном и том же файле. Это делает проще жизнь программиста, но, к сожалению, не жизнь переводчика. .Sp Подробнее см. в разделе Locale::Po4a::Pod. .IP "sgml (зрелый парсер)" 4 .IX Item "sgml (зрелый парсер)" Даже если он и заменён \s-1XML\s0 в наши дни, этот формат всё ещё используется в тех документах, что длиннее нескольких экранов. Он может даже использоваться для целых книг. Обновление переводов таких длинных документов может быть настоящим вызовом. В частности, \fBdiff\fR зачастую показывает себя абсолютно бесполезным, когда в исходном тексте изменяются отступы после обновления. К счастью, po4a может с этим помочь. .Sp На данный момент поддерживаются только DebianDoc и DocBook \s-1DTD,\s0 но добавлять поддержку новых \s-1DTD\s0 достаточно просто. Возможно даже использование po4a для перевода неизвестного \s-1SGML DTD,\s0 вообще не вмешиваясь в исходный код; достаточно только предоставить всю необходимую информацию в командной строке. См. подробности в \fBLocale::Po4a::Sgml\fR\|(3pm). .IP "TeX / LaTeX (зрелый парсер)" 4 .IX Item "TeX / LaTeX (зрелый парсер)" Формат LaTeX — это основной формат публикаций, используемый в мире Свободного ПО. .Sp Модуль \fBLocale::Po4a::LaTeX\fR\|(3pm) был проверен на документации Python, одной книге и нескольких презентациях. .IP "text (зрелый парсер)" 4 .IX Item "text (зрелый парсер)" Формат Text является базовым для многих форматов, включающих длинные блоки текста, включая Markdown, fortunes, \s-1YAML\s0 front matter section, debian/changelog и debian/control. .Sp Поддерживает общий формат, используемый в генераторах статических сайтов, \s-1README\s0 и других системах документации. Подробности смотрите в разделе \fBLocale::Po4a::Text\fR\|(3pm). .IP "xml and \s-1XHMTL\s0 (похоже, зрелый парсер)" 4 .IX Item "xml and XHMTL (похоже, зрелый парсер)" Формат \s-1XML\s0 является базовым для многих форматов документации. .Sp На данный момент, po4a поддерживает DocBook \s-1DTD\s0 (cм. \fBLocale::Po4a::Docbook\fR\|(3pm)) и \s-1XHTML.\s0 .IP "BibTex (похоже, зрелый парсер)" 4 .IX Item "BibTex (похоже, зрелый парсер)" Формат BibTex используется наряду с LaTex для форматирования списков ссылок (библиографий). .Sp Подробнее см. в разделе Locale::Po4a::BibTex. .IP "Docbook (похоже, зрелый парсер)" 4 .IX Item "Docbook (похоже, зрелый парсер)" Язык разметки на основе \s-1XML,\s0 использующий семантические теги для описания документов. .Sp Более подробную информацию см. в Locale::Po4a:Docbook. .IP "Guide \s-1XML\s0 (похоже, зрелый парсер)" 4 .IX Item "Guide XML (похоже, зрелый парсер)" Формат документации \s-1XML.\s0 Этот модуль был разработан специально для помощи в поддержке и сопровождении переводов документации Gentoo Linux по крайней мере до марта 2016 года (по данным Wayback Machine). С тех пор Gentoo перешла на XML\-формат DevBook. .Sp Более подробную информацию смотрите в Locale::Po4a:Guide. .IP "Wml (похоже, зрелый парсер)" 4 .IX Item "Wml (похоже, зрелый парсер)" Язык веб\-разметки, не путайте \s-1WML\s0 с \s-1WAP,\s0 используемым в мобильных телефонах. Этот модуль основан на модуле Xhtml, который сам основан на модуле XmL. .Sp Более подробную информацию смотрите в разделе Locale::Po4a::Wml. .IP "Yaml (похоже, зрелый парсер)" 4 .IX Item "Yaml (похоже, зрелый парсер)" Строгий суперсет \s-1JSON. YAML\s0 часто используется в качестве системных или конфигурационных проектов. \s-1YAML\s0 лежит в основе программы Ansible компании Red Hat. .Sp Более подробную информацию см. в разделе Locale::Po4a::Yaml. .IP "RubyDoc (похоже, зрелый парсер)" 4 .IX Item "RubyDoc (похоже, зрелый парсер)" Формат Ruby Document (\s-1RD\s0), первоначально формат документации по умолчанию для Ruby и Ruby\-проектов до преобразования в RDoc в 2002 году. Хотя, по\-видимому, японская версия справочного руководства по Ruby все еще использует \s-1RD.\s0 .Sp Более подробную информацию см. в разделе Locale::Po4a::Yaml. .IP "Halibut (похоже, экспериментальный парсер)" 4 .IX Item "Halibut (похоже, экспериментальный парсер)" Система создания документации, с элементами, похожими на TeX, debiandoc-sgml, TeXinfo и другие, разработанная Саймоном Тэтхемом, разработчиком PuTTY. .Sp Более подробную информацию см. в разделе Locale::Po4a:Halibut. .IP "Ini (похоже, экспериментальный парсер)" 4 .IX Item "Ini (похоже, экспериментальный парсер)" Формат файла конфигурации, популярный в MS-DOS. .Sp Более подробную информацию смотрите в разделе Locale::Po4a::Ini. .IP "texinfo (крайне экспериментальный парсер)" 4 .IX Item "texinfo (крайне экспериментальный парсер)" Вся документация \s-1GNU\s0 написана в этом формате (вообще говоря, это одно из необходимых условий, чтобы стать официальным проектом \s-1GNU\s0). Поддержка \fBLocale::Po4a::Texinfo\fR\|(3pm) в po4a пока в зачаточном состоянии. Пожалуйста сообщайте об ошибках и запрашивайте новые возможности, когда требуется. .IP "Другие поддерживаемые форматы" 4 .IX Item "Другие поддерживаемые форматы" Po4a также может обрабатывать некоторые более редкие или специализированные форматы, такие как документация опций компиляции для ядер Linux 2.4+ (Locale::Po4a::KernelHelp) или диаграммы, создаваемые инструментом dia (Locale::Po4a:Dia). Добавление нового формата часто очень просто, и главная задача состоит в том, чтобы придумать парсер для вашего целевого формата. Подробнее об этом см. в \fBLocale::Po4a::TransTractor\fR\|(3pm). .IP "Не поддерживаемые форматы" 4 .IX Item "Не поддерживаемые форматы" К сожалению, в po4a всё ещё нет поддержки нескольких форматов документации. Поддержку многих из них было бы не так сложно добавить. И это включает не только форматы документации, но и, например, описание пакетов (deb и rpm), вопросы, задаваемые интерактивными сценариями установки пакетов, файлы changelogs для пакетов, и все специализированные форматы файлов, которые используются в программах, такие как сценарии игр или файлы ресурсов wine. .SH "Использование po4a" .IX Header "Использование po4a" Исторически po4a был построен на основе четырех скриптов, каждый из которых выполнял определенную задачу. \fBpo4a\-gettextize\fR\|(1) помогает загружать переводы и, по желанию, конвертировать существующие проекты переводов в po4a. \fBpo4a\-updatepo\fR\|(1) отражает изменения в оригинальной документации в соответствующих po\-файлах. \fBpo4a\-translate\fR\|(1) создает переведенный исходный файл из исходного файла и соответствующего PO\-файла. Кроме того, \fBpo4a\-normalize\fR\|(1) в основном полезен для отладки парсеров po4a, так как он создает непереведенный документ из исходного. Это облегчает поиск ошибок, вносимых процессом синтаксического анализа. .PP Most projects only require the features of \fBpo4a\-updatepo\fR\|(1) and \fBpo4a\-translate\fR\|(1), but these scripts proved to be cumbersome and error prone to use. If the documentation to translate is split over several source files, it is difficult to keep the \s-1PO\s0 files up to date and build the documentation files correctly. As an answer, a all-in-one tool was provided: \fBpo4a\fR\|(1). This tool takes a configuration file describing the structure of the translation project: the location of the \s-1PO\s0 files, the list of files to translate, and the options to use, and it fully automates the process. When you invoke \fBpo4a\fR\|(1), it both updates the \s-1PO\s0 files and regenerate the translation files that need to. If everything is already up to date, \fBpo4a\fR\|(1) does not change any file. .PP В остальной части этого раздела приводится обзор использования интерфейса скриптов po4a. Большинство пользователей, вероятно, предпочтут использовать инструмент \*(L"все в одном\*(R", который описан в документации \fBpo4a\fR\|(1). .SS "Наглядный обзор сценариев po4a" .IX Subsection "Наглядный обзор сценариев po4a" Следующая схема дает представление о том, как можно использовать каждый сценарий po4a. Здесь \fImaster.doc\fR \- это пример названия документации, подлежащей переводу; \fI\s-1XX\s0.doc\fR \- это тот же документ, переведенный на язык \s-1XX,\s0 а \fIdoc.XX.po\fR \- это каталог переводов для этого документа на язык \s-1XX.\s0 Авторы документации в основном будут иметь дело с \fImaster.doc\fR (который может быть manpage, XML\-документом, файлом asciidoc или подобным); переводчики в основном будут иметь дело с PO\-файлом, а конечные пользователи будут видеть только файл \fI\s-1XX\s0.doc\fR. .PP .Vb 10 \& мастер.doc \& | \& V \& +<\-\-\-\-<\-\-\-\-+<\-\-\-\-\-<\-\-\-\-\-<\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\->\-\-\-\-\-\-\-\->\-\-\-\-\-\-\-+ \& : | | : \& {перевод} | { обновление мастер.doc } : \& : | | : \& XX.doc | V V \&(необязательно) | мастер.doc \->\-\-\-\-\-\-\-\->\-\-\-\-\-\->+ \& : | (новый) | \& V V | | \& [po4a\-gettextize] doc.XX.po \-\->+ | | \& | (старый) | | | \& | ^ V V | \& | | [po4a\-updatepo] | \& V | | V \& перевод.pot ^ V | \& | | doc.XX.po | \& | | (неточный) | \& { перевод } | | | \& | ^ V V \& | | {ручное редактирование} | \& | | | | \& V | V V \& doc.XX.po \-\-\->\-\-\-\->+<\-\-\-<\-\- doc.XX.po дополнение мастер.doc \& (начальный) (актуальный) (необязательно) (актуальный) \& : | | | \& : V | | \& +\-\-\-\-\->\-\-\-\-\->\-\-\-\-\->\-\-\-\-\-\-> + | | \& | | | \& V V V \& +\-\-\-\-\-\->\-\-\-\-\-+\-\-\-\-\-\-<\-\-\-\-\-\-+ \& | \& V \& [po4a\-translate] \& | \& V \& XX.doc \& (актуальный) .Ve .PP Эта схема сложна, но на практике только правая часть (включающая \fBpo4a\-updatepo\fR\|(1) и \fBpo4a\-translate\fR\|(1)) используется после установки и настройки проекта. .PP В левой части показано, как \fBpo4a\-gettextize\fR\|(1) можно использовать для преобразования существующего проекта перевода в инфраструктуру po4a. Этот скрипт берет оригинальный документ и его переведенный аналог и пытается построить соответствующий PO\-файл. Такое ручное преобразование довольно громоздко (подробнее см. документацию \fBpo4a\-gettextize\fR\|(1)), но оно необходимо только один раз для преобразования существующих переводов. Если у вас нет переводов для преобразования, вы можете забыть об этом и сосредоточиться на нужной части схемы. .PP В верху правой части, изображены действия автора оригинала — обновление документации. В середине правой части показывает автоматические действия, производимые \fBpo4a\-updatepo\fR\|(1). Новые материалы извлекаются и сравниваются с существующим переводом. Для тех частей, которые не были изменены используется уже существующий перевод, а те части, которые были изменены частично соединяются с уже существующим переводом, но с пометкой «неточно» (fuzzy), указывающей, что перевод должен быть обновлён. Новые или сильно изменённые части оказываются непереведёнными. .PP Затем, в разделе \fIручное редактирование\fR описываются действия переводчиков, которые изменяют файлы \s-1PO,\s0 чтобы обеспечить перевод каждой оригинальной строки и абзаца. Это может быть сделано с помощью специального редактора, такого как \fB\s-1GNOME\s0 Translation Editor\fR, \s-1KDE\s0's \fBLokalize\fR или \fBpoedit\fR, или с помощью онлайн\-платформы локализации, такой как \fBweblate\fR или \fBpootle\fR. Результатом перевода является набор PO\-файлов, по одному на каждый язык. Более подробную информацию см. в документации gettext. .PP В нижней части рисунка показано, как \fBpo4a\-translate\fR\|(1) создает переведенный исходный документ из исходного документа \fImaster.doc\fR и каталога переводов \fIdoc.XX.po\fR, который был обновлен переводчиками. Структура документа используется повторно, а оригинальное содержание заменяется его переведенным аналогом. По желанию можно использовать дополнение, чтобы добавить к переводу дополнительный текст. Это часто используется для добавления имени переводчика в окончательный документ. Подробности см. ниже. .PP Как уже отмечалось, программа \fBpo4a\fR\|(1) объединяет результаты отдельных сценариев, обновляя PO\-файлы и переведенный документ за один вызов. Основополагающая логика остается прежней. .SS "Начало нового перевода" .IX Subsection "Начало нового перевода" Если вы используете \fBpo4a\fR\|(1), то для начала перевода не требуется никаких специальных шагов. Вам просто нужно перечислить языки в конфигурационном файле, и недостающие PO\-файлы будут созданы автоматически. Естественно, переводчик должен будет затем предоставить переводы для каждого содержимого, используемого в ваших документах. \fBpo4a\fR\|(1) также создает файл \s-1POT,\s0 то есть файл шаблона \s-1PO.\s0 Потенциальные переводчики могут перевести ваш проект на новый язык, переименовав этот файл и предоставив переводы на своем языке. .PP Если вы предпочитаете использовать отдельные скрипты по отдельности, то для создания файла \s-1POT\s0 следует использовать \fBpo4a\-gettextize\fR\|(1) следующим образом. Затем этот файл можно скопировать в \fI\s-1XX\s0.po\fR, чтобы инициировать новый перевод. .PP .Vb 1 \& $ po4a\-gettextize \-\-format <формат> \-\-master <мастер.doc> \-\-po <переводы.pot> .Ve .PP Мастер\-документ используется на входе, а файл \s-1POT\s0 является выходом этого процесса. .SS "Интеграция изменений в исходный документ" .IX Subsection "Интеграция изменений в исходный документ" Для этого следует использовать скрипт \fBpo4a\-updatepo\fR\|(1) (подробности см. в документации к нему): .PP .Vb 1 \& $ po4a\-updatepo \-\-format <формат> \-\-master <новый_мастер.doc> \-\-po <старый_doc.XX.po> .Ve .PP Мастер\-документ используется на входе, а файл \s-1PO\s0 обновляется: он используется как на входе, так и на выходе. .SS "Генерация переведённого документа" .IX Subsection "Генерация переведённого документа" Когда вы закончите с переводом, вы захотите получить переведённую документацию и распространять её своим пользователям вместе с оригиналом. Для этого используйте программу \fBpo4a\-translate\fR\|(1) следующим образом: .PP .Vb 1 \& $ po4a\-translate \-\-format <формат> \-\-master <мастер.doc> \-\-po \-\-localized .Ve .PP Мастер\-документ и \s-1PO\s0 файлы используются на входе, а локализованный файл является выходом этого процесса. .SS "Использование дополнений для добавления дополнительного текста к переводам" .IX Subsection "Использование дополнений для добавления дополнительного текста к переводам" Добавление нового текста в перевод \- это, пожалуй, единственное, что в долгосрочной перспективе проще, когда вы переводите файлы вручную :). Это происходит, когда вы хотите добавить в переведенный документ дополнительный раздел, не соответствующий какому\-либо содержанию в оригинальном документе. Классический вариант использования \- отдать должное команде переводчиков и указать, как сообщать о проблемах, связанных с переводом. .PP В po4a необходимо указать файлы \fBaddendum\fR, которые концептуально можно рассматривать как патчи, накладываемые на локализованный документ после обработки. Каждое дополнение должно быть представлено в виде отдельного файла, формат которого, однако, сильно отличается от классических патчей. Первая строка \- это \fIстрока заголовка\fR, определяющая точку вставки дополнения (с, к сожалению, загадочным синтаксисом \- см. ниже), в то время как остальная часть файла добавляется дословно в определенную позицию. .PP Строка заголовка должна начинаться со строки \fB\s-1PO4A\-HEADER:\s0\fR, за которой следует список полей \fIkey\fR\fB=\fR\fIvalue\fR, разделенных запятой. .PP Например, следующий заголовок объявляет о дополнении, которое должно быть помещено в самый конец перевода. .PP .Vb 1 \& PO4A\-HEADER: mode=eof .Ve .PP Things are more complex when you want to add your extra content in the middle of the document. The following header declares an addendum that must be placed after the \s-1XML\s0 section containing the string \f(CW\*(C`About this document\*(C'\fR in translation. .PP .Vb 1 \& PO4A\-HEADER: position=Об этом документе; mode=after; endboundary= .Ve .PP In practice, when trying to apply an addendum, po4a searches for the first line matching the \f(CW\*(C`position\*(C'\fR argument (this can be a regexp). Do not forget that po4a considers the \fBtranslated\fR document here. This documentation is in English, but your line should probably read as follows if you intend your addendum to apply to the French translation of the document. .PP .Vb 1 \& PO4A\-HEADER: position=À propos de ce document; mode=after; endboundary= .Ve .PP Once the \f(CW\*(C`position\*(C'\fR is found in the target document, po4a searches for the next line after the \f(CW\*(C`position\*(C'\fR that matches the provided \f(CW\*(C`endboundary\*(C'\fR. The addendum is added right \fBafter\fR that line (because we provided an \fIendboundary\fR, i.e. a boundary ending the current section). .PP The exact same effect could be obtained with the following header, that is equivalent: .PP .Vb 1 \& PO4A\-HEADER: position=Об этом документе; mode=after; beginboundary=
.Ve .PP Here, po4a searches for the first line matching \f(CW\*(C` after the line matching \f(CW\*(C`About this document\*(C'\fR in the translation, and add the addendum \fBbefore\fR that line since we provided a \fIbeginboundary\fR, i.e. a boundary marking the beginning of the next section. So this header line requires to place the addendum after the section containing \f(CW\*(C`About this document\*(C'\fR, and instruct po4a that a section starts with a line containing the \f(CW\*(C` tag. This is equivalent to the previous example because what you really want is to add this addendum either after \f(CW\*(C`/section\*(C'\fR> or before \f(CW\*(C`. .PP You can also set the insertion \fImode\fR to the value \f(CW\*(C`before\*(C'\fR, with a similar semantic: combining \f(CW\*(C`mode=before\*(C'\fR with an \f(CW\*(C`endboundary\*(C'\fR will put the addendum just \fBafter\fR the matched boundary, that the last potential boundary line before the \f(CW\*(C`position\*(C'\fR. Combining \f(CW\*(C`mode=before\*(C'\fR with an \f(CW\*(C`beginboundary\*(C'\fR will put the addendum just \fBbefore\fR the matched boundary, that the last potential boundary line before the \f(CW\*(C`position\*(C'\fR. .PP .Vb 7 \& Mode | Boundary kind | Used boundary | Insertion point compared to the boundary \& ========|===============|========================|========================================= \& \*(Aqbefore\*(Aq| \*(Aqendboundary\*(Aq | last before \*(Aqposition\*(Aq | Right after the selected boundary \& \*(Aqbefore\*(Aq|\*(Aqbeginboundary\*(Aq| last before \*(Aqposition\*(Aq | Right before the selected boundary \& \*(Aqafter\*(Aq | \*(Aqendboundary\*(Aq | first after \*(Aqposition\*(Aq | Right after the selected boundary \& \*(Aqafter\*(Aq |\*(Aqbeginboundary\*(Aq| first after \*(Aqposition\*(Aq | Right before the selected boundary \& \*(Aqeof\*(Aq | (none) | n/a | End of file .Ve .PP \fIСоветы и хитрости при использовании дополнений\fR .IX Subsection "Советы и хитрости при использовании дополнений" .IP "\(bu" 4 Запомните, что это регулярные выражения. Например, если вы хотите сопоставить конец секции nroff, которая заканчивается строкой \f(CW\*(C`.fi\*(C'\fR, то не используйте \f(CW\*(C`.fi\*(C'\fR как \fBendboundary\fR, ибо в данном случае также будет сопоставлена строка \f(CW\*(C`the[ fi]le\*(C'\fR, что, очевидно, не то, что вы ожидаете. Правильный \fBendboundary\fR в этом случае будет: \f(CW\*(C`^\e.fi$\*(C'\fR. .IP "\(bu" 4 White spaces \s-1ARE\s0 important in the content of the \f(CW\*(C`position\*(C'\fR and boundaries. So the two following lines \fBare different\fR. The second one will only be found if there is enough trailing spaces in the translated document. .Sp .Vb 2 \& PO4A\-HEADER: position=Об этом документе; mode=after; beginboundary=
\& PO4A\-HEADER: position=Об этом документе ; mode=after; beginboundary=
.Ve .IP "\(bu" 4 Хотя и можно считать, что этот контекстный поиск, грубо говоря, перебирает текст \fBперевода\fR построчно, но на самом деле он работает со строками во внутреннем представлении данных документов. Этой строкой может быть, например, текст целого абзаца, разбитый на несколько фактических строк или один XML\-тег сам по себе. Непосредственная \fIточка вставки\fR дополнения должна быть до или после такой строки во внутреннем представлении и не может быть вставлена в середину оной. .IP "\(bu" 4 Pass the \fB\-vv\fR argument to po4a to understand how the addenda are added to the translation. It may also help to run po4a in debug mode to see the actual internal data string when your addendum does not apply. .PP \fIПримеры дополнений\fR .IX Subsection "Примеры дополнений" .IP "\(bu" 4 Если вы хотите добавить что\-то после следующего раздела nroff (формат man\-страниц): .Sp .Vb 1 \& .SH "АВТОРЫ" .Ve .Sp Вам следует выбрать подход с двумя регулярными выражениями, т.е. задать \fBmode=after\fR. Затем сузьте поиск до строк идущих после \fBАВТОРЫ\fR с помощью регулярного выражения в аргументе \fBposition\fR. После этого вы должны сопоставить начало следующей секции (например, с помощью \fB^\e.SH\fR) в аргументе \fBbeginboundary\fR. Короче говоря: .Sp .Vb 1 \& PO4A\-HEADER: mode=after; position=АВТОРЫ; beginboundary=\e. SH .Ve .IP "\(bu" 4 Если вы хотите добавить что\-то сразу после конкретной строки (например, после «Copyright Большая Шишка»), используйте значение \fBposition\fR, соответствующее этой строке, задайте \fBmode=after\fR, а \fBbeginboundary\fR — значение, соответствие любой строке. .Sp .Vb 1 \& PO4A\-HEADER:mode=after;position=Copyright Большая Шишка, 2004;beginboundary=^ .Ve .IP "\(bu" 4 Если вы хотите добавить что\-то в конец документа, то присвойте \fBposition\fR регулярное выражение, сопоставляемое любой строке вашего документа (но только одна строке; po4a выдаст ошибку, если она будет не уникальна), и задайте \fBendboundary\fR не соответствующее ни чему. Лучше не использовать здесь простые строки, например \fB\*(L"\s-1EOF\*(R"\s0\fR, а отдать предпочтение тем, у которых меньше шансов оказаться в вашем документе. .Sp .Vb 1 \& PO4A\-HEADER:mode=after;position=О программе;beginboundary=FakePo4aBoundary .Ve .PP \fIБолее подробный пример\fR .IX Subsection "Более подробный пример" .PP Исходный документ (формат \s-1POD\s0): .PP .Vb 7 \& |=head1 NAME \& | \& |dummy \- a dummy program \& | \& |=head1 AUTHOR \& | \& |Me .Ve .PP Тогда следующее дополнение обеспечит добавление раздела о переводчике (на русском) в конец файла. .PP .Vb 6 \& |PO4A\-HEADER:mode=after;position=АВТОР;beginboundary=^=head \& | \& |=head1 ПЕРЕВОД \& | \& |Я \& | .Ve .PP Чтобы поместить своё дополнение перед «АВТОР», используйте следующий заголовок: .PP .Vb 1 \& PO4A\-HEADER:mode=after;position=ИМЯ;beginboundary=^=head1 .Ve .PP Это работает, так как следующая сопоставляемая \fBbeginboundary\fR /^=head1/ строка после раздела «NAME» (переведённого как «ИМЯ» на русский) и начинает раздел с перечислением авторов. Таким образом, дополнение будет помещено между этими двумя разделами. Заметьте, что если в дальнейшем какой\-либо другой раздел будет добавлен между разделами «ИМЯ» и «АВТОР», то данный пример будет работать не корректно, ибо дополнение будет вставляться перед этим новым разделом. .PP Чтобы избежать этого, можете использовать аналогичный заголовок с \fBmode\fR=\fIbefore\fR: .PP .Vb 1 \& PO4A\-HEADER:mode=before;position=^=head1 АВТОР .Ve .SH "Как это работает?" .IX Header "Как это работает?" В этой главе даётся краткий обзор внутренних компонентов po4a так, чтобы вы могли чувствовать себя увереннее, если вы захотите помочь нам сопровождать и улучшать его. Это также может помочь вам понять, почему он не делаете того, что вы ожидали, и как решить ваши проблемы. .PP Архитектура po4a объектно\-ориентирована. Общим предком всех классов\-парсеров po4a является \fBLocale::Po4a::TransTractor\fR\|(3pm). Своё странное имя он получил оттого, что он одновременно отвечает и за перевод документа и извлечение строк. .PP Если точнее, TransTractor берёт документ для перевода плюс PO\-файл с переводами, кои являются его входными данными, и производит два отдельных набора выходных данных: другой PO\-файл (как результат извлечения переводимых строк из входного документа) и переведённый документ (с той же структурой, что и входной, но со всеми переводимыми строками заменёнными содержимым входного PO\-файла). Ниже приведено графическое представление этого процесса: .PP .Vb 6 \& Входной документ \-\e /\-\-\-> Выходной документ \& \e TransTractor:: / (переведённый) \& +\-\->\-\- parse() \-\-\-\-\-\-\-\-+ \& / \e \& Входной PO \-\-\-\-\-\-/ \e\-\-\-> Выходной PO \& (извлечённый) .Ve .PP Эта маленькая косточка и является ядром всей архитектуры po4a. Если вы уберёте входной \s-1PO\s0 и выходной документ, вы получите \fBpo4a\-gettextize\fR. Если предоставите оба набора входных данных и проигнорируете выходной \s-1PO,\s0 вы получите \fBpo4a\-translate\fR. \fBpo4a\fR вызывает TransTractor дважды и вызывает \fBmsgmerge \-U\fR между оными вызовами, дабы это было комплексное решение с одним файлом настроек. См. подробности в \fBLocale::Po4a::TransTractor\fR\|(3pm). .SH "Проекты с открытым исходным кодом, использующие po4a" .IX Header "Проекты с открытым исходным кодом, использующие po4a" Here is a very partial list of projects that use po4a in production for their documentation. If you want to add your project to the list, just drop us an email (or a Merge Request). .IP "\(bu" 4 adduser (man): инструмент по управлению пользователями и группами. .IP "\(bu" 4 apt (man, docbook): менеджер пакетов Debian. .IP "\(bu" 4 aptitude (docbook, svg): консольный менеджер пакетов для Debian .IP "\(bu" 4 F\-Droid website (markdown): устанавливаемый каталог свободных и открытых приложений (Free and Open Source Software) для платформы Android. .IP "\(bu" 4 git (asciidoc): распределённая система контроля изменений исходного кода. .IP "\(bu" 4 Linux manpages (man) .Sp This project provides an infrastructure for translating many manpages to different languages, ready for integration into several major distributions (Arch Linux, Debian and derivatives, Fedora). .IP "\(bu" 4 Stellarium (\s-1HTML\s0): a free open source planetarium for your computer. po4a is used to translate the sky culture descriptions. .IP "\(bu" 4 Other item to sort out: .SH "Часто задаваемые вопросы" .IX Header "Часто задаваемые вопросы" .SS "Как вы произносите po4a?" .IX Subsection "Как вы произносите po4a?" I personally vocalize it as pouah , which is a French onomatopoetic that we use in place of yuck :) I may have a strange sense of humor :) .SS "Как насчёт других инструментов перевода документации, использующих gettext?" .IX Subsection "Как насчёт других инструментов перевода документации, использующих gettext?" There are a few of them. Here is a possibly incomplete list, and more tools are coming at the horizon. .IP "\fBpoxml\fR" 4 .IX Item "poxml" Это инструмент, разработанный командой \s-1KDE\s0 для работы с DocBook \s-1XML.\s0 На сколько я знаю, это была первая программа, которая извлекала переводимые строки из документации в PO\-файлы и подставляла их обратно после перевода. .Sp Она может обрабатывать только \s-1XML\s0 и только с определённым \s-1DTD.\s0 Мне не очень нравится, как она обрабатывает списки, которые представляются одним большим msgid. Когда список становится большим, весь этот кусок становится сложно переработать. .IP "\fBpo-debiandoc\fR" 4 .IX Item "po-debiandoc" Эта программа, созданная Денисом Барбье, является своего рода предшественником модуля \s-1SGML\s0 в po4a, который более или менее делает её устаревшей. Как становится ясно из названия, она обрабатывает только \s-1DTD\s0 DebianDoc, который также относительно устарел. .IP "\fBxml2po.py\fR" 4 .IX Item "xml2po.py" Used by the \s-1GIMP\s0 Documentation Team since 2004, works quite well even if, as the name suggests, only with \s-1XML\s0 files and needs specially configured makefiles. .IP "\fBSphinx\fR" 4 .IX Item "Sphinx" The Sphinx Documentation Project also uses gettext extensively to manage its translations. Unfortunately, it works only for a few text formats, rest and markdown, although it is perhaps the only tool that does this managing the whole translation process. .PP Основные преимущества po4a перед оными — это простота добавления дополнительного содержипого (по крайней мере там это реализовано ещё хуже) и возможность проведения геттекстизации. .SS "РЕЗЮМЕ преимуществ подхода, основанного на gettext" .IX Subsection "РЕЗЮМЕ преимуществ подхода, основанного на gettext" .IP "\(bu" 2 Переводы хранятся отдельно от оригиналов, что позволяет определить, устарели ли первые. .IP "\(bu" 2 Переводы на разные языки хранятся в отдельных файлах, что не даёт разноязычным переводчикам мешать друг другу, как при отправке ими патчей, так и на уровне кодировок файлов. .IP "\(bu" 2 Внутренне устройство основано на \fBgettext\fR (но \fBpo4a\fR предлагает простой интерфейс, так что вам не нужно понимать его внутреннее устройство, чтобы просто пользоваться им). Таким образом, нам не приходится заново изобретать колесо, а, так как \fBgettext\fR широко используется, мы можем считать, что в нём остаётся относительно мало программных ошибок. .IP "\(bu" 2 Для конечного пользователя ничего не меняется (помимо того факта, что, надо надеяться, перевод будет лучше поддерживаться). Полученный файл документации распространяется точно так же. .IP "\(bu" 2 Переводчикам не нужно изучать новый синтаксис файлов, и их любимого редактора PO\-файлов (например, PO\-режим Emacs, Lokalize или Gtranslator) будет вполне достаточно. .IP "\(bu" 2 gettext предлагает простой способ получить статистику о том, что готово, что должно быть проверено и обновлено, а что ещё предстоит сделать. Некоторые примеры можно найти по следующим ссылкам: .Sp .Vb 2 \& \- https://docs.kde.org/stable5/en/kdesdk/lokalize/project\-view.html \& \- http://www.debian.org/intl/l10n/ .Ve .PP Но не всё так радужно, и этот подход также имеет некоторые недостатки, с которыми нам приходится смириться. .IP "\(bu" 2 Дополнения… странные на первый взгляд. .IP "\(bu" 2 Вы не можете приспособить переведённый текст к своим предпочтениям, например, разделить какой\-то абзац здесь\-то или объединили два в один там\-то. Но в некотором смысле, если есть проблема в оригинале, об этом должно быть сообщено, как об ошибке. .IP "\(bu" 2 Даже при том, что интерфейс является простым, po4a остаётся новым инструментом, который людям придётся изучать. .Sp Одна моя мечта состоит в том, чтобы каким\-то образом интегрировать po4a в Gtranslator или Lokalize. Тогда при открытии файла документации, строки автоматически извлекались бы, а когда он сохранялся, переведённый файл и PO\-файл мог ли бы записываться на диск. Если бы нам удалось сделать модуль \s-1MS\s0 Word (\s-1TM\s0) (или, по крайней мере, \s-1RTF\s0), то даже профессиональные переводчики могли бы использовать po4a. .SH "СМОТРИТЕ ТАКЖЕ" .IX Header "СМОТРИТЕ ТАКЖЕ" .IP "\(bu" 4 The documentation of the all-in-one tool that you should use: \fBpo4a\fR\|(1). .IP "\(bu" 4 Документация отдельных сценариев po4a: \fBpo4a\-gettextize\fR\|(1), \fBpo4a\-normalizeupdatepo\fR\|(1), \fBpo4a\-translate\fR\|(1), po4a(7\-\fBnormalize\fR\|(1). .IP "\(bu" 4 The additional helping scripts: \fBmsguntypot\fR\|(1), \fBpo4a\-display\-man\fR\|(1), \fBpo4a\-display\-pod\fR\|(1). .IP "\(bu" 4 Парсеры для каждого отдельного формата, в особенности обратите внимани на параметры, принимаемые каждым из них: \fBLocale::Po4a::AsciiDoc\fR\|(3pm) \fBLocale::Po4a::Dia\fR\|(3pm), \fBLocale::Po4a::Guide\fR\|(3pm), \fBLocale::Po4a::Ini\fR\|(3pm), \fBLocale::Po4a::KernelHelp\fR\|(3pm), \fBLocale::Po4a::Man\fR\|(3pm), \fBLocale::Po4a::RubyDoc\fR\|(3pm), \fBLocale::Po4a::Texinfo\fR\|(3pm), \fBLocale::Po4a::Text\fR\|(3pm), \fBLocale::Po4a::Xhtml\fR\|(3pm), \fBLocale::Po4a::Yaml\fR\|(3pm), \fBLocale::Po4a::BibTeX\fR\|(3pm), \fBLocale::Po4a::Docbook\fR\|(3pm), \fBLocale::Po4a::Halibut\fR\|(3pm), \fBLocale::Po4a::LaTeX\fR\|(3pm), \fBLocale::Po4a::Pod\fR\|(3pm), \fBLocale::Po4a::Sgml\fR\|(3pm), \fBLocale::Po4a::TeX\fR\|(3pm), \fBLocale::Po4a::Wml\fR\|(3pm), \fBLocale::Po4a::Xml\fR\|(3pm). .IP "\(bu" 4 The implementation of the core infrastructure: \fBLocale::Po4a::TransTractor\fR\|(3pm) (particularly important to understand the code organization), \fBLocale::Po4a::Chooser\fR\|(3pm), \fBLocale::Po4a::Po\fR\|(3pm), \fBLocale::Po4a::Common\fR\|(3pm). Please also check the \fI\s-1CONTRIBUTING\s0.md\fR file in the source tree. .SH "АВТОРЫ" .IX Header "АВТОРЫ" .Vb 2 \& Денис Барбье (Denis Barbier) \& Мартин Кенсон (Martin Quinson) (mquinson#debian.org) .Ve