1.0 - en to ru translation catalogue (1121 entries)

note: type: Attribute 'xml:lang' of: <refentry>
en: en
ru: ru

note: type: Content of: <refentry><refmeta><refmiscinfo>
en: Po4a Tools
ru: Инструменты Po4a

note: type: Content of: <refentry><refnamediv><refpurpose>
en: display a translated man page according to a PO
ru: отобразить переведённую man-страницу в соответствии с PO-файлом

note: type: Content of: <refentry><refsynopsisdiv><cmdsynopsis>
en: <command>po4a-display-man</command> <arg choice='plain'><option>-p</option> </arg> <arg choice='plain'><replaceable>PO_FILE</replaceable></arg> <arg choice='opt'><arg choice='plain'><option>-m</option> </arg><arg choice='plain'><replaceable>MASTER_FILE</replaceable></arg></arg> <arg choice='opt'><arg choice='plain'><option>-o</option> </arg><arg choice='plain'><replaceable>PO4A_OPT</replaceable></arg></arg>
ru: <command>po4a-display-man</command> <arg choice='plain'><option>-p</option> </arg> <arg choice='plain'><replaceable>PO_ФАЙЛ</replaceable></arg> <arg choice='opt'><arg choice='plain'><option>-m</option> </arg><arg choice='plain'><replaceable>МАСТЕР_ДОКУМЕНТ</replaceable></arg></arg> <arg choice='opt'><arg choice='plain'><option>-o</option> </arg><arg choice='plain'><replaceable>ПАРАМЕТРЫ_PO4A</replaceable></arg></arg>

note: type: =head1
en: DESCRIPTION
ru: ОПИСАНИЕ

note: type: Content of: <refentry><refsect1><para>
en: Translators can use <command>po4a-display-man</command> to see how their translation of a man page will be rendered to the end users, without recompiling and reinstalling the whole project.
ru: Переводчики могут посмотреть, как в итоге будет выглядеть их перевод man-страницы, с помощью <command>po4a-display-man</command>. При этом перекомпилировать или переустанавливать весь проект не потребуется.

note: type: Content of: <refentry><refsect1><para>
en: This script only works with man pages written directly in <emphasis remap='I'>nroff</emphasis> and handled by the po4a's <emphasis remap='I'>man</emphasis> module.  Manual pages generated from other formats, like DocBook or POD, are not supported.  See <citerefentry><refentrytitle>po4a-display-pod</refentrytitle><manvolnum>1</manvolnum></citerefentry> for an equivalent supporting <emphasis remap='I'>POD</emphasis> documents.
ru: Этот скрипт работает только с man-страницами написанными непосредственно в формате <emphasis remap='I'>nroff</emphasis> и обрабатываемых <emphasis remap='I'>man</emphasis>-модулем  po4a. Man-страницы сгенерированные из других форматов, таких как DocBook или POD, не поддерживаются.  См. <citerefentry><refentrytitle>po4a-display-pod</refentrytitle><manvolnum>1</manvolnum></citerefentry> для эквивалента, поддерживающего <emphasis remap='I'>POD</emphasis>-документы.

note: type: =head1
en: OPTIONS
ru: ПАРАМЕТРЫ

note: type: Content of: <refentry><refsect1><variablelist><varlistentry><term>
en: <option>-p </option><replaceable>PO_FILE</replaceable>
ru: <option>-p </option><replaceable>PO_ФАЙЛ</replaceable>

note: type: Content of: <refentry><refsect1><variablelist><varlistentry><listitem><para>
en: The PO file containing the translations.
ru: PO-файл, содержащий перевод.

note: type: Content of: <refentry><refsect1><variablelist><varlistentry><term>
en: <option>-m </option><replaceable>MASTER_FILE</replaceable>
ru: <option>-m </option><replaceable>МАСТЕР_ДОКУМЕНТ</replaceable>

note: .br type: Content of: <refentry><refsect1><variablelist><varlistentry><listitem><para>
en: The original man page.  It can be the absolute or relative path to the original man page (gzipped or not), the name of the man page or the name and section of the man page (using the man.section format).  When the master document is not provided with the <option>-m</option> option, <command>po4a-display-man</command> tries to find the original man page based on the line reference of the first string in the PO.
ru: Исходная man-страница. Это может быть абсолютный или относительный путь к исходной man-странице (как сжатой gzip, так и нет), имя man-страницы или её имя и раздел (в форме имя.номер_раздела). Если мастер-документ (master) не указан с помощью параметра <option>-m</option>, то <command>po4a-display-man</command> попытается определить исходную man-страницу на основе сносок в первой строке PO-файла.

note: type: Content of: <refentry><refsect1><variablelist><varlistentry><term>
en: <option>-o </option><replaceable>PO4A_OPT</replaceable>
ru: <option>-o </option><replaceable>ПАРАМЕТРЫ_PO4A</replaceable>

note: type: Content of: <refentry><refsect1><variablelist><varlistentry><listitem><para>
en: Some options to pass to <citerefentry><refentrytitle>po4a-translate</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
ru: Параметры, которые будут переданы <citerefentry><refentrytitle>po4a-translate</refentrytitle><manvolnum>1</manvolnum></citerefentry>.

note: type: =head1
en: SEE ALSO
ru: СМОТРИТЕ ТАКЖЕ

note: type: Content of: <refentry><refsect1><title>
en: AUTHOR
ru: АВТОР

note: type: Content of: <refentry><refsect1><para>
en: Thomas Huriaux
ru: Томас Юрио (Thomas Huriaux)

note: type: Content of: <refentry><refnamediv><refpurpose>
en: display of a translated POD file according to a PO
ru: отобразить страницу переводимого в данный момент POD-файла, в соответствии с PO-файлом

note: type: Content of: <refentry><refsynopsisdiv><cmdsynopsis>
en: <command>po4a-display-pod</command> <arg choice='plain'><option>-p </option></arg> <arg choice='plain'><replaceable>PO_FILE</replaceable></arg> <arg choice='plain'><option>-m </option></arg> <arg choice='plain'><replaceable>POD_FILE</replaceable></arg> <arg choice='opt'><arg choice='plain'><option>-o </option></arg><arg choice='plain'><replaceable>PO4A_OPT</replaceable></arg></arg>
ru: <command>po4a-display-man</command> <arg choice='plain'><option>-p </option></arg> <arg choice='plain'><replaceable>PO_ФАЙЛ</replaceable></arg> <arg choice='plain'><option>-m </option></arg> <arg choice='plain'><replaceable>POD_ФАЙЛ</replaceable></arg> <arg choice='opt'><arg choice='plain'><option>-o </option></arg><arg choice='plain'><replaceable>ПАРАМЕТРЫ_PO4A</replaceable></arg></arg>

note: type: Content of: <refentry><refsect1><para>
en: Translators can use <command>po4a-display-pod</command> to see how their translation of a man page will be rendered to the end users, without recompiling and reinstalling the whole project.  Most of the time, the POD file is only available in source package or embedded in Perl script.
ru: С помощью <command>po4a-display-pod</command> переводчик может посмотреть, как будет выглядеть его перевод man-стараницы без перекомпиляции или переустановки всего проекта. Обычно, POD-файл находится только в пакете исходных текстов или встроен в сценарий Perl.

note: type: Content of: <refentry><refsect1><variablelist><varlistentry><term>
en: <option>-m </option><replaceable>POD_FILE</replaceable>
ru: <option>-m </option><replaceable>POD_ФАЙЛ</replaceable>

note: type: Content of: <refentry><refsect1><variablelist><varlistentry><listitem><para>
en: The original POD file used by po4a to generate PO file.
ru: Исходный POD-файл, использованный po4a для создания PO-файла.

note: type: Content of: <refentry><refsect1><para>
en: Florentin Duneau
ru: Флорентин Дюно (Florentin Duneau)

note: type: =head1
en: NAME
ru: НАЗВАНИЕ

note: type: textblock
en: po4a - update both the PO files and translated documents in one shot
ru: po4a - обновление PO-файлов и переведённой документации за один проход

note: type: =head1
en: SYNOPSIS
ru: КРАТКОЕ СОДЕРЖАНИЕ

note: type: textblock
en: B<po4a> [I<options>] I<config_file>
ru: B<po4a> [I<параметры>] I<файл_настроек>

note: type: textblock
en: po4a (PO for anything) eases the maintenance of documentation translation using the classical gettext tools. The main feature of po4a is that it decouples the translation of content from its document structure.  Please refer to the page L<po4a(7)> for a gentle introduction to this project.
ru: po4a (PO for anything, PO для всего) упрощает поддержку переводов документации, используя обычные инструменты gettext. Основная идея po4a состоит в том, что оно отделяет перевод содержимого от структуры документа. Пошаговое вводное руководство по работе с данным проектом можно посмотреть на странице L<po4a(7)>.

note: type: textblock
en: Upon execution, B<po4a> parses all documentation files specified in its configuration file. It updates the PO files (containing the translation) to reflect any change to the documentation, and produce a translated documentation by injecting the content's translation (found in the PO files) into the structure of the original master document.
ru: После запуска программа B<po4a> парсит все файлы документации, перечисленные в её файле настроек. Она обновляет содержащие перевод PO-файлы, таким образом отражает изменения в документации и создает переведенный документ, включая в структуру исходного мастер-документа перевод содержимого (находящийся в PO-файлах).

note: type: textblock
en: At first, the PO files only contain the strings to translate from the original documentation. This file format allows the translators to manually provide a translation for each paragraph extracted by B<po4a>. If the documentation is modified after translation, B<po4a> marks the corresponding translations as "fuzzy" in the PO file to request a manual review by the translators. The translators can also provide so-called "addendum", that are extra content stating for example who did the translation and how to report bugs.
ru: Вначале PO-файлы содержат только не переведённые строки исходного документа. Этот формат файла позволяет переводить каждый абзац, извлечённый B<po4a> по-отдельности. Если, уже после того как перевод был сделан, исходный документ изменяется, то B<po4a> отмечает этот перевод в PO-файле как «неточный» ("fuzzy"), чтобы сообщить переводчику, что данный перевод необходимо пересмотреть. Также переводчик может добавить так называемый «аддендум» ("addendum") — дополнительная информация, например, об авторе перевода и о том, как и куда сообщать об ошибках в переводе.

note: type: verbatim
en:  master documents ---+---->-------->---------+
      (doc authoring)    |                       |
                         V   (po4a executions)   >-----+--> translated
                         |                       |     |     documents
     existing PO files -->--> updated PO files >-+     |
          ^                            |               |
          |                            V               |
          +----------<---------<-------+               ^
           (manual translation process)                |
                                                       |
     addendum -->--------------------------------------+
ru:  мастер-документы ------+--------->-------->--------+
     (создание документа)   |                           |
                            V     (выполнение po4a)     >--+--> переводы
                            |                           |  |
     существующие PO-файлы ->-> обновлённые PO-файлы ->-+  |
            ^                            |                 |
            |                            V                 |
            +----------<---------<-------+                 ^
                     (ручной перевод)                      |
                                                           |
     аддендум -->------------------------------------------+

note: type: textblock
en: The workflow of B<po4a> is asynchronous, as suited to open-source projects. The documentation writers author the master documents at their own pace. The translators review and update the translations in the PO files. The maintainers rerun B<po4a> on need, to reflect any change to the original documentation to the PO files, and to produce updated documentation translations, by injecting the latest translation into the latest document structure.
ru: Работа B<po4a асинхронная и подходит для open-source проектов. Технические писатели создают master-документ в одном месте. Переводчики просматривают и обновляют перевод PO-файлов. Мейнтейнеры при необходимости запускают B<po4a>, для отражения именений из исходной документации в PO-файлах и для получения обновленных переводов документации путем вставки обновленных переводов в обновленную структуру документации.

note: type: textblock
en: By default, a given translated document is produced when at least 80% of its content is translated. The untranslated text is kept in the original language.  The produced documentation thus mixes languages if the translation is not complete. You can change the 80% threshold with the I<--keep> option described below. Note however that discarding translations as soon as they are not 100% may be discouraging for the translators whose work will almost never be shown to the users, while showing "translations" that are too incomplete may be troubling for the end users.
ru: По умолчанию переведённые документы создаются, когда переведено хотя бы 80% содержимого. Непереведённый текст на исходном языке сохраняется. Таким образом, если перевод не завершён, в созданной документации языки комбинируются. Вы можете изменить пороговое значение 80% при помощи описанного ниже параметра I<--keep>. Следует учесть, что если отбрасывать перевод целиком до его завершения на 100%, это может демотивировать переводчиков, так как пользователи практически никогда не будут видеть их работу. С другой стороны, вы можете вызвать у конечных пользователей затруднения, предоставляя им «переводы», которые слишком далеки от завершения.

note: type: textblock
en: Storing the translated documentation files in the version control system is probably a bad idea, since they are automatically generated. The precious files are the PO files, that contain the hard work of your fellow translators. Also, some people find it easier to interact with the translators through an online platform such as S<weblate>, but this is naturally fully optional.
ru: Хранение файлов переведенной документации в системе контроля версий, возможно, не лучшая идея, так как она автоматически генерируется. Наиболее ценными являются PO-файлы, которые содержат кропотливую работу выших соратников-переводчиков. Так, некоторые люди считают более простым взаимодействие с переводчиками посредством онлайнплатформ, таких как S<weblate>, но это естественно необязательно.

note: type: =head2
en: Quick start tutorial
ru: Быстрый старт

note: type: textblock
en: Let's assume you maintain a program named B<foo> which has a man page F<man/foo.1> written in English (the bridge language in most open-source projects, but B<po4a> can be used from or to any language). Some times ago, someone provided a German translation named F<man/foo.de.1> and disappeared.  This is a problem because you just got a bug report saying that your documentation contains a gravely misleading information that must be fixed in all languages, but you don't speak German so you can only modify the original, not the translation. Now, another contributor wants to contribute a translation to Japanese, a language that you don't master either.
ru: Предположим, что вы занимаетесь поддержкой программы B<foo>, у который есть man-страница F<man/foo.1> на Английском (общий язык в большинстве СПО-проектах, хотя, вообще говоря, B<po4a> можно использовать и для переводов с любого языка или на любой другой). Некоторое время назад кто-то сделал перевод на немецкий с именем F<man/foo.de.1>, но затем перестал выходить на связь. Затем вы получаете сообщение об ошибке, в котором говорится, что ваша документация содержит недостоверную информацию. Это срочно нужно поправить, причём в документации на всех языках. Но проблема в том, что вы не знаете немецкого, так что вы можете исправить эту ошибку только в исходном документе, но не в переводе. Теперь другой участник хочет добавить японский перевод; язык, которым вы также овладели пока не в полной мере.

note: type: textblock
en: It is time to convert your documentation to B<po4a> to solve your documentation maintenance nightmares. You want to update the doc when needed, you want to ease the work of your fellow translators, and you want to ensure that your users never see any outdated and thus misleading documentation.
ru: Это как раз тот момент, когда пришло время начать использовать B<po4a> в вашем проекте, дабы хоть как-то вырваться из этого ада попыток поддержания документации в актуальном состоянии. Вы хотите обновлять документацию по мере необходимости! Вы хотите облегчить работу своих коллег-переводчиков! Вы хотите быть уверенными в том, что ваши пользователи никогда не увидят ни строчки устаревшей и, следовательно, вводящей в заблуждение документации!

note: type: textblock
en: The conversion includes two steps: setup the po4a infrastructure, and convert the previous German translation to salvage the previous work. This latter part is done using S<po4a-gettextize>, as follows. As detailed in the documentation of L<po4a-gettextize(1)>, this process rarely fully automatic, but once it's done, the B<de.po> file containing the German translation can be integrated in your po4a workflow.
ru: Чтобы преобразовать проект для использования po4a необходимо выполнить два шага: собственно настройте инфраструктуру po4a и конвертировать уже существующий немецкий перевод, чтобы не потерять уже проделанную работу. Последнее делается с помощью S<po4a-gettextize>. Как описано в документации L<po4a-gettextize(1)>, этот процесс редко является полностью автоматическим, но как только это будет сделано, полученный файл B<de.po> с немецким переводом, может быть с лёгкостью интегрирован в обычный рабочий процесс, основанный на po4a.

note: type: textblock
en: Let's now configure po4a. With the appropriate file layout, your configuration file could be as simple as this:
ru: Теперь давайте собственно настроим po4a. При соответствующей структуре файлов, файл настроек может состоять всего из пары строк:

note: type: textblock
en: It specifies that all PO files (containing the work of the translators) are in the F<man/po4a/> directory, and that you have only one master file, F<man/foo.1>. If you had several master files, you would have several lines similar to the second one. Each such line also specify where to write the corresponding translation files. Here, the German translation of F<man/foo.1> is in F<man/translated/foo.de.1>.
ru: В нём указано, что все PO-файлы (содержащие работу переводчиков) находятся в каталоге F<man/po4a/>, а также то, что у вас только один мастер-файл, F<man/foo.1>. Если бы у вас их было несколько, то вам надо было бы добавить несколько строчек аналогичных второй. Каждая подобная строка также содержит, куда записывать переведённые файлы. В данном случае немецкий перевод F<man/foo.1> находится в F<man/translated/foo.de.1>.

note: type: textblock
en: The last thing we need to complete the configuration of B<po4a> is a POT file containing the template material that should be used to start a new translation.  Simply create an empty file with the S<.pot> extension in the specified S<po_directory> (e.g. F<man/po4a/foo.pot>), and B<po4a> will fill it with the expected content.
ru: Последние, что нам понадобится для нашего B<po4a>-проекта — это POT-файл, который является шаблоном для создания новых переводов на другие языки. Просто создайте пустой файл с расширением S<.pot> в каталоге, указанном в S<po_directory>, (например, F<man/po4a/foo.pot>); B<po4a> сам заполнит его содержимым.

note: type: textblock
en: Here is a recap of the files in this setup:
ru: В нашем примере структура файлов будет выглядеть следующим образом:

note: type: verbatim
en:   ├── man/
      │   ├── foo.1        <- The original man page, in English
      │   ├── po4a/
      │   │   ├── de.po    <- The German PO translation, from gettextization
      │   │   └── foo.pot  <- The POT template of future translations (empty at first)
      │   └── translated/  <- Directory where the translations will be created
      └── po4a.cfg         <- The configuration file
ru:   ├── man/
      │   ├── foo.1        <- исходная man-страница, на английском языке
      │   ├── po4a/
      │   │   ├── de.po    <- Немецкий перевод в PO-формате, полученный геттекстизацией
      │   │   └── foo.pot  <- POT-шаблон для будущих переводов (изначально пустой)
      │   └── translated/  <- Каталог, в котором будут создаваться переводы
      └── po4a.cfg         <- файл настроек

note: type: textblock
en: Once setup, executing B<po4a> will parse your documentation, update the POT template file, use it to update the PO translation files, and use them to update the documentation translation files. All in one command:
ru: После того, как всё это будет готово, запустите B<po4a>: он проведёт разбор вашего файла документации, обновит POT-шаблон, использует его для обновления PO-файлов с переводами, а затем использует их для обновления файлов с собственно переведённой документацией. Всё это за одну команду:

note: type: textblock
en: This is it. B<po4a> is now fully configured. Once you've fixed your error in F<man/foo.1>, the offending paragraph in the German translation will be replaced by the fixed text in English. Mixing languages is not optimal, but it's the only way to remove errors in translations that you don't even understand, and ensure that the content presented to the users is never misleading. Updating the German translation is also much easier in the corresponding PO file, so the language mix-up may not last long. Finally, when a Japanese translator wants to contribute a new translation, she should rename the S<foo.pot> into S<ja.po> and complete the translation. Once you have this file, just drop it in F<man/po4a/po/>. A translated page will appear as F<man/translated/foo.ja.1> (provided that enough content is translated) when you run B<po4a> again.
ru: Это всё. B<po4a> теперь полностью настроен. Как только вы исправите ошибку в F<man/foo.1>, проблемный абзац в немецком переводе будет заменён исправленным текстом на английском. Смешение языков, конечно, не самое лучшее решение, но это единственный способ убрать ошибки из переводов на языки, которые вы даже не понимаете, а также это гарантирует, что информация, которую будет видеть конечный пользователь останется достоверной. Обновлять немецкий перевод через PO-файл также будут намного проще, так что языковая путаница, вероятно, продлиться недолго. Наконец, когда японская переводчица захочет добавить новый перевод, она должна будет скопировать S<foo.pot> в S<ja.po> и сделать перевод в нём. Когда она передаст вам этот файл, просто поместите его в F<man/po4a/po/>. Затем, когда вы снова запустите B<po4a>, переведённая страница будет создана в F<man/translated/foo.ja.1> (при условии, что достаточная часть объёма файла действительно переведена).

note: type: textblock
en: Minimal threshold for translation percentage to keep (i.e. write) the resulting file (default: 80). I.e. by default, files have to be translated at least at 80% to be written on disk.
ru: Минимальное пороговое значение, в процентах, для сохранения (например, для записи) результирующего файла (по умолчанию: 80). То есть, по умолчанию, для того чтобы файл был записан, необходимо перевести как минимум 80%.

note: type: textblock
en: Column at which we should wrap the resulting file if the format supports it (default: 76).  If the provided value is 0 or negative, then the resulting file will not be wraped at all.  This is useful with some formats that could break when rewraped.
ru: Количество символов в строке, после которых текст в результирующем файле переносится на новую строку, если формат это поддерживает (значение по умолчанию: 76). Если значение равно нулю или меньше нуля, строки переноситься не будут (полезно в случаях, когда разбиение на строки нарушает разметку).

note: type: textblock
en: Show a short help message.
ru: Отобразить короткую справку.

note: type: textblock
en: Charset of the files containing the documents to translate. Note that all master documents must use the same charset.
ru: Кодировка файлов переводимых документов. Обратите внимание, что все мастер-документы должны использовать одну и ту же кодировку.

note: type: textblock
en: Charset of the files containing the localized documents. Note that all translated documents will use the same charset.
ru: Кодировка файлов локализованных документов. Обратите внимание, что все переведённые документы должны использовать одну и ту же кодировку.

note: type: textblock
en: Charset of the addenda. Note that all the addenda should be in the same charset.
ru: Кодировка аддендумов. Обратите внимание, что все аддендумы должны иметь одну и ту же кодировку.

note: type: textblock
en: Display the version of the script and exit.
ru: Отобразить версию и завершить работу сценария.

note: type: textblock
en: Increase the verbosity of the program.
ru: Увеличить количество выводимой пояснительной информации.

note: type: textblock
en: Decrease the verbosity of the program.
ru: Уменьшить количество выводимой пояснительной информации.

note: type: textblock
en: Output some debugging information.
ru: Вывод отладочной информации.

note: type: textblock
en: 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'.
ru: Дополнительные параметры, передаваемые модулю формата. См. описание возможных параметров и их значений в документации каждого конкретного модуля. Например, вы можете указать '-o tablecells' парсеру AsciiDoc, в то время как парсер text принимал бы '-o tabs=split'.

note: type: textblock
en: Always generate the POT and PO files, even if B<po4a> considers it is not necessary.
ru: Всегда создавать POT и PO-файлы, даже если B<po4a> считает, что это не требуется.

note: type: textblock
en: The default behavior (when B<--force> is not specified) is the following:
ru: Поведение по умолчанию (когда параметр B<--force> не установлен) следующее:

note: type: textblock
en: If the POT file already exists, it is regenerated if a master document or the configuration file is more recent (unless B<--no-update> is provided).  The POT file is also written in a temporary document and B<po4a> verifies that the changes are really needed.
ru: Если POT-файл уже существует, он создаётся повторно, если мастер-документ или файл настроек был недавно изменён (и если не задан параметр B<--no-update>). POT-файл также записывается во временный документ и B<po4a> проверяет, что изменения действительно необходимы.

note: type: textblock
en: Also, a translation is regenerated only if its master document, the PO file, one of its addenda or the configuration file is more recent.  To avoid trying to regenerate translations which do not pass the threshold test (see B<--keep>), a file with the F<.po4a-stamp> extension can be created (see B<--stamp>).
ru: Кроме того, перевод обновляется (regenerated) только если его мастер-документ, PO-файл, один из его аддендумов или файл настроек были обновлены после перевода. Дабы избежать повторяющихся бесплодных попыток обновления переводов, которые ещё не преодолели порогового значения (см. B<--keep>), можно создать файл с расширением F<.po4a-stamp> (см. B<--stamp>).

note: type: textblock
en: If a master document includes files, you should use the B<--force> flag because the modification time of these included files are not taken into account.
ru: Если мастер-документ включает файлы, вам необходимо использовать флаг B<--force>, потому что время изменения включённых файлов не принимается во внимание.

note: type: textblock
en: The PO files are always re-generated based on the POT with B<msgmerge -U>.
ru: PO-файлы всегда обновляются из POT-файлов с помощью B<msgmerge -U>.

note: type: textblock
en: Tells B<po4a> to create stamp files when a translation is not generated because it does not reach the threshold. These stamp files are named according to the expected translated document, with the F<.po4a-stamp> extension.
ru: Указывает B<po4a> создать файлы-заглушки, если перевод не создаётся, поскольку он не преодолел порогового значения. Эти файлы будут называться также как и переведённый документ, с расширением F<.po4a-stamp>.

note: type: textblock
en: Note: This only activates the creation of the F<.po4a-stamp> files. The stamp files are always used if they exist, and they are removed with B<--rm-translations> or when the file is finally translated.
ru: Примечание: Параметр активирует только создание F<.po4a-stamp> файлов. Файлы-заглушки используются всегда если они существуют, и удаляются при выполнении B<--rm-translations> или когда файл полностью переведён.

note: type: textblock
en: Do not generate the translated documents, only update the POT and PO files.
ru: Не регенерировать переведённые документы, только обновлять POT и PO-файлы.

note: type: textblock
en: Do not change the POT and PO files, only the translation may be updated.
ru: Не менять POT и PO-файлы, только обновить переводы.

note: type: textblock
en: Keeps the existing translation files even if the translation doesn't meet the threshold specified by B<--keep>.  This option does not create new translation files with few content, but it will save existing translations which decay because of changes to the master files.
ru: Не удалять файлы перевода даже если перевод не соответствует пороговому значению, заданному B<--keep>. Этот параметр указывает po4a не создавать новые переведённые файлы с недостаточным количеством переведённого материала, а сохранять старые переводы, которые находятся в упадке из-за изменений в мастер-документах.

note: type: textblock
en: WARNING: This flag changes the po4a behavior in a rather drastic way: your translated files will not get updated at all until the translation improves. Only use this flag if you prefer shipping an outdated translated documentation rather than only shipping an accurate untranslated documentation.
ru: ПРЕДУПРЕЖДЕНИЕ: этот флаг изменяет поведение po4a достаточно радикальным образом: ваши переведённые файлы не будут обновляться вообще, пока перевод не улучшится. Используйте этот ключ только если вам больше по нраву поставлять устаревшую, но переведённою документацию, нежели только точную, но непереведённую.

note: type: textblock
en: Remove the translated files (implies B<--no-translations>).
ru: Удалить переведённые файлы (подразумевает B<--no-translations>).

note: type: textblock
en: This flag does nothing since 0.41, and may be removed in later releases.
ru: Этот флаг ничего не делает начиная с 0.41 и может быть удалён в последующих версиях.

note: type: =item
en: B<--translate-only> I<translated-file>
ru: B<--translate-only> I<переводимый-файл>

note: type: textblock
en: Translate only the specified file.  It may be useful to speed up processing if a configuration file contains a lot of files.  Note that this option does not update PO and POT files.  This option can be used multiple times.
ru: Перевести только указанный файл. Это может быть полезно, чтобы ускорить обработку, когда файл настроек содержит значительное количество файлов. Заметим, что этот параметр не обновляет PO и POT-файлы. Этот параметр может быть указан несколько раз.

note: type: =item
en: B<--variable> I<var>B<=>I<value>
ru: B<--variable> I<переменная>B<=>I<значение>

note: type: textblock
en: Define a variable that will be expanded in the B<po4a> configuration file.  Every occurrence of I<$(var)> will be replaced by I<value>.  This option can be used multiple times.
ru: Определяет переменную которая будет использоваться в файле настроек B<po4a>. Каждое появление I<$(переменная)> будет замещено на I<значение>. Данный параметр можно использовать несколько раз.

note: type: =item
en: B<--target-lang> I<LANG>
ru: B<--target-lang> I<ЯЗЫК>

note: type: textblock
en: Update PO files and generate translated documents only for the specified language. This option can be used multiple times.
ru: Обновлять PO-файлы и создавать переведённые документы только для указанного языка. Этот параметр может быть указан несколько раз.

note: type: =item
en: B<--srcdir> I<SRCDIR>
ru: B<--srcdir> I<ИСХОДНЫЙ_КАТАЛОГ>

note: type: textblock
en: Set the base directory for all input documents specified in the B<po4a> configuration file.
ru: Задаёт базовый каталог для всех входных документов, указанных в файле настроек B<po4a>.

note: type: textblock
en: If both I<destdir> and I<srcdir> are specified, input files are searched in the following directories, in order: I<destdir>, the current directory and I<srcdir>. Output files are written to I<destdir> if specified, or to the current directory.
ru: Если заданы оба параметра I<destdir> и I<srcdir>, то po4a будет искать входные файлы в следующих каталогах (в порядке перечисления): в I<destdir>, в текущем каталоге и в I<srcdir>. Выходные файлы будут записываться в I<destdir>, если этот параметр задан, иначе — в текущий каталог.

note: type: =item
en: B<--destdir> I<DESTDIR>
ru: B<--destdir> I<КАТАЛОГ_НАЗНАЧЕНИЯ>

note: type: textblock
en: Set the base directory for all the output documents specified in the B<po4a> configuration file (see B<--srcdir> above).
ru: Задаёт базовый каталог для всех выходных документов, указанных в файле настроек B<po4a> (см. описание B<--srcdir> выше).

note: type: =head2
en: Options modifying the POT header
ru: Параметры, изменяющие заголовок POT-файла

note: type: =item
en: B<--porefs> I<type>
ru: B<--porefs> I<тип>

note: type: textblock
en: Specify the reference format. Argument I<type> can be one of B<never> to not produce any reference, B<file> to only specify the file without the line number, B<counter> to replace line number by an increasing counter, and B<full> to include complete references (default: full).
ru: Задаёт формат сносок в комментариях PO-файла. Аргумент I<тип> может быть одним из: B<never> — не выводить никаких сносок, B<file> — не выводить номера строк (точнее, все номера строк будут заменены на 1), B<counter> — заменяет номера строк инкрементным счётчиком и B<full> — включает полноценные сноски (по умолчанию: B<full>).

note: type: =item
en: B<--wrap-po> B<no>|B<newlines>|I<number> (default: 76)
ru: B<--wrap-po> B<no>|B<newlines>|I<число> (по умолчанию: 76)

note: type: textblock
en: Specify how the po file should be wrapped. This gives the choice between either files that are nicely wrapped but could lead to git conflicts, or files that are easier to handle automatically, but harder to read for humans.
ru: Задаёт, как должны переносится строки в PO-файле. С помощью этого параметра можно выбрать одно из двух: или чтобы переносы в файлах были удобно расставлены для чтения людьми (хотя это и может привести к конфликтам в git), или чтобы файлы больше подходили для автоматической обработки (хотя это и снизит удобство чтения оных людьми).

note: type: textblock
en: Historically, the gettext suite has reformatted the po files at the 77th column for cosmetics. This option specifies the behavior of po4a. If set to a numerical value, po4a will wrap the po file after this column and after newlines in the content. If set to B<newlines>, po4a will only split the msgid and msgstr after newlines in the content. If set to B<no>, po4a will not wrap the po file at all.  The reference comments are always wrapped by the gettext tools that we use internally.
ru: Исторически сложилось так, что gettext переносил строки в PO-файлах на 77-м столбце (по косметическим соображениям). Этот параметр определяет, как должен вести себя po4a в связи с этим. Если в нём указано число, po4a будет переносить строки в PO-файле после указанного столбца, а также после символов перевода строки в содержимом. Если указано B<newlines>, то po4a будет разделять msgid и msgstr на строки только в местах перевода строк в самом их содержимом. Если же указано B<no>, то po4a вообще не будет переносить строки в PO-файле. Строки комментариев со ссылками на местоположение строки в исходном документе всегда разбиваются на строки по усмотрению инструментов gettext, которые используются внутри po4a.

note: type: textblock
en: Note that this option has no impact on how the msgid and msgstr are wrapped, i.e.  on how newlines are added to the content of these strings.
ru: Замечание: этот параметр ни как не влияет на то, как будут расставлены переносы строк внутри самих msgid и msgstr, т.е. на то, как переносы строк будут добавляться к их содержимому.

note: type: textblock
en: Language of the source files containing the documents to translate. Note that all master documents must use the same language.
ru: Язык файлов переводимых документов. Обратите внимание, что все мастер-документы должны быть на одном языке.

note: type: textblock
en: Set the report address for msgid bugs. By default, the created POT files have no Report-Msgid-Bugs-To fields.
ru: Установить адрес для сообщений об ошибках в msgid. По умолчанию, созданные POT-файлы не имеют поля Report-Msgid-Bugs-To.

note: type: =item
en: B<--copyright-holder> I<string>
ru: B<--copyright-holder> I<строка>

note: type: textblock
en: Set the copyright holder in the POT header. The default value is "Free Software Foundation, Inc."
ru: Указать владельца авторских прав в заголовке POT файла. Значение по умолчанию: «Free Software Foundation, Inc.»

note: type: =item
en: B<--package-name> I<string>
ru: B<--package-name> I<строка>

note: type: textblock
en: Set the package name for the POT header. The default is "PACKAGE".
ru: Указать имя пакета в заголовке POT-файла. Значение по умолчанию: «PACKAGE».

note: type: =item
en: B<--package-version> I<string>
ru: B<--package-version> I<строка>

note: type: textblock
en: Set the package version for the POT header. The default is "VERSION".
ru: Указать версию пакета в заголовке POT-файла. Значение по умолчанию: «VERSION».

note: type: =head2
en: Options to modify the PO files
ru: Параметры, изменяющие PO-файлы

note: type: =item
en: B<--msgmerge-opt> I<options>
ru: B<--msgmerge-opt> I<параметры>

note: type: textblock
en: Extra options for B<msgmerge>(1).
ru: Дополнительные параметры для B<msgmerge>(1).

note: type: textblock
en: Note: B<$lang> will be extended to the current language.
ru: Примечание: B<$lang> будет заменён на текущий язык.

note: type: textblock
en: This option removes B<--previous> from the options passed to B<msgmerge>.  This is necessary to support versions of B<gettext> earlier than 0.16.
ru: Данный параметр удаляет параметр B<--previous> из настроек B<msgmerge>. Это необходимо, при использовании версий B<gettext> ниже 0.16.

note: type: textblock
en: This option adds B<--previous> to the options passed to B<msgmerge>.  It requires B<gettext> 0.16 or later, and is activated by default.
ru: Данный параметр добавляет B<--previous> к параметрам, передаваемым B<msgmerge>. Для этого требуется B<gettext> версии 0.16 или выше; данный параметр активирован по умолчанию.

note: type: =head1
en: CONFIGURATION FILE
ru: ФАЙЛ НАСТРОЕК

note: type: textblock
en: po4a expects a configuration file as argument. This file must contain the following elements:
ru: po4a ожидает, что в качестве аргумента ему будет передан файл настроек. Этот файл должен содержать следующие данные:

note: type: =item
en: The path to the PO files and the list of languages existing in the project;
ru: Путь к PO-файлам и список языков, доступных в проекте;

note: type: =item
en: Optionally, some global options and so-called configuration aliases that are used as templates to configure individual master files;
ru: Опционально, некоторые глобальные параметры и, так называемые, псевдонимы настроек (configuration aliases), которые можно использовать в качестве шаблонов для настройки отдельных мастер-файлов;

note: type: =item
en: The list of each master file to translate, along with specific parameters.
ru: Список всех мастер-файлов, которые нужно переводить, и специфические параметры для оных.

note: type: textblock
en: All lines contain a command between square braces, followed by its parameters.  Comments begin with the char '#' and run until the end of the line. You can escape the end of line to spread a command over several lines.
ru: Каждая строка файла должна содержать директиву, заключённую в квадратные скобки, и её параметры. Комментарии начинаются с символа «#» и продолжаются до конца строки. Конец строки может быть экранирован (с помощью обратного слеша C<\>), в таком случае комментарий может быть растянут на несколько строк.

note: type: textblock
en: Some full examples are presented on this page, while other examples can be found in the C<t/cfg> directory of the source distribution.
ru: Несколько полноценных примеров представлены на этой страницы; дополнительные примеры можно найти в каталоге C<t/cfg> дистрибутива с исходными кодами.

note: type: =head2
en: Finding the PO and POT files
ru: Поиск POT и PO-файлов

note: type: textblock
en: The simplest solution is to explicitly give the path to POT and PO files, as follows:
ru: Самое простое решение — явно задать путь к POT и PO-файлам следующим образом:

note: type: verbatim
en:  [po4a_paths] man/po/project.pot de:man/po/de.po fr:man/po/fr.po
ru:  [po4a_paths] man/po/project.pot ru:man/po/ru.po fr:man/po/fr.po

note: type: textblock
en: This specifies the path to the POT file first, and then the paths to the German and French PO files.
ru: Это задаст пути к POT-файлу, а также к русскому и французскому PO-файлам.

note: type: textblock
en: The same information can be written as follows to reduce the risk of copy/paste errors:
ru: Тоже самое может быть записано следующим образом, дабы уменьшить риск ошибок при копировании/вставке:

note: type: verbatim
en:  [po4a_langs] fr de
     [po4a_paths] man/po/project.pot $lang:man/po/$lang.po
ru:  [po4a_langs] fr ru
     [po4a_paths] man/po/project.pot $lang:man/po/$lang.po

note: type: textblock
en: The C<$lang> component is automatically expanded using the provided languages list, reducing the risk of copy/paste error when a new language is added.
ru: Вместо C<$lang> будет автоматически подставлен, код языка из списка, что уменьшает риск ошибок, вызванных копированием/вставкой при добавлении нового языка.

note: type: textblock
en: You can further compact the same information by only providing the path to the directory containing your translation project, as follows.
ru: Также можно ещё сильнее сократить эту же информацию, задав путь к каталогу с переводами следующим образом.

note: type: textblock
en: The provided directory must contain a set of PO files, each named F<XX.po> with C<XX> the ISO 639-1 of the language used in this file. The directory must also contain a single POT file, with the C<.pot> 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).
ru: Указанный каталог должен содержать набор PO-файлов, каждый из которых имеет имя вида F<XX.po>, где C<XX> — это код языка перевода в соответствии с ISO 639-1. В каталоге также должен быть один единственный POT-файл, с расширением C<.pot>. Во время первого запуска этот файл может быть пустым, но он должен существовать (po4a не может сам угадать, какое имя файла ему вставить перед расширением).

note: type: textblock
en: Note that you must choose only one between C<po_directory> and C<po4a_paths>. The first one (C<po_directory>) 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 (C<po4a_paths>), is more explicit, probably more readable, and advised when you setup your first project with po4a.
ru: Заметьте, что вы можете выбрать только одно: или C<po_directory>, или C<po4a_paths>. Первый вариант (C<po_directory>) более компактен, что снижает риск ошибок из-за копирования/вставки, но заставляет вас использовать предопределённые имена файлов и структуру проекта. Второй (C<po4a_paths>) — более явный, вероятно, более читаемый и рекомендованный в случае, если вы впервые используете po4a для своего проекта.

note: type: =head3
en: Centralized or split PO files?
ru: Централизованные или раздельные PO-файлы?

note: type: textblock
en: By default, po4a produces one single PO 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.
ru: По умолчанию po4a создаёт один большой PO-файл для каждого языка, содержащий весь ваш перевод. С разрастанием вашего проекта размер этих файлов может стать проблемой. При использовании Weblate возможно задать приоритеты каждому сегменту перевода (т.е. msgid), чтобы важные строки переводились первыми, хотя некоторые команды всё же предпочитают разделять перевод на несколько файлов.

note: type: textblock
en: To have one PO file per master file, you simply have to use the string C<$master> in the name of your PO files on the C<[po4a_paths]> line, as follows.
ru: Чтобы использовать отдельный PO-файл для каждого мастер-файла, просто добавьте C<$master> в имя своего PO-файла в директиве C<[po4a_paths]>.

note: type: textblock
en: With this line, po4a will produce separate POT and PO files for each document to translate.  For example, if you have 3 documents and 5 languages, this will result in 3 POT files and 15 PO files. These files are named as specified on the C<po4a_paths> template, with C<$master> substituted to the basename of each document to translate. In case of name conflict, you can specify the POT file to use as follows, with the C<pot=> parameter.
ru: С такими настройками po4a будет создавать отдельные POT и PO-файлы, для каждого переводимого документа. Например, если в вашем проекте 3 документа и 5 языков, то будут созданы 3 POT-файла и 15 PO-файлов. Имена этих файлов будут получены на основе шаблона, заданном в C<po4a_paths>, с заменой C<$master> на базовое имя переводимого файла. При возникновении конфликта имён, вы также можете задать имена POT-файлов с помощью параметра C<pot=>, как показано ниже.

note: type: textblock
en: This feature can also be used to group several translated files into the same POT file. The following example only produces 2 POT files: F<l10n/po/foo.pot> (containing the material from F<foo/gui.xml>) and F<l10n/po/bar.pot> (containing the material from both F<bar/gui.xml> and F<bar/cli.xml>).
ru: Это также может быть использовано для того, чтобы сгруппировать несколько переводимых файлов в один POT-файл. Следующий пример создаёт только 2 POT-файла: F<l10n/po/foo.pot> (со стоками из F<foo/gui.xml>) и F<l10n/po/bar.pot> (со стоками и из F<bar/gui.xml>, и из F<bar/cli.xml>).

note: type: textblock
en: In split mode, B<po4a> builds a temporary compendium during the PO update, to share the translations between all the PO files. If two PO files have different translations for the same string, B<po4a> will mark this string as fuzzy and will submit both translations in all the PO files containing this string. When unfuzzied by the translator, the translation is automatically used in every PO files.
ru: В раздельном режиме B<po4a> создаёт временный неточный (fuzzy)сборник всех переводов во время обновления PO-файлов, чтобы объединить перевод одинаковых строк из различных PO-файлов. Если два PO-файла имеют различные переводы для одной и той же строки, B<po4a> пометит данные переводы как неточные (fuzzy) и добавит оба варианта в каждый PO-файл, содержащий эту строку. Затем, когда переводчик снимет пометку «неточно» хотя бы в одном PO-файле, перевод данной строки будет обновлён во всех PO-файлах автоматически.

note: type: =head2
en: Specifying the documents to translate
ru: Задание документов для перевода

note: type: textblock
en: You must also list the documents that should be translated. For each master file, you must specify the format parser to use, the location of the translated document to produce, and optionally some configuration. File names should be quoted or escaped if they contain spaces. Here is an example:
ru: Вы также должны перечислить документы, которые необходимо переводить. Для каждого мастер-файла нужно указать, какой парсер формата использовать, местоположение, куда записывать переведённые документы, а также, по необходимости, некоторые дополнительные параметры. Имена файлов, содержащие пробелы, должны быть взяты в кавычки или же пробелы должны быть экранированы слешами. Например:

note: type: textblock
en: But again, these complex lines are difficult to read and modify, e.g. when adding a new language. It is much simpler to reorganize things using the C<$lang> template as follows:
ru: Но, опять же, такие тяжеловесные конструкции сложно читать и изменять, например, когда нужно добавить новый язык. Намного проще будет реорганизовать всё это с помощью шаблонов с C<$lang>:

note: type: =head2
en: Specifying options
ru: Задание параметров

note: type: textblock
en: There is two types of options: I<po4a options> are default values to the po4a command line options while I<format options> are used to change the behavior of the format parsers. As a I<po4a options>, you could for example specify in your configuration file that the default value of the B<--keep> command line parameter is 50% instead of 80%. I<Format options> are documented on the specific page of each parsing module, e.g. L<Locale::Po4a::Xml(3pm)>. You could for example pass B<nostrip> to the XML parser to not strip the spaces around the extracted strings.
ru: Есть два вида параметров: I<параметры po4a>, которые задают значения по умолчанию для параметров командной строки самого po4a, и I<параметры форматов>, которые изменяют поведение парсера конкретного формата. I<Параметром po4a> будет являться, например, если вы зададите в своём файле настроек, что значение по умолчанию параметра командной строки B<--keep> будет 50% вместо 80%. I<Параметры форматов> описаны на справочной странице каждого отдельного модуля парсера конкретного формата, например L<Locale::Po4a::Xml(3pm)>. Вы, например, можете передать B<nostrip> парсеру XML, чтобы он не убирал пробелы у извлекаемых им строк.

note: type: textblock
en: You can pass these options for a specific master file, or even for a specific translation of that file, using C<opt:> and C<opt_XX:> for the C<XX> language.  In the following example, the B<nostrip> option is passed to the XML parser (for all languages), while the threshold will be reduced to 0% for the French translation (that is thus always kept).
ru: Вы можете передать эти параметры для конкретного мастер-файла или даже для перевода файла на конкретный язык, используя C<opt:> и C<opt_XX:> для языка C<XX>. В примере ниже, параметр B<nostrip>  передаётся парсеру XML (для всех языков), а порог завершения перевода будет уменьшен до 0% только для французского (чтобы он никогда не отбрасывался).

note: type: textblock
en: In any case, these configuration chunks must be located at the end of the line.  The declaration of files must come first, then the addendum if any (see below), and then only the options. The grouping of configuration chunks is not very important, since elements are internally concatenated as strings. The following examples are all equivalent:
ru: В любом случае, такие настройки должны находится в конце строки. Имена файлов должны идти вначале, затем аддендумы, если они есть (см. ниже), и только затем параметры. Как именно сгруппированы параметры друг с другом не очень важно, ибо внутри себя po4a просто соединяет их все в одну строку. Следующие варианты абсолютно эквивалентны:

note: type: textblock
en: Note that language specific options are not used when building the POT file. It is for example impossible to pass B<nostrip> to the parser only when building the French translation, because the same POT file is used to update every languages. So the only options that can be language-specific are the ones that are used when producing the translation, as the C<--keep> option.
ru: Заметьте, что параметры, специфичные для отдельных языков не используются во время создания POT-файла. Например, невозможно передать B<nostrip> парсеру только для французского перевода, так как тот же самый POT-файл используется для обновления всех языков. Так что специфичными для языка могут быть только те параметры, которые используются во время создания перевода, как параметр C<--keep>.

note: type: =head3
en: Configuration aliases
ru: Настройка псевдонимов (aliases)

note: type: textblock
en: To pass the same options to several files, the best is to define a type alias as follows. In the next example, C<--keep 0> is passed to every Italian translation using this C<test> type, that is an extension of the C<man> type.
ru: Наилучшим способом передать одинаковые параметры различным файлам будет определить псевдоним (alias) типа, как это показано ниже. В примере C<--keep 0> передаётся всех документов на итальянский с помощью типа C<test>, который является расширением типа C<man>.

note: type: textblock
en: You can also extend an existing type reusing the same name for the alias as follows. This is not interpreted as as an erroneous recursive definition.
ru: Вы также можете расширить существующий тип, использовав то же самое имя для псевдонима. Это не будет считаться ошибкой рекурсивного определения.

note: type: =head3
en: Global default options
ru: Глобальные параметры по умолчанию

note: type: textblock
en: You can also use C<[options]> lines to define options that must be used for all files, regardless of their type.
ru: Вы также можете использовать строки с директивой C<[options]>, чтобы определить параметры, которые должны использоваться для всех файлов, независимо от их типа.

note: type: textblock
en: As with the command line options, you can abbreviate the parameters passed in the configuration file:
ru: Как и параметры командной строки, параметры передаваемые в файле настроек можно сокращать:

note: type: =head3
en: Option priorities
ru: Приоритет параметров

note: type: textblock
en: The options of every sources are concatenated, ensuring that the default values can easily be overridden by more specific options. The order is as follows:
ru: Параметры из каждого источника соединяются в одну строку, что гарантирует, что значения по умолчанию могут быть переопределены более специфическими параметрами. Порядок приоритетов следующий:

note: type: =item
en: C<[options]> lines provide default values that can be overridden by any other source.
ru: Директивы C<[options]> задают значения по умолчанию, которые могут быть переопределены любым другим источником.

note: type: =item
en: Type aliases are then used. Language specific settings override the ones applicable to all languages.
ru: Затем идут псевдонимы типов.При этом настройки, специфичные для конкретных языков переопределяют те что применяются ко всем языкам.

note: type: =item
en: Settings that are specific to a given master file override both the default ones and the ones coming from the type alias. In this case also, language specific settings override the global ones.
ru: Настройки, специфичные для конкретного мастер-файла переопределяют и настройки по умолчанию и те что заданы в псевдонимах типов. В данном случае настройки, специфичные для языков, также переопределяют общие.

note: type: =item
en: Finally, parameters provided on the B<po4a> command line override any settings from the configuration file.
ru: Наконец, параметры, переданные в командной строке переопределяют любые параметры из файла настройки.

note: type: =head3
en: Example
ru: Пример

note: type: textblock
en: Here is an example showing how to quote the spaces and quotes:
ru: Пример, показывающий, как следует экранировать пробелы и кавычки:

note: type: =head2
en: Addendum: Adding extra content in the translation
ru: Аддендумы (addendum): добавление дополнительного содержимого в перевод

note: type: textblock
en: If you want to add an extra section to the translation, for example to give credit to the translator, then you need to define an addendum to the line defining your master file. Please refer to the page L<po4a(7)> for more details on the syntax of addendum files.
ru: Если вы хотите добавить дополнительный раздел в перевод, например, чтобы отдать дань уважения переводчику, то в строку с описанием вашего мастер-документа, вам нужно добавить определение аддендума. Подробности о синтаксисе аддендумов см. в L<po4a(7)>.

note: type: textblock
en: You can also use language templates as follow:
ru: Вы также можете использовать шаблоны языков:

note: type: textblock
en: If an addendum fails to apply, the translation is discarded.
ru: Если аддендум не получается применить, то весь перевод отбрасывается.

note: type: =head3
en: Modifiers for the addendum declaration
ru: Модификаторы объявления аддендума

note: type: textblock
en: Addendum modifiers can simplify the configuration file in the case where not all languages provide an addendum, or when the list of addenda changes from one language to the other. The modifier is a single char located before the file name.
ru: Модификаторы аддендумов могут упростить файл настройки в случае, если аддендум нужен для переводов не на все языки или если список аддендумов меняется от языка к языку. Модификатор представляет собой один символ, стоящий перед именем файла.

note: type: textblock
en: Include I<addendum_path> if this file does exist, otherwise do nothing.
ru: Использовать файл I<путь_к_аддендуму>, если этот файл существует, в противном случае — ничего не делать.

note: type: textblock
en: I<addendum_path> is not a regular addendum but a file containing a list of addenda, one by line.  Each addendum may be preceded by modifiers.
ru: I<путь_к_аддендому> является не собственно файлом-аддендумом, а файлом содержащим список аддендумов, по одному в каждой строке. Каждый такой аддендум также могут предварять свои модификаторы.

note: type: textblock
en: I<addendum_path> is discarded, it is not loaded and will not be loaded by any further addendum specification.
ru: I<путь_к_аддендуму> отбрасывается, он не загружается и не будет загружаться никакими будущими определениями аддендумов.

note: type: textblock
en: The following includes an addendum in any language, but if only it exists. No error is reported if the addendum does not exist.
ru: Например, чтобы включить аддендум для всех языков, для которых существует указанный файл можно сделать следующее (если файл не существует, то сообщение об ошибке не будет выдано):

note: type: textblock
en: The following includes a list of addendum for every language:
ru: Следующий пример задаёт список аддендумов для всех языков:

note: type: =head2
en: Filtering the translated strings
ru: Фильтрация переведённых строк

note: type: textblock
en: Sometimes, you want to hide some strings from the translation process. To that extend, you can give a C<pot_in> parameter to your master file to specify the name of the file to use instead of the real master when building the POT file. Here is an example:
ru: Иногда, вам хочется скрыть некоторые строки от переводчиков. Для этого вы можете задать параметр C<pot_in> в определении мастер-файла, дабы указать имя файла, из которого следует извлекать строки для создания POT-файла для перевода вместо настоящего мастер-файла. Например:

note: type: textblock
en: With this setting, the strings to translate will be extracted from the F<book-filtered.xml> (that must be produced before calling B<po4a>) while the translated files will be built from F<book.xml>. As a result, any string that is part of F<book.xml> but not in F<book-filtered.xml> will not be included in the PO files, preventing the translators from providing a translation for them. So these strings will be left unmodified when producing the translated documents.  This naturally decreases the level of translation, so you may need the C<--keep> option to ensure that the document is produced anyway.
ru: С такими настройками строки для перевода будут извлекаться из F<book-filtered.xml> (который должен быть создан до вызова B<po4a>), а переведённые документы будут собираться на основе F<book.xml>. В результате, все строки, которые есть только в F<book.xml>, но не в F<book-filtered.xml> не будут включены в PO-файлы, что предотвратит возможность того, что переводчики переведут что-то, что не должно быть переведено. Таким образом, эти строки останутся без изменений во время создания переведённых документов. Это, конечно, снижает фактический уровень готовности перевода, так что вам придётся снизить значение параметра C<--keep>, дабы документ всё равно создавался.

note: type: =head1
en: AUTHORS
ru: АВТОРЫ

note: type: verbatim
en:  Denis Barbier <barbier@linuxfr.org>
     Nicolas François <nicolas.francois@centraliens.net>
     Martin Quinson (mquinson#debian.org)
ru:  Денис Барбье (Denis Barbier) <barbier@linuxfr.org>
     Николя Франсуа (Nicolas François) <nicolas.francois@centraliens.net>
     Мартин Кенсон (Martin Quinson) (mquinson#debian.org)

note: type: =head1
en: COPYRIGHT AND LICENSE
ru: АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИИ

note: type: textblock
en: This program is free software; you may redistribute it and/or modify it under the terms of GPL v2.0 or later (see the COPYING file).
ru: Данная программа является свободным программным обеспечением; вы можете распространять и/или изменять её на условиях Универсальной общественной лицензии (GPL) GNU v2.0 или новее (см. файл COPYING).

note: type: textblock
en: po4a-gettextize - convert an original file (and its translation) to a PO file
ru: po4a-gettextize - преобразует исходный файл (и его перевод) в PO-файл

note: type: textblock
en: B<po4a-gettextize> B<-f> I<fmt> B<-m> I<master.doc> B<-l> I<XX.doc> B<-p> I<XX.po>
ru: B<po4a-gettextize> B<-f> I<формат> B<-m> I<мастер_документ.doc> B<-l> I<XX.doc> B<-p> I<XX.po>

note: type: textblock
en: (I<XX.po> is the output, all others are inputs)
ru: (I<XX.po> является выходным файлом, все остальные являются входными параметрами)

note: type: textblock
en: The B<po4a-gettextize> script helps you converting your previously existing translations into a po4a-based workflow. This is only to be done once to salvage an existing translation while converting to po4a, not on a regular basis after the conversion of your project. This tedious process is explained in details in Section 'Converting a manual translation to po4a' below.
ru: Скрипт B<po4a-gettextize> поможет вам преобразовать уже существующие переводы для использования их в рабочем процессе, основанном на po4a. Это необходимо сделать только один раз, чтобы во время интеграции po4a уже проделанная работа по переводу не пропала впустую; это не нужно будет делать регулярно при работе над вашим проектом. Этот нудный процесс описан во всех подробностях в главе «Преобразование уже существующего перевода в po4a» ниже.

note: type: textblock
en: You must provide both a master file (e.g., the source in English) and an existing translated file (e.g., a previous translation attempt without po4a). If you provide more than one master or translation files, they will be used in sequence, but it may be easier to gettextize each page or chapter separately and then use B<msgmerge> to merge all produced PO files. As you wish.
ru: Вы должны задать как мастер-файл (т.е. исходный документ на английском), так и уже существующий переведённый файл (т.е. предыдущая попытка перевода, выполненная без использования po4a). Если вы задали больше одного мастер-файла или файла с переводом, то они будут использованы последовательно, но учтите, что, скорей всего, проще будет геттекстизировать каждую страницу или главу отдельно, а затем слить их вместе в один PO-файл с помощью B<msgmerge>. Но это на ваше усмотрение.

note: type: textblock
en: If the master document has non-ASCII characters, the new generated PO file will be in UTF-8. If the master document is completely in ASCII, the generated PO will use the encoding of the translated input document.
ru: Если мастер-документ содержит не-ASCII символы, то созданный PO-файл будет в кодировке UTF-8. В противном случае, если мастер-документ полностью в кодировке ASCII, то созданный PO-файл будет использовать кодировку переводимого входного документа.

note: type: textblock
en: Format of the documentation you want to handle. Use the B<--help-format> option to see the list of available formats.
ru: Формат документации которой вы хотите обработать. Используйте параметр B<--help-format>, чтобы просмотреть список доступных форматов.

note: type: textblock
en: File containing the master document to translate. You can use this option multiple times if you want to gettextize multiple documents.
ru: Файл содержащий мастер-документ для перевода. Вы можете использовать этот параметр несколько раз, если вы хотите создать один PO-файл сразу для нескольких документов.

note: type: textblock
en: Charset of the file containing the document to translate.
ru: Кодировка файла, содержащаяся в документе для перевода.

note: type: textblock
en: File containing the localized (translated) document. If you provided multiple master files, you may wish to provide multiple localized file by using this option more than once.
ru: Файл, содержащий локализованный (переведённый) документ. Если вы указали несколько мастер-файлов, может возникнуть необходимость предоставить несколько файлов локализации, указав данный параметр несколько раз.

note: type: textblock
en: Charset of the file containing the localized document.
ru: Кодировка файла, содержащего переведённый документ.

note: type: textblock
en: File where the message catalog should be written. If not given, the message catalog will be written to the standard output.
ru: Файл в который будет записан каталог сообщений. Если не задан, то каталог сообщений будет записан в стандартный вывод.

note: type: textblock
en: List the documentation formats understood by po4a.
ru: Выводит список поддерживаемых po4a форматов.

note: type: textblock
en: Keep the temporary master and localized POT files built before merging.  This can be useful to understand why these files get desynchronized, leading to gettextization problems.
ru: Не удалять временные POT-файлы для мастер-документа и перевода, которые создаются перед их сшивкой. Это может быть полезно, чтобы понять, почему некоторые файлы рассинхронизированы (что приводит к проблемам с геттекстизацией).

note: type: =head2
en: Converting a manual translation to po4a
ru: Преобразование уже существующего перевода в po4a

note: type: textblock
en: B<po4a-gettextize> synchronizes the master and localized files to extract their content into a PO file. The content of the master file gives the B<msgid> while the content of the localized file gives the B<msgstr>. This process is somewhat fragile: the Nth string of the translated file is supposed to be the translation of the Nth string in the original.
ru: B<po4a-gettextize> синхронизирует мастер-файла с его переведённой версией, извлекая их содержимое в PO-файл. Содержимое мастер-файла даёт B<msgid>, а содержимое переведённого — B<msgstr>. Этот процесс в некоторой степени хрупок: предполагается что N-ый строка, извлечённая из переведённого файла является переводом N-ой строки исходного.

note: type: textblock
en: Gettextization works best if you manage to retrieve the exact version of the original document that was used for translation. Even so, you may need to fiddle with both master and localized files to align their structure if it was changed by the original translator, so working on files' copies is advised.
ru: Геттекстизация пройдёт легче, если вы сможете заполучить в точности ту версию исходного документа, которая использовалась для перевода. Хотя даже в этом случае вам, возможно, придётся немного поиграться и с мастер-документом, и с его переведённой версией, чтобы выравнять их структуры, например, в ситуации, когда они были изменены изначальным переводчиком.

note: type: textblock
en: Internally, each po4a parser reports the syntactical type of each extracted strings. This is how desynchronization are detected during the gettextization.  In the example depicted below, it is very unlikely that the 4th string in translation (of type 'chapter') is the translation of the 4th string in original (of type 'paragraph'). It is more likely that a new paragraph was added to the original, or that two original paragraphs were merged together in the translation.
ru: Внутренне, каждый парсер po4a возвращает синтаксический тип для каждой извлечённой строки. Это и помогает определить рассинхрон файлов во время геттекстизации. Например, в ситуации приведённой ниже очень маловероятно, что 4-я строка в переводе (типа «глава») является переводом 4-й строки в оригинале (типа «параграф»). Скорее в оригинал был добавлен новый параграф или два параграфа оригинала были объединены в переводе.

note: type: verbatim
en:     Original         Translation
    
      chapter            chapter
        paragraph          paragraph
        paragraph          paragraph
        paragraph        chapter
      chapter              paragraph
        paragraph          paragraph
ru:     Оригинал     Перевод
    
      глава        глава
        абзац        абзац
        абзац        абзац
        абзац      глава
      глава          абзац
        абзац        абзац

note: type: textblock
en: B<po4a-gettextize> will verbosely diagnose any structure desynchronization. When this happens, you should manually edit the files to add fake paragraphs or remove some content here and there until the structure of both files actually match. Some tricks are given below to salvage the most of the existing translation while doing so.
ru: B<po4a-gettextize> будет выдавать подробные диагностические сообщения о любых расхождениях в структуре файлов. Кода такое произойдёт, вам придётся вручную отредактировать эти файлы: добавить какие-то суррогатные параграфы или удалить что-то то там то тут, дабы исправить найденные несоответствия так, чтобы структура обоих файлов в точности совпадала. Несколько трюков, как это сделать так, чтобы сохранить как можно большую часть уже готового перевода, приведены ниже.

note: type: textblock
en: If you are lucky enough to have a perfect match in the file structures out of the box, building a correct PO file is a matter of seconds. Otherwise, you will soon understand why this process has such an ugly name :) Even so, gettextization often remains faster than translating everything again. I gettextized the French translation of the whole Perl documentation in one day despite the I<many> synchronization issues. Given the amount of text (2MB of original text), restarting the translation without first salvaging the old translations would have required several months of work. In addition, this grunt work is the price to pay to get the comfort of po4a. Once converted, the synchronization between master documents and translations will always be fully automatic.
ru: Если вам повезёт и структура обоих документов идеально совпадает, то создание корректного PO-файла займёт всего несколько секунд. В противном случае вы вскоре поймёте, почему у этого процесса такое уродливое название :). Но даже в таком случае, геттекстизация будет быстрее, чем переводить всё с нуля. Например, я геттекстизировал Французский перевод всей документации Perl за один день, несмотря на то, что у меня возникло I<много> проблем с синхронизацией. Учитывая объём (2Mb оригинального текста), перевод всего этого с нуля не сохраняя предыдущие наработки занял бы несколько месяцев. К тому же, эта грязная работёнка — это та цена, которую придётся заплатить за то, чтобы пользоваться удобствами po4a в дальнейшем. Как только вы завершите процесс преобразования, синхронизация между мастер-документом и переводами станет полностью автоматической.

note: type: textblock
en: After a successful gettextization, the produced documents should be manually checked for undetected disparities and silent errors, as explained below.
ru: После успешной геттекстизации, полученные документы должны быть проверены вручную на предмет скрытых несоответствий и ошибок, как описано далее.

note: type: =head3
en: Hints and tricks for the gettextization process
ru: Подсказки и хитрости для процесса gettextization

note: type: textblock
en: The gettextization stops as soon as a desynchronization is detected. When this happens, you need to edit the files as much as needed to re-align the files' structures. B<po4a-gettextize> is rather verbose when things go wrong. It reports the strings that don't match, their positions in the text, and the type of each of them. Moreover, the PO file generated so far is dumped as F<gettextization.failed.po> for further inspection.
ru: Как только в файлах обнаруживается рассинхронизация, процесс гетекстизации останавливается. Когда это происходит, вам придётся вручную отредактировать файлы так, чтобы их структуры снова стали выравненными. B<po4a-gettextize> довольно подробно описывает, что пошло не так. Он выдаст вам строки, которые не совпадают, их местоположение в документах и тип каждой из них. Кроме того, созданный до момента этого сбоя PO-файл будет сбрасываться в F<gettextization.failed.po>.

note: type: textblock
en: Here are some tricks to help you in this tedious process and ensure that you salvage the most of the previous translation:
ru: Вот еще несколько приемов, которые помогут вам в этом утомительном процессе и гарантировать, что вы сохранить большую часть уже сделанного перевода:

note: type: =item
en: Remove all extra content of the translations, such as the section giving credits to the translators. They should be added separately to B<po4a> as addenda (see L<po4a(7)>).
ru: Удалите все лишнее содержимое из переводов, например, раздел с благодарностями переводчикам. С B<po4a> подобные разделы должны добавляться в виде аддендумов (B<addendum>, см. L<po4a(7)>).

note: type: =item
en: When editing the files to align their structures, 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 first po4a run after gettextization (see below). Any unmatched translation will be dumped anyway.  That being said, you still want to edit the original document if it's too hard to get the gettextization to proceed otherwise, even if it means that one paragraph of the translation is dumped. The important thing is to get a first PO file to start with.
ru: Когда вы редактируете файлы, чтобы выравнять их структуры, то, по-возможности, лучше редактировать перевод. Действительно, если изменения в оригинале будут слишком навязчивыми, старая и новая версии не будут корректно сопоставлены при первом запуске po4a после геттекстизации (см. ниже). Любые переводы, которым нет соответствий в оригинале всё равно придётся выбросить. Тем не менее, в некоторых ситуациях, когда иначе продолжить геттекстизацию не получается, иногда будет легче всё же внести правку и в исходный документ; даже если это и означает, что один из абзацев перевода будет отброшен. Главное на этом этапе — получить первый PO-файл, с которого можно начать дальнейшую работу.

note: type: =item
en: 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.
ru: Не стесняйтесь удалять какой-либо текст в оригинале, которого нет в переведённой версии. В дальнейшем всё это содержимое будет восстановлено при синхронизации PO-файла с документом.

note: type: =item
en: You should probably inform the original author of any structural change in the translation that seems justified. Issues in the original document should reported to the author. Fixing them in your translation only fixes them for a part of the community. Plus, it is impossible to do so when using po4a ;) But you probably want to wait until the end of the conversion to B<po4a> before changing the original files.
ru: Если вы считаете, что ваши изменения структуры документа в переводе оправданы, то, скорее всего, вам следует связаться по этому поводу с его автором. О проблемах оригинального документа нужно сообщать автору оригинального документа. Если вы исправляете их только в своём переводе, то вы исправляете эти проблемы только для части сообщества. И кроме того, это невозможно при использовании po4a ;). Однако, с этим, наверное, лучше будет повременить до окончания конвертации проекта для работы с B<po4a>.

note: type: =item
en: Sometimes, the paragraph content does match, but not their types. Fixing it is rather format-dependent. In POD and man, it often comes from the fact that one of them contains a line beginning with a white space while the other does not.  In those formats, such paragraph cannot be wrapped and thus become a different type. Just remove the space and you are fine. It may also be a typo in the tag name in XML.
ru: Иногда содержимое абзацев совпадает, но не их типы. То, как именно разрешить эту ситуацию, зависит от формата. В POD и man это зачастую происходит из-за того, что один из них начинается с пробела, а другой — нет. Для этих форматов в таком абзаце (начинающемся с пробела) запрещён перенос строк и, таким образом, он рассматривается, как имеющий другой тип. Просто удалите пробел и всё будет в порядке. Это также может быть вызвано, например, опечаткой в имени тега в XML.

note: type: textblock
en: Likewise, two paragraphs may get merged together in POD when the separating line contains some spaces, or when there is no empty line between the B<=item> line and the content of the item.
ru: Аналогично, два абзаца могут слиться в один в POD, когда разделяющая их строка содержит пробелы или когда между B<=item> и содержимым элемента нет пустой строки.

note: type: =item
en: Sometimes, the desynchronization message seems odd because the translation is attached to the wrong original paragraph. It is the sign of an undetected issue earlier in the process. Search for the actual desynchronization point by inspecting the file F<gettextization.failed.po> that was produced, and fix the problem where it really is.
ru: Иногда сообщения о рассинхронизации кажутся странными так как перевод привязывается не к тому абзацу оригинала. Это признак того, что проблема где-то выше не была обнаружена. Ищите истинную точку рассинхронизации, исследуя содержимое файла F<gettextization.failed.po>, созданного после неудачной геттекстизации, и исправьте проблему там.

note: type: =item
en: Other issues may come from duplicated strings in either the original or translation. Duplicated strings are merged in PO files, with two references.  This constitutes a difficulty for the gettextization algorithm, that is a simple one to one pairing between the B<msgid>s of both the master and the localized files. It is however believed that recent versions of po4a deal properly with duplicated strings, so you should report any remaining issue that you may encounter.
ru: Другой класс проблем может возникать из-за дубликатов строк (когда одна и таже строка встречается в файле несколько раз) в оригинале или переводе. Дубликаты строк объединяются в PO-файле в одну с несколькими сносками. Это является проблемой для алгоритма геттекстизации, так как он просто попарно берёт B<msgid> полученные из мастер-файла и из перевода. Однако, считается, что относительно новые версии po4a могут корректно обрабатывать дубликаты строк, так что вам следует сообщать о любых оставшихся проблемах, с которыми вы столкнётесь.

note: type: =head2
en: Reviewing files produced by B<po4a-gettextize>
ru: Проверка файлов, созданных B<po4a-gettextize>

note: type: textblock
en: Any file produced by B<po4a-gettextize> should be manually reviewed, even when the script terminates successfully. You should skim over the PO file, ensuring that the B<msgid> and B<msgstr> actually match. It is not necessary to ensure that the translation is perfectly correct yet, as all entries are marked as fuzzy translations anyway. You only need to check for obvious matching issues because badly matched translations will be dumped in subsequent steps while you want to salvage them.
ru: Любой файл, созданный B<po4a-gettextize>, должен подлежать тщательной ручной проверке, даже если выполнение завершается успешно. Вам следует просмотреть PO-файл и убедиться, что B<msgid> и B<msgstr> действительно соответствуют друг другу. На данном этапе пока нет необходимости проверять полную корректность перевода, поскольку все записи и так помечаются как «неточные» (fuzzy). Вам надо только проверить, нет ли очевидных проблем с соответствием переводов исходным строкам, поскольку те переводы которые окажутся сопоставлены не своим строкам, будут попросту удалены на последующих этапах в то время, как вам, вероятно, хотелось бы их сохранить.

note: type: textblock
en: Fortunately, this step does not require to master the target languages as you only want to recognize similar elements in each B<msgid> and its corresponding B<msgstr>. As a speaker of French, English, and some German myself, I can do this for all European languages at least, even if I cannot say one word of most of these languages. I sometimes manage to detect matching issues in non-Latin languages by looking at string length, phrase structures (does the amount of interrogation marks match?) and other clues, but I prefer when someone else can review those languages.
ru: К счастью, для данной задачи не обязательно овладевать целевым языком в полной мере, ибо вам нужно будет только распознавать похожие элементы в B<msgid> и соответствующем ему B<msgstr>. Например я, как человек говорящий по-французски, по-английски и немного по-немецки, могу произвести подобную проверку, по крайней мере, для всех европейских языков не смотра на то, что я не могу выговорить ни слова на большинстве из них. Иногда мне удаётся обнаружить проблемы с сопоставлением и в языках с не-латинской письменностью. В этих случаях можно обращать внимание на длину строк, структуру фраз (совпадает ли количество вопросительных знаков?) и другие подсказки, но проверку подобных языков я предпочитаю оставлять на кого-то другого.

note: type: textblock
en: If you detect a mismatch, edit the original and translation files as if B<po4a-gettextize> reported an error, and try again. Once you have a decent PO file for your previous translation, backup it until you get po4a working correctly.
ru: Если вы обнаружите несоответствия, то отредактируйте исходный файл или перевод также, как если бы B<po4a-gettextize> сообщил об ошибке, и попробуйте снова. Как только у вас получится сносный PO-файл для уже существующего перевода, сохраните его резервную копию и отложите в сторону до тех пор, пока вы не настроите po4a так, чтобы она корректно обрабатывала ваш проект.

note: type: =head2
en: Running B<po4a> for the first time
ru: Запуск B<po4a> в первый раз

note: type: textblock
en: The easiest way to setup po4a is to write a B<po4a.conf> configuration file, and use the integrated B<po4a> program (B<po4a-updatepo> and B<po4a-translate> are deprecated). Please check the "CONFIGURATION FILE" Section in L<po4a(1)> documentation for more details.
ru: Самый простой способ подготовить po4a к работе — создать файл настроек B<po4a.conf> и дальше пользоваться интегрированной утилитой B<po4a> (B<po4a-updatepo> и B<po4a-translate> устарели). Более подробно это описано в раздел «ФАЙЛ НАСТРОЕК» в L<po4a(1)>.

note: type: textblock
en: When B<po4a> runs for the first time, the current version of the master documents will be used to update the PO files containing the old translations that you salvaged through gettextization. This can take quite a long time, because many of the B<msgid>s of from the gettextization do not exactly match the elements 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 run over the Perl documentation's French translation (5.5 MB PO file) took about 48 hours (yes, two days) while the subsequent ones only take seconds.
ru: При первом запуске B<po4a> текущая версия мастер-документов будет использоваться для обновления PO-файлов, содержащих старые переводы, которые вы вытащили во время геттекстизации. Это может занять довольно длительное время, поскольку многие B<msgid> после геттекстизации могут в некоторой степени отличаться от тех, что в POT-файле, созданном из последних мастер-файлов. Это приводит к тому, что gettext вынужден искать ближайшие соответствия, используя дорогостоящие алгоритмы приближённого сопоставления строк. Например, первый подобный запуск для французского перевода документации Perl (PO-файл размером 5,5 МБ) занял около 48 часов (да, два дня), а последующие — всего несколько секунд.

note: type: =head2
en: Moving your translations to production
ru: Переход к повседневной работе с переводами

note: type: textblock
en: After this first run, the PO files are ready to be reviewed by translators. All entries were marked as fuzzy in the PO file by B<po4a-gettextization>, forcing their careful review before use. Translators should take each entry to verify that the salvaged translation actually match the current original text, update the translation on need, and remove the fuzzy markers.
ru: После этого первого запуска PO-файлы готовы к проверке переводчиками. После работы B<po4a-gettextization> все записи в PO-файле были помечены как неточные (fuzzy), что вынудит переводчиков проверять их тщательно, прежде чем использовать. Переводчики должны проверить каждую запись, чтобы убедиться, что сохранённый перевод действительно соответствует текущему исходному тексту, по-необходимости обновить перевод и удалить пометку «неточный».

note: type: textblock
en: Once enough fuzzy markers are removed, B<po4a> will start generating the translation files on disk, and you're ready to move your translation workflow to production. Some projects find it useful to rely on weblate to coordinate between translators and maintainers, but that's beyond B<po4a>' scope.
ru: Как только достаточное количество переводов будут проверены (будут сняты пометки о «неточный»), B<po4a> начнёт создавать переведённые файлы на их основе, и вы будете готовы полностью интегрировать данный рабочий процесс в свою повседневную деятельность. Некоторые проекты полагаются на такие сервисы, как, например, weblate для координации взаимодействия между переводчиками и сопровождающими проекта, но это уже выходит за рамки описания работы с B<po4a>.

note: type: textblock
en: po4a-normalize - normalize a documentation file by parsing it in po4a, and writing it back
ru: po4a-normalize - нормализует файл документации, выполняя синтаксический разбор в po4a, и записывая файл снова без какого-либо перевода

note: type: textblock
en: B<po4a-normalize> B<-f> I<fmt> I<master.doc>
ru: B<po4a-normalize> B<-f> I<формат> I<мастер_докумант.doc>

note: type: textblock
en: The po4a (PO for anything) project goal is to ease translations (and more interestingly, the maintenance of translations) using gettext tools on areas where they were not expected like documentation.
ru: Целью проекта po4a (PO for anything, PO везде и для всего) является облегчение процесса перевода (и что более важно — поддержки перевода), используя инструменты gettext в тех случаях, когда их применение может выглядеть неожиданным, например для документации.

note: type: textblock
en: The B<po4a-normalize> script is a debugging tool used to make sure that po4a don't change the document when it's not supposed to. Only use it if you're developing a new module, or if you doubt the sanity of the tools.
ru: Сценарий B<po4a-normalize> — это отладочный инструмент, использующийся для того, чтобы убедиться что po4a не изменяет документ когда это не предполагается. Его использование предполагается только при разработке новых модулей или когда требуется убедится в корректности работы инструментов po4a.

note: type: textblock
en: The generated document will be written to F<po4a-normalize.output> while the generated POT file will be written to F<po4a-normalize.po> by default, but you can use the B<--localized> and B<--pot> options to change that.
ru: Сгенерированный документ будет записан в F<po4a-normalize.output>, а сгенерированный PO-файл будет записан в F<po4a-normalize.po>, но вы можете изменить это поведение с помощью параметров B<--localized> и B<--pot>.

note: type: textblock
en: Create a blank translated document.  The generated translated document will be generated assuming all messages are translated by a space or new line.
ru: Создаёт пустой переведённый документ. Этот документ будет создан, будто все сообщения переведены одним символом пробела или новой строки.

note: type: textblock
en: This is useful to check what parts of the document cannot be translated.
ru: Это можно применять для проверки того, какие части документа не могут быть переведены.

note: type: textblock
en: Both B<--blank> and B<--capitalize> can't be specified at the same time.
ru: B<--blank> и B<--capitalize> не могут быть указаны одновременно.

note: type: textblock
en: Create a translated document and corresponding po-file with original strings translated as their capitalized versions.
ru: Создать переведенный документ и соответствующий PO-файл, в которых переведенные строки представляют собой исходные строки, записанные в верхнем регистре.

note: type: textblock
en: This is useful to check what parts of the document cannot be translated and generate test data for po4a.
ru: Это полезно, чтобы проверить, какие части документа не могут быть переведены, и сгенерировать тестовые данные для po4a.

note: type: textblock
en: Name of the normalized file to produce (I<po4a-normalize.output> by default).
ru: Имя нормализованного файла для создания (по умолчанию I<po4a-normalize.output>).

note: type: textblock
en: Pot file to produce (I<po4a-normalize.po> by default).
ru: Результирующий pot файл (по умолчанию I<po4a-normalize.po>).

note: type: textblock
en: po4a-translate - convert a PO file back to documentation format
ru: po4a-translate - преобразует PO-файлы обратно в формат документации

note: type: textblock
en: B<po4a-translate> B<-f> I<fmt> B<-m> I<master.doc> B<-p> I<XX.po> B<-l> I<XX.doc>
ru: B<po4a-translate> B<-f> I<формат> B<-m> I<мастер_документ.doc> B<-p> I<XX.po> B<-l> I<XX.doc>

note: type: textblock
en: (I<XX.doc> is the output, all others are inputs)
ru: (I<XX.doc> является выходным параметром, все остальные являются входными)

note: type: textblock
en: The B<po4a-translate> script is in charge of converting the translation (which was done in a PO file) back into the documentation format. The provided PO file should be the translation of the POT file which was produced by L<po4a-gettextize(1)>.
ru: Скрипт B<po4a-translate> отвечает за преобразование перевода (который был выполнен в PO-файле) обратно в формат документации. Данный PO-файл должен являться переводом POT-файла, созданного с помощью L<po4a-gettextize(1)>.

note: type: textblock
en: Add a file to the resulting file (to put translator's name or a section "About this translation", for example). The first line of the file to insert should be a PO4A header indicating where it should be added (see section B<HOWTO add extra text to translations> in L<po4a(7)>).
ru: Файл дополнения, который будет добавлен в итоговый файл (например, для того, чтобы добавить имена переводчиков или раздел «Об этом переводе»). Первая строка в файле должна являться заголовком PO4A, указывающим местоположение, куда именно следует подставить данный файл (см. раздел B<КАК добавить дополнительный текст в перевод> в L<po4a(7)>).

note: type: textblock
en: File containing the master document to translate.
ru: Файл, содержащий мастер-документ для перевода.

note: type: textblock
en: File where the localized (translated) document should be written.
ru: Файл, в который локализованный (переведённый) документ должен быть записан.

note: type: textblock
en: File from which the message catalog should be read.
ru: Файл, из которого будет читаться каталог сообщений (message catalog).

note: type: textblock
en: Minimal threshold for translation percentage to keep (i.e. write) the resulting file (default: 80). I.e. by default, files have to be translated at least at 80% to get written.
ru: Минимальное пороговое значение, в процентах, для сохранения (например, для записи) результирующего файла (по умолчанию: 80). То есть, по умолчанию, для того чтобы файл был записан, необходимо перевести как минимум 80%.

note: type: =head1
en: Adding content (beside translations) to generated files
ru: Добавление материалов (кроме перевода) в создаваемые файлы

note: type: textblock
en: To add some extra content to the generated document beside what you translated (like the name of the translator, or an "About this translation" section), you should use the B<--addendum> option.
ru: Чтобы добавить дополнительное содержимое в создаваемый документ, помимо собственно перевода (например: имя переводчика, или раздел «Об этом переводе»), вам необходимо использовать параметр B<--addendum>.

note: type: textblock
en: The first line of the addendum must be a header indicating where to put it in the document (it can be before or after a given part of the document).  The rest of the file will be added verbatim to the resulting file without further processing.
ru: В первой строке аддендума должен содержаться заголовок, указывающий куда именно в документе он (аддендум) должно быть добавлен (он может располагаться до или после указанного раздела документа). Остальное содержимое данного файла будет взято дословно и добавлено в итоговый файл без каких-либо преобразований.

note: type: textblock
en: Note that if po4a-translate fails to add one of the given files, it discards the whole translation (because the missing file could be the one indicating the author, what would prevent the users to contact him to report bugs in the translation).
ru: Заметим, что если po4a-translate не сможет добавить один из указанных файлов, то весь перевод будет отброшен (потому что пропущенный файл может оказаться тем, в котором указан автор и его контактные данные, что в свою очередь привело бы к невозможности для пользователей связаться с ним и сообщить об ошибке в переводе).

note: type: textblock
en: The header has a pretty rigid syntax. For more information on how to use this feature and how it works, please refer to the L<po4a(7)> man page.
ru: Заголовок имеет довольно жёсткий синтаксис. Для получения более подробной информации о том, как использовать данные возможности и как они работают, обратитесь к man-странице L<po4a(7)>.

note: type: textblock
en: po4a-updatepo - update the translation (in PO format) of documentation
ru: po4a-updatepo - обновляет перевод документации (в PO-формате)

note: type: textblock
en: B<po4a-updatepo> B<-f> I<fmt> (B<-m> I<master.doc>)+ (B<-p> I<XX.po>)+
ru: B<po4a-updatepo> B<-f> I<формат> (B<-m> I<мастер_документ.doc>)+ (B<-p> I<XX.po>)+

note: type: textblock
en: (I<XX.po> are the outputs, all others are inputs)
ru: (I<XX.po> является выходным файлом, всё остальное является входными параметрами)

note: type: textblock
en: The B<po4a-updatepo> script is in charge of updating PO files to make them reflect the changes made to the original documentation file. For that, it converts the documentation file to a POT file, and call L<msgmerge(1)> on this new POT and on the provided PO files.
ru: Скрипт B<po4a-updatepo> отвечает за обновление PO-файлов, чтобы в них отражались изменения, выполненные в оригинальном файле документации. Для этого он преобразует файл документации в POT-файл и вызывает L<msgmerge(1)> для нового POT-файла и предоставленного PO-файлов.

note: type: textblock
en: It is possible to give more than one PO file (if you want to update several languages at once), and several documentation files (if you want to store the translations of several documents in the same PO file).
ru: Возможно указать более одного PO-файла (если вы хотите обновить несколько языков сразу), и несколько файлов документации (если вы хотите хранить переводы нескольких документов в одном PO-файле).

note: type: textblock
en: If the master document has non-ASCII characters, this script will convert the PO files to UTF-8 (if they weren't already), for a transparent handling of non-standard characters.
ru: Если мастер-документ содержит какие-либо не ASCII символы, то данный сценарий преобразует PO-файлы в кодировку UTF-8 (если это ещё не так).

note: type: textblock
en: File(s) containing the master document to translate.
ru: Файл(ы), содержащий мастер-документ для перевода.

note: type: textblock
en: Charset of the files containing the document to translate. Note that all files must have the same charset.
ru: Кодировка файлов, содержащих документ для перевода. Обратите внимание, что все файлы должны иметь одну и ту же кодировку.

note: type: textblock
en: PO file(s) to update. If these files do not exist, they are created by B<po4a-updatepo>.
ru: PO-файл(ы), которые будут обновлены. Если эти файлы не существуют, B<po4a-updatepo> создаст их.

note: type: textblock
en: This option removes B<--previous> from the options passed to B<msgmerge>.  This helps supporting old versions of B<gettext> (before v0.16).
ru: Данный параметр удаляет B<--previous> из параметров передаваемых B<msgmerge>. Это позволяет поддерживать работу со старыми версиями B<gettext> (до 0.16).

note: type: =item
en: B<--porefs> I<type>[,B<wrap>|B<nowrap>]
ru: B<--porefs> I<тип>[,B<wrap>|B<nowrap>]

note: type: textblock
en: Argument can be followed by a comma and either B<wrap> or B<nowrap> keyword.  References are written by default on a single line.  The B<wrap> option wraps references on several lines, to mimic B<gettext> tools (B<xgettext> and B<msgmerge>).  This option will become the default in a future release, because it is more sensible.  The B<nowrap> option is available so that users who want to keep the old behavior can do so.
ru: Аргумент может быть дополнен запятой и одним из ключевых слов: B<wrap> или B<nowrap>. Сноски по умолчанию записываются в одну строку. Опция B<wrap> разбивает их на несколько строк, подражая утилитам B<gettext> (B<xgettext> и B<msgmerge>). Этот вариант будет поведением по умолчанию в будущих версиях, так как в таком виде сноски лучше заметны. Опция B<nowrap> доступна для тех пользователей, которые хотят оставить старое поведение.

note: type: textblock
en: Historically, the gettext suite has reformatted the po files at the 77th column for cosmetics. This option specifies the behavior of po4a. If set to a numerical value, po4a will wrap the po file after this column and after newlines in the content. If set to B<newlines>, po4a will only split the msgid and msgstr after newlines in the content. If set to B<no>, po4a will not wrap the po file at all.  The wrapping of the reference comments is controlled by the B<--porefs> option.
ru: Исторически сложилось так, что gettext переносил строки в PO-файлах на 77-м столбце (по косметическим соображениям). Этот параметр определяет, как должен вести себя po4a в связи с этим. Если в нём указано число, po4a будет переносить строки в PO-файле после указанного столбца, а также после символов перевода строки в содержимом. Если указано B<newlines>, то po4a будет разделять msgid и msgstr на строки только в местах перевода строк в самом их содержимом. Если же указано B<no>, то po4a вообще не будет переносить строки в PO-файле. Перенос комментариев со сносками на расположение строк контролируется параметром B<--porefs>.

note: type: textblock
en: msguntypot - update PO files when a typo is fixed in POT file
ru: msguntypot - обновляет PO-файлы при исправлении опечаток в POT-файле

note: type: textblock
en: B<msguntypot> B<-o> I<old_pot> B<-n> I<new_pot> I<pofiles> ...
ru: B<msguntypot> B<-o> I<старый_pot> B<-n> I<новый_pot> I<po-файлы> ...

note: type: textblock
en: When you fix a trivial error which surely doesn't affect translations (e.g.  a typo) in a POT file, you should unfuzzy the corresponding msgstr in the translated PO files to avoid so extra work to the translators.
ru: При исправлении тривиальных ошибок, которые не влияют на перевод (например, опечатки), в POT-файле, необходимо снять пометку «неточный перевод» (fuzzy) с соответствующей строки msgstr в переведённых PO-файлах, чтобы не нагружать переводчиков дополнительной работой данного рода.

note: type: textblock
en: This task is difficult and error prone when done manually, and this tool is there to help doing so correctly. You just need to provide the two versions of the POT file: before the edition and after as marked in the above synopsis, and it all becomes automatic.
ru: При выполнении вручную, эта задача сложна и чревата ошибками; данный инструмент предназначен для того чтобы делать это корректно. Вам просто необходимо предоставить две версии POT-файла: до редактирования и после, как указано выше, и всё будет сделано автоматически.

note: type: =head1
en: HOW TO USE IT
ru: КАК ЭТИМ ПОЛЬЗОВАТЬСЯ

note: type: textblock
en: In short, when you discover a typo in one of your [english] message, do the following:
ru: Если коротко, то когда вы обнаружили опечатку в одном из сообщений [английских], выполните следующие действия:

note: type: =item
en: - Regenerate your POT and PO files.
ru: - Выполните обновление ваших POT и PO-файлов.

note: type: verbatim
en:   make -C po/ update-po # for message program translations
      debconf-updatepo      # for debconf translations
      po4a po4a.conf        # for po4a based documentation translations
ru:   make -C po/ update-po # для переводов сообщений программ
      debconf-updatepo      # для переводов debconf
      po4a po4a.conf        # для переводов документации управляемых po4a

note: type: textblock
en: or something else, depending on your project's building settings. You know how to make sure your POT and PO files are uptodate, don't you??
ru: или что-то подобное, в зависимости от конфигурации сборки вашего проекта. Вы же знаете, как убедиться, что POT и PO-файлы в актуальном состоянии, не так ли?

note: type: =item
en: - Make a copy of your POT file.
ru: - Сделайте копию вашего POT-файла.

note: type: =item
en: - Make a copy of all your PO files.
ru: - Создайте копии всех ваших PO-файлов.

note: type: =item
en: - Fix your typo.
ru: - Исправьте опечатки.

note: type: textblock
en: $EDITOR the_file_in_which_there_is_a_typo
ru: $EDITOR файл_в_котором_присутствуют_опечатки

note: type: textblock
en: See above.
ru: См. выше.

note: type: textblock
en: At this point, the typo fix fuzzied all the translations, and this unfortunate change is the only one between the PO files of your main directory and the one from the fridge. Here is how to solve this.
ru: После всех предыдущих действий, исправление опечатки привело к тому, что все переводы были помечены как неточные (fuzzy), и эта мелкая неприятная особенность — единственное, что отличает PO-файлы в вашем основном каталоге от тех, что сохранены в po_fridge. Дабы разрешить эту проблему выполните следующие действия.

note: type: =item
en: - Discard fuzzy translation, restore the ones from the fridge.
ru: - Удалите перевод с пометками «неточный» (fuzzy), восстановите перевод из хранилища (fridge).

note: type: =item
en: - Manually merge the PO files with the new POT file, but taking the useless fuzzy into account.
ru: - Вручную объедините PO-файлы с новым POT-файлом, принимая в расчёт существование бесполезных неточных переводов.

note: type: =item
en: - Cleanups.
ru: - Очистка.

note: type: textblock
en: You're done. The typo was eradicated from msgstr of both your POT and PO files, and the PO files were not fuzzyied in the process. Your translators love you already.
ru: Всё выполнено. Опечатка была ликвидирована из строки msgstr, а также из POT и PO-файлов, и в PO-файлах отсутствуют пометки о неточном переводе. Ваши переводчики скажут вам спасибо за это.

note: type: textblock
en: Despite its name, this tool is not part of the gettext tool suite. It is instead part of po4a. More precisely, it's a random Perl script using the fine po4a modules. For more information about po4a, please see:
ru: Несмотря на своё название, этот инструмент не входит в комплект gettext. Это часть po4a. Точнее, это сценарий Perl использующий модули po4a. Более подробную информацию о po4a можно найти здесь:

note: type: textblock
en: po4a - framework to translate documentation and other materials
ru: po4a - платформа для перевода документации и других материалов

note: type: =head1
en: Introduction
ru: Введение

note: type: textblock
en: po4a (PO for anything) eases the maintenance of documentation translation using the classical gettext tools. The main feature of po4a is that it decouples the translation of content from its document structure.
ru: Ниже приводится дополнение на любом языке, но только если оно существует. Если дополнение не существует, об ошибке не сообщается.

note: type: textblock
en: This document serves as an introduction to the po4a project with a focus on potential users considering whether to use this tool and on the curious wanting to understand why things are the way they are.
ru: Этот документ служит введением в проект po4a, ориентированным на потенциальных пользователей, рассматривающих возможность использования этого инструмента, и на любознательных, желающих понять, почему все происходит именно так, как происходит.

note: type: =head1
en: Why po4a?
ru: Почему именно po4a?

note: type: textblock
en: The philosophy of Free Software is to make the technology truly available to everyone. But licensing is not the only consideration: untranslated free software is useless for non-English speakers. Therefore, we still have some work to do to make software available to everybody.
ru: Философия свободного программного обеспечения (ПО) состоит в том, чтобы сделать технологии по-настоящему доступными всем. Но лицензирование — это не единственное, о чём стоит задуматься: непереведённое свободное ПО бесполезно для неанглоговорящих пользователей. И нам предстоит ещё кое-какая работа, чтобы сделать его доступным по-настоящему для всех.

note: type: textblock
en: This situation is well understood by most projects and everybody is now convinced of the necessity to translate everything. Yet, the actual translations represent a huge effort of many individuals, crippled by small technical difficulties.
ru: Эта ситуация хорошо понятна большинству проектов, и все сейчас убеждены в необходимости переводить все. Тем не менее, фактические переводы представляют собой огромную работу многих людей, которая осложняется небольшими техническими трудностями.

note: type: textblock
en: Thankfully, Open Source software is actually very well translated using the gettext tool suite. These tools are used to extract the strings to translate from a program and present the strings to translate in a standardized format (called PO files, or translation catalogs). A whole ecosystem of tools has emerged to help the translators actually translate these PO files. The result is then used by gettext at run time to display translated messages to the end users.
ru: К счастью, у ПО с открытым исходным кодом достаточно хорошие переводы, которые удобно поддерживать благодаря инструментам из пакета gettext. Они извлекают строки для перевода из программ, и предоставляют их переводчикам в единообразном формате (называемом PO-файлы, или translation catalogs, каталоги переводов).Целая экосистема различных инструментов выросла вокруг оных, дабы помочь переводчикам собственно переводить эти PO-файлы. Результат их работы затем используется библиотекой gettext во время исполнения программы, чтобы отображать переведённые сообщения пользователю.

note: type: textblock
en: Regarding documentation, however, the situation still somewhat disappointing.  At first translating documentation may seem to be easier than translating a program as it would seem that you just have to copy the documentation source file and start translating the content. However, when the original documentation is modified, keeping track of the modifications quickly turns into a nightmare for the translators. If done manually, this task is unpleasant and error-prone.
ru: Что касается документации, то здесь ситуация все еще несколько неутешительна.  Поначалу перевод документации может показаться проще, чем перевод программы, поскольку кажется, что нужно просто скопировать исходный файл документации и начать переводить содержимое. Однако, когда в исходную документацию вносятся изменения, отслеживание этих изменений быстро превращается в кошмар для переводчиков. Если выполнять эту задачу вручную, она становится неприятной и чреватой ошибками.

note: type: textblock
en: Outdated translations are often worse than no translation at all. End-users can be tricked by documentation describing an old behavior of the program.  Furthermore, they cannot interact directly with the maintainers since they don't speak English. Additionally, the maintainer cannot fix the problem as they don't know every language in which their documentation is translated.  These difficulties, often caused by poor tooling, can undermine the motivation of volunteer translators, further aggravating the problem.
ru: Устаревшие переводы часто хуже, чем отсутствие перевода вообще. Конечные пользователи могут быть обмануты документацией, описывающей старое поведение программы.  Более того, они не могут напрямую взаимодействовать с сопровождающими, поскольку те не говорят по-английски. Кроме того, сопровождающий не может устранить проблему, поскольку не знает всех языков, на которые переведена документация.  Эти трудности, часто вызванные плохим инструментарием, могут подорвать мотивацию добровольных переводчиков, что еще больше усугубляет проблему.

note: type: textblock
en: B<The goal of the po4a project is to ease the work of documentation translators>.  In particular, it makes documentation translations I<maintainable>.
ru: B<Цель проекта po4a - облегчить работу переводчиков документации>.  В частности, он делает переводы документации I<поддерживаемыми>.

note: type: textblock
en: The idea is to reuse and adapt the gettext approach to this field. As with gettext, texts are extracted from their original locations and presented to translators as PO translation catalogs. The translators can leverage the classical gettext tools to monitor the work to do, collaborate and organize as teams. po4a then injects the translations directly into the documentation structure to produce translated source files that can be processed and distributed just like the English files. Any paragraph that is not translated is left in English in the resulting document, ensuring that the end users never see an outdated translation in the documentation.
ru: Идея заключается в повторном использовании и адаптации подхода gettext к этой области. Как и в gettext, тексты извлекаются из оригинальных мест и представляются переводчикам в виде каталогов переводов PO. Переводчики могут использовать классические инструменты gettext для контроля за выполнением работы, сотрудничества и организации команд. po4a затем вставляет переводы непосредственно в структуру документации для создания переведенных исходных файлов, которые можно обрабатывать и распространять так же, как и английские файлы. Любой абзац, который не переведен, остается на английском языке в итоговом документе, гарантируя, что конечные пользователи никогда не увидят в документации устаревший перевод.

note: type: textblock
en: This automates most of the grunt work of the translation maintenance.  Discovering the paragraphs needing an update becomes very easy, and the process is completely automated when elements are reordered without further modification. Specific verification can also be used to reduce the chance of formatting errors that would result in a broken document.
ru: Это автоматизирует большую часть тяжелой работы по обслуживанию перевода.  Обнаружить абзацы, нуждающиеся в обновлении, становится очень просто, а процесс полностью автоматизирован, когда элементы перестраиваются без дополнительных изменений. Конкретная проверка также может быть использована для снижения вероятности ошибок форматирования, которые приведут к поломке документа.

note: type: textblock
en: Please also see the B<FAQ> below in this document for a more complete list of the advantages and disadvantages of this approach.
ru: Полный список достоинств и недостатков этого подхода перечислен в разделе «B<Часто задаваемые вопросы>» ниже в этом документе.

note: type: =head2
en: Supported formats
ru: Поддерживаемые форматы

note: type: textblock
en: Currently, this approach has been successfully implemented to several kinds of text formatting formats:
ru: На данный момент этот подход был успешно воплощён для нескольких форматов:

note: type: =item
en: man (mature parser)
ru: man (зрелый парсер)

note: type: textblock
en: The good old manual pages' format, used by so many programs out there. po4a support is very welcome here since this format is somewhat difficult to use and not really friendly to newbies.
ru: Старый добрый формат man-страниц, который используют так много программ. Поддержка po4a приходится здесь очень кстати, ибо этот формат в некоторой степени сложен, и не особо дружелюбен к новичкам.

note: type: textblock
en: The L<Locale::Po4a::Man(3pm)|Man> module also supports the mdoc format, used by the BSD man pages (they are also quite common on Linux).
ru: Модуль L<Locale::Po4a::Man(3pm)|Man> также поддерживает формат mdoc, используемый в BSD man pages (они также довольно распространены в Linux).

note: type: =item
en: AsciiDoc (mature parser)
ru: AsciiDoc (зрелый парсер)

note: type: textblock
en: This format is a lightweight markup format intended to ease the authoring of documentation. It is for example used to document the git system. Those manpages are translated using po4a.
ru: Этот формат представляет собой легкий формат разметки, предназначенный для облегчения составления документации. Например, он используется для документирования системы git. Эти manpages переведены с помощью po4a.

note: type: textblock
en: See L<Locale::Po4a::AsciiDoc> for details.
ru: Подробнее см. в разделе L<Locale::Po4a::AsciiDoc>.

note: type: =item
en: pod (mature parser)
ru: pod (зрелый парсер)

note: type: textblock
en: This is the Perl Online Documentation format. The language and extensions themselves are documented using this format in addition to most existing Perl scripts. It makes easy to keep the documentation close to the actual code by embedding them both in the same file. It makes programmer's life easier, but unfortunately, not the translator's, until you use po4a.
ru: Это формат встроенной документации языка Perl (Perl Online Documentation). Сам язык и его расширения документируются с помощью этого формата, а также и большинство существующих сценариев perl. Это делает проще поддержать документацию близкой к исходному коду, так как они вместе находятся в одном и том же файле. Это делает проще жизнь программиста, но, к сожалению, не жизнь переводчика.

note: type: textblock
en: See L<Locale::Po4a::Pod> for details.
ru: Подробнее см. в разделе L<Locale::Po4a::Pod>.

note: type: =item
en: sgml (mature parser)
ru: sgml (зрелый парсер)

note: type: textblock
en: Even if superseded by XML nowadays, this format is still used for documents which are more than a few screens long. It can even be used for complete books.  Documents of this length can be very challenging to update. B<diff> often reveals useless when the original text was re-indented after update.  Fortunately, po4a can help you after that process.
ru: Даже если он и заменён XML в наши дни, этот формат всё ещё используется в тех документах, что длиннее нескольких экранов. Он может даже использоваться для целых книг. Обновление переводов таких длинных документов может быть настоящим вызовом. В частности, B<diff> зачастую показывает себя абсолютно бесполезным, когда в исходном тексте изменяются отступы после обновления. К счастью, po4a может с этим помочь.

note: type: textblock
en: Currently, only DebianDoc and DocBook DTD are supported, but adding support for a new one is really easy. It is even possible to use po4a on an unknown SGML DTD without changing the code by providing the needed information on the command line. See L<Locale::Po4a::Sgml(3pm)> for details.
ru: На данный момент поддерживаются только DebianDoc и DocBook DTD, но добавлять поддержку новых DTD достаточно просто. Возможно даже использование po4a для перевода неизвестного SGML DTD, вообще не вмешиваясь в исходный код; достаточно только предоставить всю необходимую информацию в командной строке. См. подробности в L<Locale::Po4a::Sgml(3pm)>.

note: type: =item
en: TeX / LaTeX (mature parser)
ru: TeX / LaTeX (зрелый парсер)

note: type: textblock
en: The LaTeX format is a major documentation format used in the Free Software world and for publications.
ru: Формат LaTeX — это основной формат публикаций, используемый в мире Свободного ПО.

note: type: textblock
en: The L<Locale::Po4a::LaTeX(3pm)|LaTeX> module was tested with the Python documentation, a book and some presentations.
ru: Модуль L<Locale::Po4a::LaTeX(3pm)|LaTeX> был проверен на документации Python, одной книге и нескольких презентациях.

note: type: =item
en: text (mature parser)
ru: text (зрелый парсер)

note: type: textblock
en: The Text format is the base format for many formats that include long blocks of text, including Markdown, fortunes, YAML front matter section, debian/changelog, and debian/control.
ru: Формат Text является базовым для многих форматов, включающих длинные блоки текста, включая Markdown, fortunes, YAML-загаловки (Front Matter), debian/changelog и debian/control.

note: type: textblock
en: This supports the common format used in Static Site Generators, READMEs, and other documentation systems. See L<Locale::Po4a::Text(3pm)|Text> for details.
ru: Поддерживает общий формат, используемый в генераторах статических сайтов, README и других системах документации. Подробности смотрите в разделе L<Locale::Po4a::Text(3pm)|Text>.

note: type: =item
en: xml and XHMTL (probably mature parser)
ru: xml and XHMTL (похоже, зрелый парсер)

note: type: textblock
en: The XML format is a base format for many documentation formats.
ru: Формат XML является базовым для многих форматов документации.

note: type: textblock
en: Currently, the DocBook DTD (see L<Locale::Po4a::Docbook(3pm)> for details) and XHTML are supported by po4a.
ru: На данный момент, po4a поддерживает DocBook DTD (cм. L<Locale::Po4a::Docbook(3pm)>) и XHTML.

note: type: =item
en: BibTex (probably mature parser)
ru: BibTex (похоже, зрелый парсер)

note: type: textblock
en: The BibTex format is used alongside LaTex for formatting lists of references (bibliographies).
ru: Формат BibTex используется наряду с LaTex для форматирования списков ссылок (библиографий).

note: type: textblock
en: See L<Locale::Po4a::BibTex> for details.
ru: Подробнее см. в разделе L<Locale::Po4a::BibTex>.

note: type: =item
en: Docbook (probably mature parser)
ru: Docbook (похоже, зрелый парсер)

note: type: textblock
en: A XML-based markup language that uses semantic tags to describe documents.
ru: Язык разметки на основе XML, использующий семантические теги для описания документов.

note: type: textblock
en: See L<Locale::Po4a:Docbook> for greater details.
ru: Более подробную информацию см. в L<Locale::Po4a:Docbook>.

note: type: =item
en: Guide XML (probably mature parser)
ru: Guide XML (похоже, зрелый парсер)

note: type: textblock
en: A XML documentation format. This module was developed specifically to help with supporting and maintaining translations of Gentoo Linux documentation up until at least March 2016 (Based on the Wayback Machine). Gentoo have since moved to the DevBook XML format.
ru: Формат документации XML. Этот модуль был разработан специально для помощи в поддержке и сопровождении переводов документации Gentoo Linux по крайней мере до марта 2016 года (по данным Wayback Machine). С тех пор Gentoo перешла на XML-формат DevBook.

note: type: textblock
en: See L<Locale::Po4a:Guide> for greater details.
ru: Более подробную информацию смотрите в L<Locale::Po4a:Guide>.

note: type: =item
en: Wml (probably mature parser)
ru: Wml (похоже, зрелый парсер)

note: type: textblock
en: The Web Markup Language, do not mixup WML with the WAP stuff used on cell phones.  This module relies on the Xhtml module, which itself relies on the XmL module.
ru: Язык веб-разметки, не путайте WML с WAP, используемым в мобильных телефонах.  Этот модуль основан на модуле Xhtml, который сам основан на модуле XmL.

note: type: textblock
en: See L<Locale::Po4a::Wml> for greater details.
ru: Более подробную информацию смотрите в разделе L<Locale::Po4a::Wml>.

note: type: =item
en: Yaml (probably mature parser)
ru: Yaml (похоже, зрелый парсер)

note: type: textblock
en: A strict superset of JSON. YAML is often used as systems or configuration projects.  YAML is at the core of Red Hat's Ansible.
ru: Строгий суперсет JSON. YAML часто используется в качестве системных или конфигурационных проектов.  YAML лежит в основе программы Ansible компании Red Hat.

note: type: textblock
en: See L<Locale::Po4a::Yaml> for greater details.
ru: Более подробную информацию см. в разделе L<Locale::Po4a::Yaml>.

note: type: =item
en: RubyDoc (probably mature parser)
ru: RubyDoc (похоже, зрелый парсер)

note: type: textblock
en: The Ruby Document (RD) format, originally the default documentation format for Ruby and Ruby projects before converted to RDoc in 2002. Though apparently the Japanese version of the Ruby Reference Manual still use RD.
ru: Формат Ruby Document (RD), первоначально формат документации по умолчанию для Ruby и Ruby-проектов до преобразования в RDoc в 2002 году. Хотя, по-видимому, японская версия справочного руководства по Ruby все еще использует RD.

note: type: textblock
en: See L<Locale::Po4a::RubyDoc> for greater details.
ru: Более подробную информацию см. в разделе L<Locale::Po4a::RubyDoc>.

note: type: =item
en: Halibut (probably experimental parser)
ru: Halibut (похоже, экспериментальный парсер)

note: type: textblock
en: A documentation production system, with elements similar to TeX, debiandoc-sgml, TeXinfo, and others, developed by Simon Tatham, the developer of PuTTY.
ru: Система создания документации, с элементами, похожими на TeX, debiandoc-sgml, TeXinfo и другие, разработанная Саймоном Тэтхемом, разработчиком PuTTY.

note: type: textblock
en: See L<Locale::Po4a:Halibut> for greater details.
ru: Более подробную информацию см. в разделе L<Locale::Po4a:Halibut>.

note: type: =item
en: Ini (probably experimental parser)
ru: Ini (похоже, экспериментальный парсер)

note: type: textblock
en: Configuration file format popularized by MS-DOS.
ru: Формат файла конфигурации, популярный в MS-DOS.

note: type: textblock
en: See L<Locale::Po4a::Ini> for greater details.
ru: Более подробную информацию смотрите в разделе L<Locale::Po4a::Ini>.

note: type: =item
en: texinfo (very highly experimental parser)
ru: texinfo (крайне экспериментальный парсер)

note: type: textblock
en: All of the GNU documentation is written in this format (it's even one of the requirements to become an official GNU project). The support for L<Locale::Po4a::Texinfo(3pm)|Texinfo> in po4a is still at the beginning.  Please report bugs and feature requests.
ru: Вся документация GNU написана в этом формате (вообще говоря, это одно из необходимых условий, чтобы стать официальным проектом GNU). Поддержка L<Locale::Po4a::Texinfo(3pm)|Texinfo> в po4a пока в зачаточном состоянии. Пожалуйста сообщайте об ошибках и запрашивайте новые возможности, когда требуется.

note: type: =item
en: gemtext (very highly experimental parser)
ru: gemtext (крайне экспериментальный парсер)

note: type: textblock
en: The native plain text format of the Gemini protocol.  The extension C<.gmi> is commonly used.  Support for this module in po4a is still in its infancy.  If you find anything, please file a bug or feature request.
ru: Собственный текстовый формат документации протокола Gemini. Обычно он использует расширение C<.gmi>. Поддержка этого формата в po4a пока находится в зачаточном состоянии. Если у вас возникнут какие-либо проблемы, то не стесняйтесь создавать новые сообщения об ошибках или запросы на добавление функций.

note: type: =item
en: org (very highly experimental parser)
ru: org (крайне экспериментальный парсер)

note: type: textblock
en: The document format used by the Org mode.  Support for this module in po4a is still in its infancy.  If you find anything, please file a bug or feature request.
ru: Формат, используемый в Org-mode. Поддержка этого формата в po4a пока находится в зачаточном состоянии. Если у вас возникнут какие-либо проблемы, то не стесняйтесь создавать новые сообщения об ошибках или запросы на добавление функций.

note: type: =item
en: vimhelp (very highly experimental parser)
ru: vimhelp (крайне экспериментальный парсер)

note: type: textblock
en: The format used for Vim help files (and some third-party plugin documentation).  Support for this format in po4a is still in its infancy.  If you find anything, please file a bug report or feature request.
ru: Формат, используемый для файлов справки Vim (а также документации некоторых сторонних плагинов). Поддержка этого формата в po4a пока находится в зачаточном состоянии. Если у вас возникнут какие-либо проблемы, то не стесняйтесь создавать новые сообщения об ошибках или запросы на добавление функций.

note: type: =item
en: simplepod (very highly experimental parser)
ru: simplepod (крайне экспериментальный парсер)

note: type: textblock
en: Similar to the previously mentioned I<pod>, this one adopts the new L<Pod::Simple> as its parser.  Since it is newly created, some bugs are expected.  If you notice any strange behavior, please let us know.  Eventually, this module will replace I<pod>.
ru: Аналогичен ранее упомянутому I<pod>, но этот модуль использует новый парсер L<Pod::Simple>. Поскольку он был создан не так давно, на данный момент возможны некоторые ошибки. Если вы заметите какое-либо странное поведение, пожалуйста, сообщите нам. В конечном итоге этот модуль заменит I<pod>.

note: type: =item
en: Others supported formats
ru: Другие поддерживаемые форматы

note: type: textblock
en: Po4a can also handle some more rare or specialized formats, such as the documentation of compilation options for the 2.4+ Linux kernels (L<Locale::Po4a::KernelHelp>) or the diagrams produced by the dia tool (L<Locale::Po4a::Dia>). Adding a new format is often very easy and the main task is to come up with a parser for your target format. See L<Locale::Po4a::TransTractor(3pm)> for more information about this.
ru: Po4a также может обрабатывать некоторые более редкие или специализированные форматы, такие как документация опций компиляции для ядер Linux 2.4+ (L<Locale::Po4a::KernelHelp>) или диаграммы, создаваемые инструментом dia (L<Locale::Po4a::Dia>). Добавление нового формата часто очень просто, и главная задача состоит в том, чтобы придумать парсер для вашего целевого формата. Подробнее об этом см. в L<Locale::Po4a::TransTractor(3pm)>.

note: type: =item
en: Unsupported formats
ru: Не поддерживаемые форматы

note: type: textblock
en: Unfortunately, po4a still lacks support for several documentation formats. Many of them would be easy to support in po4a. This includes formats not just used for documentation, such as, package descriptions (deb and rpm), package installation scripts questions, package changelogs, and all the specialized file formats used by programs such as game scenarios or wine resource files.
ru: К сожалению, в po4a всё ещё нет поддержки нескольких форматов документации. Поддержку многих из них было бы не так сложно добавить. И это включает не только форматы документации, но и, например, описание пакетов (deb и rpm), вопросы, задаваемые интерактивными сценариями установки пакетов, файлы changelogs для пакетов, и все специализированные форматы файлов, которые используются в программах, такие как сценарии игр или файлы ресурсов wine.

note: type: =head1
en: Using po4a
ru: Использование po4a

note: type: textblock
en: The easiest way to use this tool in your project is to write a configuration file for the B<po4a> program, and only interact with this program. Please refer to its documentation, in L<po4a(1)>. The rest of this section provides more details for the advanced users of po4a wanting to deepen their understanding.
ru: Самый простой способ использовать данный инструментарий в вашем проекте — создать файл настроек для утилиты B<po4a> и в дальнейшем взаимодействовать только с ней. См. подробности в документации L<po4a(1)>. Остальная часть данного раздела посвящена более подробному описанию работы po4a для продвинутых пользователей, жаждущих углубить своё понимание.

note: type: =head2
en: Detailed schema of the po4a workflow
ru: Подробная схема рабочего процесса, основанного на po4a

note: type: textblock
en: Make sure to read L<po4a(1)> before this overly detailed section to get a simplified overview of the po4a workflow. Come back here when you want to get the full scary picture, with almost all details.
ru: Прежде чем приступить к данному, излишне подробному, разделу, обязательно прочтите L<po4a(1)>, дабы получить общее представление о рабочем процессе, которому следует po4a. Возвращайтесь сюда, когда захотите получить всеобъемлющую страшную картину, которая будет включать практически все детали.

note: type: textblock
en: In the following schema, F<master.doc> is an example name for the documentation to be translated; F<XX.doc> is the same document translated in the language XX while F<doc.XX.po> is the translation catalog for that document in the XX language. Documentation authors will mostly be concerned with F<master.doc> (which can be a manpage, an XML document, an AsciiDoc file, etc); the translators will be mostly concerned with the PO file, while the end users will only see the F<XX.doc> file.
ru: На следующей схеме F<master.doc> - это документ, подлежащий переводу; F<XX.doc> - это тот же документ, но переведённый на язык XX, а F<doc.XX.po> - это каталог переводов для этого документа на язык XX. Авторы документации в основном будут иметь дело с F<master.doc> (который может быть man-страницей, XML-документом, файлом AsciiDoc и т.п.); переводчики в основном будут иметь дело с PO-файлом, а конечные пользователи будут видеть только файл F<XX.doc>.

note: type: textblock
en: Transitions with square brackets such as C<[po4a updates po]> represent the execution of a po4a tool while transitions with curly brackets such as C<{update of master.doc}> represent a manual modification of the project's files.
ru: Переходы с пометками в квадратных скобках, например C<[po4a updates po]>, представляют собой запуск инструментов po4a, а переходы с фигурными скобками, например C<{обновление master.doc}> — ручное изменение файлов проекта.

note: type: verbatim
en:                                    master.doc
                                           |
                                           V
         +<-----<----+<-----<-----<--------+------->-------->-------+
         :           |                     |                        :
    {translation}    |          {update of master.doc}              :
         :           |                     |                        :
       XX.doc        |                     V                        V
     (optional)      |                 master.doc ->-------->------>+
         :           |                   (new)                      |
         V           V                     |                        |
      [po4a-gettextize]   doc.XX.po -->+   |                        |
              |            (old)       |   |                        |
              |              ^         V   V                        |
              |              |   [po4a updates po]                  |
              V              |           |                          V
       translation.pot       ^           V                          |
              |              |        doc.XX.po                     |
              |              |         (fuzzy)                      |
        {translation}        |           |                          |
              |              ^           V                          V
              |              |     {manual editing}                 |
              |              |           |                          |
              V              |           V                          V
          doc.XX.po --->---->+<---<-- doc.XX.po    addendum     master.doc
          (initial)                 (up-to-date)  (optional)   (up-to-date)
              :                          |            |             |
              :                          V            |             |
              +----->----->----->------> +            |             |
                                         |            |             |
                                         V            V             V
                                         +------>-----+------<------+
                                                      |
                                                      V
                                         [po4a updates translations]
                                                      |
                                                      V
                                                    XX.doc
                                                 (up-to-date)
ru:                                    мастер.doc
                                           |
                                           V
          +<----<----+<-----<-----<--------+------->-------->--------+
          :          |                     |                         :
      {перевод}      |           {обновление мастер.doc}             :
          :          |                     |                         :
        XX.doc       |                     V                         V
    (необязательно)  |                 мастер.doc ->-------->------->+
          :          |                  (новый)                      |
          V          V                     |                         |
       [po4a-gettextize]  doc.XX.po -->+   |                         |
              |           (старый)     |   |                         |
              |              ^         V   V                         |
              |              |   [po4a обновляет po]                 |
              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 обновляет переводы]
                                                       |
                                                       V
                                                     XX.doc
                                                  (актуальный)

note: type: textblock
en: Again, this schema is overly complicated. Check on L<po4a(1)> for a simplified overview.
ru: Опять же, эта схема несколько переусложнена. Для упрощенного обзора см. L<po4a(1)>.

note: type: textblock
en: The left part depicts how L<po4a-gettextize(1)> can be used to convert an existing translation project to the po4a infrastructure. This script takes an original document and its translated counterpart, and tries to build the corresponding PO file. Such manual conversion is rather cumbersome (see the L<po4a-gettextize(1)> documentation for more details), but it is only needed once to convert your existing translations. If you don't have any translation to convert, you can forget about this and focus on the right part of the schema.
ru: В левой части показано, как L<po4a-gettextize(1)> можно использовать для преобразования существующего проекта перевода в инфраструктуру po4a. Этот скрипт берет оригинальный документ и его переведенный аналог и пытается построить соответствующий PO-файл. Такое ручное преобразование довольно громоздко (подробнее см. документацию L<po4a-gettextize(1)>), но оно необходимо только один раз для преобразования существующих переводов. Если у вас нет переводов для преобразования, вы можете забыть об этом и сосредоточиться на нужной части схемы.

note: type: textblock
en: On the top right part, the action of the original author is depicted, updating the documentation.  The middle right part depicts the automatic updates of translation files: the new material is extracted and compared against the exiting translation. The previous translation is used for the parts that didn't change, while partially modified parts are connected to the previous translation with a "fuzzy" marker indicating that the translation must be updated. New or heavily modified material is left untranslated.
ru: В верху правой части, изображены действия автора оригинала — обновление документации. В середине правой части показываются автоматические действия по обновлению перевода. Новые материалы извлекаются и сравниваются с существующим переводом. Для тех частей, которые не были изменены используется уже существующий перевод, а те части, которые были изменены частично соединяются с уже существующим переводом, но с пометкой «неточно» (fuzzy), указывающей, что перевод должен быть обновлён. Новые или сильно изменённые части оказываются непереведёнными.

note: type: textblock
en: Then, the I<manual editing> block depicts the action of the translators, that modify the PO files to provide translations to every original string and paragraph. This can be done using either a specific editor such as the B<GNOME Translation Editor>, KDE's B<Lokalize> or B<poedit>, or using an online localization platform such as B<weblate> or B<pootle>. The translation result is a set of PO files, one per language. Please refer to the gettext documentation for more details.
ru: Затем, в разделе I<ручное редактирование> описываются действия переводчиков, которые изменяют файлы PO, чтобы обеспечить перевод каждой оригинальной строки и абзаца. Это может быть сделано с помощью специального редактора, такого как B<GNOME Translation Editor>, KDE's B<Lokalize> или B<poedit>, или с помощью онлайн-платформы локализации, такой как B<weblate> или B<pootle>. Результатом перевода является набор PO-файлов, по одному на каждый язык. Более подробную информацию см. в документации gettext.

note: type: textblock
en: The bottom part of the figure shows how B<po4a> creates a translated source document from the F<master.doc> original document and the F<doc.XX.po> translation catalog that was updated by the translators. The structure of the document is reused, while the original content is replaced by its translated counterpart. Optionally, an addendum can be used to add some extra text to the translation. This is often used to add the name of the translator to the final document. See below for details.
ru: В нижней части схемы показано, как B<po4a> создаёт переведённый документ из исходного документа F<master.doc> и каталога переводов F<doc.XX.po>, который был обновлён переводчиками. Из исходного документа берётся его структура, а изначальное содержание заменяется его переведенной версией. Чтобы добавить к переводу некий дополнительный текст, при необходимости можно также использовать аддендумы (addendum). Обычно, они применяются для добавления, например, имени переводчика в окончательный документ. Подробности см. ниже.

note: type: textblock
en: Upon invocation, B<po4a> updates both the translation files and the translated documentation files automatically.
ru: При запуске B<po4a> автоматически обновляет и файлы перевода, и файлы с переведённой документацией.

note: type: =head2
en: Starting a new translation project
ru: Начало нового проекта перевода

note: type: textblock
en: If you start from scratch, you just have to write a configuration file for po4a, and you are set.  The relevant templates are created for the missing files, allowing your contributors to translate your project to their language. Please refer to L<po4a(1)> for a quick start tutorial and for all details.
ru: Если вы начинаете с нуля, то вам нужно только создать файл настроек po4a, и на этом всё будет готово. Для файлов, которых нет, будут созданы необходимые шаблоны, которые позволят участникам вашего проекта переводить его на свои языки. Краткое руководство по началу работы и прочие подробности см. в L<po4a(1)>.

note: type: textblock
en: If you have an existing translation, i.e. a documentation file that was translated manually, you can integrate its content in your po4a workflow using B<po4a-gettextize>. This task is a bit cumbersome (as described in the tool's manpage), but once your project is converted to po4a workflow, everything will be updated automatically.
ru: Если у вас уже есть какой-либо перевод, т.е. файл документации, который был переведён вручную, то вы можете извлечь из него перевод и встроить его в рабочий процесс, основанный на po4a с помощью B<po4a-gettextize>. Этот процесс может быть несколько неуклюжим (как описано на man-странице утилиты), но как только ваш проект будет преобразован, всё будет обновляться автоматически.

note: type: =head2
en: Updating the translations and documents
ru: Обновление переводов и документов

note: type: textblock
en: Once setup, invoking B<po4a> is enough to update both the translation PO files and translated documents. You may pass the C<--no-translations> to B<po4a> to not update the translations (thus only updating the PO files) or C<--no-update> to not update the PO files (thus only updating the translations). This roughly corresponds to the individual B<po4a-updatepo> and B<po4a-translate> scripts which are now deprecated (see "Why are the individual scripts deprecated" in the FAQ below).
ru: После первоначальной настройки, простой запуск B<po4a> будет выполнять и обновление PO-файлов и переведённой документации. Вы можете передать B<po4a> параметр C<--no-translations>, чтобы не обновлять переводы (т.е. обновлять только PO-файлы) или параметр C<--no-update>, чтобы не обновлять PO-файлы (т.е. обновлять только переводы). Эти действия примерно соответствует тому, что делали специализированные сценарии B<po4a-updatepo> и B<po4a-translate>, которые сейчас признаны устаревшими (см. «Почему специализированные сценарии признаны устаревшими?» в разделе «Часто задаваемые вопросы» ниже).

note: type: =head2
en: Using addenda to add extra text to translations
ru: Использование аддендумов (addendum) для добавления дополнительного текста к переводам

note: type: textblock
en: Adding new text to the translation is probably the only thing that is easier in the long run when you translate files manually :). This happens when you want to add an extra section to the translated document, not corresponding to any content in the original document. The classical use case is to give credits to the translation team, and to indicate how to report translation-specific issues.
ru: Добавление нового текста в перевод - это, пожалуй, единственное, что в долгосрочной перспективе проще, когда вы переводите файлы вручную :). Это происходит, когда вы хотите добавить в переведённый документ дополнительный раздел, не имеющий каких-либо соответствий в исходном документе. Классический вариант — добавление раздела, который отдаёт должное команде переводчиков и указывает, как и куда сообщать о проблемах, связанных с переводом.

note: type: textblock
en: With po4a, you have to specify B<addendum> files, that can be conceptually viewed as patches applied to the localized document after processing. Each addendum must be provided as a separate file, which format is however very different from the classical patches. The first line is a I<header line>, defining the insertion point of the addendum (with an unfortunately cryptic syntax -- see below) while the rest of the file is added verbatim at the determined position.
ru: В po4a для этого необходимо задать B<addendum>-файлы, которые на концептуальном уровне можно считать некими «патчами», накладываемыми на локализованный документ после его обработки. Каждый аддендум представляет из себя отдельный файла, формат которого, однако, сильно отличается от классических патчей. Первая строка — это I<строка заголовка>, определяющая точку вставки аддендума (с, к сожалению, загадочным синтаксисом - см. ниже), в то время как остальная часть файла добавляется дословно в определенную позицию.

note: type: textblock
en: The header line must begin with the string B<PO4A-HEADER:>, followed by a semi-colon separated list of I<key>B<=>I<value> fields.
ru: Строка заголовка должна начинаться со строки B<PO4A-HEADER:>, за которой следует список полей I<key>B<=>I<value>, разделенных запятыми.

note: type: textblock
en: For example, the following header declares an addendum that must be placed at the very end of the translation.
ru: Например, следующий заголовок указывает, что аддендум должен быть вставлен в самый конец перевода.

note: type: textblock
en: 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 XML section containing the string C<About this document> in translation.
ru: Если вы хотите добавить своё дополнительное содержимое в середину документа, то всё становится сложнее. Так, следующий заголовок указывает, что аддендум должен быть вставлен после XML-раздела (ограниченного тегом C<E<lt>sectionE<gt>>), содержащего строку C<Об этом документе> (в переводе).

note: type: verbatim
en:  PO4A-HEADER: position=About this document; mode=after; endboundary=</section>
ru:  PO4A-HEADER: position=Об этом документе; mode=after; endboundary=</section>

note: type: textblock
en: In practice, when trying to apply an addendum, po4a searches for the first line matching the C<position> argument (this can be a regexp). Do not forget that po4a considers the B<translated> 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.
ru: С практической точки зрения, при применении аддендума po4a ищет первую строку, соответствующую аргументу C<position> (он является регулярным выражением). Не забывайте, что в данном случае po4a работает с уже B<переведённым> документом. Например, если вы хотите, добавить аддендум к французскому переводу документа, то строка может выглядеть следующим образом:

note: type: textblock
en: Once the C<position> is found in the target document, po4a searches for the next line after the C<position> that matches the provided C<endboundary>. The addendum is added right B<after> that line (because we provided an I<endboundary>, i.e. a boundary ending the current section).
ru: После того как C<position> будет найдена в целевом документе, po4a будет искать среди строк следующих после C<position> строку, которая соответствует указанному C<endboundary> (также регулярное выражение). Аддендум будет добавлен сразу B<после> этой строки (поскольку мы указали I<endboundary>, то есть границу, заканчивающую текущий раздел).

note: type: textblock
en: The exact same effect could be obtained with the following header, that is equivalent:
ru: Точно такого же эффекта можно было бы достичь с помощью следующего заголовка, который эквивалентен предыдущему:

note: type: verbatim
en:  PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>
ru:  PO4A-HEADER: position=Об этом документе; mode=after; beginboundary=<section>

note: type: textblock
en: Here, po4a searches for the first line matching C<< <section> >> after the line matching C<About this document> in the translation, and add the addendum B<before> that line since we provided a I<beginboundary>, i.e. a boundary marking the beginning of the next section. So this header line requires placing the addendum after the section containing C<About this document>, and instruct po4a that a section starts with a line containing the C<< <section> >> tag. This is equivalent to the previous example because what you really want is to add this addendum either after C<< </section> >> or before C<< <section> >>.
ru: Здесь po4a ищет первую строку, которая будет сопоставлена C<< <section> >> после строки, сопоставленной C<Об этом документе> в переводе, и вставляет аддендум B<перед> этой строке, поскольку мы указали I<beginboundary>, то есть границу, обозначающую начало следующего раздела. Таким образом, этот заголовок указывает po4a, что аддендум должен быть вставлен после раздела, содержащего C<Об этом документе>, и задаёт, что раздел начинается со строки, содержащей тег C<< <section> >>. Это эквивалентно предыдущему примеру, поскольку на самом деле вам нужно добавить аддендум либо после C<< </section> >>, либо перед C<< <section> >>.

note: type: textblock
en: You can also set the insertion I<mode> to the value C<before>, with a similar semantic: combining C<mode=before> with an C<endboundary> will put the addendum just B<after> the matched boundary, that is the last potential boundary line before the C<position>. Combining C<mode=before> with an C<beginboundary> will put the addendum just B<before> the matched boundary, that is the last potential boundary line before the C<position>.
ru: Вы также можете установить режим вставки (I<mode>) в значение C<before> с аналогичной семантикой: при указании C<mode=before> совместно с C<endboundary> аддендум будет размещён сразу B<после> строки сопоставленной C<endboundary>, которая расположена до C<position>; при указании C<mode=before> совместно с C<beginboundary> аддендум будет размещён сразу B<перед> строкой сопоставленной C<beginboundary> которая расположена до C<position>.

note: type: verbatim
en:   Mode   | Boundary kind |     Used boundary      | Insertion point compared to the boundary
     ========|===============|========================|=========================================
     'before'| 'endboundary' | last before 'position' | Right after the selected boundary
     'before'|'beginboundary'| last before 'position' | Right before the selected boundary
     'after' | 'endboundary' | first after 'position' | Right after the selected boundary
     'after' |'beginboundary'| first after 'position' | Right before the selected boundary
     'eof'   |   (none)      |  n/a                   | End of file
ru:   Режим  |  Вид границы  |    Используемая граница    | Точка вставки относительно границы
     ========|===============|============================|===================================
     'before'|'endboundary'  | последняя перед 'position' | Прямо после выбранной границы
     'before'|'beginboundary'| последняя перед 'position' | Прямо перед выбранной границей
     'after' |'endboundary'  | первая после 'position'    | Прямо после выбранной границы
     'after' |'beginboundary'| первая после 'position'    | Прямо перед выбранной границей
     'eof'   | (нет)         | н/д                        | Конец файла

note: type: =head3
en: Hint and tricks about addenda
ru: Советы и хитрости при использовании аддендумов

note: type: =item
en: Remember that these are regexp. For example, if you want to match the end of a nroff section ending with the line C<.fi>, do not use C<.fi> as B<endboundary>, because it will match with C<the[ fi]le>, which is obviously not what you expect. The correct B<endboundary> in that case is: C<^\.fi$>.
ru: Запомните, что параметры аргументов аддендумов — это регулярные выражения. Например, если вы хотите сопоставить конец секции nroff, которая заканчивается строкой C<.fi>, то не стоит использовать C<.fi> в качестве B<endboundary>, ибо в таком случае также будет сопоставлена строка C<the[ fi]le>, что, очевидно, не то, что вы ожидаете. Правильный B<endboundary> в этом случае будет: C<^\.fi$>.

note: type: =item
en: White spaces ARE important in the content of the C<position> and boundaries. So the two following lines B<are different>. The second one will only be found if there is enough trailing spaces in the translated document.
ru: Для параметров C<position> и границ пробелы ВАЖНЫ. Например, две следующие строки B<различны>. Вторая из них будет найден только в том случае, если в переведенном документе окажутся лишние пробелы на конце строки.

note: type: verbatim
en:  PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>
     PO4A-HEADER: position=About this document ; mode=after; beginboundary=<section>
ru:  PO4A-HEADER: position=Об этом документе; mode=after; beginboundary=<section>
     PO4A-HEADER: position=Об этом документе ; mode=after; beginboundary=<section>

note: type: =item
en: Although this context search may be considered to operate roughly on each line of the B<translated> document, it actually operates on the internal data string of the translated document. This internal data string may be a text spanning a paragraph containing multiple lines or may be a XML tag itself alone. The exact I<insertion point> of the addendum must be before or after the internal data string and can not be within the internal data string.
ru: Хотя и можно считать, что этот контекстный поиск, грубо говоря, перебирает текст B<перевода> построчно, но на самом деле он работает со строками во внутреннем представлении данных документов. Этой строкой может быть, например, текст целого абзаца, разбитый на несколько фактических строк или один XML-тег сам по себе. Непосредственная I<точка вставки> аддендума должна быть или до, или после таковой строки во внутреннем представлении и не может быть вставлена в середину оной.

note: type: =item
en: Pass the C<-vv> argument to B<po4a> to understand how the addenda are added to the translation. It may also help to run B<po4a> in debug mode to see the actual internal data string when your addendum does not apply.
ru: Чтобы лучше понять, как аддендумы добавляются к переводу, передайте B<po4a> параметр C<-vv>. Также, когда ваш аддендум не применяется и вы не можете определить, почему, то может быть полезно запустить B<po4a> в режиме отладки, чтобы непосредственно увидеть строку с данными во внутреннем представлении.

note: type: =head3
en: Addenda examples
ru: Примеры аддендумов

note: type: =item
en: If you want to add something after the following nroff section:
ru: Если вы хотите добавить что-то после следующего раздела nroff (формат man-страниц):

note: type: verbatim
en:   .SH "AUTHORS"
ru:   .SH "АВТОРЫ"

note: type: textblock
en: You should select a two-step approach by setting B<mode=after>. Then you should narrow down search to the line after B<AUTHORS> with the B<position> argument regex. Then, you should match the beginning of the next section (i.e., B<^\.SH>) with the B<beginboundary> argument regex. That is to say:
ru: Вам следует выбрать подход с двумя регулярными выражениями, т.е. задать B<mode=after>. Затем сузьте поиск до строк идущих после B<АВТОРЫ> с помощью регулярного выражения в аргументе B<position>. После этого вы должны сопоставить начало следующей секции (например, с помощью B<^\.SH>) в аргументе B<beginboundary>. Короче говоря:

note: type: verbatim
en:  PO4A-HEADER:mode=after;position=AUTHORS;beginboundary=\.SH
ru:  PO4A-HEADER: mode=after; position=АВТОРЫ; beginboundary=\.SH

note: type: =item
en: If you want to add something right after a given line (e.g. after the line "Copyright Big Dude"), use a B<position> matching this line, B<mode=after> and give a B<beginboundary> matching any line.
ru: Если вы хотите добавить что-то сразу после конкретной строки (например, после «Copyright Большая Шишка»), используйте значение B<position>, соответствующее этой строке, задайте B<mode=after>, а B<beginboundary> — значение, соответствие любой строке.

note: type: verbatim
en:  PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^
ru:  PO4A-HEADER:mode=after;position=Copyright Большая Шишка, 2004;beginboundary=^

note: type: =item
en: If you want to add something at the end of the document, give a B<position> matching any line of your document (but only one line. Po4a won't proceed if it's not unique), and give an B<endboundary> matching nothing. Don't use simple strings here like B<"EOF">, but prefer those which have less chance to be in your document.
ru: Если вы хотите добавить что-то в конец документа, то присвойте B<position> регулярное выражение, сопоставляемое любой строке вашего документа (но только одна строке; po4a выдаст ошибку, если она будет не уникальна), и задайте B<endboundary> не соответствующее ни чему. Лучше не использовать здесь простые строки, например B<"EOF">, а отдать предпочтение тем, у которых меньше шансов оказаться в вашем документе.

note: type: verbatim
en:  PO4A-HEADER:mode=after;position=About this document;beginboundary=FakePo4aBoundary
ru:  PO4A-HEADER:mode=after;position=О программе;beginboundary=FakePo4aBoundary

note: type: =head3
en: More detailed example
ru: Более подробный пример

note: type: textblock
en: Original document (POD formatted):
ru: Исходный документ (формат POD):

note: type: verbatim
en:  |=head1 NAME
     |
     |dummy - a dummy program
     |
     |=head1 AUTHOR
     |
     |me
ru:  |=head1 NAME
     |
     |dummy - a dummy program
     |
     |=head1 AUTHOR
     |
     |Me <me@example.com>

note: type: textblock
en: Then, the following addendum will ensure that a section (in French) about the translator is added at the end of the file (in French, "TRADUCTEUR" means "TRANSLATOR", and "moi" means "me").
ru: Тогда следующий аддендум обеспечит добавление раздела о переводчике (на русском) в конец файла.

note: type: verbatim
en:  |PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
     |
     |=head1 TRADUCTEUR
     |
     |moi
     |
ru:  |PO4A-HEADER:mode=after;position=АВТОР;beginboundary=^=head
     |
     |=head1 ПЕРЕВОД
     |
     |Я <me@example.ru>
     |

note: type: textblock
en: To put your addendum before the AUTHOR, use the following header:
ru: Чтобы поместить свой аддендум перед «АВТОР», используйте следующий заголовок:

note: type: verbatim
en:  PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1
ru:  PO4A-HEADER:mode=after;position=ИМЯ;beginboundary=^=head1

note: type: textblock
en: This works because the next line matching the B<beginboundary> C</^=head1/> after the section "NAME" (translated to "NOM" in French), is the one declaring the authors. So, the addendum will be put between both sections. Note that if another section is added between NAME and AUTHOR sections later, po4a will wrongfully put the addenda before the new section.
ru: Это работает, так как следующая сопоставляемая B<beginboundary> C</^=head1/> строка после раздела «NAME» (переведённого как «ИМЯ» на русский) и начинает раздел с перечислением авторов. Таким образом, аддендум будет помещено между этими двумя разделами. Заметьте, что если в дальнейшем какой-либо другой раздел будет добавлен между разделами «ИМЯ» и «АВТОР», то данный пример будет работать не корректно, ибо аддендум будет вставляться перед этим новым разделом.

note: type: textblock
en: To avoid this you may accomplish the same using B<mode>=I<before>:
ru: Чтобы избежать этого, можете использовать аналогичный заголовок с B<mode>=I<before>:

note: type: verbatim
en:  PO4A-HEADER:mode=before;position=^=head1 AUTEUR
ru:  PO4A-HEADER:mode=before;position=^=head1 АВТОР

note: type: =head1
en: How does it work?
ru: Как это работает?

note: type: textblock
en: This chapter gives you a brief overview of the po4a internals, so that you may feel more confident to help us to maintain and to improve it. It may also help you to understand why it does not do what you expected, and how to solve your problems.
ru: В этой главе даётся краткий обзор внутренних компонентов po4a так, чтобы вы могли чувствовать себя увереннее, если вы захотите помочь нам сопровождать и улучшать его. Это также может помочь вам понять, почему он не делаете того, что вы ожидали, и как решить ваши проблемы.

note: type: =head2
en: TransTractors and project architecture
ru: TransTractors и архитектура проекта

note: type: textblock
en: At the core of the po4a project, the L<Locale::Po4a::TransTractor(3pm)|TransTractor> class is the common ancestor to all po4a parsers. This strange name comes from the fact that it is at the same time in charge of translating document and extracting strings.
ru: В сердце всего проекта po4a находится L<Locale::Po4a::TransTractor(3pm)|TransTractor>, общий предком всех классов-парсеров. Своё странное имя он получил оттого, что он одновременно отвечает и за перевод документа и извлечение строк.

note: type: textblock
en: More formally, it takes a document to translate plus a PO file containing the translations to use as input while producing two separate outputs: Another PO file (resulting of the extraction of translatable strings from the input document), and a translated document (with the same structure as the input one, but with all translatable strings replaced with content of the input PO). Here is a graphical representation of this:
ru: Если точнее, TransTractor берёт документ для перевода плюс PO-файл с переводами, кои являются его входными данными, и производит два отдельных набора выходных данных: другой PO-файл (как результат извлечения переводимых строк из входного документа) и переведённый документ (с той же структурой, что и входной, но со всеми переводимыми строками заменёнными содержимым входного PO-файла). Ниже приведено графическое представление этого процесса:

note: type: verbatim
en:    Input document --\                             /---> Output document
                         \      TransTractor::       /       (translated)
                          +-->--   parse()  --------+
                         /                           \
       Input PO --------/                             \---> Output PO
                                                           (extracted)
ru:    Входной документ -\                            /---> Выходной документ
                          \      TransTractor::      /       (переведённый)
                          +-->--   parse()  --------+
                         /                           \
       Входной PO ------/                             \---> Выходной PO
                                                           (извлечённый)

note: type: textblock
en: This little bone is the core of all the po4a architecture. If you provide both input and disregard the output PO, you get B<po4a-translate>. If you disregard the output document instead, you get B<po4a-updatepo>. The B<po4a> uses a first TransTractor to get an up-to-date output POT file (disregarding the output documents), calls B<msgmerge -U> to update the translation PO files on disk, and builds a second TransTractor with these updated PO files to update the output documents. In short, B<po4a> provides one-stop solution to update what needs to be, using a single configuration file.
ru: Эта маленькая косточка и является ядром всей архитектуры po4a. Если вы предоставляете оба входных файла и игнорируете выходной PO-файл, вы получаете B<po4a-translate>. Если вместо этого вы проигнорируете выходной документ то, вы получите B<po4a-updatepo>. B<po4a> сначала использует один TransTractor для получения актуального выходного POT-файла (игнорирую выходные документы), вызывает B<msgmerge -U> для обновления PO-файлов перевода, а затем создаёт второй TransTractor, который использует эти файлы для обновления уже выходных документов. Короче говоря, B<po4a> предоставляет комплексное решение для обновления всего, что нужно обновить, используя всего одну команду и один файл настроек.

note: type: textblock
en: B<po4a-gettextize> also uses two TransTractors, but another way: It builds one TransTractor per language, and then build a new PO file using the msgids of the original document as msgids, and the msgids of the translated document as msgstrs. Much care is needed to ensure that the strings matched this way actually match, as described in L<po4a-gettextize(1)>.
ru: B<po4a-gettextize> также использует два экземпляра TransTractor, но по-другому: она создаёт по одному TransTractor для каждого языка, а затем создаёт новый PO-файл, используя значения msgid из исходного документа в качестве, собственно, msgid и значения msgid из переведённого документа в качестве msgstr. При этом требуется значительная осторожность, чтобы гарантировать, что строки, сопоставленные таким образом, действительно соответствуют друг другу, как описано в L<po4a-gettextize(1)>.

note: type: =head2
en: Format-specific parsers
ru: Парсеры, специфические для конкретных форматов

note: type: textblock
en: All po4a format parsers are implemented on top of the TransTractor. Some of them are very simple, such as the Text, Markdown and AsciiDoc ones. They load the lines one by one using C<TransTractor::shiftline()>, accumulate the paragraphs' content or whatever. Once a string is completely parsed, the parser uses C<TransTractor::translate()> to (1) add this string to the output PO file and (2) get the translation from the input PO file. The parser then pushes the result to the output file using C<TransTractor::pushline()>.
ru: Парсеры всех форматов в po4a реализованы поверх TransTractor. Некоторые из них очень простые, например Text, Markdown и AsciiDoc. Они загружают строки одну за другой, используя C<TransTractor::shiftline()>, и накапливают содержимое абзацев (или что-то еще). После того как целая логическая строка (обычно, абзац) будет прочитана и разобрана, парсер использует C<TransTractor::translate()>, чтобы (1) добавить эту строку в выходной PO-файл и (2) получить перевод из входного PO-файла. Далее парсер отправляет результат в выходной файл с помощью C<TransTractor::pushline()>.

note: type: textblock
en: Some other parsers are more complex because they rely on an external parser to analyze the input document. The Xml, HTML, SGML and Pod parsers are built on top of SAX parsers. They declare callbacks to events such as "I found a new title which content is the following" to update the output document and output POT files according to the input content using C<TransTractor::translate()> and C<TransTractor::pushline()>. The Yaml parser is similar but different: it serializes a data structure produced by the YAML::Tiny parser. This is why the Yaml module of po4a fails to declare the reference lines: the location of each string in the input file is not kept by the parser, so we can only provide "$filename:1" as a string location. The SAX-oriented parsers use globals and other tricks to save the file name and line numbers of references.
ru: Некоторые другие парсиры более сложны, поскольку для анализа входного документа они полагаются на сторонние парсеры. Так например, парсеры Xml, HTML, SGML и Pod построены на основе SAX-парсеров. Они создают обратные вызовы для таких событий, как «Я нашёл новый заголовок со следующим содержимым», чтобы обновить выходной документ и выходные POT-файлы в соответствии со входным содержимым, используя C<TransTractor::translate()> и C<TransTractor::pushline()>. Парсер Yaml также похож, но отличается: он сохраняет структуру данных, созданную парсером YAML::Tiny. В этом причина того, что Yaml-модуль po4a не может корректно сохранять сноски на расположение строк в исходном файле: синтаксический анализатор не сохраняет расположение каждой строки, поэтому всё что мы можем, это только добавить «$имя_файла:1» в качестве местоположения строки. Парсеры же, основанные на SAX-модели, используют глобальные переменные и другие приёмы для сохранения имен файлов и номеров строк в сносках.

note: type: textblock
en: One specific issue arises from file encodings and BOM markers. Simple parsers can forget about this issue, that is handled by C<TransTractor::read()> (used internally to get the lines of an input document), but the modules relying on an external parser must ensure that all files are read with an appropriate PerlIO decoding layer. The easiest is to open the file yourself, and provide an filehandle or directly the full string to your external parser. Check on C<Pod::read()> and C<Pod::parse()> for an example. The content read by the TransTractor is ignored, but a fresh filehandle is passed to the external parser. The important part is the C<< "<:encoding($charset)" >> mode that is passed to the B<open()> perl function.
ru: Особый класс проблем возникает из-за кодировок файлов и маркера порядка байт. Более простые парсеры могут не волноваться об этом, так как C<TransTractor::read()> (используется внутри пасеров для чтения входного документа) сам заботится об обработке кодировок. А вот модули, использующие внешний парсеры, должны сами контролировать, что все файлы, которые они читают проходят через соответствующие уровни декодирования PerlIO. Самое простое — открыть файл самостоятельно и передать внешнему парсеру или дескриптор файла, или прочитать его самостоятельно и передать всё его содержимое парсеру в виде строки. В качестве примера см. C<Pod::read()> и C<Pod::parse()>. В случае, когда дескриптор файла передаётся внешнему парсеру, то то, что читает TransTractor, должно быть проигнорированно, а также важно, чтобы при открытии файла perl-функции B<open()> передавалась корректная кодировка: C<< <:encoding($charset) >>.

note: type: =head2
en: Po objects
ru: PO-объекты

note: type: textblock
en: The L<Locale::Po4a::Po(3pm)|Po> class is in charge of loading and using PO and POT files. Basically, you can read a file, add entries, get translations with the B<gettext()> method, write the PO into a file. More advanced features such as merging a PO file against a POT file or validating a file are delegated to B<msgmerge> and B<msgfmt> respectively.
ru: Класс L<Locale::Po4a::Po(3pm)|Po> отвечает за загрузку PO и POT-файлов, а также запрос переведённых строк из них. Если кратко, то вы можете читать файл, добавлять в него записи, получать из него переводы с помощью B<gettext()> и снова сохранять PO-файл. Более сложная функциональность, вроде объединение PO-файлов с POT-файлами или проверка файлов, отдаётся уже на откуп утилитам B<msgmerge> и B<msgfmt> соответственно.

note: type: =head2
en: Contributing to po4a
ru: Внесение своего вклада в po4a

note: type: textblock
en: Even if you have never contributed to any Open Source project in the past, you are welcome: we are willing to help and mentor you here. po4a is best maintained by its users nowadays. As we lack manpower, we try to make the project welcoming by improving the doc and the automatic tests to make you confident in contributing to the project. Please refer to the CONTRIBUTING.md file for more details.
ru: Даже если вы никогда раньше не участвовали в каких-либо проектах с открытым исходным кодом, мы будем вам рады: здесь мы готовы помочь вам и, по-необходимости, можем дать вам некоторые наставления. po4a в настоящее время в основном поддерживается пользователями. Поскольку нам не хватает рабочей силы, мы стараемся сделать проект приветливым и привлекательным, улучшая документацию и автоматизированные тесты, чтобы вам было проще внести свой вклад в проект. Более подробную информацию можно найти в файле CONTRIBUTING.md.

note: type: =head1
en: Open-source projects using po4a
ru: Проекты с открытым исходным кодом, использующие po4a

note: type: textblock
en: 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).
ru: Вот очень неполный список проектов, которые используют po4a при переводе своей документации. Если вы хотите добавить свой проект в список, то просто напишите нам e-mail (или запрос на слияние).

note: type: =item
en: adduser (man): users and groups management tool.
ru: adduser (man): инструмент по управлению пользователями и группами.

note: type: =item
en: apt (man, docbook): Debian package manager.
ru: apt (man, docbook): менеджер пакетов Debian.

note: type: =item
en: aptitude (docbook, svg): terminal-based package manager for Debian
ru: aptitude (docbook, svg): консольный менеджер пакетов для Debian

note: type: =item
en: L<F-Droid website|https://gitlab.com/fdroid/fdroid-website> (markdown): installable catalog of FOSS (Free and Open Source Software) applications for the Android platform.
ru: L<F-Droid website|https://gitlab.com/fdroid/fdroid-website> (markdown): каталог свободных и открытых приложений (Free and Open Source Software) для платформы Android.

note: type: =item
en: L<git|https://github.com/jnavila/git-manpages-l10n> (asciidoc): distributed version-control system for tracking changes in source code.
ru: L<git|https://github.com/jnavila/git-manpages-l10n> (asciidoc): распределённая система контроля изменений исходного кода.

note: type: textblock
en: 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).
ru: Также этот проект предоставляет инфраструктуру для перевода на разные языки множества разношёрстных man-страниц, которые затем интегрируются во многие основные дистрибутивы (в частности, Arch Linux, Debian и его производные, Fedora).

note: type: =item
en: L<Stellarium|https://github.com/Stellarium/stellarium> (HTML): a free open source planetarium for your computer. po4a is used to translate the sky culture descriptions.
ru: L<Stellarium|https://github.com/Stellarium/stellarium> (HTML): свободный планетарий для Вашего компьютера с открытым исходным кодом. po4a используется для перевода названий созвездий в различных культурах.

note: type: =item
en: L<Jamulus|https://jamulus.io/> (markdown, yaml, HTML): a FOSS application for online jamming in real time. The website documentation is maintained in multiple languages using po4a.
ru: L<Jamulus|https://jamulus.io/> (markdown, yaml, HTML): FOSS-приложение для онлайн джем-сессий в режиме реального времени. Переводы документации и веб-сайта на несколько языков поддерживаются с использованием po4a.

note: type: =item
en: Other item to sort out: L<https://gitlab.com/fdroid/fdroid-website/> L<https://github.com/fsfe/reuse-docs/pull/61>
ru: И другие проекты, в которых мы пока не разобрались: L<https://gitlab.com/fdroid/fdroid-website/> L<https://github.com/fsfe/reuse-docs/pull/61>

note: type: =head1
en: FAQ
ru: Часто задаваемые вопросы

note: type: =head2
en: How do you pronounce po4a?
ru: Как вы произносите «po4a»?

note: type: textblock
en: I personally vocalize it as L<pouah|https://en.wiktionary.org/wiki/pouah>, which is a French onomatopoetic that we use in place of yuck :) I may have a strange sense of humor :)
ru: Лично я произношу это как L<pouah|https://en.wiktionary.org/wiki/pouah>, это французское междометие, подобное русскому «фу!» :) Возможно, у меня странное чувство юмора :)

note: type: =head2
en: Why are the individual scripts deprecated?
ru: Почему специализированные сценарии признаны устаревшими?

note: type: textblock
en: Indeed, B<po4a-updatepo> and B<po4a-translate> are deprecated in favor of B<po4a>. The reason is that while B<po4a> can be used as a drop-in replacement to these scripts, there is quite a lot of code duplication here. Individual scripts last around 150 lines of codes while the B<po4a> program lasts 1200 lines, so they do a lot in addition of the common internals. The code duplication results in bugs occurring in both versions and needing two fixes. One example of such duplication are the bugs #1022216 in Debian and the issue #442 in GitHub that had the exact same fix, but one in B<po4a> and the other B<po4a-updatepo>.
ru: B<po4a-updatepo> и B<po4a-translate>, действительно, считаются устаревшими (depricated) в пользу B<po4a>. Причина в том, что, с одной стороны, B<po4a> можно использовать в качестве прямой замены этих сценариев, а с другой — между ними довольно много дублирующегося кода, который сложно поддерживать. Отдельные сценарии состоят примерно из 150 строк кода, а утилита B<po4a> — из 1200, так что она имеет куда более изощрённую логику. К тому же, дублирование кода приводит к тому, что ошибки, возникающие в обеих версиях, требуют того, чтобы их исправляли дважды. Одним из таких примеров может служить баг #1022216 в Debian и сообщение об ошибке #442 на GitHub, для которых требовались практически одинаковые действия по исправлению, но одно было в B<po4a>, а другое в B<po4a-updatepo>.

note: type: textblock
en: In the long run, I would like to drop the individual scripts and only maintain one version of this code. The sure thing is that the individual scripts will not get improved anymore, so only B<po4a> will get the new features. That being said, there is no deprecation urgency. I plan to keep the individual scripts as long as possible, and at least until 2030. If your project still use B<po4a-updatepo> and B<po4a-translate> in 2030, you may have a problem.
ru: В долгосрочной перспективе я бы хотел полностью отказаться от специализированных сценариев и поддерживать только одну версию этого кода. Разумеется, в специализированные сценарии больше не будет добавляться ни какой новой функциональности, которая будет только в B<po4a>. При этом нет никакой срочности в полном отказе от оных. Я планирую сохранять специализированные сценарии как можно дольше, по крайней мере, до 2030 года. Если в 2030 году ваш проект по-прежнему будет использовать B<po4a-updatepo> и B<po4a-translate>, то у вас могут возникнуть проблемы.

note: type: textblock
en: We may also remove the deprecation of these scripts at some point, if a refactoring reduces the code duplication to zero. If you have an idea (or better: a patch), your help is welcome.
ru: Мы также можем в какой-то момент и отменить решение о признании этих скриптов устаревшими, в случае, если рефакторинг кода когда-нибудь полностью устранит дупликацию. Если у вас есть идея на этот счёт (а лучше патч), ваша помощь приветствуется.

note: type: =head2
en: What about the other translation tools for documentation using gettext?
ru: Как насчёт других инструментов перевода документации, использующих gettext?

note: type: textblock
en: There are a few of them. Here is a possibly incomplete list, and more tools are coming at the horizon.
ru: Таковых есть несколько. Вот их (возможно неполный) список, а также на горизонте маячат несколько новых инструментов.

note: type: textblock
en: This is the tool developed by KDE people to handle DocBook XML. AFAIK, it was the first program to extract strings to translate from documentation to PO files, and inject them back after translation.
ru: Это инструмент, разработанный командой KDE для работы с DocBook XML. На сколько я знаю, это была первая программа, которая извлекала переводимые строки из документации в PO-файлы и подставляла их обратно после перевода.

note: type: textblock
en: It can only handle XML, and only a particular DTD. I'm quite unhappy with the handling of lists, which end in one big msgid. When the list become big, the chunk becomes harder to swallow.
ru: Она может обрабатывать только XML и только с определённым DTD. Мне не очень нравится, как она обрабатывает списки, которые представляются одним большим msgid. Когда список становится большим, весь этот кусок становится сложно переработать.

note: type: textblock
en: This program done by Denis Barbier is a sort of precursor of the po4a SGML module, which more or less deprecates it. As the name says, it handles only the DebianDoc DTD, which is more or less a deprecated DTD.
ru: Эта программа, созданная Денисом Барбье, является своего рода предшественником модуля SGML в po4a, который более или менее делает её устаревшей. Как становится ясно из названия, она обрабатывает только DTD DebianDoc, который также относительно устарел.

note: type: textblock
en: Used by the GIMP Documentation Team since 2004, works quite well even if, as the name suggests, only with XML files and needs specially configured makefiles.
ru: Используется командой документации GIMP с 2004 года; работает достаточно хорошо, даже с учётом того, что, как следует из названия, она работает только с XML-файлами, а также она требует специализированных make-файлов.

note: type: textblock
en: 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.
ru: Генератор документации Sphinx также активно использует gettext для управления переводами. К сожалению, он работает только с ограниченным набором текстовых форматов: rest и markdown, хотя это, пожалуй, единственный инструмент, который полностью управляет всем процессом перевода.

note: type: textblock
en: The main advantages of po4a over them are the ease of extra content addition (which is even worse there) and the ability to achieve gettextization.
ru: Основные преимущества po4a перед оными — это простота добавления дополнительного содержипого (по крайней мере там это реализовано ещё хуже) и возможность проведения геттекстизации.

note: type: =head2
en: SUMMARY of the advantages of the gettext based approach
ru: РЕЗЮМЕ преимуществ подхода, основанного на gettext

note: type: =item
en: The translations are not stored along with the original, which makes it possible to detect if translations become out of date.
ru: Переводы хранятся отдельно от оригиналов, что позволяет определить, устарели ли первые.

note: type: =item
en: The translations are stored in separate files from each other, which prevents translators of different languages from interfering, both when submitting their patch and at the file encoding level.
ru: Переводы на разные языки хранятся в отдельных файлах, что не даёт разноязычным переводчикам мешать друг другу, как при отправке ими патчей, так и на уровне кодировок файлов.

note: type: =item
en: It is based internally on B<gettext> (but B<po4a> offers a very simple interface so that you don't need to understand the internals to use it).  That way, we don't have to re-implement the wheel, and because of their wide use, we can think that these tools are more or less bug free.
ru: Внутренне устройство основано на B<gettext> (но B<po4a> предлагает простой интерфейс, так что вам не нужно понимать его внутреннее устройство, чтобы просто пользоваться им). Таким образом, нам не приходится заново изобретать колесо, а, так как B<gettext> широко используется, мы можем считать, что в нём остаётся относительно мало программных ошибок.

note: type: =item
en: Nothing changed for the end-user (beside the fact translations will hopefully be better maintained). The resulting documentation file distributed is exactly the same.
ru: Для конечного пользователя ничего не меняется (помимо того факта, что, надо надеяться, перевод будет лучше поддерживаться). Полученный файл документации распространяется точно так же.

note: type: =item
en: No need for translators to learn a new file syntax and their favorite PO file editor (like Emacs' PO mode, Lokalize or Gtranslator) will work just fine.
ru: Переводчикам не нужно изучать новый синтаксис файлов, и их любимого редактора PO-файлов (например, PO-режим Emacs, Lokalize или Gtranslator) будет вполне достаточно.

note: type: =item
en: gettext offers a simple way to get statistics about what is done, what should be reviewed and updated, and what is still to do. Some example can be found at those addresses:
ru: gettext предлагает простой способ получить статистику о том, что готово, что должно быть проверено и обновлено, а что ещё предстоит сделать. Некоторые примеры можно найти по следующим ссылкам:

note: type: textblock
en: But everything isn't green, and this approach also has some disadvantages we have to deal with.
ru: Но не всё так радужно, и этот подход также имеет некоторые недостатки, с которыми нам приходится смириться.

note: type: =item
en: Addenda are somewhat strange at the first glance.
ru: Аддендумы несколько странные на первый взгляд.

note: type: =item
en: You can't adapt the translated text to your preferences, like splitting a paragraph here, and joining two other ones there. But in some sense, if there is an issue with the original, it should be reported as a bug anyway.
ru: Вы не можете приспособить переведённый текст к своим предпочтениям, например, разделить какой-то абзац здесь-то или объединили два в один там-то. Но в некотором смысле, если есть проблема в оригинале, об этом должно быть сообщено, как об ошибке.

note: type: =item
en: Even with an easy interface, it remains a new tool people have to learn.
ru: Даже при том, что интерфейс является простым, po4a остаётся новым инструментом, который людям придётся изучать.

note: type: textblock
en: One of my dreams would be to integrate somehow po4a to Gtranslator or Lokalize. When a documentation file is opened, the strings are automatically extracted, and a translated file + po file can be written to disk. If we manage to do an MS Word (TM) module (or at least RTF) professional translators may even use it.
ru: Одна моя мечта состоит в том, чтобы каким-то образом интегрировать po4a в Gtranslator или Lokalize. Тогда при открытии файла документации, строки автоматически извлекались бы, а когда он сохранялся, переведённый файл и PO-файл мог ли бы записываться на диск. Если бы нам удалось сделать модуль MS Word (TM) (или, по крайней мере, RTF), то даже профессиональные переводчики могли бы использовать po4a.

note: type: =item
en: The documentation of the all-in-one tool that you should use: L<po4a(1)>.
ru: Документацию L<po4a(1)>, основной утилиты, которую вы должны использовать.

note: type: =item
en: The documentation of the individual po4a scripts: L<po4a-gettextize(1)>, L<po4a-updatepo(1)>, L<po4a-translate(1)>, L<po4a-normalize(1)>.
ru: Документация отдельных сценариев po4a: L<po4a-gettextize(1)>, L<po4a-updatepo(1)>, L<po4a-translate(1)>, L<po4a-normalize(1)>.

note: type: =item
en: The additional helping scripts: L<msguntypot(1)>, L<po4a-display-man(1)>, L<po4a-display-pod(1)>.
ru: Дополнительные вспомогательные сценарии: L<msguntypot(1)>, L<po4a-display-man(1)>, L<po4a-display-pod(1)>.

note: type: =item
en: The parsers of each formats, in particular to see the options accepted by each of them: L<Locale::Po4a::AsciiDoc(3pm)> L<Locale::Po4a::Dia(3pm)>, L<Locale::Po4a::Gemtext(3pm)>, L<Locale::Po4a::Guide(3pm)>, L<Locale::Po4a::Ini(3pm)>, L<Locale::Po4a::KernelHelp(3pm)>, L<Locale::Po4a::Man(3pm)>, L<Locale::Po4a::RubyDoc(3pm)>, L<Locale::Po4a::Texinfo(3pm)>, L<Locale::Po4a::Text(3pm)>, L<Locale::Po4a::Xhtml(3pm)>, L<Locale::Po4a::Yaml(3pm)>, L<Locale::Po4a::BibTeX(3pm)>, L<Locale::Po4a::Docbook(3pm)>, L<Locale::Po4a::Halibut(3pm)>, L<Locale::Po4a::LaTeX(3pm)>, L<Locale::Po4a::Org(3pm)>, L<Locale::Po4a::Pod(3pm)>, L<Locale::Po4a::SimplePod(3pm)>, L<Locale::Po4a::Sgml(3pm)>, L<Locale::Po4a::TeX(3pm)>, L<Locale::Po4a::VimHelp>, L<Locale::Po4a::Wml(3pm)>, L<Locale::Po4a::Xml(3pm)>.
ru: Парсеры для каждого отдельного формата, в особенности обратите внимание на параметры, принимаемые каждым из них: L<Locale::Po4a::AsciiDoc(3pm)> L<Locale::Po4a::Dia(3pm)>, L<Locale::Po4a::Gemtext(3pm)>, L<Locale::Po4a::Guide(3pm)>, L<Locale::Po4a::Ini(3pm)>, L<Locale::Po4a::KernelHelp(3pm)>, L<Locale::Po4a::Man(3pm)>, L<Locale::Po4a::RubyDoc(3pm)>, L<Locale::Po4a::Texinfo(3pm)>, L<Locale::Po4a::Text(3pm)>, L<Locale::Po4a::Xhtml(3pm)>, L<Locale::Po4a::Yaml(3pm)>, L<Locale::Po4a::BibTeX(3pm)>, L<Locale::Po4a::Docbook(3pm)>, L<Locale::Po4a::Halibut(3pm)>, L<Locale::Po4a::LaTeX(3pm)>, L<Locale::Po4a::Org(3pm)>, L<Locale::Po4a::Pod(3pm)>, L<Locale::Po4a::Sgml(3pm)>, L<Locale::Po4a::TeX(3pm)>, L<Locale::Po4a::VimHelp>, L<Locale::Po4a::Wml(3pm)>, L<Locale::Po4a::Xml(3pm)>.L<Locale::Po4a::Dia(3pm)>, L<Locale::Po4a::Gemtext(3pm)>, L<Locale::Po4a::Guide(3pm)>, L<Locale::Po4a::Ini(3pm)>, L<Locale::Po4a::KernelHelp(3pm)>, L<Locale::Po4a::Man(3pm)>, L<Locale::Po4a::RubyDoc(3pm)>, L<Locale::Po4a::Texinfo(3pm)>, L<Locale::Po4a::Text(3pm)>, L<Locale::Po4a::Xhtml(3pm)>, L<Locale::Po4a::Yaml(3pm)>, L<Locale::Po4a::BibTeX(3pm)>, L<Locale::Po4a::Docbook(3pm)>, L<Locale::Po4a::Halibut(3pm)>, L<Locale::Po4a::LaTeX(3pm)>, L<Locale::Po4a::Org(3pm)>, L<Locale::Po4a::Pod(3pm)>, L<Locale::Po4a::SimplePod(3pm)>, L<Locale::Po4a::Sgml(3pm)>, L<Locale::Po4a::TeX(3pm)>, L<Locale::Po4a::VimHelp>, L<Locale::Po4a::Wml(3pm)>, L<Locale::Po4a::Xml(3pm)>.

note: type: =item
en: The implementation of the core infrastructure: L<Locale::Po4a::TransTractor(3pm)> (particularly important to understand the code organization), L<Locale::Po4a::Chooser(3pm)>, L<Locale::Po4a::Po(3pm)>, L<Locale::Po4a::Common(3pm)>. Please also check the F<CONTRIBUTING.md> file in the source tree.
ru: Реализации базовых классов: L<Locale::Po4a::TransTractor(3pm)> (особенно важно для понимания организации кода), L<Locale::Po4a::Chooser(3pm)>, L<Locale::Po4a::Po(3pm)>, L<Locale::Po4a::Common(3pm)>. Также проверьте файл F<CONTRIBUTING.md> в дереве исходного кода.

note: type: verbatim
en:  Denis Barbier <barbier,linuxfr.org>
     Martin Quinson (mquinson#debian.org)
ru:  Денис Барбье (Denis Barbier) <barbier,linuxfr.org>
     Мартин Кенсон (Martin Quinson) (mquinson#debian.org)

note: type: textblock
en: Locale::Po4a::AsciiDoc - convert AsciiDoc documents from/to PO files
ru: Locale::Po4a::AsciiDoc: преобразование документов AsciiDoc в/из PO-файлы

note: type: textblock
en: Locale::Po4a::AsciiDoc is a module to help the translation of documentation in the AsciiDoc format.
ru: Locale::Po4a::AsciiDoc — это модуль, предназначенным для помощи в переводе документации в формате AsciiDoc.

note: type: =head1
en: OPTIONS ACCEPTED BY THIS MODULE
ru: ПАРАМЕТРЫ ПРИНИМАЕМЫЕ ЭТИМ МОДУЛЕМ

note: type: textblock
en: These are this module's particular options:
ru: Ниже приведены специфические для данного модуля параметры:

note: type: textblock
en: The name of a file containing definitions for po4a, as defined in the B<INLINE CUSTOMIZATION> section.  You can use this option if it is not possible to put the definitions in the document being translated.
ru: Имя файла с po4a-определениями (definitions), которые описаны в разделе B<ВСТРОЕННЫЕ НАСТРОЙКИ ПОВЕДЕНИЯ>. Вы можете использовать этот параметр, если добавить эти определения непосредственно в переводимый документ не является возможным.

note: type: textblock
en: In a definitions file, lines must not start by two slashes, but directly by B<po4a:>.
ru: В файле с определениями строки должны начинаться не, как комментарии, с двух слешей, а сразу с B<po4a:>.

note: type: textblock
en: Space-separated list of attribute entries you want to translate.  By default, no attribute entries are translatable.
ru: Список атрибутов, разделённых пробелами, значения которых должны переводиться. По умолчанию ни какие атрибуты не считаются переводимыми.

note: type: textblock
en: Space-separated list of macro definitions.
ru: Список определений макросов (macro definitions), разделённых пробелами.

note: type: textblock
en: Space-separated list of style definitions.
ru: Список определений стилей (style definitions), разделённых пробелами.

note: type: textblock
en: Enable automatic line wrapping in non-verbatim blocks, even if the result could be misinterpreted by AsciiDoc formatters.
ru: Включить автоматический перенос строк (кроме дословных (verbatim) блоков), даже если результат может быть в дальнейшем некорректно интерпретирован другими инструментами AsciiDoc.

note: type: textblock
en: By default, po4a will not wrap the produced AsciiDoc files because a manual inspection is mandated to ensure that the wrapping does not change the formatting. Consider for instance the following list item:
ru: По умолчанию po4a не будет переносить строки в создаваемых файлах AsciiDoc, поскольку для того, чтобы полученных текст был корректен, требуется ручная проверка, дабы убедиться, что перенос строк не испортит форматирование. Например, рассмотрим следующий элемент списка:

note: type: verbatim
en:  * a long sentence that is ending with a number 1. A second sentence.
ru:  * длинное предложение, оканчивающееся цифрой 1. Второе предложение.

note: type: textblock
en: If the wrapping leads to the following presentation, the item is split into a numbered sub-list. To make things worse, only the speakers of the language used in the translation can inspect the situation.
ru: Если перенос строк приведёт к следующей разбивке, то из элемента списка будет выделен в новый нумерованный подсписок. Что ещё хуже, эту проблему могут смогут заметить только носители языка, на котором осуществляется перевод.

note: type: verbatim
en:  * a long sentence that is ending with a number
       1. A second sentence.
ru:  * длинное предложение, оканчивающееся цифрой
       1. Второе предложение.

note: type: textblock
en: Note that not wrapping the files produced by po4a should not be a problem since those files are meant to be processed automatically.  They should not be regarded as source files anyway.
ru: Обратите внимание, что если po4a не будет добавлять дополнительные переносы строк, то это не должно создать ни каких проблем, поскольку эти файлы предназначены, в первую очередь, для обработки автоматическими инструментами. В любом случае, к ним не стоит относится, как к полноценным исходным файлам.

note: type: textblock
en: With this option, po4a will produce better-looking AsciiDoc files, but it may lead to possibly erroneous formatted outputs.
ru: При указании этой опции po4a будет создавать более красивые файлы в формате AsciiDoc, однако это может привести к ошибочному форматированию в документах, созданных на их основе этих файлов.

note: type: textblock
en: By default, the targets of block images are translatable to give opportunity to make the content point to translated images. This can be stopped by setting this option.
ru: По умолчанию, дабы дать переводчикам возможность вставлять в документ локализованные версии изображений, ссылки на них являются переводимыми строками. Это можно изменить, указав данный параметр.

note: type: textblock
en: This option is a flag that enables sub-table segmentation into cell content.  The segmentation is limited to cell content, without any parsing inside of it.
ru: Этот параметр является флагом, при указании которого таблицы будут разбиты на ячейки. Разбиение ограничивается только ячейками без какого-либо разбора их содержимого.

note: type: textblock
en: Switch parsing rules to compatibility with different tools. Available options are "asciidoc" or "asciidoctor". Asciidoctor has stricter parsing rules, such as equality of length of opening and closing block fences.
ru: Этот параметр переключает правила парсинга в режим совместимости со сторонними инструментами. Доступные варианты: "asciidoc" и "asciidoctor". Asciidoctor предъявляет более строгие требования к документам, например, он требует чтобы линии, стоящие в начале и конце блока, состояли из одинакового количества символов.

note: type: textblock
en: Disable linting messages. When the source code cannot be fixed for clearer document structure, these messages are useless.
ru: Отключить сообщения с предложениями по улучшению. Иногда эти советы могут быть контрпродуктивны, т.к. буквальное следование оным может привести к ухудшению читаемости.

note: type: textblock
en: Remove extra spaces from the source segments in no-wrap mode. This is useful when the translation tools are sensitive to the number of spaces.
ru: Удалить лишние пробелы из исходных фрагментов в режиме без переноса. Это полезно, когда инструменты перевода чувствительны к количеству пробелов.

note: type: textblock
en: Comma-separated list of keys to process for translation in the YAML Front Matter section. All other keys are skipped. Keys are matched with a case-sensitive match. If B<yfm_paths> and B<yfm_keys> are used together, values are included if they are matched by at least one of the options. Array values are always translated, unless the B<yfm_skip_array> option is provided.
ru: Список (разделённый запятыми) ключей из YAML-загаловка (Front Matter), которые нужно переводить. Все остальные ключи переводиться не будут. Ключи чувствительны к регистру. Если одновременно заданы и B<yfm_keys>, и B<yfm_paths>, то значения ключей будут переводиться, если они перечислены хотя бы в одном из этих параметров. Значения массивов всегда переводятся (если не задан параметр B<yfm_skip_array>).

note: type: textblock
en: Do not translate array values in the YAML Front Matter section.
ru: Не переводить значения массивов, присутствующих в YAML-загаловке (Front Matter).

note: type: textblock
en: Comma-separated list of hash paths to process for extraction in the YAML Front Matter section, all other paths are skipped. Paths are matched with a case-sensitive match. If B<yfm_paths> and B<yfm_keys> are used together, values are included if they are matched by at least one of the options.  Arrays values are always returned unless the B<yfm_skip_array> option is provided.
ru: Список (разделённый запятыми) «путей» из ключей хешей в YAML-заголовке (Front Matter), которые нужно переводить. Все остальные пути переводиться не будут. Пути чувствительны к регистру. Если одновременно заданы и B<yfm_keys>, и B<yfm_paths>, то значения ключей будут переводиться, если они перечислены хотя бы в одном из этих параметров. Значения массивов всегда переводятся (если не задан параметр B<yfm_skip_array>).

note: type: =head1
en: INLINE CUSTOMIZATION
ru: ВСТРОЕННЫЕ НАСТРОЙКИ ПОВЕДЕНИЯ

note: type: textblock
en: The AsciiDoc module can be customized with lines starting by B<//po4a:>.  These lines are interpreted as commands to the parser.  The following commands are recognized:
ru: Поведение модуля AsciiDoc может быть изменено добавлением команд данному парсеру, находящихся непосредственно в самом документе. Такими командами являются строки, начинающиеся с B<//po4a:>. Поддерживаются следующие команды:

note: type: =item
en: B<//po4a: macro >I<name>B<[>I<attribute list>B<]>
ru: B<//po4a: macro >I<имя>B<[>I<список атрибутов>B<]>

note: type: textblock
en: This describes in detail the parameters of a B<macro>; I<name> must be a valid macro name, and it ends with an underscore if the target must be translated.
ru: Этот параметр описывает, как именно нужно обрабатывать B<макрос> и его параметры. I<Имя> должно быть действительным именем макроса. Если цель (target) макроса должна быть переведена, то к имени оного должно быть добавлено подчёркивание.

note: type: textblock
en: The I<attribute list> argument is a comma separated list which contains information about translatable arguments.  This list contains either numbers, to define positional parameters, or named attributes.
ru: I<список атрибутов> — это список аргументов макроса, разделённых пробелами, которые также должны быть переведены. Этот список состоит либо из чисел, которые задают номера позиционных параметров, либо из непосредственно самих имён оных атрибутов.

note: type: textblock
en: If a plus sign (B<+>) is prepended to I<name>, then the macro and its arguments are translated as a whole.  There is no need to define attribute list in this case, but brackets must be present.
ru: Если в начало I<имени> добавлен знак плюс (B<+>), то макрос и все его аргументы переводятся как единое целое. В этом случае нет необходимости задавать список аргументов, но скобки всё равно должны присутствовать.

note: type: =item
en: B<//po4a: style >B<[>I<attribute list>B<]>
ru: B<//po4a: style >B<[>I<список атрибутов>B<]>

note: type: textblock
en: This describes in detail which attributes of a style must be translated.
ru: Этот параметр описывает, какие именно атрибуты стиля должны переводиться.

note: type: textblock
en: The I<attribute list> argument is a comma separated list which contains information about translatable arguments.  This list contains either numbers, to define positional parameters, or named attributes.  The first attribute is the style name, it will not be translated.
ru: I<список атрибутов> — это список аргументов, разделённых запятыми, которые должны быть переведены. Этот список содержит либо числа, которые задают номера позиционных параметров, либо непосредственно сами имена оных. При этом первым аргументом считается имя стиля, которое в любом случае не будет переведено.

note: type: textblock
en: If a plus sign (B<+>) is prepended to the style name, then the attribute list is translated as a whole.  There is no need to define translatable attributes.
ru: Если в начало имени стиля добавлен знак плюс (B<+>), то весь список атрибутов переводится как единое целое. В этом случае нет необходимости задавать список атрибутов.

note: type: textblock
en: If a minus sign (B<->) is prepended to the style name, then this attribute is not translated.
ru: Если в начало имени стиля добавлен знак минус (B<->), то его атрибуты не будут переводиться.

note: type: textblock
en: If a percent signe (B<%>) is appended to the style name, then the style is processed as verbatim. The lines in paragraph or block of such style are preserved in the po files and the corresponding entries are marked as no-wrap.
ru: Если к названию стиля добавлен знак процента (B<%>), то стиль обрабатывается как дословный (verbatim). Расстановка переводов строк в абзаце или блоке с таким стилем сохраняются при их добавлении в PO-файл, а соответствующие записи помечаются как «no-wrap» (без переноса).

note: type: =item
en: B<//po4a: entry >I<name>
ru: B<//po4a: entry >I<имя>

note: type: textblock
en: This declares an attribute entry as being translatable.  By default, they are not translated.
ru: Этот параметр делает значение атрибута переводимым. По умолчанию значения атрибутов остаются без перевода.

note: type: =head1
en: STATUS OF THIS MODULE
ru: СОСТОЯНИЕ ЭТОГО МОДУЛЯ

note: type: textblock
en: Tested successfully on simple AsciiDoc files.
ru: Успешно протестирован на простых файлах AsciiDoc.

note: type: verbatim
en:  Nicolas François <nicolas.francois@centraliens.net>
     Denis Barbier <barbier@linuxfr.org>
ru:  Николя Франсуа (Nicolas François) <nicolas.francois@centraliens.net>
     Денис Барбье (Denis Barbier) <barbier@linuxfr.org>

note: type: verbatim
en:  Copyright © 2005-2008 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.
     Copyright © 2012 Denis BARBIER <barbier@linuxfr.org>.
     Copyright © 2017 Martin Quinson <mquinson#debian.org>.
ru:  Copyright © 2005-2008 Николя Франсуа (Nicolas FRANÇOIS) <nicolas.francois@centraliens.net>.
     Copyright © 2012 Денис Барбье (Denis BARBIER) <barbier@linuxfr.org>.
     Copyright © 2017 Мартин Кенсон (Martin Quinson) <mquinson#debian.org>.

note: type: textblock
en: Locale::Po4a::BibTeX - convert BibTeX documents from/to PO files
ru: Locale::Po4a::BibTeX: преобразование документов BibTeX из/в PO-файлы

note: type: textblock
en: Locale::Po4a::BibTeX is a module to help the translation of bibliographies in the BibTeX format into other [human] languages.
ru: Locale::Po4a::BibTeX — это модуль, предназначенным для помощи в переводе библиографий в формате BibTeX на другие [человеческие] языки.

note: type: textblock
en: Fields values are extracted and proposed for translation.
ru: Для перевода извлекаются значения полей записей.

note: type: textblock
en: NONE.
ru: НИКАКИХ.

note: type: textblock
en: It is a very simple module, but still young.
ru: Это очень простой модуль, однако он всё ещё сырой.

note: type: verbatim
en:  Nicolas François <nicolas.francois@centraliens.net>
ru:  Николя Франсуа (Nicolas François) <nicolas.francois@centraliens.net>

note: type: verbatim
en:  Copyright © 2006 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.
ru:  Copyright © 2006 Николя Франсуа (Nicolas FRANÇOIS) <nicolas.francois@centraliens.net>.

note: type: textblock
en: Locale::Po4a::Chooser - manage po4a modules
ru: Locale::Po4a::Chooser: управление модулями форматов po4a

note: type: textblock
en: Locale::Po4a::Chooser is a module to manage po4a modules. Previously, all po4a binaries used to know all po4a modules (pod, man, sgml, etc). This made the addition of a new module boring, because you had to make sure that the documentation is synchronized in all modules, and that each of them can access the new module.
ru: Locale::Po4a::Chooser — это модуль, для управления другими модулями po4a. Раньше все программы po4a работали напрямую со всеми модулями po4a (pod, man, sgml, и т.д.). Это делало добавление новых модулей занудным делом, ибо в те времена вам надо было постоянно проверять, что документация во всех модулях синхронизирована и что каждый из них имеет доступ к новому модулю.

note: type: textblock
en: Now, you just have to call the Locale::Po4a::Chooser::new() function, passing the name of module as argument.
ru: Теперь вы можете просто вызвать функцию Locale::Po4a::Chooser::new(), передавая имя модуля в качестве аргумента.

note: type: textblock
en: The function Locale::Po4a::Chooser::list() lists the available formats, and exits with the value passed as argument. So, we call Locale::Po4a::Chooser::list(0) when requested for the list of formats, and Locale::Po4a::Chooser::list(1) when passed an invalid format name.
ru: Функция Locale::Po4a::Chooser::list() выводит список всех доступных модулей форматов и завершает работу (через exit()) с кодом, переданном ей в качестве аргумента. Так что, чтобы вывести список всех доступных модулей, мы вызываем Locale::Po4a::Chooser::list(0), а чтобы завершить работу, когда запрошен не верный формат — Locale::Po4a::Chooser::list(1).

note: type: =item
en: About po4a:
ru: О po4a:

note: type: =item
en: About modules:
ru: О модуля:

note: type: verbatim
en:  Denis Barbier <barbier@linuxfr.org>
     Martin Quinson (mquinson#debian.org)
ru:  Денис Барбье (Denis Barbier) <barbier@linuxfr.org>
     Мартин Кенсон (Martin Quinson) (mquinson#debian.org)

note: type: textblock
en: Locale::Po4a::Common - common parts of the po4a scripts and utils
ru: Locale::Po4a::Common: общий код сценариев и утилит po4a

note: type: textblock
en: Locale::Po4a::Common contains common parts of the po4a scripts and some useful functions used along the other modules.
ru: Locale::Po4a::Common содержит общий код сценариев po4a, а также некоторые полезные функции используемые в других модулях.

note: type: textblock
en: If needed, you can disable the use of Text::WrapI18N as such:
ru: В случае необходимости можно отключить Text::WrapI18N следующим образом:

note: type: textblock
en: instead of:
ru: вместо:

note: type: textblock
en: The ordering is important here: as most Locale::Po4a modules load themselves Locale::Po4a::Common, the first time this module is loaded determines whether Text::WrapI18N is used.
ru: В данном случае порядок имеет значение: большинство модулей в Locale::Po4a сами загружают Locale::Po4a::Common, а используется ли Text::WrapI18N определяется при первой загрузке модуля.

note: type: =head1
en: FUNCTIONS
ru: ФУНКЦИИ

note: type: =head2
en: Showing output messages
ru: Форматирование сообщений

note: type: textblock
en: Shows the current version of the script, and a short copyright message. It takes the name of the script as an argument.
ru: Выводит текущую версию сценария и короткое сообщение об авторском праве. В качестве аргумента она принимает имя сценария.

note: type: textblock
en: This function displays a message the same way as sprintf() does, but wraps the result so that they look nice on the terminal.
ru: Данная функция возвращает отформатированную строку точно также, как sprintf(), но также расставляет переносы строк, чтобы сообщение хорошо смотрелось в терминале.

note: type: textblock
en: This function works like wrap_msg(), but it takes a module name as the first argument, and leaves a space at the left of the message.
ru: Данная функция делает тоже, что и wrap_msg(), но она также принимает имя модуля в качестве первого аргумента и добавляет пробелы в начало перенесённых строк.

note: type: textblock
en: This function works like wrap_msg(), but it takes a file:line reference as the first argument, a module name as the second one, and leaves a space at the left of the message.
ru: Данная функция делает тоже, что и wrap_msg(), но в качестве первого аргумента она принимает сноску вида «файл:строка» и имя модуля в качестве второго. Она также добавляет пробелы в начало перенесённых строк.

note: type: =head2
en: Wrappers for other modules
ru: Обёртки для других модулей

note: type: textblock
en: When the Locale::Gettext module cannot be loaded, this module provide dummy (empty) implementation of the following functions. In that case, po4a messages won't get translated but the program will continue to work.
ru: Если не удаётся загрузить модуль Locale::Gettext, то данный модуль предоставляет заглушки для следующих функций. В таком случае сообщения po4a не будут переводится, но сама программа будет работать.

note: type: textblock
en: If Locale::gettext is present, this wrapper also calls setlocale(LC_MESSAGES, "") so callers don't depend on the POSIX module either.
ru: Если Locale::gettext существует, то эта обёртка также вызывает setlocale(LC_MESSAGES, ""), чтобы вызывающим не приходилось зависеть от модуля POSIX.

note: type: verbatim
en:  Jordi Vilalta <jvprat@gmail.com>
ru:  Жорди Вилальта (Jordi Vilalta) <jvprat@gmail.com>

note: type: textblock
en: Locale::Po4a::Dia - convert uncompressed Dia diagrams from/to PO files
ru: Locale::Po4a::Dia: преобразование несжатых диаграмм Dia из/в PO-файлы

note: type: textblock
en: Locale::Po4a::Dia is a module to help the translation of diagrams in the uncompressed Dia format into other [human] languages.
ru: Locale::Po4a::Dia — это модуль, предназначенным для помощи в переводе диаграмм в несжатом формате Dia в на другие [человеческие] языки.

note: type: verbatim
en: You can get Dia (the graphical editor for these diagrams) from:
      http://www.gnome.org/projects/dia/
ru: Вы можете скачать Dia (графический редактор диаграмм) с:
      http://www.gnome.org/projects/dia/

note: type: =head1
en: TRANSLATING WITH PO4A::DIA
ru: ПЕРЕВОД С ПОМОЩЬЮ PO4A::DIA

note: type: textblock
en: This module only translates uncompressed Dia diagrams.  You can save your uncompressed diagrams with Dia itself, unchecking the "Compress diagram files" at the "Save Diagram" dialog.
ru: Этот модуль переводит только несжатые диаграммы Dia. Вы можете сохранить свою диаграмму в несжатом формате с помощью самого Dia, сняв флажок «Сжимать сохраняемые файлы» в диалоге «Сохранить как…».

note: type: verbatim
en: Another way is to uncompress the dia files from command line with:
      gunzip < original.dia > uncompressed.dia
ru: Другой способ распаковать файл dia — через командную строку:
      gunzip < original.dia > uncompressed.dia

note: type: textblock
en: This module is fully functional, as it relies in the L<Locale::Po4a::Xml> module. This only defines the translatable tags (E<lt>dia:stringE<gt>), and filters the internal strings (the content of the E<lt>dia:diagramdataE<gt> tag), not interesting for translation.
ru: Этот модуль полностью функционален так как он полагается на модуль L<Locale::Po4a::Xml>. Этот модуль только объявляет переводимые теги (E<lt>dia:stringE<gt>) и фильтрует внутренние строки (содержимое тегов E<lt>dia:diagramdataE<gt>), не представляющие интереса для переводчиков.

note: type: textblock
en: Copyright © 2004 Jordi Vilalta <jvprat@gmail.com>
ru: Copyright © 2004 Жорди Вилальта (Jordi Vilalta) <jvprat@gmail.com>

note: type: textblock
en: Locale::Po4a::Docbook - convert DocBook XML documents from/to PO files
ru: Locale::Po4a::Docbook: преобразование документов DocBook XML из/в PO-файлы

note: type: textblock
en: Locale::Po4a::Docbook is a module to help the translation of DocBook XML documents into other [human] languages.
ru: Locale::Po4a::Docbook — это модуль, предназначенным для помощи в переводе документов DocBook XML на другие [человеческие] языки.

note: type: textblock
en: This module is fully functional, as it relies in the L<Locale::Po4a::Xml> module. This only defines the translatable tags and attributes.
ru: Этот модуль полностью функционален так как он полагается на модуль L<Locale::Po4a::Xml>. Этот модуль только объявляет переводимые теги и атрибуты.

note: type: textblock
en: The only known issue is that it doesn't handle entities yet, and this includes the file inclusion entities, but you can translate most of those files alone (except the typical entities files), and it's usually better to maintain them separated.
ru: Единственная проблема в том, что он пока не поддерживает объектов-подстановок (entities), в том числе объектов-подстановок включения файлов, но вы можете переводить большинство этих файлов отдельно. И зачастую это упростит сопровождение оных.

note: type: =head2
en: OVERRIDE THE DEFAULT BEHAVIOR WITH COMMAND LINE OPTIONS
ru: ПЕРЕОПРЕДЕЛЕНИЕ ПОВЕДЕНИЯ ПО УМОЛЧАНИЮ ПАРАМЕТРАМИ КОМАНДНОЙ СТРОКИ

note: type: textblock
en: The default behavior of system provided modules is set to be on the safe side.
ru: Поведение системного модуля по умолчанию настроено из соображений, что на всякий случай необходимо подстраховаться.

note: type: textblock
en: For example, the default of B<< <author> >> tag is aiming it to appear under B<< <para> >>.  But you may be using it only under B<< <bookinfo> >>.  For this case, you may want to translate it independently for each author.
ru: Например, по умолчанию тег B<< <author> >> ожидает, что он будет находиться в секции B<< <para> >>. Но вы можете использовать его непосредственно под B<< <bookinfo> >>. В этом случае вы, возможно, захотите переводить его её независимо для каждого автора.

note: type: textblock
en: If you don't like the default behavior of the xml module and its derivative modules, you can provide command line options to change their behavior.  For example, you can add the following to the po4a configuration file:
ru: Если поведение по умолчанию модуля xml и унаследованных от него модулей вас не устраивает, вы можете передать некоторые параметры командной строки, дабы изменить данное поведение. Например, вы можете добавить следующее в файл настроек po4a:

note: type: textblock
en: This overrides the default behavior for B<< <bookinfo> >> and B<< <author> >>, set B<< <bookinfo> >> and B<< <author> >> to break input data stream on these tags, set B<< <bookinfo> >> not to translate its tagged content, and set B<< <author> >> to translate its tagged content.
ru: Это переопределит поведение по умолчанию для B<< <bookinfo> >> и B<< <author> >>, сделает так что B<< <bookinfo> >> и B<< <author> >> будут разбивать входной поток данный на этих тегах, установит, что содержимое тега B<< <bookinfo> >> не должно переводиться и что содержимое B<< <author> >>, напротив, должно переводиться.

note: type: verbatim
en:  Copyright © 2004 Jordi Vilalta  <jvprat@gmail.com>
     Copyright © 2007-2009 Nicolas François <nicolas.francois@centraliens.net>
ru:  Copyright © 2004 Жорди Вилальта (Jordi Vilalta)  <jvprat@gmail.com>
     Copyright © 2007-2009 Николя Франсуа (Nicolas François) <nicolas.francois@centraliens.net>

note: type: textblock
en: Locale::Po4a::Gemtext - convert Gemtext documents from/to PO files.
ru: Locale::Po4a::Gemtext: преобразование документов Gemtext из/в PO-файлы.

note: type: textblock
en: Locale::Po4a::Gemtext is a module to help the translation of Gemtext documents into other [human] languages.
ru: Locale::Po4a::Gemtext — это модуль, предназначенным для помощи в переводе документов Gemtext на другие [человеческие] языки.

note: type: textblock
en: Tested successfully on simple Gemtext files, such as the official Gemtext documentation.
ru: Успешно протестирован на простых файлах Gemtext, таких как официальная документация Gemtext.

note: type: textblock
en: Locale::Po4a::Guide - convert Guide XML documents from/to PO files
ru: Locale::Po4a::Guide: преобразование документов Guide XML из/в PO-файлы

note: type: textblock
en: Locale::Po4a::Guide is a module to help in the translation of the Gentoo Linux documentation in the Guide XML format into other [human] languages.
ru: Locale::Po4a::Guide — это модуль, предназначенным для помощи в переводе документации Gentoo Linux в формате Guide XML на другие [человеческие] языки.

note: type: textblock
en: This format is documented here: http://www.gentoo.org/doc/en/xml-guide.xml
ru: Этот формат описан по адресу: http://www.gentoo.org/doc/en/xml-guide.xml

note: type: textblock
en: The only known issue is that it doesn't include files with the <include href="..."> tag, but you can translate all those files alone, and it's usually better to have them separated.
ru: Единственная известная проблема в том, что он не включает файлы с помощью тега <include href="...">, но вы можете переводить все эти файлы отдельно. И обычно даже лучше оставить их таковыми.

note: type: textblock
en: Locale::Po4a::Halibut - convert Halibut documents and derivates from/to PO files
ru: Locale::Po4a::Halibut: преобразование документов Halibut и производных форматов из/в PO-файлы

note: type: textblock
en: Locale::Po4a::Halibut is a module to help the translation of Halibut documents into other [human] languages.
ru: Locale::Po4a::Halibut — это модуль, предназначенным для помощи в переводе документов Halibut на другие [человеческие] языки.

note: type: textblock
en: This module contains the definitions of common Halibut commands and environments.
ru: Этот модуль содержит определения общих команд и элементов среды Halibut.

note: type: textblock
en: This module is still beta.  Please send feedback and feature requests.
ru: Этот модуль всё ещё находится в бета-стадии. Пожалуйста присылайте отзывы и запросы новых возможностей.

note: type: =head1
en: CAVEAT
ru: ПРЕДУПРЕЖДЕНИЕ

note: type: textblock
en: Some constructs are badly supported. The known ones are documented below.
ru: Некоторые конструкции поддерживаются плохо, известные перечислены ниже.

note: type: =head2
en: Verbatim blocks
ru: Дословные блоки

note: type: textblock
en: The verbatim block is not considered as a whole. Each line will be translated separately.
ru: Дословные блоки не рассматриваются, как цельные. Каждая строка будет переводиться отдельно.

note: type: textblock
en: Copyright © 2004-2008 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.
ru: Copyright © 2004-2008 Николя Франсуа (Nicolas FRANÇOIS) <nicolas.francois@centraliens.net>.

note: type: textblock
en: Locale::Po4a::Ini - convert INI files from/to PO files
ru: Locale::Po4a::Ini: преобразование Ini-файлов из/в PO-файлы

note: type: textblock
en: Locale::Po4a::Ini is a module to help the translation of INI files into other [human] languages.
ru: Locale::Po4a::Ini — это модуль, предназначенным для помощи в переводе файлов Ini на другие [человеческие] языки.

note: type: textblock
en: The module searches for lines of the following format and extracts the quoted text:
ru: Этот модуль ищет строки следующего формата и извлекает текст заключённый в кавычки:

note: type: textblock
en: identificator="text than can be translated"
ru: identificator="текст, который может быть переведён"

note: type: textblock
en: NOTE: If the text is not quoted, it will be ignored.
ru: Замечание: Если текст не заключён в кавычки, он будет проигнорирован.

note: type: verbatim
en:  Razvan Rusu <rrusu@bitdefender.com>
     Costin Stroie <cstroie@bitdefender.com>
ru:  Рэзван Русу (Razvan Rusu) <rrusu@bitdefender.com>
     Костин Стройе (Costin Stroie) <cstroie@bitdefender.com>

note: type: textblock
en: Locale::Po4a::KernelHelp - convert kernel configuration help from/to PO files
ru: Locale::Po4a::KernelHelp: преобразование справочных страниц конфигурации ядра ОС из/в PO-файлы

note: type: textblock
en: Locale::Po4a::KernelHelp is a module to help the translation of documentation for the Linux kernel configuration options into other [human] languages.
ru: Locale::Po4a::KernelHelp — это модуль, предназначенным для перевода документации параметров сборки ядра Linux на другие [человеческие] языки.

note: type: textblock
en: This module is just written, and needs more tests. Most of the needed work will concern the tools used to parse this file (and configure the kernel), so that they accept to read the documentation from another (translated)  file.
ru: Этот модуль только написан и требует больше тестов. Основная требуемая работа касается изменения утилит, которые используют эти файлы (в частности, конфигураторы ядра), чтобы они читали справку из других (переведённых) файлов.

note: type: textblock
en: Locale::Po4a::LaTeX - convert LaTeX documents and derivates from/to PO files
ru: Locale::Po4a::LaTeX: преобразование документов LaTeX и производных форматов из/в PO-файлы

note: type: textblock
en: Locale::Po4a::LaTeX is a module to help the translation of LaTeX documents into other [human] languages. It can also be used as a base to build modules for LaTeX-based documents.
ru: Locale::Po4a::LaTeX — это модуль, предназначенным для помощи в переводе документов LaTeX на другие [человеческие] языки. Он также используется другими модулями для документов основанных на LaTeX.

note: type: textblock
en: This module contains the definitions of common LaTeX commands and environments.
ru: Этот модуль содержит определения общих команд и элементов среды LaTeX.

note: type: textblock
en: See the L<Locale::Po4a::TeX(3pm)|Locale::Po4a::TeX> manpage for the list of recognized options.
ru: Смотрите список поддерживаемых параметров в man-странице L<Locale::Po4a::TeX(3pm)|Locale::Po4a::TeX>.

note: type: textblock
en: Copyright © 2004, 2005 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.
ru: Copyright © 2004, 2005 Николя Франсуа (Nicolas FRANÇOIS) <nicolas.francois@centraliens.net>.

note: type: textblock
en: Locale::Po4a::Man - convert manual pages from/to PO files
ru: Locale::Po4a::Man: преобразование man-страниц из/в PO-файлы

note: type: textblock
en: Locale::Po4a::Man is a module to help the translation of documentation in the nroff format (the language of manual pages) into other [human] languages.
ru: Locale::Po4a::Man — это модуль, предназначенным для помощи в переводе документации в формате nroff (язык разметки man-страниц) на другие [человеческие] языки.

note: type: =head1
en: TRANSLATING WITH PO4A::MAN
ru: ПЕРЕВОД С ПОМОЩЬЮ PO4A::MAN

note: type: textblock
en: This module tries pretty hard to make translator's life easier. For that, the text presented to translators isn't a verbatim copy of the text found in the man page. Indeed, the cruder parts of the nroff format are hidden, so that translators can't mess up with them.
ru: Этот модуль старается как только может, чтобы облегчить жизнь переводчика. Чтобы добиться этого, передаваемый переводчику текст не является дословной копией содержимого man-страницы. Фактически, большинство сырых элементов формата nroff скрыты от глаз переводчика так, чтобы он не смог их испортить.

note: type: =head2
en: Text wrapping
ru: Перенос текста

note: type: textblock
en: Unindented paragraphs are automatically rewrapped for the translator.  This can lead to some minor difference in the generated output, since the rewrapping rules used by groff aren't very clear. For example, two spaces after a parenthesis are sometimes preserved.
ru: Абзацы без отступов будут автоматически переформатированы для переводчика. Это может привести к некоторым незначительным отличиям в выходных файлах, т.к. правила форматирования используемые groff не совсем чёткие. Например, иногда резервируется два пробела после скобок.

note: type: textblock
en: Anyway, the difference will only be about the position of the extra spaces in wrapped paragraph, and I think it's worth.
ru: В любом случае, отличия будут только в положении дополнительных пробелов в переформатированном абзаце и, как мне кажется, это мелочь.

note: type: =head2
en: Font specification
ru: Определение шрифтов

note: type: textblock
en: The first change is about font change specifications.  In nroff, there are several ways to specify if a given word should be written in small, bold or italics. In the text to translate, there is only one way, borrowed from the POD (Perl online documentation) format:
ru: Первое изменение — это изменение способа определения шрифтов. В nroff, существует несколько способов определить, каким должен быть шрифт, маленьким, жирным или курсивом. В переводимом тексте, существует только один способ, позаимствованный из формата POD (Perl online documentation):

note: type: =item
en: IE<lt>textE<gt> -- italic text
ru: IE<lt>текстE<gt> -- курсив

note: type: textblock
en: equivalent to \fItext\fP or ".I text"
ru: эквивалентен \fIтекст\fP или ".I текст"

note: type: =item
en: BE<lt>textE<gt> -- bold text
ru: BE<lt>текстE<gt> -- жирный

note: type: textblock
en: equivalent to \fBtext\fP or ".B text"
ru: эквивалентен \fBтекст\fP или ".B текст"

note: type: =item
en: RE<lt>textE<gt> -- roman text
ru: RE<lt>текстE<gt> -- обычный (man использует термин «roman» )

note: type: textblock
en: equivalent to \fRtext\fP
ru: эквивалентен \fRтекст\fP

note: type: =item
en: CWE<lt>textE<gt> -- constant width text
ru: CWE<lt>текстE<gt> -- моноширинный

note: type: textblock
en: equivalent to \f(CWtext\fP or ".CW text"
ru: эквивалентен \f(CWтекст\fP или ".CW текст"

note: type: textblock
en: Remark: The CW face is not available for all groff devices. It is not recommended to use it. It is provided for your convenience.
ru: Замечание: Начертание CW доступно не на всех groff устройствах. Такое начертание не рекомендуется использовать. Предоставляется только для вашего удобства.

note: type: =head2
en: Automatic characters transliteration
ru: Автоматическая транслитерация символов

note: type: textblock
en: Po4a automatically transliterate some characters to ease the translation or the review of the translation.  Here is the list of the transliterations:
ru: Po4a автоматически производит транслитерацию некоторых символов для облегчения перевода или последующей проверки оного. Ниже приведён список таких транслитераций:

note: type: =item
en: hyphens
ru: дефисы

note: type: textblock
en: Hyphens (-) and minus signs (\-) in man pages are all transliterated as simple dashes (-) in the PO file.  Then all dash are transliterated into roff minus signs (\-) when the translation is inserted into the output document.
ru: Дефис (-) и знак минуса (\-) в man страницах транслитерируются в простое тире (-) в PO-файле. Затем все тире транслитерируются в знак минуса roff (\-) при формировании выходного документа.

note: type: textblock
en: Translators can force an hyphen by using the roff glyph '\[hy]' in their translations.
ru: Переводчики могут принудительно использовать roff дефис '\[hy]' в своих переводах.

note: type: =item
en: non-breaking spaces
ru: неразрывные пробелы

note: type: textblock
en: Translators can use non-breaking spaces in their translations.  These non-breaking spaces (0xA0 in latin1) will be transliterated into a roff non-breaking space ('\ ').
ru: Переводчики могут использовать неразрывные пробелы. Такие неразрывные пробелы (0xA0 в latin1) будут транслитерированы в неразрывные пробелы roff ('\ ').

note: type: =item
en: quotes transliterations
ru: транслитерация кавычек

note: type: textblock
en: `` and '' are respectively tranliterated into \*(lq and \*(rq.
ru: `` и '' будут соответственно транслитерированы в \*(lq и \*(rq.

note: type: textblock
en: To avoid these transliterations, translators can insert a zero width roff character (i.e., using `\&` or '\&' respectively).
ru: Чтобы избежать подобной транслитерации, переводчики могут вставить roff символ нулевой ширины (т.е., использовать `\&` или '\&' соответственно).

note: type: =head2
en: Putting 'E<lt>' and 'E<gt>' in translations
ru: Вставка 'E<lt>' и 'E<gt>' в перевод

note: type: textblock
en: Since these chars are used to delimit parts under font modification, you can't use them verbatim. Use EE<lt>ltE<gt> and EE<lt>gtE<gt> instead (as in POD, one more time).
ru: Поскольку эти символы используются для разделения частей при изменении шрифта, вы не можете использовать их буквально. Используйте вместо них EE<lt>ltE<gt> и EE<lt>gtE<gt> (так же как в POD).

note: type: textblock
en: Activate debugging for some internal mechanisms of this module.  Use the source to see which parts can be debugged.
ru: Включение отладки некоторых внутренних механизмов данного модуля. Какие части имеют отладочные закладки смотрите в исходном коде.

note: type: textblock
en: Increase verbosity.
ru: Увеличение количества выводимой служебной информации.

note: type: textblock
en: This option controls the behavior of the module when it encounter a .de, .ie or .if section. It can take the following values:
ru: Данный параметр изменяет поведение модуля при обработке секций .de, .ie или .if. Он может принимать следующие значения:

note: type: textblock
en: This is the default value.  The module will fail when a .de, .ie or .if section is encountered.
ru: Значение по умолчанию. Модуль будет приводить к останову при встрече с секциями .de, .ie или .if.

note: type: textblock
en: Indicates that the .de, .ie or .if sections must be copied as is from the original to the translated document.
ru: Указывает на то, чтобы секции de, .ie или .if были скопированы как есть из оригинала в переведённый документ.

note: type: textblock
en: Indicates that the .de, .ie or .if sections will be proposed for the translation.  You should only use this option if a translatable string is contained in one of these section. Otherwise, I<verbatim> should be preferred.
ru: Указывает, чтобы секции .de, .ie или .if были предложены для перевода. Данное значение необходимо использовать, если эти секции содержат кукую-либо переводимую строку. В противном случае, следует использовать I<verbatim>.

note: type: textblock
en: This option specifies that the file was generated, and that po4a should not try to detect if the man pages was generated from another format.  This option is mandatory to use po4a on generated man pages.  Note that translating generated pages instead of sources ones is often more fragile, and thus a bad idea.
ru: Данный параметр указывает, что файл был сгенерирован из другого формата, и что po4a не должен пытаться самостоятельно определить это. Этот параметр обязателен при использовании po4a для сгенерированных man-страниц. Возьмите на заметку, что перевод сгенерированных man-страниц, а не тех файлов из которых они были сгенерированы — ненадёжный процесс, и, следовательно, не самая лучшая идея.

note: type: textblock
en: This option is only useful for mdoc pages.
ru: Данный параметр может быть полезен только для mdoc страниц.

note: type: textblock
en: It selects a stricter support of the mdoc format by telling po4a not to translate the 'NAME' section.  mdoc pages whose 'NAME' section is translated won't generate any header or footer.
ru: Позволяет использовать более строгий формат mdoc, в частности, указывая po4a не переводить название секции 'NAME'. Для страниц mdoc, с переведённой секцией 'NAME', не будут создаваться собственные верхние и нижние колонтитулы.

note: type: verbatim
en: According to the groff_mdoc page, the NAME, SYNOPSIS and DESCRIPTION
    sections are mandatory.
    There are no known issues with translated SYNOPSIS or DESCRIPTION section,
    but you can also specify these sections this way:
     -o mdoc=NAME,SYNOPSIS,DESCRIPTION
ru: Согласно странице справки groff_mdoc, секции NAME, SYNOPSIS и DESCRIPTION обязательны.
    Однако, какие-либо проблемы при переводе названий секций SYNOPSIS или DESCRIPTION, на данный момент не известны,
    но вы также можете предотвратить перевод имён данных секций следующим образом:
     -o mdoc=NAME,SYNOPSIS,DESCRIPTION

note: type: verbatim
en: This mdoc issue can also be solved with an addendum like this one:
     PO4A-HEADER:mode=before;position=^.Dd
     .TH DOCUMENT_TITLE 1 "Month day, year" OS "Section Name"
ru: Эти проблемы mdoc также можно решить с помощью аддендума:
     PO4A-HEADER:mode=before;position=^.Dd
     .TH НАЗВАНИЕ_ДОКУМЕНТА 1 "Месяц, день, год" OS "Имя man-раздела"

note: type: textblock
en: The following options specify the behavior of a user-defined macro (with a .de request), or of a classical macro that is not supported by po4a.  They take as argument a comma-separated list of macros.  For example:
ru: Следующие параметры задают поведение макросов, определённых пользователем (с помощью директивы .de), или классических макросов, не поддерживаемых po4a. В качестве аргумента они принимают список макросов, разделённых запятыми. Например:

note: type: textblock
en: Note: if a macro is not supported by po4a and if you consider that it is a standard roff macro, you should submit it to the po4a development team.
ru: Замечание: если макрос не поддерживается po4a и вы считаете, что это стандартный макрос roff, сообщите, пожалуйста, об этом команде разработчиков po4a.

note: type: textblock
en: B<untranslated> indicates that this macro (at its arguments) don't have to be translated.
ru: B<untranslated> указывает, что данные макросы (указанные в аргументе) не требуют перевода.

note: type: textblock
en: B<noarg> is like B<untranslated>, except that po4a will verify that no argument is added to this macro.
ru: B<noarg> подобен B<untranslated>, с той разницей что po4a будет проверять чтобы аргументы не передавались данному макросу.

note: type: textblock
en: B<translate_joined> indicates that po4a must propose to translate the arguments of the macro.
ru: B<translate_joined> указывает, что po4a должен отметить для перевода аргументы данного макроса.

note: type: textblock
en: With B<translate_each>, the arguments will also be proposed for the translation, except that each one will be translated separately.
ru: С B<translate_each>, аргументы будут также отмечены для перевода, но каждый из них будет переводиться отдельно.

note: type: textblock
en: This option takes as argument a list of comma-separated couples I<begin>:I<end>, where I<begin> and I<end> are commands that delimit the begin and end of a section that should not be rewrapped.
ru: Данный параметр принимает в качестве аргумента разделённый запятыми список пар I<begin>:I<end>, где I<begin> и I<end> являются командами, которые определяют начало и конец секции, которая не должна быть переформатирована (rewrapped).

note: type: textblock
en: Note: no test is done to ensure that an I<end> command matches its I<begin> command; any ending command stop the no_wrap mode.  If you have a I<begin> (respectively I<end>) macro that has no I<end> (respectively I<begin>), you can specify an existing I<end> (like fi) or I<begin> (like nf) as a counterpart.  These macros (and their arguments) won't be translated.
ru: Замечание: не производится никаких проверок, что каждая команда I<end> соответствует своей команде I<begin>; любая завершающая команда отключает режим no_wrap. Если макрос, который вы хотите использовать в качестве I<begin> (или I<end>), не имеет соответствующего ему макроса I<end> (или I<begin> соответственно), то вы можете указать любой существующий макрос для I<end> (например fi) или для I<begin> (например nf). Данный макрос (и его аргументы) переводиться не будут.

note: type: textblock
en: This option specifies a list of comma-separated macros that must not split the current paragraph. The string to translate will then contain I<foo E<lt>.bar baz quxE<gt> quux>, where I<bar> is the command that should be inlined, and I<baz qux> its arguments.
ru: Данный параметр определяет разделённый запятыми список макросов, которые не должны разбивать текущий абзац. Переводимая строка будет содержать I<foo E<lt>.bar baz quxE<gt> quux>, где I<bar> — это команда, переданная B<inline>, а I<baz> и I<qux> — её аргументы.

note: type: textblock
en: This option indicates how po4a should behave when an unknown macro is found.  By default, po4a fails with a warning.  It can take the following values: B<failed> (the default value), B<untranslated>, B<noarg>, B<translate_joined>, or B<translate_each> (see above for an explanation of these values).
ru: Этот параметр определяет поведение po4a когда встречается неизвестный макрос.  По умолчанию po4a завершает работу выводя предупреждение.  Он может принимать следующие значения: B<failed> (значение по умолчанию), B<untranslated>, B<noarg>, B<translate_joined>, B<translate_each>. (См. описание этих значений выше).

note: type: =head1
en: AUTHORING MAN PAGES COMPLIANT WITH PO4A::MAN
ru: СОЗДАНИЕ MAN-СТРАНИЦ СОВМЕСТИМЫХ С PO4A::MAN

note: type: textblock
en: This module is still very limited, and will always be, because it's not a real nroff interpreter. It would be possible to do a real nroff interpreter, to allow authors to use all the existing macros, or even to define new ones in their pages, but we didn't want to. It would be too difficult, and we thought it wasn't necessary. We do think that if manpages' authors want to see their productions translated, they may have to adapt to ease the work of translators.
ru: Данный модуль очень ограничен в своих возможностях и будет таким всегда, т.к. он не является интерпретатором nroff. Конечно, было бы возможно создать полноценный интерпретатор nroff, чтобы предоставить авторам возможность использовать все существующие макросы или даже объявлять новые, но мы не хотим этим заниматься. Это было бы слишком сложной задачей и, как мы считаем, в этом нет необходимости. Мы считаем, что если авторы man-страниц хотят видеть свои творения переведёнными, то они смогут их немного адаптировать, чтобы облегчить работу переводчикам.

note: type: textblock
en: So, the man parser implemented in po4a have some known limitations we are not really inclined to correct, and which will constitute some pitfalls you'll have to avoid if you want to see translators taking care of your documentation.
ru: Таким образом у парсера, реализованного в po4a, есть несколько известных ограничений, которые мы не собираемся устранять. Эти ограничения содержат некоторые ловушки, которые вам придётся избегать, если вы хотите чтобы переводчики позаботились о вашей документации.

note: type: =head2
en: Don't program in nroff
ru: Не программируйте на nroff

note: type: textblock
en: nroff is a complete programming language, with macro definition, conditionals and so on. Since this parser isn't a fully featured nroff interpreter, it will fail on pages using these facilities (There are about 200 such pages on my box).
ru: nroff это полноценный язык программирования, с возможностью определения макросов, условными операторами и так далее. Так как этот парсер не является полнофункциональным интерпретатором nroff, он не сможет обработать страницы, использующие подобные возможности (у меня есть около 200 таких страниц).

note: type: =head2
en: Use the plain macro set
ru: Используйте простой набор макросов

note: type: textblock
en: There are still some macros which are not supported by po4a::man. This is only because I failed to find any documentation about them. Here is the list of unsupported macros used on my box. Note that this list isn't exhaustive since the program fails on the first encountered unsupported macro. If you have any information about some of these macros, I'll happily add support for them. Because of these macros, about 250 pages on my box are inaccessible to po4a::man.
ru: Есть ещё несколько макросов, которые не поддерживаются po4a::man только потому, что я не смог отыскать документацию по ним. Ниже приведён список таковых макросов используемых на моём компьютере. Обратите внимание, что этот список не является полным, т.к. программа завершает работу при первой встрече с неподдерживаемым макросом. Если у вас есть информация о каком либо из них, я с удовольствием добавлю поддержку оного. Из-за таких макросов po4a::man не может обработать корректно порядка 250 страниц на моём компьютере.

note: type: =head2
en: Hiding text from po4a
ru: Скрытие текста от po4a

note: type: textblock
en: Sometimes, the author knows that some parts are not translatable, and should not be extracted by po4a. For example, an option may accept an I<other> argument, and I<other> may also appear as the last item of a list. In the first case, I<other> should be not be translatable. And in the second case, I<other> should be translated.
ru: Иногда автор знает, что некоторые части не подлежат переводу и не должны извлекаться программой po4a. Например, параметр может принимать аргумент I<other>, и I<other> может также обозначать последний аргумент списка. В первом случае, I<other> не должно быть переведено. А во втором случае — должно.

note: type: textblock
en: In such case, the author can avoid po4a to extract some strings, using some special groff constructs:
ru: В этом случае, автор может заставить po4a воздержаться от извлечения некоторых строк, с помощью определённых groff конструкций:

note: type: textblock
en: (this will require the B<-o groff_code=verbatim> option)
ru: (это потребует параметра B<-o groff_code=verbatim>)

note: type: verbatim
en: A new macro can also be defined to automate this:
     .de IR_untranslated
     .    IR \\$@
     ..
ru: Можно также определить новый макрос, чтобы автоматизировать этот процесс:
     .de IR_untranslated
     .    IR \\$@
     ..

note: type: textblock
en: (this will require the options B<-o groff_code=verbatim> and B<-o untranslated=IR_untranslated>; with this construct, the B<.if !'po4a'hide'> conditional is not strictly needed since po4a will not parse the internal of the macro definition)
ru: (это потребует параметров B<-o groff_code=verbatim> и B<-o untranslated=IR_untranslated>; с этой конструкцией условный оператор B<.if !'po4a'hide'>, строго говоря, не обязателен т.к. po4a не будет пытаться разобрать внутреннюю часть макроопределения)

note: type: verbatim
en: or using an alias:
     .als IR_untranslated IR
ru: или использовать псевдоним:
     .als IR_untranslated IR

note: type: textblock
en: This will require the B<-o untranslated=als,IR_untranslated> option.
ru: Это потребует параметра B<-o untranslated=als,IR_untranslated>.

note: type: =head2
en: Conclusion
ru: Заключение

note: type: textblock
en: To summarise this section, keep simple, and don't try to be clever while authoring your man pages. A lot of things are possible in nroff, and not supported by this parser. For example, don't try to mess with \c to interrupt the text processing (like 40 pages on my box do). Or, be sure to put the macro arguments on the same line that the macro itself. I know that it's valid in nroff, but would complicate too much the parser to be handled.
ru: Подводя итоги выше сказанному, делайте всё просто и не пытайтесь умничать, когда готовите свои man-страницы. В nroff есть много возможностей, и многие из них не поддерживаются этим парсером. Например, не пытайтесь связываться с \c, чтобы остановить исполнение (как делают 40 страниц на моей машине). И убедитесь, что оставляете аргументы макроса на той же строке, что и он сам. Я знаю, что обратное допустимо в nroff, но это сильно осложнит работу парсера.

note: type: textblock
en: Of course, another possibility is to use another format, more translator friendly (like POD using po4a::pod, or one of the XML family like SGML), but thanks to po4a::man it isn't needed anymore. That being said, if the source format of your documentation is POD, or XML, it may be clever to translate the source format and not this generated one. In most cases, po4a::man will detect generated pages and issue a warning. It will even refuse to process POD generated pages, because those pages are perfectly handled by po4a::pod, and because their nroff counterpart defines a lot of new macros I didn't want to write support for. On my box, 1432 of the 4323 pages are generated from POD and will be ignored by po4a::man.
ru: Конечно, другая возможность — это использовать другой формат, более дружелюбный к переводчикам (например POD с po4a::pod или один из XML-семейства, например SGML), но благодаря po4a::man в этом больше нет необходимости. Как говорится, если исходный формат вашей документации POD или XML, то будет мудро переводить исходный формат, а не то что из него сгенерировано. В большинстве случаев, po4a::man определяет сгенерированные страницы и выводит предупреждение. Он даже откажется обрабатывать сгенерированные из POD страницы, потому что такие страницы идеально обрабатываются с помощью po4a::pod и потому что nroff в них определяет уйму новых макросов, для которых у меня нет ни какого желания писать поддержку. На моей машине, 1432 из 4323 страниц сгенерированы из POD и будут проигнорированы po4a::man.

note: type: textblock
en: In most cases, po4a::man will detect the problem and refuse to process the page, issuing an adapted message. In some rare cases, the program will complete without warning, but the output will be wrong. Such cases are called "bugs" ;) If you encounter such case, be sure to report this, along with a fix when possible…
ru: В большинстве случаев po4a::man будет находить проблему и прекратит обработку страницы, выводя удовлетворительное сообщение. В некоторых редких случаях программа завершится без предупреждений, но вывод будет ошибочным. Такие случаи называются «Багами» ;) Если вы столкнётесь с подобными ситуациями, обязательно сообщайте о них, по возможности с исправлениями…

note: type: textblock
en: This module can be used for most of the existing man pages.
ru: Этот модуль можно использовать с большинством существующих man страниц.

note: type: textblock
en: Some tests are regularly run on Linux boxes:
ru: Некоторые проверки регулярно проводятся на машинах с Linux:

note: type: =item
en: one third of the pages are refused because they were generated from another format supported by po4a (e.g. POD or SGML).
ru: треть всех страниц отвергаются, потому что они были сгенерированы из других форматов поддерживаемых po4a (например, POD или SGML).

note: type: =item
en: 10% of the remaining pages are rejected with an error (e.g. a groff macro is not supported).
ru: 10% оставшихся страниц отвергаются с какой-либо ошибкой (например из-за того, что макросы groff не поддерживаются).

note: type: =item
en: Then, less than 1% of the pages are accepted silently by po4a, but with significant issues (i.e. missing words, or new words inserted)
ru: Затем, менее 1% страниц проходят все проверки po4a без сообщений об ошибках, но в результате имеют значительные проблемы (например, пропущенные или лишние слова)

note: type: =item
en: The other pages are usually handled without differences more important than spacing differences or line rewrapped (font issues in less than 10% of the processed pages).
ru: Все остальные страницы обычно обрабатываются без каких-либо проблем более значительных, нежели изменения пробелов или переносов строк (проблемы со шрифтами в менее, чем 10% обработанных страниц).

note: type: textblock
en: Locale::Po4a::Org - convert Org documents from/to PO files.
ru: Locale::Po4a::Org - преобразование документов Org из/в PO-файлы.

note: type: verbatim
en:  [type:org] /path/to/master.org              \
            $lang:/path/to/translation.$lang.org \
            opt:"                                \
            --option skip_keywords='             \
                include                          \
                export_file_name                 \
                link'                            \
            --option skip_properties='           \
                copying                          \
                NOBLOCKING                       \
                ORDERED'"
ru:  [type:org] /путь/к/мастер.org          \
            $lang:/путь/к/перевод.$lang.org \
            opt:"                           \
            --option skip_keywords='        \
                include                     \
                export_file_name            \
                link'                       \
            --option skip_properties='      \
                copying                     \
                NOBLOCKING                  \
                ORDERED'"

note: type: textblock
en: C<Locale::Po4a::Org> is a module to help the translation of documentation in the Org format, used by the L<Org Mode|https://orgmode.org/>.
ru: C<Locale::Po4a::Org> -- это модуль, предназначенный для помощи в переводе документов в формате Org, используемом L<Org Mode|https://orgmode.org/>.

note: type: =head1
en: CONFIGURATION
ru: Конфигурация

note: type: textblock
en: Space-separated list of keywords which won't be translated.
ru: Список ключевых слов, разделённых пробелами, которые не будут переведены.

note: type: textblock
en: Space-separated list of properties which won't be translated.
ru: Список свойств, разделённых пробелами, которые не будут переведены.

note: type: textblock
en: If this is a true value, skip translating headings.  When your translation is converted to Texinfo format, the translation of headings can cause node names to become bizarre.  This option prevents that.
ru: Если установлено значение I<true>, заголовки не будут переведены.  Когда ваш перевод преобразуется в формат Texinfo, перевод заголовков может привести к тому, что ноды будут иметь странные названия.  Данный параметр предотвращает это.

note: type: textblock
en: This module is in an early stage of development.  It is tested successfully on simple Org files, such as the L<Org Mode Compact Guide|https://orgmode.org/guide/>.  However it does not support the full L<Org syntax|https://orgmode.org/worg/org-syntax.html>; footnotes and nested plain lists cannot currently be parsed, for example.
ru: Данный модуль находится на ранней стадии разработки. Он успешно протестирован на простых файлах формата Org, таких как L<Org Mode Compact Guide|https://orgmode.org/guide/>. Однако L<синтаксис Org|https://orgmode.org/worg/org-syntax.html> поддерживается не полностью; например, в настоящее время не обрабатываются сноски и вложенные списки.

note: type: textblock
en: This program is free software; you may redistribute it and/or modify it under the terms of GPL v2.0 or later (see the F<COPYING> file).
ru: Данная программа является свободным программным обеспечением; вы можете распространять и/или изменять её на условиях Универсальной общественной лицензии (GPL) GNU v2.0 или новее (см. файл F<COPYING>).

note: type: textblock
en: Locale::Po4a::Po - PO file manipulation module
ru: Locale::Po4a::Po: модуль манипуляции PO-файлами

note: type: verbatim
en:     use Locale::Po4a::Po;
        my $pofile=Locale::Po4a::Po->new();
    
        # Read PO file
        $pofile->read('file.po');
    
        # Add an entry
        $pofile->push('msgid' => 'Hello', 'msgstr' => 'bonjour',
                      'flags' => "wrap", 'reference'=>'file.c:46');
    
        # Extract a translation
        $pofile->gettext("Hello"); # returns 'bonjour'
    
        # Write back to a file
        $pofile->write('otherfile.po');
ru:     use Locale::Po4a::Po;
        my $pofile=Locale::Po4a::Po->new();
    
        # Прочитать PO-файл
        $pofile->read('file.po');
    
        # Добавить запись
        $pofile->push('msgid' => 'Hello', 'msgstr' => 'bonjour',
                      'flags' => "wrap", 'reference'=>'file.c:46');
    
        # Извлечь перевод
        $pofile->gettext("Hello"); # возвращает 'bonjour'
    
        # Записать файл обратно
        $pofile->write('otherfile.po');

note: type: textblock
en: Locale::Po4a::Po is a module that allows you to manipulate message catalogs. You can load and write from/to a file (which extension is often I<po>), you can build new entries on the fly or request for the translation of a string.
ru: Locale::Po4a::Po — это модуль, который позволяет вам производить манипуляции с каталогами сообщений. Вы можете читать и писать из/в файл (с расширением, обычно, I<po>), вы можете создавать новые записи на лету или запрашивать переводы строк.

note: type: textblock
en: For a more complete description of message catalogs in the PO format and their use, please refer to the info documentation of the gettext program (node "`PO Files"').
ru: Более всеобъемлющее описание того, что представляют из себя каталоги сообщений в PO-формате и как их использовать, можно найти в документации программы gettext, в частности на её info-странице (глава «PO Files»).

note: type: textblock
en: This module is part of the po4a project, which objective is to use PO files (designed at origin to ease the translation of program messages) to translate everything, including documentation (man page, info manual), package description, debconf templates, and everything which may benefit from this.
ru: Этот модуль является частью проекта po4a, целью которого является использование PO-файлов (разработанных изначально для перевода сообщений в самих программах) для перевода вообще всего, включая документацию (man и info-страницы), описаний пакетов, шаблонов debconf, а также всего остального, где это только может принести хоть какую-либо пользу.

note: type: =head1
en: Functions concerning entire message catalogs
ru: Функции, относящиеся ко всему каталогу сообщений

note: type: textblock
en: Creates a new message catalog. If an argument is provided, it's the name of a PO file we should load.
ru: Создаёт новый каталог сообщений. Если указан аргумент, то это имя PO-файла, который будет загружен.

note: type: textblock
en: Reads a PO file (which name is given as argument).  Previously existing entries in self are not removed, the new ones are added to the end of the catalog.
ru: Читает PO-файл (имя которого указано в качестве аргумента). Записи, уже присутствующие в каталоге, не удаляются; новые записи добавляются в конец каталога.

note: type: textblock
en: Writes the current catalog to the given file.
ru: Записывает текущий каталог в указанный файл.

note: type: textblock
en: Like write, but if the PO or POT file already exists, the object will be written in a temporary file which will be compared with the existing file to check if the update is needed (this avoids to change a POT just to update a line reference or the POT-Creation-Date field).
ru: Аналогично write(), но если PO или POT-файл уже существует, то объект будет записан во временный файл, который будет сравнён с существующим, дабы проверить, требуется ли обновление (это позволяет избежать изменения POT-файла только для обновления сносок на строки в исходных документах или поля POT-Creation-Date).

note: type: textblock
en: This function extracts a catalog from an existing one. Only the entries having a reference in the given file will be placed in the resulting catalog.
ru: Эта функция извлекает часть записей из существующего каталога сообщений в новый. В результирующий каталог будут помещены только записи, у которых есть сноски на строки в указанном файле (похоже, эта функция может фильтровать не только по файлу, I<прим. переводчика>).

note: type: textblock
en: This function parses its argument, converts it to a Perl function definition, evals this definition and filters the fields for which this function returns true.
ru: Эта функция анализирует переданную ей строку, преобразуя её в функцию Perl, вызывает для неё B<eval> и фильтрует каталог сообщений, оставляя только те поля, для которых функция возвращает true.

note: type: textblock
en: I love Perl sometimes ;)
ru: Иногда я люблю Perl ;)

note: type: =head1
en: Functions to use a message catalog for translations
ru: Функции для использования каталога сообщений для перевода

note: type: textblock
en: Request the translation of the string given as argument in the current catalog.  The function returns the original (untranslated) string if the string was not found.
ru: Запросить перевод строки, указанной в качестве аргумента, в текущем каталоге. Если строка не найдена, функция возвращает исходную (непереведённую) строку.

note: type: textblock
en: After the string to translate, you can pass a hash of extra arguments. Here are the valid entries:
ru: После переводимой строки вы можете также передать хеш с дополнительными аргументами. Допустимые ключи:

note: type: textblock
en: boolean indicating whether we can consider that whitespaces in string are not important. If yes, the function canonizes the string before looking for a translation, and wraps the result.
ru: логическое значение, указывающее, можем ли мы считать, что пробелы в строке не важны. Если да, функция канонизирует строку перед поиском перевода и добавляет переносы строк в результат по необходимости (вызывая B<wrap()>).

note: type: textblock
en: the column at which we should wrap (default: 76).
ru: количество символов в строке, после которых должен выполняться автоматический перенос текста на новую строку (по умолчанию: 76).

note: type: textblock
en: Returns statistics about the hit ratio of gettext since the last time that stats_clear() was called. Please note that it's not the same statistics than the one printed by msgfmt --statistic. Here, it's statistics about recent usage of the PO file, while msgfmt reports the status of the file.  Example of use:
ru: Возвращает статистику о коэффициенте попадания gettext (т.е. доли запросов, для которых был найден перевод строки) с момента последнего вызова stats_clear(). Обратите внимание, что это не та статистика, которую выводит C<msgfmt --statistic>. Эта функция возвращает статистику недавнего использования PO-файла, в то с время как B<msgfmt> выводит информацию о количестве переводов и строк в самом файле. Пример использования:

note: type: verbatim
en:     [some use of the PO file to translate stuff]
    
        ($percent,$hit,$queries) = $pofile->stats_get();
        print "So far, we found translations for $percent\%  ($hit of $queries) of strings.\n";
ru:     [использования PO-фойла для перевода чего-нибудь]
    
        ($percent,$hit,$queries) = $pofile->stats_get();
        print "На данный момент мы нашли переводы для $percent\% ($hit из $queries) строк.\n";

note: type: textblock
en: Clears the statistics about gettext hits.
ru: Сбрасывает статистику успешности запросов gettext.

note: type: =head1
en: Functions to build a message catalog
ru: Функции для наполнения каталога сообщений

note: type: textblock
en: Push a new entry at the end of the current catalog. The arguments should form a hash table. The valid keys are:
ru: Добавить новую запись в конец текущего каталога. Принимает хеш-таблицу. Допустимые ключи:

note: type: textblock
en: the string in original language.
ru: строка на исходном языке.

note: type: textblock
en: the translation.
ru: перевод.

note: type: textblock
en: an indication of where this string was found. Example: file.c:46 (meaning in 'file.c' at line 46). It can be a space-separated list in case of multiple occurrences.
ru: указание, где была найдена эта строка. Например: file.c:46 (строка 46 из файла «file.c»). Может быть списком (разделённым пробелами) в случае, если строка встречается несколько раз.

note: type: textblock
en: a comment added here manually (by the translators). The format here is free.
ru: добавленный вручную (переводчиком) комментарий. Формат может быть произвольным.

note: type: textblock
en: a comment which was automatically added by the string extraction program. See the B<--add-comments> option of the B<xgettext> program for more information.
ru: комментарий, добавленный программой извлечения строк. Для более подробной информации см. описание параметра B<--add-comments> для программы B<xgettext>.

note: type: textblock
en: space-separated list of all defined flags for this entry.
ru: список флагов, разделённых пробелами, которые были заданы для данной записи .

note: type: textblock
en: Valid flags are: B<c-text>, B<python-text>, B<lisp-text>, B<elisp-text>, B<librep-text>, B<smalltalk-text>, B<java-text>, B<awk-text>, B<object-pascal-text>, B<ycp-text>, B<tcl-text>, B<wrap>, B<no-wrap> and B<fuzzy>.
ru: Допустимы следующие флаги: B<c-text>, B<python-text>, B<lisp-text>, B<elisp-text>, B<librep-text>, B<smalltalk-text>, B<java-text>, B<awk-text>, B<object-pascal-text>, B<ycp-text>, B<tcl-text>, B<wrap>, B<no-wrap> и B<fuzzy>.

note: type: textblock
en: See the gettext documentation for their meaning.
ru: См. документацию gettext для описания их значений.

note: type: textblock
en: this is mostly an internal argument: it is used while gettextizing documents. The idea here is to parse both the original and the translation into a PO object, and merge them, using one's msgid as msgid and the other's msgid as msgstr. To make sure that things get ok, each msgid in PO objects are given a type, based on their structure (like "chapt", "sect1", "p" and so on in DocBook). If the types of strings are not the same, that means that both files do not share the same structure, and the process reports an error.
ru: в основном это параметр для внутреннего использования: он используется при геттекстизации документов. Идея здесь состоит в том, чтобы разобрать и исходный документ, и перевод в PO-объект и сшить их, используя msgid одного в качестве msgid, а msgid второго в качестве msgstr. Чтобы удостовериться, что всё корректно, каждому msgid в PO-объектах присваивается тип, основываясь на структуре файла из которого они были извлечены (например, «chapt», «sect1», «p» и т.п. в DocBook). Если типы строк не совпадают, то это означает, что оба файла имеют разную структуру, и процесс завершается с ошибкой.

note: type: textblock
en: This information is written as automatic comment in the PO file since this gives to translators some context about the strings to translate.
ru: Также эта информация записывается в виде автоматического комментария в PO-файл, поскольку это предоставляет переводчикам некоторый дополнительный контекст для строк, которые они переводят.

note: type: textblock
en: boolean indicating whether whitespaces can be mangled in cosmetic reformattings. If true, the string is canonized before use.
ru: логическое значение, указывающее, можно ли изменять пробельные символы ради косметического переформатирования. Если истина, то строка будет канонизирована перед использованием.

note: type: textblock
en: This information is written to the PO file using the B<wrap> or B<no-wrap> flag.
ru: Эта информация записывается в PO-файл с помощью флагов B<wrap> или B<no-wrap>.

note: type: textblock
en: ignored; the key is kept for backward computability.
ru: не используется; данный параметр сохранен в целях обратной совместимости.

note: type: =head1
en: Miscellaneous functions
ru: Прочие функции

note: type: textblock
en: Returns the number of entries in the catalog (without the header).
ru: Возвращает количество записей в каталоге (не считая заголовка).

note: type: textblock
en: Returns the number of entries in document. If a string appears multiple times in the document, it will be counted multiple times.
ru: Возвращает количество записей в документе. Если строка встречается в документе несколько раз, она будет учитываться несколько раз.

note: type: textblock
en: Returns the msgid of the given number.
ru: Возвращает msgid записи с указанным порядковым номером.

note: type: textblock
en: Returns the msgid with the given position in the document.
ru: Возвращает msgid с заданной порядковой позицией в документе.

note: type: textblock
en: Returns the type of the msgid with the given position in the document. This is probably only useful to gettextization, and it's stored separately from {$msgid}{'type'} because the later location may be overwritten by another type when the $msgid is duplicated in the master document.
ru: Возвращает тип msgid с заданной позицией в документе. Вероятно, это полезно только для геттекстизации, и это значение хранится отдельно от B<{$msgid}{'type'}>, поскольку этот тип может быть позднее перезаписан в случае, если строка с таким же B<$msgid> встретится в мастер-докумете позднее.

note: type: textblock
en: Returns the character set specified in the PO header. If it hasn't been set, it will return "UTF-8".
ru: Возвращает кодировку, указанную в PO-заголовке. Если кодировка не установлена, возвращается C<UTF-8>.

note: type: textblock
en: Locale::Po4a::Pod - convert POD data from/to PO files
ru: Locale::Po4a::Pod: преобразование POD-данных из/в PO-файлы

note: type: verbatim
en:     use Locale::Po4a::Pod;
        my $parser = Locale::Po4a::Pod->new();
    
        # Read POD from STDIN and write to STDOUT.
        $parser->parse_from_filehandle;
    
        # Read POD from file.pod and write to file.txt.
        $parser->parse_from_file ('file.pod', 'file.txt');
ru:     use Locale::Po4a::Pod;
        my $parser = Locale::Po4a::Pod->new();
    
        # Прочитать POD из STDIN и записать в STDOUT.
        $parser->parse_from_filehandle;
    
        # Прочитать POD из file.pod и записать в file.txt.
        $parser->parse_from_file ('file.pod', 'file.txt');

note: type: textblock
en: Locale::Po4a::Pod is a module to help the translation of documentation in the POD format (the preferred language for documenting Perl) into other [human] languages.
ru: Locale::Po4a::Pod — это модуль, предназначенным для помощи в переводе документации в формате POD (предпочтительный язык разметки документации Perl) на другие [человеческие] языки.

note: type: textblock
en: A new L<SimplePod|Locale::Po4a::SimplePod> parser is now available.  Please consider using it instead of the current Pod module.  If you encounter any bugs, your reports would be greatly appreciated.
ru: Теперь доступен новый парсер: L<SimplePod|Locale::Po4a::SimplePod>. Пожалуйста, подумайте о том, чтобы использования его вместо данного модуля (Pod). Если вы столкнётесь с какими-либо ошибками, мы будем очень признательны, если вы сообщите о них нам.

note: type: textblock
en: The above warning message will be displayed for a transitional period.  To disable it, set the C<no-warn-simple> option.
ru: Вышеуказанное предупреждение будет отображаться в течение переходного периода. Чтобы отключить его, передайте параметр модуля C<no-warn-simple>.

note: type: textblock
en: I think that this module is rock stable, and there is only one known bug with F</usr/lib/perl5/Tk/MainWindow.pod> (and some other pages, see below) which contains:
ru: Я думаю, что этот модуль стабилен, как скала, и есть только одна известная ошибка в F</usr/lib/perl5/Tk/MainWindow.pod> (и в некоторых других страницах, см. ниже), которые содержат:

note: type: textblock
en: Lack of luck, in the po4a version, this was split on the space by the wrapping. As result, in the original version, the man page contains:
ru: Из-за неудачного стечение обстоятельств, в версии po4a часть этой строки было перенесена на следующую на пробеле. В результате в исходной версии man-страница содержит:

note: type: textblock
en: and mine contains:
ru: а моя содержит:

note: type: textblock
en: which is logic since CE<lt>foobarE<gt> is rewritten "foobar".
ru: что логично, т.к. CE<lt>foobarE<gt> преобразуется в "foobar".

note: type: textblock
en: Complete list of pages having this problem on my box (from 564 pages; note that it depends on the chosen wrapping column):
ru: Полный список страниц, на которых возникала подобная проблема на моей машине (из 564 страниц; также заметьте, что это зависит от количества знаков после которого осуществляется перенос):

note: type: =head1
en: INTERNALS
ru: ВНУТРЕННОСТИ

note: type: textblock
en: As a derived class from Pod::Parser, Locale::Po4a::Pod supports the same methods and interfaces.  See L<Pod::Parser> for all the details; briefly, one creates a new parser with C<< Locale::Po4a::Pod->new() >> and then calls either parse_from_filehandle() or parse_from_file().
ru: Являясь производным классом Pod::Parser, Locale::Po4a::Pod поддерживает те же методы и интерфейсы. См. подробности в L<Pod::Parser>; если вкратце, то надо создать новый парсер с помощью C<< Locale::Po4a::Pod->new() >>, а затем вызывать либо parse_from_filehandle(), либо parse_from_file().

note: type: textblock
en: Locale::Po4a::RubyDoc -- Convert Ruby Document data from/to PO files
ru: Locale::Po4a::RubyDoc: преобразование данных в формате документации Ruby из/в PO-файлы

note: type: textblock
en: Locale::Po4a::RubyDoc is a module to help the translation of documentation in the Ruby Document (RD) format (a language used to document Ruby) into other [human] languages.
ru: Locale::Po4a::RubyDoc — это модуль, предназначенным для помощи в переводе документации в формате Ruby Document (RD, язык разметки документации Ruby) на другие [человеческие] языки.

note: type: textblock
en: This module has been successfully tested on simple Ruby Document files covering a good part of the format syntax.
ru: Этот модуль был успешно протестирован на простых файлах с документацией Ruby, покрывающих большую часть возможностей синтаксиса этого формата.

note: type: textblock
en: A known limitation is that it fails to properly recognize the stacked structure of input Ruby Document: this implies that when, for instance, an EnumListItem consists of more than one Block, only the first Block is actually recognized as EnumListItem, while the subsequent ones are considered just as TextBlocks...
ru: Известное ограничение заключается в том, что он не может правильно распознать составную структуру входного Ruby-документа: это означает, что, когда, например, EnumListItem состоит из более чем одного блока, то по факту только первый блок распознаётся как EnumListItem, а последующие — уже как TextBlocks...

note: type: textblock
en: This module supports the following option:
ru: Данный модуль поддерживает следующие параметры:

note: type: textblock
en: Handle files entirely made of Ruby Document formatted text (without any "=begin" line).
ru: Обрабатывать файлы, полностью состоящие из текста в формате Ruby Document (без каких-либо "=begin").

note: type: textblock
en: By default, this module only handles Ruby Document formatted text between "=begin" and "=end" lines (hence ignoring, among other things, everything that precedes the first "=begin" line).
ru: По умолчанию этот модуль обрабатывает только текст в формате Ruby Document между строками "=begin" и "=end" (т.е. игнорируя, среди прочего, всё, что предшествует первой строке "=begin").

note: type: textblock
en: Francesco Poli <invernomuto@paranoici.org>
ru: Франческо Поли (Francesco Poli) <invernomuto@paranoici.org>

note: type: verbatim
en:  Copyright © 2016-2017 Francesco Poli <invernomuto@paranoici.org>
ru:  Copyright © 2016-2017 Франческо Поли (Francesco Poli) <invernomuto@paranoici.org>

note: type: textblock
en: This work is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
ru: Данная программа является свободным программным обеспечением. Вы вправе распространять ее и/или модифицировать в соответствии с условиями версии 2 либо по вашему выбору с условиями более поздней версии Стандартной Общественной Лицензии GNU, опубликованной Free Software Foundation.

note: type: textblock
en: This work is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
ru: Мы распространяем данную программу в надежде на то, что она будет вам полезной, однако НЕ ПРЕДОСТАВЛЯЕМ НА НЕЕ НИКАКИХ ГАРАНТИЙ, в том числе ГАРАНТИИ ТОВАРНОГО СОСТОЯНИЯ ПРИ ПРОДАЖЕ и ПРИГОДНОСТИ ДЛЯ ИСПОЛЬЗОВАНИЯ В КОНКРЕТНЫХ ЦЕЛЯХ. Для получения более подробной информации ознакомьтесь со Стандартной Общественной Лицензией GNU.

note: type: textblock
en: You should have received a copy of the GNU General Public License along with this work; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
ru: Вместе с данной программой вы должны были получить экземпляр Стандартной Общественной Лицензии GNU. Если вы его не получили, сообщите об этом в Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

note: type: textblock
en: Parts of the code (such as many regular expressions) were adapted from the source of rdtool, under the terms of the GNU General Public License, version 2 or later.  These parts are originally:
ru: Некоторые части кода (как, например, многие регулярные выражения) были взяты из исходного кода rdtool в соответствии с условиями Стандартной общественной лицензии GNU версии 2 или более поздней. Изначально авторские права на эти части принадлежали:

note: type: textblock
en: The initialize code was adapted from the source of Locale::Po4a::Text, under the terms of the GNU General Public License, version 2 or later.  This code was originally:
ru: Код функции initialize() был взяты из исходного кода Locale::Po4a::Text в соответствии с условиями Стандартной общественной лицензии GNU версии 2 или более поздней. Изначально авторские права на этот код принадлежали:

note: type: verbatim
en:  Copyright © 2005-2008 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>
ru:  Copyright © 2005-2008 Николя Франсуа (Nicolas FRANÇOIS) <nicolas.francois@centraliens.net>

note: type: textblock
en: Locale::Po4a::Sgml - convert SGML documents from/to PO files
ru: Locale::Po4a::SGML: преобразование документов SGML из/в PO-файлы

note: type: textblock
en: Locale::Po4a::Sgml is a module to help the translation of documentation in the SGML format into other [human] languages.
ru: Locale::Po4a::Sgml — это модуль, предназначенным для помощи в переводе документации в формате SGML на другие [человеческие] языки.

note: type: textblock
en: This module uses B<onsgmls>(1) to parse the SGML files. Make sure it is installed.  Also make sure that the DTD of the SGML files are installed in the system.
ru: Этот модуль использует B<onsgmls>(1) для разбора файлов SGML. Убедитесь, что он установлен. Также убедитесь, что в системе установлены DTD-файлы SGML.

note: type: textblock
en: Space-separated list of keywords indicating which category of extra debug messages should be shown. Possible values are: C<entities>, C<generic>, C<onsgml>, C<refs> and C<tag>.
ru: Список ключевых слов, разделенных пробелами, задающий, какие категории отладочных сообщения выводить. Возможные значения: C<entities>, C<generic>, C<onsgml>, C<refs> и C<tag>.

note: type: textblock
en: Give more information about what's going on.
ru: Выводить больше информации, о том, что сейчас происходит.

note: type: textblock
en: Space-separated list of extra tags (beside the DTD provided ones) whose content should form an extra msgid, i.e that should be translated.
ru: Список тегов, разделенных пробелами, (помимо тех, что перечислены в DTD), на основе которых нужно создавать msgid, т.е. содержимое которых нужно переводить.

note: type: textblock
en: Space-separated list of extra tags (beside the DTD provided ones)  containing other tags, some of them being of category B<translate>.
ru: Список тегов, разделенных пробелами, (помимо тех, что перечислены в DTD), которые содержат другие теги. Некоторые из них могут также входить в категорию B<translate>.

note: type: textblock
en: Space-separated list of tags which increase the indentation level. This will affect the indentation in the resulting document.
ru: Список тегов, разделенных пробелами, которые добавляют дополнительные отступы к своему содержимому. Это повлияет на отступы в итоговом документе.

note: type: textblock
en: The layout within those tags should not be changed. The paragraph won't get wrapped, and no extra indentation space or new line will be added for cosmetic purpose.
ru: Расположение элементов внутри этих тегов не должно изменяться. Переводы строк в абзацах будут сохранены, никакие дополнительные отступы добавляться не будут.

note: type: textblock
en: Tags not needing to be closed.
ru: Теги, которые могут быть не закрытыми.

note: type: textblock
en: Tags ignored and considered as plain char data by po4a. That is to say that they can be part of an msgid. For example, E<lt>bE<gt> is a good candidate for this category since putting it in the B<translate> section would create a msgids with only its content, (and it's usually not a whole sentence), which is bad.
ru: Теги, которые игнорируются и рассматриваются po4a просто как часть строки. То есть они могут быть частью msgid. Например, E<lt>bE<gt> является хорошим примером такого тега, поскольку, если бы он был переводимым (B<translate>), то его содержимое извлекалось бы в отдельный msgids, в котором было бы только его содержимое (и обычно оно не представляет из себя законченного предложения), что не есть хорошо.

note: type: textblock
en: A space-separated list of attributes that need to be translated. You can specify the attributes by their name (for example, C<lang>), but you can also prefix it with a tag hierarchy, to specify that this attribute will only be translated when it is into the specified tag. For example: C<< <bbb><aaa>lang >> specifies that the lang attribute will only be translated if it is in an C<< <aaa> >> tag, which is in a C<< <bbb> >> tag.  The tag names are actually regular expressions so you can also write things like C<< <aaa|bbb>lang >> to only translate C<lang> attributes that are in an C<< <aaa> >> or a C<< <bbb> >> tag.
ru: Список атрибутов тегов, разделённых пробелами, которые необходимо переводить. Вы можете задавать атрибуты просто по их имени (например, С<lang>), но вы также можете добавить к нему префикс из одного или нескольких тегов, чтобы указать, что этот атрибут должен переводиться только когда он относится к конкретному тегу. Например: C<< <bbb><aaa>lang >> указывает, что C<lang> будет переводиться только если он относится к тегу C<< <aaa> >>, который в свою очередь находится внутри тега C<< <bbb> >>. Имена тегов, на самом деле, являются регулярными выражениями, поэтому вы также можете делать штуки вроде C<< <aaa|bbb>lang >>, чтобы переводить атрибут C<lang>, когда он находятся или в теге C<< <aaa> >> или в C<< <bbb> >>.

note: type: textblock
en: A space-separated list of attributes for which the translation must be qualified by the attribute name, i.e. the text extracted for the translation will include both the attributes name and it's value. e.g. for a tag like C<< <aaa lang_en="foo"> >> translators will be presented with the string C<lang_en="foo">. Note that this also automatically adds the given attribute into the B<attributes> list too.
ru: Список атрибутов, разделенных пробелами, для которых перевод должен быть дополнен именем атрибута, т.е. текст, извлечённый для перевода, будет включать как имя атрибута, так и его значение. Так например, для тега C<< <aaa lang_en="foo"> >> переводчикам для перевода будет доступна строка C<lang_en="foo">. Обратите внимание, что этот параметр также автоматически добавляет данный атрибут в список B<attributes>.

note: type: textblock
en: Proceed even if the DTD is unknown or if B<onsgmls> finds errors in the input file.
ru: Не прекращать работу даже, если DTD неизвестен или B<onsgmls> нашёл ошибку во входном файле.

note: type: textblock
en: By default, msgids containing only one entity (like C<&version;>) are skipped for the translators' comfort. Activating this option prevents this optimisation. It can be useful if the document contains a construction like C<< <title>&Aacute;</title> >>, even if I doubt such things to ever happen...
ru: По умолчанию msgid, содержащие только одну сущность (например, C<&version;>), пропускаются (для удобства переводчиков). При задании этого параметра подобные строки будут извлечены для перевода наравне со всеми остальными. Это может быть полезно, если в документе будет что-то вроде C<< <title>&Aacute;</title> >>, хотя я сомневаюсь, что такое когда-нибудь действительно случится...

note: type: textblock
en: Space-separated list of entities that won't be inlined.  Use this option with caution: it may cause B<onsgmls> (used internally) to add tags and render the output document invalid.
ru: Список сущностей, разделенных пробелами, которые не будут встроены. Используйте этот параметр с осторожностью: он может привести к тому, что B<onsgmls> (используемый внутри модуля) будет добавлять лишние теги, и, в следствии этого, к созданию некорректного выходного документа.

note: type: textblock
en: The result is perfect. I.e., the generated documents are exactly the same as the originals. But there are still some problems:
ru: Результат идеальный. То есть сгенерированные документы получаются абсолютно такими же как и оригинал. Но некоторые проблемы всё ещё остаются:

note: type: =item
en: The error output of B<onsgmls> is redirected to /dev/null by default, which is clearly bad. I don't know how to avoid that.
ru: Поток ошибок B<onsgmls> по умолчанию перенаправляется в /dev/null, что, очевидно, плохо. Я не знаю, как сделать это по-другому.

note: type: textblock
en: The problem is that I have to "protect" the conditional inclusions (i.e. the C<E<lt>! [ %foo [> and C<]]E<gt>> stuff) from B<onsgmls>. Otherwise B<onsgmls> eats them, and I don't know how to restore them in the final document. To prevent that, I rewrite them to C<{PO4A-beg-foo}> and C<{PO4A-end}>.
ru: Проблема в том, что мне нужно «защитить» условные включения (то есть элементы вроде C<E<lt>! [ %foo [> и C<]]E<gt>>) от B<onsgmls>. В противном случае B<onsgmls> их съедает, и я не знаю, как их восстановить в итоговом документе. Чтобы предотвратить это, я заменяю их на C<{PO4A-beg-foo}> и C<{PO4A-end}>.

note: type: textblock
en: The problem with this is that the C<{PO4A-end}> and such I add are invalid in the document (not in a E<lt>pE<gt> tag or so).
ru: И проблема в том, что расположение C<{PO4A-end}> и т.п., которые я добавляю,в самом документе (а не в теге E<lt>pE<gt> или вроде того) на самом деле некорректны.

note: type: textblock
en: If you want to view the B<onsgmls> output, just add the following to your command line (or po4a configuration line):
ru: Если вы хотите увидеть вывод B<onsgmls>, то просто добавьте следующий параметр в командную строку (или в файл настроек po4a):

note: type: =item
en: It does work only with the DebianDoc and DocBook DTD. Adding support for a new DTD should be very easy. The mechanism is the same for every DTD, you just have to give a list of the existing tags and some of their characteristics.
ru: Этот модуль работает только с DebianDoc и DocBook DTD. Добавить поддержку других новых DTD, скорей всего, будет очень легко. Механизм одинаков для всех DTD, вам просто нужно указать список существующих тегов и некоторые их характеристики.

note: type: textblock
en: I agree, this needs some more documentation, but it is still considered as beta, and I hate to document stuff which may/will change.
ru: Я согласен, что это момент мог бы быть задокументирован и по-лучше, но этот модуль, как считается, всё ещё находится на стадии бета-версии, а я ненавижу документировать вещи, которые могут/будут измениться в будущем.

note: type: =item
en: Warning, support for DTDs is quite experimental. I did not read any reference manual to find the definition of every tag. I did add tag definition to the module 'till it works for some documents I found on the net. If your document use more tags than mine, it won't work. But as I said above, fixing that should be quite easy.
ru: Внимание: поддержка DTD является относительно экспериментальной. Я не поверял определение всех тегов в каких-либо справочных руководствах. Я просто добавлял теги в модуль, пока оно не начало работать на некоторых документах, которые я нашёл в сети. Если в вашей документации используются какие-то ещё теги, которых не было в моей, то этот модуль не будет работать. Но, как я уже сказал выше, поправить это будет довольно легко.

note: type: textblock
en: I did test DocBook against the SAG (System Administrator Guide) only, but this document is quite big, and should use most of the DocBook specificities.
ru: DocBook я тестировал только на Руководстве системного администратора (SAG, System Administrator Guide), но этот документ довольно большой и, скорей всего, использует большую часть того что есть в спецификации DocBook.

note: type: textblock
en: For DebianDoc, I tested some of the manuals from the DDP, but not all yet.
ru: Что касается DebianDoc, то я протестировал модуль на некоторых руководствах из DDP, хотя и не всех.

note: type: =item
en: In case of file inclusion, string reference of messages in PO files (i.e. lines like C<#: en/titletoc.sgml:9460>) will be wrong.
ru: Если файл включает другие файлы, то сноски на номера строк в PO-файлах (т.е. строки типа C<#: en/titletoc.sgml:9460>) будут некорректными.

note: type: textblock
en: This is because I preprocess the file to protect the conditional inclusion (i.e. the C<E<lt>! [ %foo [> and C<]]E<gt>> stuff) and some entities (like C<&version;>) from B<onsgmls> because I want them verbatim to the generated document. For that, I make a temp copy of the input file and do all the changes I want to this before passing it to B<onsgmls> for parsing.
ru: Это связано с тем, что я предварительно обрабатываю файл, чтобы защитить условные включения (т.е. элементы вроде C<E<lt>! [ %foo [> и C<]]E<gt>>) и некоторые объекты (например, C<&version;>) от B<onsgmls>, потому что я хочу, чтобы они копировались дословно в итоговый документ. Для этого я делаю временную копию входного файла и вношу в него все необходимые изменения, прежде чем передавать его B<onsgmls>.

note: type: textblock
en: So that it works, I replace the entities asking for a file inclusion by the content of the given file (so that I can protect what needs to be in a subfile also). But nothing is done so far to correct the references (i.e., filename and line number) afterward. I'm not sure what the best thing to do is.
ru: Чтобы это работало, я заменяю сущности, которые запрашивают включение файла, на содержимое данного файла (чтобы также обработать это содержимое). Но для коррекции сносок (т.е. имени файла и номеров строк) ничего не делается. И я не уверен, каким образом это всё было бы лучше сделать.

note: type: textblock
en: This module is an adapted version of sgmlspl (SGML postprocessor for the ONSGMLS parser) which was:
ru: Этот модуль является версией кода позаимствованного из sgmlspl (постпроцессора SGML для парсера ONSGMLS), изначальные авторские права на который принадлежали:

note: type: verbatim
en:  Copyright © 1995 David Megginson <dmeggins@aix1.uottawa.ca>
ru:  Copyright © 1995 Дэвид Меггинсон (David Megginson) <dmeggins@aix1.uottawa.ca>

note: type: textblock
en: The adaptation for po4a was done by:
ru: Адаптация к po4a была выполнена:

note: type: verbatim
en:  Copyright © 1995 David Megginson <dmeggins@aix1.uottawa.ca>.
     Copyright © 2002-2005 SPI, Inc.
ru:  Copyright © 1995 Дэвид Меггинсон (David Megginson) <dmeggins@aix1.uottawa.ca>
     Copyright © 2002-2005 SPI, Inc.

note: type: textblock
en: Locale::Po4a::SimplePod - convert POD data from/to PO files, with Pod::Simple
ru: Locale::Po4a::SimplePod - преобразование POD-данных из/в PO-файлы c помощью Pod::Simple

note: type: verbatim
en:   [po4a_paths] /path/to/pot $lang:/path/to/po
      [type:SimplePod] /path/to/source.pod $lang:/path/to/localized.pod
ru:   [po4a_paths] /путь/к/pot $lang:/путь/к/po
      [type:SimplePod] /путь/к/исходнику.pod $lang:/путь/к/переводу.pod

note: type: textblock
en: or
ru: или

note: type: verbatim
en:   [po4a_paths] /path/to/pot $lang:/path/to/po
      [po4a_alias:pod] SimplePod
      [type:pod] /path/to/source.pod $lang:/path/to/localized.pod
ru:   [po4a_paths] /путь/к/pot $lang:/путь/к/po
      [po4a_alias:pod] SimplePod
      [type:pod] /путь/к/исходнику.pod $lang:/путь/к/переводу.pod

note: type: textblock
en: This is a module to help the translation of documentation in the POD format (the preferred language for documenting Perl) into other human languages.
ru: Этот модуль, предназначенным для помощи в переводе документации в формате POD (предпочтительный язык разметки документации Perl) на другие (человеческие) языки.

note: type: textblock
en: The main differences between the current Pod format and the SimplePod format are as follows:
ru: Можно отметить следующие основные различия между старым форматом Pod и форматом SimplePod:

note: type: =item
en: SimplePod format never includes additional newlines in messages to be translated.  The current Pod format, however, may contain extra newlines, particularly in verbatim message entries.
ru: Формат SimplePod никогда не включает дополнительные пустые строки в сообщения для перевода. Старый формат Pod, однако, может содержать лишние пустые строки, особенно в абзацах, в частности в дословных абзацах (извлекаемых без изменения переносов строк).

note: type: =item
en: Paragraphs may be rendered with line wrapping.  The L<Pod::Parser> module might apply special handling for line wrapping, making it difficult to replicate with L<Pod::Simple>.  However, L<Pod::Simple> appears to produce a more natural output.
ru: Абзацы могут отображаться с переносом строк. Модуль L<Pod::Parser> может применять специальную обработку для переносов строк, что затрудняет воспроизведение такого поведения с помощью L<Pod::Simple>. Однако, вывод L<Pod::Simple> кажется более естественным.

note: type: textblock
en: Locale::Po4a::TeX - convert TeX documents and derivatives from/to PO files
ru: Locale::Po4a::TeX: преобразование документов TeX и производных форматов из/в PO-файлы

note: type: textblock
en: Locale::Po4a::TeX is a module to help the translation of TeX documents into other [human] languages. It can also be used as a base to build modules for TeX-based documents.
ru: Locale::Po4a::TeX — это модуль, предназначенным для помощи в переводе документов TeX на другие [человеческие] языки. Он также используется другими модулями для документов основанных на TeX.

note: type: textblock
en: Users should probably use the LaTeX module, which inherits from the TeX module and contains the definitions of common LaTeX commands.
ru: Конечным пользователям, вероятно, следует использовать модуль LaTeX который наследуется от модуля TeX и содержит определения распространённых LaTeX-команд.

note: type: =head1
en: TRANSLATING WITH PO4A::TEX
ru: ПЕРЕВОД С ПОМОЩЬЮ PO4A::TEX

note: type: textblock
en: This module can be used directly to handle generic TeX documents.  This will split your document in smaller blocks (paragraphs, verbatim blocks, or even smaller like titles or indexes).
ru: Этот модуль можно использовать непосредственно для обработки простых документов TeX. Он разделит ваш документ на более мелкие части (абзацы, дословные блоки или даже меньшие части такие, как заголовки или элементы предметных указателей).

note: type: textblock
en: This module can also be customized by lines starting with "% po4a:" in the TeX file. This process is described in the B<INLINE CUSTOMIZATION> section.
ru: Поведение этого модуля можно также изменить с помощью строк в TeX-файле, начинающихся с «% po4a:». Это описано в разделе B<ВСТРОЕННЫЕ НАСТРОЙКИ ПОВЕДЕНИЯ>.

note: type: textblock
en: Comma-separated list of environments which should not be re-wrapped.
ru: Список окружений, разделенных запятыми, переносы строк в которых будут сохранены без изменений.

note: type: textblock
en: Note that there is a difference between verbatim and no_wrap environments.  There is no command and comments analysis in verbatim blocks.
ru: Заметьте, что есть различия между I<verbatim> и I<no_wrap>. В случае использования I<verbatim> не обрабатываются команды и комментарии.

note: type: textblock
en: If this environment was not already registered, po4a will consider that this environment does not take any parameters.
ru: Если это окружение еще не зарегистрировано, po4a будет считать, что это окружение не принимает никаких параметров.

note: type: textblock
en: Colon-separated list of files that should not be included by \input and \include.
ru: Список файлов, разделенных символом двоеточия, которые не будут включены командами \input и \include.

note: type: textblock
en: Comma-separated list of environments which should be taken as verbatim.
ru: Список окружений, разделенных запятыми, содержимое которых должно воспроизводиться буквально.

note: type: textblock
en: Use these options to override the default behavior of the defined commands.
ru: Используйте эти параметры, чтобы переопределить поведение по умолчанию для определенных команд.

note: type: textblock
en: The TeX module can be customized with lines starting by B<% po4a:>.  These lines are interpreted as commands to the parser.  The following commands are recognized:
ru: Модуль TeX может быть настроен с помощью строк, начинающихся с B<% po4a:>. Эти строки интепретируются как команды парсера. Распознаются следующие команды:

note: type: =item
en: B<% po4a: command> I<command1> B<alias> I<command2>
ru: B<% po4a: command> I<команда1> B<псевдоним> I<команда2>

note: type: textblock
en: Indicates that the arguments of the I<command1> command should be treated as the arguments of the I<command2> command.
ru: Указывает, что аргументы I<команды1> должны рассматриваться как аргументы I<команды2>.

note: type: =item
en: B<% po4a: command> I<command1> I<parameters>
ru: B<% po4a: command> I<команда1> I<параметры>

note: type: textblock
en: This describes in detail the parameters of the I<command1> command.  This information will be used to check the number of arguments and their types.
ru: Описывает параметры I<команды1>. Эта информация будет использоваться для проверки количества параметров и их типов.

note: type: textblock
en: You can precede the I<command1> command by
ru: Перед именем I<команды1> может стоять один из следующих знаков

note: type: =item
en: an asterisk (B<*>)
ru: звездочка (B<*>)

note: type: textblock
en: po4a will extract this command from paragraphs (if it is located at the beginning or the end of a paragraph).  The translators will then have to translate the parameters that are marked as translatable.
ru: po4a извлечет эту команду из абзаца (при условии, что она находится в начале или в конце абзаца). Для перевода будет доступен только текст параметров команды, если они помечены как переводимые.

note: type: =item
en: a plus (B<+>)
ru: плюс (B<+>)

note: type: textblock
en: As for an asterisk, the command will be extracted if it appear at an extremity of a block, but the parameters won't be translated separately.  The translator will have to translate the command concatenated to all its parameters.  This keeps more context, and is useful for commands with small words in parameter, which can have multiple meanings (and translations).
ru: Так же как при указании звездочки, команда будет извлечена, если она появится в конце блока, но текст параметров нельзя будет перевести отдельно. Для перевода будет доступна команда вместе с параметрами. Это сохраняет контекст и может быть полезно для команд, имеющих в параметрах короткие слова, которые могут иметь несколько значений (и переводов).

note: type: textblock
en: Note: In this case you don't have to specify which parameters are translatable, but po4a must know the type and number of parameters.
ru: Примечание: В этом случае вам не нужно указывать, какие параметры являются переводимыми, но po4a должен знать тип и количество параметров.

note: type: =item
en: a minus (B<->)
ru: минус (B<->)

note: type: textblock
en: In this case, the command won't be extracted from any block.  But if it appears alone on a block, then only the parameters marked as translatable will be presented to the translator.  This is useful for font commands.  These commands should generally not be separated from their paragraph (to keep the context), but there is no reason to annoy the translator with them if a whole string is enclosed in such a command.
ru: В этом случае команда не будет извлечена из блока. Но если команда появляется в отдельном блоке, то переводчику будут представлены только параметры, помеченные как доступные для перевода. Это полезно для команд шрифтов. Такие команды, в общем случае, не должны отделяться от абзаца (чтобы сохранить контекст), но нет смысла раздражать ими переводчика, если в такую команду заключена целая строка.

note: type: verbatim
en: The I<parameters> argument is a set of [] (to indicate an optional
    argument) or {} (to indicate a mandatory argument).
    You can place an underscore (_) between these brackets to indicate that
    the parameter must be translated. For example:
     % po4a: command *chapter [_]{_}
ru: Аргумент I<параметры> может быть заключен в квадратные скобки [] (необязательные параметры)
    или в фигурные скобки {} (обязательные параметры).
    Вы можете поместить между скобками символ подчеркивания (_), чтобы указать,
    что параметры должны быть переведены. Например:
     % po4a: command *chapter [_]{_}

note: type: verbatim
en: This indicates that the chapter command has two parameters: an optional
    (short title) and a mandatory one, which must both be translated.
    If you want to specify that the href command has two mandatory parameters,
    that you don't want to translate the URL (first parameter), and that you
    don't want this command to be separated from its paragraph (which allow
    the translator to move the link in the sentence), you can use:
     % po4a: command -href {}{_}
ru: Это означает, что команда chapter имеет два параметра: необязательный
    (короткий заголовок) и обязательный, оба эти параметра доступны для перевода.
    Если вы хотите для команды href указать два обязательных параметра,
    но не хотите, чтобы первый параметр (URL) был доступен для перевода,
    и не хотите отделять команду от абзаца
    (это позволит переводчику перемещать ссылку внутри предложения), вы можете использовать следующую конструкцию:
     % po4a: command -href {}{_}

note: type: textblock
en: In this case, the information indicating which arguments must be translated is only used if a paragraph is only composed of this href command.
ru: В этом случае информация, указывающая, какие аргументы должны быть переведены, используется, только когда абзац состоит из одной команды href.

note: type: =item
en: B<% po4a: environment> I<env> I<parameters>
ru: B<% po4a: environment> I<окружение> I<параметры>

note: type: verbatim
en: This defines the parameters accepted by the I<env> environment and specifies the ones to be translated.
    This information is later used to check the number of arguments of the
    \begin command.
    The syntax of the I<parameters> argument is the same as described for the
    others commands.
    The first parameter of the \begin command is the name of the environment.
    This parameter must not be specified in the list of parameters. Here are
    some examples:
     % po4a: environment multicols {}
     % po4a: environment equation
ru: Это определяет, какие параметры принимает I<окружение>, и какие из них должны быть переведены.
    Позднее данная информация используется для проверки количества аргументов
    команды \begin.
    Синтаксис |<параметров> такой же как у
    других команд.
    Первый параметр команды \begin -- это имя окружения.
    Он не должен указываться в списке параметров. Вот несколько
    примеров:
     % po4a: environment multicols {}
     % po4a: environment equation

note: type: textblock
en: As for the commands, I<env> can be preceded by a plus (+) to indicate that the \begin command must be translated with all its arguments.
ru: Перед именем I<окружения> так же как перед именем команды может стоять знак плюс (+), означающий, что команда \begin должна быть переведена со всеми аргументами.

note: type: =item
en: B<% po4a: separator> I<env> B<">I<regex>B<">
ru: B<% po4a: separator> I<окружение> B<">I<регулярное_выражение>B<">

note: type: textblock
en: Indicates that an environment should be split according to the given regular expression.
ru: Означает, что окружение должно быть разделено в соответствии с заданным регулярным выражением.

note: type: textblock
en: The regular expression is delimited by quotes.  It should not create any back-reference.  You should use (?:) if you need a group.  It may also need some escapes.
ru: Регулярное выражение должно быть заключено в кавычки. Оно не должно создавать никаких обратных ссылок. Вы должны использовать (?:) для группировки. Это может потребовать экранирования некоторых символов.

note: type: textblock
en: For example, the LaTeX module uses the "(?:&|\\\\)" regular expression to translate separately each cell of a table (lines are separated by '\\' and cells by '&').
ru: К примеру, модуль LaTeX использует регулярное выражение "(?:&|\\\\)" для перевода отдельных ячеек таблицы (строки разделяются символами '\\', ячейки разделяются символом '&').

note: type: textblock
en: The notion of environment is expanded to the type displayed in the PO file.  This can be used to split on "\\\\" in the first mandatory argument of the title command.  In this case, the environment is title{#1}.
ru: Понятие окружения расширяется до типа, отображаемого в PO-файле. Это позволяет рассматривать "\\\\" как разделитель в первом обязательном аргументе команды title. В этом случае окружением является title{#1}.

note: type: =item
en: B<% po4a: verbatim environment> I<env>
ru: B<% po4a: verbatim environment> I<окружение>

note: type: textblock
en: Indicate that I<env> is a verbatim environment.  Comments and commands will be ignored in this environment.
ru: Означает, что содержимое I<окружения> воспроизводится буквально. Комментарии и команды будут игнорироваться.

note: type: =head1
en: WRITING DERIVATE MODULES
ru: НАПИСАНИЕ ПРОИЗВОДНЫХ МОДУЛЕЙ

note: type: textblock
en: Add a string as a comment to be added around the next translated element.  This is mostly useful to the texinfo module, as comments are automatically handled in TeX.
ru: Добавить строку в качестве комментария к следующему переведенному элементу. В основном это полезно для модуля texinfo, поскольку комментарии автоматически обрабатываются в TeX.

note: type: textblock
en: Wrapper around Transtractor's translate, with pre- and post-processing filters.
ru: Функция с фильтрами пред- и пост-обработки. Является оберткой для одноименной функции из модуля Transtractor.

note: type: textblock
en: Comments of a paragraph are inserted as a PO comment for the first translated string of this paragraph.
ru: Комментарии к абзацу вставляются PO-комментарии к первой переведенной строке этого абзаца.

note: type: textblock
en: This function returns:
ru: Эта функция возвращает:

note: type: =item
en: A command name
ru: Имя команды

note: type: textblock
en: If no command is found at the beginning of the given buffer, this string will be empty.  Only commands that can be separated are considered.  The %separated_command hash contains the list of these commands.
ru: Если команда не найдена в начале буфера, эта строка будет пустой. Рассматриваются только те команды, которые могут быть разделены. Хэш %separated_command содержит список таких команд.

note: type: =item
en: A variant
ru: Вариант вызова команды

note: type: textblock
en: This indicates if a variant is used.  For example, an asterisk (*) can be added at the end of sections command to specify that they should not be numbered.  In this case, this field will contain "*".  If there is no variant, the field is an empty string.
ru: Указывает, что используется вариант команды. Например, команда создания раздела section существует в варианте section* (со звездочкой), это означает, что раздел не должен быть пронумерован. В этом случае данное поле будет содержать "*". Если вариант не используется, поле содержит пустую строку.

note: type: =item
en: An array of tuples (type of argument, argument)
ru: Массив кортежей (тип аргумента, аргумент)

note: type: textblock
en: The type of argument can be either '{' (for mandatory arguments) or '[' (for optional arguments).
ru: Тип аргумента может быть '{' (для обязательных аргументов) или '[' (для необязательных аргументов).

note: type: =item
en: The remaining buffer
ru: Остаток буфера

note: type: textblock
en: The rest of the buffer after the removal of this leading command and its arguments.  If no command is found, the original buffer is not touched and returned in this field.
ru: Часть буфера, оставшаяся после удаления имени команды и аргументов. Если имя команды не обнаружено, исходный буфер остается нетронутым и возвращается в это поле.

note: type: textblock
en: The same as B<get_leading_command>, but for commands at the end of a buffer.
ru: То же самое, что и B<get_leading_command>, но для команд, содержащихся в конце буфера.

note: type: textblock
en: Recursively translate a buffer by separating leading and trailing commands (those which should be translated separately) from the buffer.
ru: Рекурсивный перевод содержимого буфера с отделением команд, содержащихся в начале и в конце буфера (те, которые должны быть переведены отдельно).

note: type: textblock
en: If a function is defined in %translate_buffer_env for the current environment, this function will be used to translate the buffer instead of translate_buffer().
ru: Если функция определена в %translate_buffer_env для текущего окружения, она будет использована вместо translate_buffer().

note: type: textblock
en: Overloads Transtractor's read().
ru: Перегружает функцию read(), содержащуюся в модуле Transtractor.

note: type: textblock
en: Recursively read a file, appending included files which are not listed in the @exclude_include array.  Included files are searched using the B<kpsewhich> command from the Kpathsea library.
ru: Рекурсивно читает файл, добавляя содержимое файлов, указанных в командах \input и \include, за исключением файлов, перечисленных в @exclude_include. Поиск включаемых файлов производится с помощью команды B<kpsewhich> из библиотеки Kpathsea.

note: type: textblock
en: Except from the file inclusion part, it is a cut and paste from Transtractor's read.
ru: Кроме части кода, отвечающей за включение файла. Эта часть кода взята из функции read() модуля Transtractor.

note: type: textblock
en: Subroutine for parsing a file with po4a directives (definitions for new commands).
ru: Подпрограмма для разбора файла с инструкциями po4a (определения новых команд).

note: type: textblock
en: Parse a definition line of the form "% po4a: ".
ru: Разбор строки в форме "% po4a: ".

note: type: textblock
en: See the B<INLINE CUSTOMIZATION> section for more details.
ru: Подробности см. в B<ВСТРОЕННЫЕ НАСТРОЙКИ ПОВЕДЕНИЯ>.

note: type: =head1
en: INTERNAL FUNCTIONS used to write derivative parsers
ru: ВНУТРЕННИЕ ФУНКЦИИ, используемые при создании производных парсеров

note: type: textblock
en: Command and environment functions take the following arguments (in addition to the $self object):
ru: Функции command и environment принимают следующие аргументы (в дополнение к $self object):

note: type: =item
en: An array of (type, argument) tuples
ru: Массив кортежей (тип аргумента, аргумент)

note: type: =item
en: The current environment
ru: Текущее окружение

note: type: textblock
en: The first 3 arguments are extracted by get_leading_command or get_trailing_command.
ru: Первые три аргумента, извлекаемые функцией get_leading_command или get_trailing_command.

note: type: textblock
en: Command and environment functions return the translation of the command with its arguments and a new environment.
ru: Функция command возвращает перевод команды с её аргументами. Функция environment возвращает новое окружение.

note: type: textblock
en: Environment functions are called when a \begin command is found. They are called with the \begin command and its arguments.
ru: Функции environment вызываются при обнаружении команды \begin. Они вызываются с командой \begin и её аргументами.

note: type: textblock
en: The TeX module only proposes one command function and one environment function: generic_command and generic_environment.
ru: Модуль TeX предлагает только одну функцию command и одну функцию environment: generic_command и generic_environment.

note: type: verbatim
en: generic_command uses the information specified by
    register_generic_command or by adding definition to the TeX file:
     % po4a: command I<command1> I<parameters>
ru: generic_command использует информацию указанную в
    register_generic_command или в определении из TeX-файла:
     % po4a: command I<команда1> I<параметры>

note: type: verbatim
en: generic_environment uses the information specified by
    register_generic_environment or by adding definition to the TeX file:
     % po4a: environment I<env> I<parameters>
ru: generic_environment использует информацию указанную в
    register_generic_environment или в определении из TeX-файла:
     % po4a: environment I<окружение> I<параметры>

note: type: textblock
en: Both functions will only translate the parameters that were specified as translatable (with a '_').  generic_environment will append the name of the environment to the environment stack and generic_command will append the name of the command followed by an identifier of the parameter (like {#7} or [#2]).
ru: Обе функции будут переводить только те параметры, которые помечены как переводимые (с символом '_'). generic_environment добавит имя окружения в стек environment, а generic_command добавит имя команды, за которым следует идентификатор параметра (например {#7} или [#2]).

note: type: textblock
en: This module needs more tests.
ru: Этот модуль нуждается в дополнительном тестировании.

note: type: textblock
en: It was tested on a book and with the Python documentation.
ru: Этот модуль тестировался на одной книге и документации Python.

note: type: =head1
en: TODO LIST
ru: Список TODO

note: type: =item
en: Automatic detection of new commands
ru: Автоматическое обнаружение новых команд

note: type: textblock
en: The TeX module could parse the newcommand arguments and try to guess the number of arguments, their type and whether or not they should be translated.
ru: Модуль TeX мог бы разбирать аргументы команды newcommand и пытаться угадать их количество, тип и то, следует ли их переводить.

note: type: =item
en: Translation of the environment separator
ru: Перевод разделителей окружения

note: type: textblock
en: When \item is used as an environment separator, the item argument is attached to the following string.
ru: Когда \item используется как разделитель окружения, аргумент item прикрепляется к следующей строке.

note: type: =item
en: Some commands should be added to the environment stack
ru: Некоторые команды должны быть добавлены в стек environment

note: type: textblock
en: These commands should be specified by couples.  This can be used to specify commands beginning or ending a verbatim environment.
ru: Эти команды должны быть указаны парами. Это может использоваться для указания команд, начинающих или заканчивающих verbatim.

note: type: =item
en: Others
ru: Другое

note: type: textblock
en: Various other points are tagged TODO in the source.
ru: В исходном коде различные точки помечены как TODO.

note: type: =head1
en: KNOWN BUGS
ru: ИЗВЕСТНЫЕ ОШИБКИ

note: type: textblock
en: Various points are tagged FIXME in the source.
ru: В исходном коде различные точки помечены как FIXME.

note: type: textblock
en: Locale::Po4a::Texinfo - convert Texinfo documents and derivates from/to PO files
ru: Locale::Po4a::Texinfo: преобразование документов Texinfo и производных форматов из/в PO-файлы

note: type: textblock
en: Locale::Po4a::Texinfo is a module to help the translation of Texinfo documents into other [human] languages.
ru: Locale::Po4a::Texinfo — это модуль, предназначенным для помощи в переводе документов Texinfo на другие [человеческие] языки.

note: type: textblock
en: This module contains the definitions of common Texinfo commands and environments.
ru: Этот модуль содержит объявления общих команд и элементов среды Texinfo.

note: type: textblock
en: Only the comments starting with 'TRANSLATORS' are added to the PO files to guide the translators.
ru: В PO-файлы, чтобы помочь переводчикам, будут добавляться только те комментарии, которые начинающиеся со строки "TRANSLATORS".

note: type: textblock
en: This module is still beta and not ready for production use.  Please send patches to contribute, not bug reports as we don't know how to deal with them.
ru: Этот модуль все еще находится на стадии бета-тестирования и не готов к использованию в рабочей среде.  Пожалуйста, присылайте исправления, чтобы внести свой вклад, а не сообщения об ошибках, поскольку мы не знаем, как с ними бороться.

note: type: textblock
en: Do not warn about the current state of this module.
ru: Не выводить предупреждение о текущем состоянии данного модуля.

note: type: textblock
en: Copyright © 2004-2007 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.
ru: Copyright © 2004-2007 Николя Франсуа (Nicolas FRANÇOIS) <nicolas.francois@centraliens.net>.

note: type: textblock
en: Locale::Po4a::Text - convert text documents from/to PO files
ru: Locale::Po4a::Text: преобразование обычных текстовых документов из/в PO-файлы

note: type: textblock
en: Locale::Po4a::Text is a module to help the translation of text documents into other [human] languages.
ru: Locale::Po4a::Text — это модуль, предназначенным для помощи в переводе документов на другие [человеческие] языки.

note: type: textblock
en: Paragraphs are split on empty lines (or lines containing only spaces or tabulations).
ru: Абзацы отделяются друг от друга пустыми строками (или строками, содержащими только пробелы и табуляции).

note: type: textblock
en: If a paragraph contains a line starting by a space (or tabulation), this paragraph won't be rewrapped.
ru: Если в абзаце есть строки, начинающиеся с пробела (или табуляции), то переносы строк в этом параграфе сохранены.

note: type: textblock
en: Treat paragraphs that look like a colon-separated key-value pair as verbatim (with the C<no-wrap> flag in the PO file). A key-value pair string is a string like C<key: value>, containing one or more non-colon and non-space characters followed by a colon followed by at least one non-space character before the end of the line.
ru: Обрабатывать абзацы, которые выглядят как пара ключ-значение (разделённые двоеточием), как «буквальные» (verbatim, т.е. добавлять флаг C<no-wrap> в PO-файл). Парой ключ-значение считается строка вида C<ключ:значение>, содержащая один или несколько символов не являющихся двоеточием или пробелом, за которыми следует двоеточие, за которым следует хотя бы один непробельный символ перед концом строки.

note: type: textblock
en: Deactivate the detection of bullets.
ru: Отключить автоматическое обнаружение ненумерованных списков.

note: type: textblock
en: By default, when a bullet is detected, the bullet paragraph is not considered as a verbatim paragraph (with the C<no-wrap> flag in the PO file). Instead, the corresponding paragraph is rewrapped in the translation.
ru: По умолчанию при обнаружении маркера ненумерованного списка в начале строки, абзац не считается «дословным» (verbatim, т.е. флаг C<no-wrap> в PO-файл не добавляется) и переводы строк в нём будут расставлены автоматически.

note: type: =item
en: B<tabs=>I<mode>
ru: B<tabs=>I<режим>

note: type: textblock
en: Specify how tabulations shall be handled. The I<mode> can be any of:
ru: Указывает, как следует обрабатывать табуляции. I<режим> может быть одним из:

note: type: textblock
en: Lines with tabulations introduce breaks in the current paragraph.
ru: Строки, содержащие только одну табуляцию будут разделять абзацы.

note: type: textblock
en: Paragraph containing tabulations will not be re-wrapped.
ru: Переносы строк в параграфах, содержащих табуляции, будут сохранены.

note: type: textblock
en: By default, tabulations are considered as spaces.
ru: По умолчанию табуляции считаются просто пробельными символами.

note: type: textblock
en: A regular expression matching lines which introduce breaks.  The regular expression will be anchored so that the whole line must match.
ru: Регулярное выражение для строк, разделяющих абзацы. К этому регулярному выражению будут добавлены специальные символы (^$) так, чтобы оно сопоставляло всю строку целиком.

note: type: textblock
en: Handle the header and footer of released versions, which only contain non translatable information.
ru: Обрабатывать верхний и нижний колонтитулы описаний пакетов, которые содержат только непереводимую информацию, специальным образом.

note: type: textblock
en: Handle the fortunes format, which separate fortunes with a line which consists in '%' or '%%', and use '%%' as the beginning of a comment.
ru: Обрабатывать формат B<fortune>, в котором афоризмы разделяются строкой, состоящей из '%' или '%%', и '%%' используется в качестве начала комментария.

note: type: textblock
en: Handle some special markup in Markdown-formatted texts.
ru: Обрабатывать некоторую разметку, специфичную для текстов в формате Markdown.

note: type: =item
en: B<yfm_keys> (markdown-only)
ru: B<yfm_keys> (только для markdown)

note: type: =item
en: B<yfm_lenient> (markdown only)
ru: B<yfm_lenient> (только для markdown)

note: type: textblock
en: Allow the YAML Front Matter parser to fail on malformated headers. This is particularly helpful when your file starts with a horizontal ruler instead of a YAML Front Matter, but you insist on using three dashes only for your ruler.
ru: Допускать возникновение ошибок при анализе некорректного YAML-заголовка (Front Matter). Это особенно полезно, если ваш файл начинается с горизонтальной линии, а не собственно с YAML-заголовка, и вы по какой-то неизвестной причине убеждены, что вам необходимы продолжать использовать только три дефиса (и не больше) для обозначения этой линии линии.

note: type: =item
en: B<yfm_paths> (markdown only)
ru: B<yfm_paths> (только для markdown)

note: type: =item
en: B<yfm_skip_array> (markdown-only)
ru: B<yfm_skip_array> (только для markdown)

note: type: =item
en: B<control>[B<=>I<field_list>]
ru: B<control>[B<=>I<список_полей>]

note: type: textblock
en: Handle Debian's control files.  A comma-separated list of fields to be translated can be provided.
ru: Обрабатывать control-файлы Debian. Также можно задать список (разделённый запятыми) полей, значения которых будут извлечены для перевода.

note: type: textblock
en: Prevent po4a from wrapping any lines. This means that every content is handled verbatim, even simple paragraphs.
ru: Сохранять все переносы. Это значит, что всё содержимое будет передано дословно (verbatim), даже простые текстовые абзацы.

note: type: textblock
en: Tested successfully on simple text files and NEWS.Debian files.
ru: Успешно протестирован на простых текстовых файлах и файлах NEWS.Debian.

note: type: verbatim
en:  Copyright © 2005-2008 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.
    
     Copyright © 2008-2009, 2018 Jonas Smedegaard <dr@jones.dk>.
     Copyright © 2020 Martin Quinson <mquinson#debian.org>.
ru:  Copyright © 2005-2008 Николя Франсуа (Nicolas FRANÇOIS) <nicolas.francois@centraliens.net>.
     Copyright © 2008-2009, 2018 Йонас Смедегард (Jonas Smedegaard) <dr@jones.dk>.
     Copyright © 2020 Мартин Кенсон (Martin Quinson) <mquinson#debian.org>.

note: type: textblock
en: Locale::Po4a::TransTractor - generic trans(lator ex)tractor.
ru: Locale::Po4a::TransTractor - обобщённый экстрактор переводов (от Trans[lator ex]Tractor).

note: type: textblock
en: This class is the ancestor of every po4a parser used to parse a document, to search translatable strings, to extract them to a PO file and to replace them by their translation in the output document.
ru: Данный класс является предком каждого парсера po4a, используемого для анализа документа, поиска переводимых строк, извлечения их в PO-файл и замены их переводом в итоговом документе.

note: type: textblock
en: More formally, it takes the following arguments as input:
ru: Более формально, он принимает на вход следующие аргументы:

note: type: textblock
en: a document to translate;
ru: документ для перевода;

note: type: textblock
en: a PO file containing the translations to use.
ru: PO-файл, содержащий перевод.

note: type: textblock
en: As output, it produces:
ru: На выходе он производит:

note: type: textblock
en: another PO file, resulting of the extraction of translatable strings from the input document;
ru: другой PO-файл, как результат извлечения переводимых строк из входного документа;

note: type: textblock
en: a translated document, with the same structure than the one in input, but with all translatable strings replaced with the translations found in the PO file provided in input.
ru: переведённый документ с той же структурой, что и входной, но все переводимые строки заменены переводами, найденными во входном PO-файле.

note: type: textblock
en: Here is a graphical representation of this:
ru: Ниже приведено графическое представление этого процесса:

note: type: verbatim
en:    Input document --\                             /---> Output document
                         \                           /       (translated)
                          +-> parse() function -----+
                         /                           \
       Input PO --------/                             \---> Output PO
                                                             (extracted)
ru:    Входной документ --\                             /---> Выходной документ
                          \                           /       (переведённый)
                           +-> функция parse() ------+
                          /                           \
      Входной PO --------/                             \---> Выходной PO
                                                              (извлечённый)

note: type: =head1
en: FUNCTIONS YOUR PARSER SHOULD OVERRIDE
ru: ФУНКЦИИ, КОТОРЫЕ ДОЛЖНЫ БЫТЬ ПЕРЕОПРЕДЕЛЕНЫ В ВАШЕМ ПАРСЕРЕ

note: type: textblock
en: This is where all the work takes place: the parsing of input documents, the generation of output, and the extraction of the translatable strings. This is pretty simple using the provided functions presented in the section B<INTERNAL FUNCTIONS> below. See also the B<SYNOPSIS>, which presents an example.
ru: Именно здесь происходит вся работа: разбор входного документа, генерация выходного документа и извлечение переводимых строк. Это довольно просто сделать, используя предоставленные функции, описанные ниже в разделе B<ВНУТРЕННИЕ ФУНКЦИИ>. См. также пример в разделе B<КРАТКОЕ ОПИСАНИЕ>.

note: type: textblock
en: This function is called by the process() function below, but if you choose to use the new() function, and to add content manually to your document, you will have to call this function yourself.
ru: Эта функция вызывается из функции process() описанной ниже, но если вы решите использовать функцию new() и вручную добавите содержимое в ваш документ, вам придется вызывать эту функцию самостоятельно.

note: type: textblock
en: This function returns the header we should add to the produced document, quoted properly to be a comment in the target language.  See the section B<Educating developers about translations>, from L<po4a(7)|po4a.7>, for what it is good for.
ru: Эта функция возвращает заголовок, который мы должны добавить к созданному документу. Правильно процитированный, он будет комментарием на целевом языке. Для чего это нужно, см. раздел B<Educating developers about translations> в L<po4a(7)|po4a.7>.

note: type: textblock
en: The following example parses a list of paragraphs beginning with "<p>". For the sake of simplicity, we assume that the document is well formatted, i.e. that '<p>' tags are the only tags present, and that this tag is at the very beginning of each paragraph.
ru: В следующем примере анализируется список абзацев, начинающихся с "<p>". Для простоты мы предполагаем, что документ хорошо отформатирован, т.е в нем присутствуют только теги '<p>', и каждый такой тег находится в начале абзаца.

note: type: verbatim
en:  sub parse {
       my $self = shift;
    
       PARAGRAPH: while (1) {
           my ($paragraph,$pararef)=("","");
           my $first=1;
           my ($line,$lref)=$self->shiftline();
           while (defined($line)) {
               if ($line =~ m/<p>/ && !$first--; ) {
                   # Not the first time we see <p>.
                   # Reput the current line in input,
                   #  and put the built paragraph to output
                   $self->unshiftline($line,$lref);
    
                   # Now that the document is formed, translate it:
                   #   - Remove the leading tag
                   $paragraph =~ s/^<p>//s;
    
                   #   - push to output the leading tag (untranslated) and the
                   #     rest of the paragraph (translated)
                   $self->pushline(  "<p>"
                                   . $self->translate($paragraph,$pararef)
                                   );
    
                   next PARAGRAPH;
               } else {
                   # Append to the paragraph
                   $paragraph .= $line;
                   $pararef = $lref unless(length($pararef));
               }
    
               # Reinit the loop
               ($line,$lref)=$self->shiftline();
           }
           # Did not get a defined line? End of input file.
           return;
       }
     }
ru:  sub parse {
       my $self = shift;
    
       PARAGRAPH: while (1) {
           my ($paragraph,$pararef)=("","");
           my $first=1;
           my ($line,$lref)=$self->shiftline();
           while (defined($line)) {
               if ($line =~ m/<p>/ && !$first--; ) {
                   # Это не первый раз, когда мы видим <p>.
                   # вернём текущую строку обратно в поток ввода,
                   #  а прочитанный абзац отправим на вывод
                   $self->unshiftline($line,$lref);
    
                   # Now that the document is formed, translate it:
                   #   - Уберём ведущий тег
                   $paragraph =~ s/^<p>//s;
    
                   #   - Отправим на вывод этот тег (непереведённым)
                   #     и сам абзац (переведённый)
                   $self->pushline(  "<p>"
                                   . $self->translate($paragraph,$pararef)
                                   );
    
                   next PARAGRAPH;
               } else {
                   # Присоединить в конец текущего абзаца
                   $paragraph .= $line;
                   $pararef = $lref unless(length($pararef));
               }
    
               # Переинициализировать цикл
               ($line,$lref)=$self->shiftline();
           }
           # Не получили строку? Значит это конец файла.
           return;
       }
     }

note: type: textblock
en: Once you've implemented the parse function, you can use your document class, using the public interface presented in the next section.
ru: После реализации функции синтаксического анализа, вы можете задействовать ваш класс с помощью публичного интерфейса, представленного в следующем разделе.

note: type: =head1
en: PUBLIC INTERFACE for scripts using your parser
ru: ПУБЛИЧНЫЙ ИНТЕРФЕЙС для скриптов, использующих ваш парсер

note: type: textblock
en: This function can do all you need to do with a po4a document in one invocation. Its arguments must be packed as a hash. ACTIONS:
ru: Эта функция может выполнить все, что вам нужно, с документом po4a за один вызов. Ее аргументы должны быть упакованы в виде хэша. ДЕЙСТВИЯ:

note: type: textblock
en: Reads all the PO files specified in po_in_name
ru: Читает все PO-файлы, указанные в po_in_name

note: type: textblock
en: Reads all original documents specified in file_in_name
ru: Читает все исходные документы, указанные в file_in_name

note: type: textblock
en: Parses the document
ru: Выполняет разбор документа

note: type: textblock
en: Reads and applies all the addenda specified
ru: Читает и применяет все указанные дополнения

note: type: textblock
en: Writes the translated document to file_out_name (if given)
ru: Записывает переведенный документ в file_out_name (если указано)

note: type: textblock
en: Writes the extracted PO file to po_out_name (if given)
ru: Записывает извлеченный PO-файл в po_out_name (если указано)

note: type: textblock
en: ARGUMENTS, beside the ones accepted by new() (with expected type):
ru: АРГУМЕНТЫ, кроме тех, которые принимаются new() (с ожидаемым типом):

note: type: textblock
en: List of filenames where we should read the input document.
ru: Список имен файлов входных документов.

note: type: textblock
en: Charset used in the input document (if it isn't specified, use UTF-8).
ru: Кодировка, используемая во входном документе (если не указано, используется UTF-8).

note: type: textblock
en: Filename where we should write the output document.
ru: Имя файла выходного документа.

note: type: textblock
en: Charset used in the output document (if it isn't specified, use UTF-8).
ru: Кодировка, используемая в выходном документе (если не указано, используется UTF-8).

note: type: textblock
en: List of filenames where we should read the input PO files from, containing the translation which will be used to translate the document.
ru: Список имен входных PO-файлов, которые будут использоваться для перевода документа.

note: type: textblock
en: Filename where we should write the output PO file, containing the strings extracted from the input document.
ru: Имя выходного PO-файла, содержащего строки, извлеченные из входного документа.

note: type: textblock
en: List of filenames where we should read the addenda from.
ru: Список имен файлов аддендумов.

note: type: textblock
en: Charset for the addenda.
ru: Кодировка аддендума.

note: type: textblock
en: Create a new po4a document. Accepted options (in the hash passed as a parameter):
ru: Создать новый po4a-документ. Допустимые параметры (в хэше, передаваемом в качестве параметра):

note: type: textblock
en: Sets the verbosity.
ru: Устанавливает уровень детализации.

note: type: textblock
en: Sets the debugging.
ru: Устанавливает режим отладки.

note: type: textblock
en: The column at which we should wrap text in output document (default: 76).
ru: Количество символов в строке, после которых текст в выходном документе переносится на новую строку (значение по умолчанию: 76).

note: type: textblock
en: The negative value means not to wrap lines at all.
ru: Отрицательное значение означает, что строки вообще не переносятся.

note: type: textblock
en: Also it accepts next options for underlying Po-files: B<porefs>, B<copyright-holder>, B<msgid-bugs-address>, B<package-name>, B<package-version>, B<wrap-po>.
ru: Также для базовых PO-файлов принимаются следующие аргументы: B<porefs>, B<copyright-holder>, B<msgid-bugs-address>, B<package-name>, B<package-version>, B<wrap-po>.

note: type: =head2
en: Manipulating document files
ru: Манипулирование файлами документов

note: type: textblock
en: Add another input document data at the end of the existing array C<< @{$self->{TT}{doc_in}} >>.
ru: Добавить содержимое другого входного документа в конец существующего массива C<< @{$self->{TT}{doc_in}} >>.

note: type: verbatim
en: This function takes two mandatory arguments and an optional one.
     * The filename to read on disk;
     * The name to use as filename when building the reference in the PO file;
     * The charset to use to read that file (UTF-8 by default)
ru: Эта функция принимает два обязательных аргумента и один необязательный.
    * Имя файла, считываемого с диска;
    * Имя используемое в качестве имени файла при создании ссылки в PO-файле;
    * Кодировка, используемая при чтении файла (по умолчанию UTF-8)

note: type: verbatim
en: This array C<< @{$self->{TT}{doc_in}} >> holds this input document data as an
    array of strings with alternating meanings.
     * The string C<$textline> holding each line of the input text data.
     * The string C<< $filename:$linenum >> holding its location and called as
       "reference" (C<linenum> starts with 1).
ru: Массив C<< @{$self->{TT}{doc_in}} >> содержит данные входного документа в виде
    массива строк с чередующимися значениями.
     * Строка C<$textline> содержит каждую строку входных текстовых данных.
     * Строка C<< $filename:$linenum >> содержит ее местоположение и называется
       "ссылкой" (C<linenum> начинается с 1).

note: type: textblock
en: Please note that it does not parse anything. You should use the parse()  function when you're done with packing input files into the document.
ru: Обратите внимание, что эта функция ничего не анализирует. Вам следует использовать функцию parse(), когда вы закончите упаковывать входные файлы в документ.

note: type: textblock
en: Write the translated document to the given filename.
ru: Записывает переведенный документ в указанное имя файла.

note: type: verbatim
en: This translated document data are provided by:
     * C<< $self->docheader() >> holding the header text for the plugin, and
     * C<< @{$self->{TT}{doc_out}} >> holding each line of the main translated text in the array.
ru: Эти переведенные данные предоставляются с помощью:
     * C<< $self->docheader() >> содержит текст заголовка для плагина, и
     * C<< @{$self->{TT}{doc_out}} >> содержит в массиве каждую строку главного переведенного текста.

note: type: =head2
en: Manipulating PO files
ru: Манипулирование PO-файлами

note: type: textblock
en: Add the content of a file (which name is passed as argument) to the existing input PO. The old content is not discarded.
ru: Добавляет содержимое файла (имя которого передано в качестве аргумента) в существующий входной PO-файл. Старое содержимое не удаляется.

note: type: textblock
en: Write the extracted PO file to the given filename.
ru: Записывает извлеченный PO-файл в файл в указанным именем.

note: type: textblock
en: Returns some statistics about the translation done so far. Please note that it's not the same statistics than the one printed by msgfmt --statistic. Here, it's stats about recent usage of the PO file, while msgfmt reports the status of the file. It is a wrapper to the Locale::Po4a::Po::stats_get function applied to the input PO file. Example of use:
ru: Возвращает некоторую статистику о выполненном на данный момент переводе. Обратите внимание, что это не та статистика, которая выводится командой msgfmt --statistic.Здесь приведена статистика о недавнем использовании файла PO, в то время как msgfmt сообщает о состоянии файла. Это обертка для функции Locale::Po4a::Po::stats_get, применяемой к входному PO-файлу. Пример использования:

note: type: verbatim
en:     [normal use of the po4a document...]
    
        ($percent,$hit,$queries) = $document->stats();
        print "We found translations for $percent\%  ($hit from $queries) of strings.\n";
ru:     ($percent,$hit,$queries) = $document->stats();
        print "We found translations for $percent\%  ($hit from $queries) of strings.\n";

note: type: =head2
en: Manipulating addenda
ru: Манипулирование аддендумами

note: type: textblock
en: Please refer to L<po4a(7)|po4a.7> for more information on what addenda are, and how translators should write them. To apply an addendum to the translated document, simply pass its filename to this function and you are done ;)
ru: Пожалуйста, обратитесь к L<po4a(7)|po4a.7> для получения более подробной информации о том, что такое аддендумы и как переводчикам следует их писать. Чтобы применить аддендум к переведенному документу, просто передайте его имя в эту функцию, и все готово ;)

note: type: textblock
en: This function returns a non-null integer on error.
ru: В случае ошибки эта функция возвращает числовое значение, отличное от нуля.

note: type: =head2
en: Getting input, providing output
ru: Получение входных данных, предоставление выходных данных

note: type: textblock
en: Four functions are provided to get input and return output. They are very similar to shift/unshift and push/pop of Perl.
ru: Для получения входных данных и возврата выходных данных предусмотрены четыре функции. Они очень похожи на shift/unshift и push/pop в Perl.

note: type: verbatim
en:  * Perl shift returns the first array item and drop it from the array.
     * Perl unshift prepends an item to the array as the first array item.
     * Perl pop returns the last array item and drop it from the array.
     * Perl push appends an item to the array as the last array item.
ru:  * Оператор shift в Perl удаляет из массива первый элемент и возвращает его значение.
     * Оператор unshift в Perl добавляет элемент в начало массива.
     * Оператор pop в Perl удаляет из массива последний элемент и возвращает его значение.
     * Оператор push в Perl добавляет элемент в конец массива.

note: type: textblock
en: The first pair is about input, while the second is about output. Mnemonic: in input, you are interested in the first line, what shift gives, and in output you want to add your result at the end, like push does.
ru: Первая пара относится к вводу, а вторая -- к выводу. Мнемоника: при вводе вас интересует первая строка -- то, что дает shift, а при выводе вы хотите добавить ваш результат в конец, как это делает push.

note: type: textblock
en: This function returns the first line to be parsed and its corresponding reference (packed as an array) from the array C<< @{$self->{TT}{doc_in}} >> and drop these first 2 array items.  Here, the reference is provided by a string C<< $filename:$linenum >>.
ru: Эта функция возвращает первую строку для анализа и соответствующую ссылку (упакованную в виде массива) из массива C<< @{$self->{TT}{doc_in}} >> и удаляет эти первые 2 элемента массива. Здесь ссылка представлена строкой C<< $filename:$linenum >>.

note: type: textblock
en: Unshifts the last shifted line of the input document and its corresponding reference back to the head of C<< {$self->{TT}{doc_in}} >>.
ru: Отменяет последнее действие shiftline(). Строка и соотвествующая ссылка помещаются обратно в начало массива C<< {$self->{TT}{doc_in}} >>.

note: type: textblock
en: Push a new line to the end of C<< {$self->{TT}{doc_out}} >>.
ru: Помещает новую строку в конец массива C<< {$self->{TT}{doc_out}} >>.

note: type: textblock
en: Pop the last pushed line from the end of C<< {$self->{TT}{doc_out}} >>.
ru: Удаляет из массива C<< {$self->{TT}{doc_out}} >> последний элемент и возвращает его значение.

note: type: =head2
en: Marking strings as translatable
ru: Пометка строк как переводимых

note: type: textblock
en: One function is provided to handle the text which should be translated.
ru: Предусмотрена одна функция для обработки текста, который должен быть переведен.

note: type: textblock
en: Mandatory arguments:
ru: Обязательные агрументы:

note: type: textblock
en: A string to translate
ru: Строка для перевода

note: type: textblock
en: The reference of this string (i.e. position in inputfile)
ru: Ссылка на эту строку (т.е. её позиция во входном файле)

note: type: textblock
en: The type of this string (i.e. the textual description of its structural role; used in Locale::Po4a::Po::gettextization(); see also L<po4a(7)|po4a.7>, section B<Gettextization: how does it work?>)
ru: Тип строки (т.е. текстовое описание её структурной роли; используется в Locale::Po4a::Po::gettextization(); см. также L<po4a(7)|po4a.7>, раздел B<Как это работает?>)

note: type: textblock
en: This function can also take some extra arguments. They must be organized as a hash. For example:
ru: Эта функция также может принимать некоторые дополнительные аргументы. Они должны быть организованы в виде хэша. Например:

note: type: textblock
en: boolean indicating whether we can consider that whitespaces in string are not important. If yes, the function canonizes the string before looking for a translation or extracting it, and wraps the translation.
ru: логическое значение, указывающее, можем ли мы считать, что пробелы в строке не важны. Если да, функция канонизирует строку перед поиском перевода или его извлечением и добавляет переносы строк в результат по необходимости (вызывая B<wrap()>).

note: type: textblock
en: the column at which we should wrap (default: the value of B<wrapcol> specified during creation of the TransTractor or 76).
ru: количество символов в строке, после которых должен выполняться автоматический перенос текста на новую строку (по умолчанию: значение B<wrapcol>, указанное при создании TransTractor или 76).

note: type: textblock
en: The negative value will be substracted from the default.
ru: Отрицательное значение будет вычитаться из значения по умолчанию.

note: type: textblock
en: an extra comment to add to the entry.
ru: дополнительный комментарий для добавления к записи.

note: type: textblock
en: Actions:
ru: Действия:

note: type: textblock
en: Pushes the string, reference and type to po_out.
ru: Отправляет строку, ссылку и тип в po_out.

note: type: textblock
en: Returns the translation of the string (as found in po_in) so that the parser can build the doc_out.
ru: Возвращает перевод строки (найденный в po_in), чтобы парсер мог создать doc_out.

note: type: textblock
en: Handles the charsets to recode the strings before sending them to po_out and before returning the translations.
ru: Обрабатывает кодировки для перекодирования строк перед отправкой их в po_out и перед возвратом переводов.

note: type: =head2
en: Misc functions
ru: Прочие функции

note: type: textblock
en: Returns if the verbose option was passed during the creation of the TransTractor.
ru: Возвращает значение 1, если параметр verbose был передан во время создания TransTractor.

note: type: textblock
en: Returns if the debug option was passed during the creation of the TransTractor.
ru: Возвращает значение 1, если параметр debug был передан во время создания TransTractor.

note: type: textblock
en: This function return the charset that was provided as master charset
ru: Эта функция возвращает кодировку, которая была предоставлена в качестве основной

note: type: textblock
en: This function will return the charset that should be used in the output document (usually useful to substitute the input document's detected charset where it has been found).
ru: Эта функция вернет кодировку, которая должна использоваться в выходном документе (обычно это полезно для замены обнаруженной кодировки входного документа там, где она была найдена).

note: type: textblock
en: It will use the output charset specified in the command line. If it wasn't specified, it will use the input PO's charset, and if the input PO has the default "CHARSET", it will return the input document's charset, so that no encoding is performed.
ru: Эта функция будет использовать выходную кодировку, указанную в командной строке. Если кодировка не была указана, будет использоваться кодировка, указанная во входном PO-файле, если же во входном PO-файле кодировка имеет значение "CHARSET", функция вернет кодировку входного документа, в этом случае перекодирование выполнено не будет.

note: type: =head1
en: FUTURE DIRECTIONS
ru: ПЛАНЫ НА БУДУЩЕЕ

note: type: textblock
en: One shortcoming of the current TransTractor is that it can't handle translated document containing all languages, like debconf templates, or .desktop files.
ru: Одним из недостатков текущего TransTractor является то, что он не может обрабатывать переведенные документы, содержащие все языки, такие как шаблоны debconf или файлы .desktop.

note: type: textblock
en: To address this problem, the only interface changes needed are:
ru: Для решения этой проблемы необходимы только следующие изменения интерфейса:

note: type: textblock
en: take a hash as po_in_name (a list per language)
ru: взять хэш в виде po_in_name (список для каждого языка)

note: type: textblock
en: add an argument to translate to indicate the target language
ru: добавить аргумент перевода для указания целевого языка

note: type: textblock
en: make a pushline_all function, which would make pushline of its content for all languages, using a map-like syntax:
ru: создать функцию pushline_all, которая производила бы pushline из своего содержимого для всех языков, используя map-подобный синтаксис:

note: type: textblock
en: Will see if it's enough ;)
ru: Посмотрим, достаточно ли этого ;)

note: type: verbatim
en:  Denis Barbier <barbier@linuxfr.org>
     Martin Quinson (mquinson#debian.org)
     Jordi Vilalta <jvprat@gmail.com>
ru:  Денис Барбье (Denis Barbier) <barbier@linuxfr.org>
     Мартин Кенсон (Martin Quinson) (mquinson#debian.org)
     Жорди Вилальта (Jordi Vilalta) <jvprat@gmail.com>

note: type: textblock
en: Locale::Po4a::VimHelp - convert Vim help files from/to PO files.
ru: Locale::Po4a::VimHelp: преобразование файлов справки Vim из/в PO-файлы.

note: type: textblock
en: C<Locale::Po4a::VimHelp> is a module to help the translation of Vim help file.  See also L<Writing help files|https://vimhelp.org/helphelp.txt.html#help-writing> for its syntax.
ru: C<Locale::Po4a::VimHelp> — это модуль, предназначенным для помощи в переводе файлов справки Vim. См. также описание его синтаксиса в L<Writing help files|https://vimhelp.org/helphelp.txt.html#help-writing>.

note: type: textblock
en: which might be translated to
ru: которое может быть переведён как

note: type: textblock
en: Locale::Po4a::Wml - convert WML (web markup language) documents from/to PO files
ru: Locale::Po4a::Wml: преобразование документов Wml (web markup language, язык разметки web) в/из PO-файлы

note: type: textblock
en: Locale::Po4a::Wml is a module to help the translation of WML documents into other [human] languages. Do not mixup the WML we are speaking about here (web markup language) and the WAP crap used on cell phones.
ru: Locale::Po4a::Wml — это модуль, предназначенный для помощи в переводе документации в формате WML на другие [человеческие] языки. Не путайте WML (web markup language), о котором здесь говорится с WAP-хламом, который используется на мобильных телефонах.

note: type: textblock
en: Please note that this module relies upon the Locale::Po4a::Xhtml module, which also relies upon the Locale::Po4a::Xml module.  This means that all tags for web page expressions are assumed to be written in the XHTML syntax.
ru: Пожалуйста замете, что этот модуль полагается на Locale::Po4a::Xhtml, который в свою очередь полагается на Locale::Po4a::Xml. Это значит, что все теги для отображения веб-страницы должны быть записаны согласно синтаксису XHTML.

note: type: textblock
en: This module works for some simple documents, but is still young.  Currently, the biggest issue of the module is probably that it cannot handle documents that contain non-XML inline tags such as <email "foo@example.org">, which are often defined in the WML.  Improvements will be added in the future releases.
ru: Этот модуль работает для некоторых простых документов, однако он всё ещё сырой. На данный момент самая большая проблема модуля в том, что он не может работать с документами содержащими встроенные теги не соответствующие XML, как например <email "foo@example.org">, которые часто встречаются в WML. Улучшения ожидаются в будущих версиях.

note: type: verbatim
en:  Martin Quinson (mquinson#debian.org)
     Noriada Kobayashi <nori1@dolphin.c.u-tokyo.ac.jp>
ru:  Мартин Кенсон (Martin Quinson) (mquinson#debian.org)
     Норитада Кобаяси (Noriada Kobayashi) <nori1@dolphin.c.u-tokyo.ac.jp>

note: type: textblock
en: Locale::Po4a::Xhtml - convert XHTML documents from/to PO files
ru: Locale::Po4a::Xhtml: преобразование документов XHTML в/из PO-файлы

note: type: textblock
en: Locale::Po4a::Xhtml is a module to help the translation of XHTML documents into other [human] languages.
ru: Locale::Po4a::Xhtml — это модуль, предназначенный для помощи в переводе документации в формате XHTML на другие [человеческие] языки.

note: type: =item
en: B<includessi>[B<=>I<rootpath>]
ru: B<includessi>[B<=>I<базовый_путь>]

note: type: textblock
en: Include files specified by an include SSI (Server Side Includes) element (e.g. <!--#include virtual="/foo/bar.html" -->).
ru: Включать файлы указанные в качестве SSI (Server Side Includes, Включения на Стороне Сервера) элемента (например <!--#include virtual="/foo/bar.html" -->).

note: type: textblock
en: B<Note:> You should use it only for static files.
ru: B<Замечание:> используйте это только для статических файлов.

note: type: textblock
en: An additional I<rootpath> parameter can be specified. It specifies the root path to find files included by a B<virtual> attribute.
ru: Может быть указан дополнительный аргумент I<базовый_путь>, который задаёт путь, относительно которого будут искаться файлы указанные атрибутом B<virtual>.

note: type: textblock
en: "It works for me", which means I use it successfully on my personal Web site.  However, YMMV: please let me know if something doesn't work for you.
ru: «У меня всё работает», что значит, что я использую его на моём личном веб сайте. Однако у вас могут быть другие результаты. Пожалуйста, сообщите мне, если что-то не работает.

note: type: verbatim
en:  Yves Rütschlé <po4a@rutschle.net>
     Nicolas François <nicolas.francois@centraliens.net>
ru:  Ив Рючле (Yves Rütschlé) <po4a@rutschle.net>
     Николя Франсуа (Nicolas François) <nicolas.francois@centraliens.net>

note: type: verbatim
en:  Copyright © 2004 Yves Rütschlé <po4a@rutschle.net>
     Copyright © 2007-2008 Nicolas François <nicolas.francois@centraliens.net>
ru:  Copyright © 2004 Ив Рючле (Yves Rütschlé) <po4a@rutschle.net>
     Copyright © 2007-2008 Николя Франсуа (Nicolas François) <nicolas.francois@centraliens.net>

note: type: textblock
en: Locale::Po4a::Xml - convert XML documents and derivates from/to PO files
ru: Locale::Po4a::Xml: преобразование документов XML и производных форматов в/из PO-файлы

note: type: textblock
en: Locale::Po4a::Xml is a module to help the translation of XML documents into other [human] languages. It can also be used as a base to build modules for XML-based documents.
ru: Locale::Po4a::Xml — это модуль, предназначенный для помощи в переводе документации в формате XML на другие [человеческие] языки. Его также можно использовать в качестве базы для создания других модулей для документов других форматов, основанных на XML.

note: type: =head1
en: TRANSLATING WITH PO4A::XML
ru: ПЕРЕВОД С ПОМОЩЬЮ PO4A::XML

note: type: textblock
en: This module can be used directly to handle generic XML documents.  This will extract all tag's content, and no attributes, since it's where the text is written in most XML based documents.
ru: Этот модуль может непосредственно обрабатывать документы XML общего вида. Он будет извлекать содержимое всех тегов, но не атрибутов т.к. именно в них содержится текст в большинстве документов основанных на XML.

note: type: textblock
en: There are some options (described in the next section) that can customize this behavior.  If this doesn't fit to your document format you're encouraged to write your own module derived from this, to describe your format's details.  See the section B<WRITING DERIVATE MODULES> below, for the process description.
ru: Есть нескоько параметров (описанных в следующей секции), которые могут изменить поведение. Если для вашего формата документации этого недостаточно, то мы рекомендуем вам написать свой собственный модуль производный от данного, дабы лучше описать детали своего формата. Как это сделать, см. в секции B<НАПИСАНИЕ ПРОИЗВОДНЫХ МОДУЛЕЙ> ниже.

note: type: textblock
en: The global debug option causes this module to show the excluded strings, in order to see if it skips something important.
ru: Глобальный параметр `debug` делает так, что данный модуль будет показывать отброшенные строки, чтобы дать возможность пользователю посмотреть, не пропустил ли он что-то важное.

note: type: textblock
en: Prevents it to strip the spaces around the extracted strings.
ru: Не обрезать начальные и конечные пробелы в извлекаемых строках.

note: type: textblock
en: Canonicalizes the string to translate, considering that whitespaces are not important, and wraps the translated document. This option can be overridden by custom tag options. See the B<translated> option below.
ru: Приводить переводимые строки к каноническому виду (учитывая, что пробелы не важны) и расставляет переносы строк в документе. Действие этого параметра можно отменить специфическими параметрами для тегов. Смотрите описание параметра B<translated> ниже.

note: type: textblock
en: Attributes are wrapped by default. This option disables wrapping.
ru: По умолчанию в атрибуты могут добавляться переносы строк. Этот параметр отключает оное поведение.

note: type: textblock
en: It makes the tags and attributes searching to work in a case insensitive way.  If it's defined, it will treat E<lt>BooKE<gt>laNG and E<lt>BOOKE<gt>Lang as E<lt>bookE<gt>lang.
ru: Этот параметр делает поиск тегов и атрибутов нечувствительным к регистру. Если он задан, то и «E<lt>BooKE<gt>laNG», и «E<lt>BOOKE<gt>Lang» будут сопоставлены «E<lt>bookE<gt>lang».

note: type: textblock
en: Escape quotes in output strings.  Necessary, for example, for creating string resources for use by Android build tools.
ru: Экранировать кавычки в выходных строках. Необходимо, например, для создания строковых ресурсов, используемых инструментами сборки для Android.

note: type: textblock
en: See also: https://developer.android.com/guide/topics/resources/string-resource.html
ru: Смотрите также: https://developer.android.com/guide/topics/resources/string-resource.html

note: type: textblock
en: When defined, external entities are included in the generated (translated)  document, and for the extraction of strings.  If it's not defined, you will have to translate external entities separately as independent documents.
ru: Когда этот параметр задан, из внешних сущностей (entities) будут извлечены строки для перевода, и они, сущности, будут включены в сгенерированный (переведённый) документ. В противном случае, вам придётся переводить внешние сущности отдельно как независимые документы.

note: type: textblock
en: This option defines the behavior of the module when it encounters invalid XML syntax (a closing tag which does not match the last opening tag).  It can take the following values:
ru: Данный параметр определяет поведение модуля, когда он встречается с недопустимым XML синтаксисом (Например, закрывающий тег, не соответствующий последнему открывающему тегу). Он может принимать следующие значения:

note: type: textblock
en: This is the default value.  The module will exit with an error.
ru: Это значение по умолчанию. Модуль будет завершать работу с ошибкой.

note: type: textblock
en: The module will continue, and will issue a warning.
ru: Модуль выдаст предупреждение и продолжит работу.

note: type: textblock
en: The module will continue without any warnings.
ru: Модуль продолжит работу без каких-либо предупреждений.

note: type: textblock
en: Be careful when using this option.  It is generally recommended to fix the input file.
ru: Используйте данный параметр с осторожностью. Вообще говоря, рекомендуется исправить исходный файл.

note: type: textblock
en: Note: This option is deprecated.
ru: Замечание: Использование этого параметра нежелательно (deprecated).

note: type: textblock
en: Extracts only the specified tags in the B<tags> option.  Otherwise, it will extract all the tags except the ones specified.
ru: Извлекать только теги указанные в параметре B<tags>. Иначе, будут извлекаться все теги кроме заданных.

note: type: textblock
en: String that will try to match with the first line of the document's doctype (if defined). If it doesn't, a warning will indicate that the document might be of a bad type.
ru: Строка, которая будет сопоставляться с первой строкой doctype документа (если задан). Если они не совпадают, то будет выведено предупреждение, что документ может быть неправильного типа.

note: type: textblock
en: String indicating the path (e.g. E<lt>bbbE<gt>E<lt>aaaE<gt>) of a tag where a lang="..." attribute shall be added. The language will be defined as the basename of the PO file without any .po extension.
ru: Строка, задающая путь (например, E<lt>bbbE<gt>E<lt>aaaE<gt>) к тегу, в который следует добавить атрибут lang="E<lt>языкE<gt>", где E<lt>языкE<gt> — это имя PO-файла без расширения «.po».

note: type: textblock
en: Boolean indicating whether closing tags are optional (as in HTML). By default, missing closing tags raise an error handled according to B<ontagerror>.
ru: Логическое значение, указывающее, являются ли закрывающие теги опциональными (как в HTML). По умолчанию пропущенный закрывающий тег вызывает ошибку, обрабатываемую в соответствии с B<ontagerror>.

note: type: textblock
en: Note: This option is deprecated.  You should use the B<translated> and B<untranslated> options instead.
ru: Замечание: Использование этого параметра нежелательно (deprecated). Вместо него вам следует использовать параметры B<translated> и B<untranslated>.

note: type: textblock
en: Space-separated list of tags you want to translate or skip.  By default, the specified tags will be excluded, but if you use the "tagsonly" option, the specified tags will be the only ones included.  The tags must be in the form E<lt>aaaE<gt>, but you can join some (E<lt>bbbE<gt>E<lt>aaaE<gt>) to say that the content of the tag E<lt>aaaE<gt> will only be translated when it's into a E<lt>bbbE<gt> tag.
ru: Список тегов, разделённых пробелами, которые вы хотите переводить или, наоборот, исключить из перевода. По умолчанию указанные теги будут исключены, но если вы укажите также параметр «tagsonly», то будут включены только указанные теги. Теги должны быть заданы в формате E<lt>aaaE<gt>. Вы также можете объединить несколько тегов подряд (E<lt>bbbE<gt>E<lt>aaaE<gt>), чтобы указать, что содержимое тега E<lt>aaaE<gt> будет переводимым только если он находится внутри тега E<lt>bbbE<gt>.

note: type: textblock
en: You can also specify some tag options by putting some characters in front of the tag hierarchy. For example, you can put I<w> (wrap) or I<W> (don't wrap)  to override the default behavior specified by the global B<wrap> option.
ru: Вы также можете указать некоторые специфические параметры тегов, добавив некоторые символы перед иерархией тегов. Например, можно добавить I<w> (переносить строки, wrap) или I<W> (не переносить строки), чтобы переопределить поведение по умолчанию, заданное глобальным параметром B<wrap>.

note: type: textblock
en: Example: WE<lt>chapterE<gt>E<lt>titleE<gt>
ru: Пример: WE<lt>chapterE<gt>E<lt>titleE<gt>

note: type: textblock
en: Space-separated list of tag's attributes you want to translate.  You can specify the attributes by their name (for example, "lang"), but you can prefix it with a tag hierarchy, to specify that this attribute will only be translated when it's in the specified tag. For example: E<lt>bbbE<gt>E<lt>aaaE<gt>lang specifies that the lang attribute will only be translated if it's in an E<lt>aaaE<gt> tag, and it's in a E<lt>bbbE<gt> tag.
ru: Список атрибутов тегов, разделённых пробелами, которые вы хотите переводить. Вы можете задавать атрибуты просто по их имени (например, «lang»), но вы также можете предварять их иерархией тегов, чтобы указать, что они должны быть переводимыми только когда они относятся к конкретным тегам. Например: E<lt>bbbE<gt>E<lt>aaaE<gt>lang указывает, что «lang» будет переводиться только если он находится внутри тега E<lt>aaaE<gt>, который в свою очередь находится внутри тега E<lt>bbbE<gt>.

note: type: textblock
en: Do not translate attributes in inline tags.  Instead, replace all attributes of a tag by po4a-id=<id>.
ru: Не переводить атрибуты во встроенных (inline) тегах. Вместо этого заменять все атрибуты тегов на po4a-id=<id>.

note: type: textblock
en: This is useful when attributes shall not be translated, as this simplifies the strings for translators, and avoids typos.
ru: Это полезно, когда атрибуты не должны переводиться, так как это упрощает строки, что проще для переводчиков, и позволяет избегать опечаток.

note: type: textblock
en: Space-separated list of tags which should not be treated as tags.  These tags are treated as inline, and do not need to be closed.
ru: Список тегов, разделённых пробелами, которые не должны обрабатываться как теги. Эти теги обрабатываются как встроенные (inline), и не требуют того, чтобы они обязательно были закрытыми.

note: type: textblock
en: Space-separated list of tags which should break the sequence.  By default, all tags break the sequence.
ru: Список тегов, разделённых пробелами, которые должны обрывать переводимые строку. По умолчанию все теги являются таковыми.

note: type: textblock
en: The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag (<aaa>) should only be considered when it's within another tag (<bbb>).
ru: Теги должны быть заданы в виде <aaa>, но их также можно объединять (<bbb><aaa>) в случае, если тег <aaa> должен учитываться только если он находится внутри тега <bbb>.

note: type: textblock
en: Please note a tag should be listed in only one of the B<break>, B<inline> B<placeholder>, or B<customtag> setting string.
ru: Учтите, что любой конкретный тег может быть задан только в одном из списков: B<break>, B<inline>, B<placeholder> или B<customtag>.

note: type: textblock
en: Space-separated list of tags which should be treated as inline.  By default, all tags break the sequence.
ru: Список тегов, разделённых пробелами, которые должны обрабатываться как встроенные (inline). По умолчанию все теги обрывают переводимую строку (не являются встроенными).

note: type: textblock
en: Space-separated list of tags which should be treated as placeholders.  Placeholders do not break the sequence, but the content of placeholders is translated separately.
ru: Список тегов, разделённых пробелами, которые должны обрабатываться как местозаполнители (placeholder). Метки-заполнители не обрывают переводимую строку, но их содержимое переводится отдельно.

note: type: textblock
en: The location of the placeholder in its block will be marked with a string similar to:
ru: Местоположение местозаполнителей в их блоке будет помечены строкой на подобии следующей:

note: type: textblock
en: By default, Processing Instructions (i.e., C<E<lt>? ... ?E<gt>> tags) are handled as inline tags.  Pass this option if you want the PI to be handled as breaking tag.  Note that unprocessed PHP tags are handled as Processing Instructions by the parser.
ru: По умолчанию, инструкция обработки (processing instruction, PI, т.е теги вида C<E<lt>? ... ?E<gt>>) рассматриваются как встроенные теги. Добавьте данный параметр, если вы хотите обрабатывать их как разделяющие. Заметьте, что необработанные теги PHP также рассматриваются парсером, как инструкции обработки.

note: type: textblock
en: Space separated list of tags that the module should not try to set by default in any category.
ru: Список тегов, разделённых пробелами, которые по умолчанию не будут отнесены к какой-либо категории данным модулем.

note: type: textblock
en: If you have a tag which has its default setting by the subclass of this module but you want to set alternative setting, you need to list that tag as a part of the B<nodefault> setting string.
ru: Если в вашем документе есть теги, у которых есть какие-либо настройки по умолчанию, установленные модулями созданными на основе данного, то это поведение можно изменить, указав их в B<nodefault>.

note: type: textblock
en: Support C preprocessor directives.  When this option is set, po4a will consider preprocessor directives as paragraph separators.  This is important if the XML file must be preprocessed because otherwise the directives may be inserted in the middle of lines if po4a consider it belong to the current paragraph, and they won't be recognized by the preprocessor.  Note: the preprocessor directives must only appear between tags (they must not break a tag).
ru: Поддержка директив препроцессора Си. Когда этот параметр установлен, po4a будет считать директивы препроцессора разделителями абзацев. Это важно, когда XML-файл должен быть обработан препроцессором, ибо в противном случае директивы могут быть вставлены в середину переводимых строк, если po4a решит, что они принадлежат текущему параграфу, так что они могут быть не распознаны при последующей обработке. Замечание: директивы должны располагаться между тегами (они не могут разбивать тег).

note: type: textblock
en: Space-separated list of tags you want to translate.
ru: Список тегов, разделённых пробелами, которые должны быть переведены.

note: type: textblock
en: You can also specify some tag options by putting some characters in front of the tag hierarchy.  This overrides the default behavior specified by the global B<wrap> and B<defaulttranslateoption> option.
ru: Вы также можете задавать некоторые специальные опции для тегов, добавив символ перед данным иерархическим списком. Это переопределяет поведение, заданное глобальными параметрами B<wrap> и B<defaulttranslateoption>.

note: type: textblock
en: Tags should be translated and content can be re-wrapped.
ru: Теги будут переводиться и переносы строк будут расставляться автоматически.

note: type: textblock
en: Tags should be translated and content should not be re-wrapped.
ru: Теги будут переводиться и переносы строк не будут изменяться.

note: type: textblock
en: Tags should be translated inline.
ru: Теги будут переводиться как встроенные (inline).

note: type: textblock
en: Tags should be translated as placeholders.
ru: Теги будут переводиться как местозаполнители (placeholders).

note: type: textblock
en: Internally, the XML parser only cares about these four options: I<w> I<W> I<i> I<p>.
ru: Внутри себя парсер XML использует только эти четыре опции: I<w> I<W> I<i> I<p>.

note: type: textblock
en: * Tags listed in B<break> are set to I<w> or I<W> depending on the B<wrap> option.
ru: * Тегам, перечисленные в B<break>, задаётся опция I<w> или I<W>, в зависимости от параметра B<wrap>.

note: type: textblock
en: * Tags listed in B<inline> are set to I<i>.
ru: * Тегам, перечисленные в B<inline>, задаётся опция I<i>.

note: type: textblock
en: * Tags listed in B<placeholder> are set to I<p>.
ru: * Тегам, перечисленные в B<placeholder>, задаётся опция I<p>.

note: type: textblock
en: * Tags listed in B<untranslated> are without any of these options set.
ru: * Тегам, перечисленные в B<untranslated>, не задаётся ни одна из этих опций.

note: type: textblock
en: You can verify actual internal parameter behavior by invoking B<po4a> with B<--debug> option.
ru: Вы можете просмотреть, какие именно используются внутренние параметры поведения, запустив B<po4a> с параметром B<--debug>.

note: type: textblock
en: Please note a tag should be listed in either B<translated> or B<untranslated> setting string.
ru: Учтите, что тег может присутствовать только в одном из списков: или в B<translated>, или в B<untranslated>.

note: type: textblock
en: Space-separated list of tags you do not want to translate.
ru: Список тегов, разделённых пробелами, которые не должны быть переведены.

note: type: textblock
en: Please note a translatable inline tag in an untranslated tag is treated as a translatable breaking tag, I<i> setting is dropped and I<w> or I<W> is set depending on the B<wrap> option.
ru: Учтите, что переводимый встроенный (inline) тег, расположенный внутри непереводимого тега интерпретируется, как переводимый и разделяющий (breaking) тег. Опция I<i> убирается и будет установлена I<w> или I<W> в зависимости от параметра B<wrap>.

note: type: textblock
en: The default categories for tags that are not in any of the translated, untranslated, break, inline, or placeholder.
ru: Категория по умолчанию для тегов, которые не относятся ни к одной другой категории: переводимых, непереводимых, разделяющих, встроенных или местозаполнителей.

note: type: textblock
en: This is a set of letters as defined in B<translated> and this setting is only valid for translatable tags.
ru: Это набор символов, определённых в B<translated>, и эти настройки действительны только для переводимых тегов.

note: type: =head1
en: WRITING DERIVATIVE MODULES
ru: СОЗДАНИЕ ПРОИЗВОДНЫХ МОДУЛЕЙ

note: type: =head2
en: DEFINE WHAT TAGS AND ATTRIBUTES TO TRANSLATE
ru: ОПРЕДЕЛЕНИЕ, КАКИЕ ТЕГИ И АТТРИБУТЫ НУЖНО ПЕРЕВОДИТЬ

note: type: textblock
en: The simplest customization is to define which tags and attributes you want the parser to translate.  This should be done in the initialize function.  First you should call the main initialize, to get the command-line options, and then, append your custom definitions to the options hash.  If you want to treat some new options from command line, you should define them before calling the main initialize:
ru: Самое простое, что вы можете изменить — это задать парсеру, какие теги и атрибуты вы хотите переводить. Это должно быть сделано в функции инициализации. Во-первых, вы должны вызвать основную функцию инициализации, чтобы получить параметры командной строки, а затем добавить свои специализированные определения в хеш параметров. Если вы хотите обрабатывать свои параметры командной строки, то необходимо определить их до вызова основной функции инициализации:

note: type: textblock
en: You should use the B<_default_inline>, B<_default_break>, B<_default_placeholder>, B<_default_translated>, B<_default_untranslated>, and B<_default_attributes> options in derivative modules. This allow users to override the default behavior defined in your module with command line options.
ru: В производных модулях вам стоит использовать параметры B<_default_inline>, B<_default_break>, B<_default_placeholder>, B<_default_translated>, B<_default_untranslated>, и B<_default_attributes>. Это позволит пользователю переопределить поведение по умолчанию, заданное вашем модулем из командной строки.

note: type: textblock
en: If you don't like the default behavior of this xml module and its derivative modules, you can provide command line options to change their behavior.
ru: Если вас не устраивает поведение xml-модуля или его производных по умолчанию, то вы можете задать параметры командной строки, которые его изменят.

note: type: textblock
en: See L<Locale::Po4a::Docbook(3pm)|Locale::Po4a::Docbook>,
ru: См. L<Locale::Po4a::Docbook(3pm)|Locale::Po4a::Docbook>,

note: type: =head2
en: OVERRIDING THE found_string FUNCTION
ru: ПЕРЕОПРЕДЕЛЕНИЕ ФУНКЦИИ found_string

note: type: textblock
en: Another simple step is to override the function "found_string", which receives the extracted strings from the parser, in order to translate them.  There you can control which strings you want to translate, and perform transformations to them before or after the translation itself.
ru: Другой простой шаг, который вы можете предпринять — это переопределить функцию «found_string», которая получает от парсера извлечённые строки, которые нужно перевести. Здесь вы можете контролировать, какие строки вы хотите переводить и преобразовать их произвольным образом до или после перевода.

note: type: textblock
en: It receives the extracted text, the reference on where it was, and a hash that contains extra information to control what strings to translate, how to translate them and to generate the comment.
ru: Она принимает извлечённый текст, местоположение, откуда он был извлечён и хеш с дополнительной информацией, которая позволит контролировать, какие строки следует переводить, как их переводить и какой комментарий следует добавить для переводчика.

note: type: textblock
en: The content of these options depends on the kind of string it is (specified in an entry of this hash):
ru: Содержимое этих параметров зависит от того, что именно это за строка (указано в вышеупомянутом хеше):

note: type: textblock
en: The found string is the content of a translatable tag. The entry "tag_options" contains the option characters in front of the tag hierarchy in the module "tags" option.
ru: Найденная строка является содержимым переводимого тега. По ключу «tag_options» в хеше будет указан символ опции, заданный перед иерархией тегов в параметре «tags».

note: type: textblock
en: Means that the found string is the value of a translatable attribute. The entry "attribute" has the name of the attribute.
ru: Найденная строка является значением переводимого атрибута. Имя атрибута будет доступно в хеше по ключу «attribute».

note: type: textblock
en: It must return the text that will replace the original in the translated document. Here's a basic example of this function:
ru: Она должна возвращать текст перевода, который заменит исходную строку (значение функции «translate()» из Locale::Po4a::TransTractor, прим. переводчика). Базовый пример подобной функции:

note: type: textblock
en: There's another simple example in the new Dia module, which only filters some strings.
ru: Другой простой пример можно посмотреть в модуле перевода диаграмм Dia, который только фильтрует некоторые строки.

note: type: =head2
en: MODIFYING TAG TYPES (TODO)
ru: ИЗМЕНЕНИЕ ТИПОВ ТЕГОВ (TODO)

note: type: textblock
en: This is a more complex one, but it enables a (almost) total customization.  It's based on a list of hashes, each one defining a tag type's behavior. The list should be sorted so that the most general tags are after the most concrete ones (sorted first by the beginning and then by the end keys). To define a tag type you'll have to make a hash with the following keys:
ru: Хотя этот подход и сложнее, зато он позволяет обрабатывать документ (практически) как угодно. В основе оного лежит список хешей каждый из которых определяет поведение «типа тега». Список должен быть отсортирован так, чтобы самые общие теги следовали после самых конкретных (сначала отсортированы по началу ключей (B<begining>), а затем по завершению (B<end>)). Для того чтобы определить тип тега, нужно создать хеш со следующими ключами:

note: type: textblock
en: Specifies the beginning of the tag, after the "E<lt>".
ru: Задаёт начало тега, то что следует после символа «E<lt>».

note: type: textblock
en: Specifies the end of the tag, before the "E<gt>".
ru: Задаёт окончание тега, то что следует перед символом «E<gt>».

note: type: textblock
en: It says if this is a breaking tag class.  A non-breaking (inline) tag is one that can be taken as part of the content of another tag.  It can take the values false (0), true (1) or undefined.  If you leave this undefined, you'll have to define the f_breaking function that will say whether a concrete tag of this class is a breaking tag or not.
ru: Задаёт, является ли данный класс тегов прерывающим. Не прерывающие (встроенные, inline) теги — это теги, которые могут являться частью или содержимым других тегов. Значениями данного ключа могут быть false (0), true (1) или он может быть не определён (undefined). В последнем случае вы должны будете определить функцию f_breaking, которая будет выдавать, является ли конкретный тег прерывающим или нет.

note: type: textblock
en: It's a function that will tell if the next tag is a breaking one or not.  It should be defined if the B<breaking> option is not.
ru: Это функция, которая должна возвращать, является ли следующие тег прерывающим или нет. Она должна быть определена, когда B<breaking> не определено..

note: type: textblock
en: If you leave this key undefined, the generic extraction function will have to extract the tag itself.  It's useful for tags that can have other tags or special structures in them, so that the main parser doesn't get mad.  This function receives a boolean that says if the tag should be removed from the input stream or not.
ru: Если вы не определите этот ключ, то для экстракции самого тега будет использована базовая функция. Это полезно для тегов, которые могут иметь внутри себя другие теги или специальные структуры так, чтобы основной парсер на это не ругался. Эта функция принимает логическое значение, которое говорит, должен ли тег быть удалён из входного потока или нет.

note: type: textblock
en: This function receives the tag (in the get_string_until() format) and returns the translated tag (translated attributes or all needed transformations) as a single string.
ru: Эта функция принимает текущий тег (в формате get_string_until()) и возвращает переведённый тег (включая переведённые атрибуты и все необходимые преобразования исходного тега) в виде одной строки.

note: type: =head2
en: WORKING WITH TAGS
ru: РАБОТА С ТЕГАМИ

note: type: textblock
en: This function returns the path to the current tag from the document's root, in the form E<lt>htmlE<gt>E<lt>bodyE<gt>E<lt>pE<gt>.
ru: Эта функция возвращает путь от корня документа до текущего тега в формате E<lt>htmlE<gt>E<lt>bodyE<gt>E<lt>pE<gt>.

note: type: textblock
en: An additional array of tags (without brackets) can be passed as argument.  These path elements are added to the end of the current path.
ru: Дополнительный массив тегов (без угловых скобок) может быть передан в качестве необязательного аргумента. Эти теги будут добавлены в конец текущего пути.

note: type: textblock
en: This function returns the index from the tag_types list that fits to the next tag in the input stream, or -1 if it's at the end of the input file.
ru: Эта функция возвращает порядковый номер типа тега в списке tag_types, который соответствует следующему тегу во входном потоке или -1 при достижении конца входного файла.

note: type: textblock
en: Here, the tag has structure started by E<lt> and end by E<gt> and it can contain multiple lines.
ru: В данном случае структура тега начинается с E<lt> и заканчивается E<gt> и может содержать несколько строк.

note: type: textblock
en: This works on the array C<< @{$self->{TT}{doc_in}} >> holding input document data and reference indirectly via C<< $self->shiftline() >> and C<< $self->unshiftline($$) >>.
ru: Это делается через обработку массива C<< @{$self->{TT}{doc_in}} >>, содержащего исходные данные документа, посредством получения неявных ссылок на него через C<< $self->shiftline() >> и C<< $self->unshiftline($$) >>.

note: type: textblock
en: This function returns the next tag from the input stream without the beginning and end, in an array form, to maintain the references from the input file.  It has two parameters: the type of the tag (as returned by tag_type) and a boolean, that indicates if it should be removed from the input stream.
ru: Эта функция возвращает следующий тег из потока ввода без начальной и конечной строки (beginning и end) в виде массива, дабы сохранить их местоположение в исходном файле. Она принимает два параметра: тип тега (как в tag_type) и булево значение, которое указывает, удалять ли этот тег из потока ввода.

note: type: textblock
en: This function returns the name of the tag passed as an argument, in the array form returned by extract_tag.
ru: Эта функция возвращает имя тега переданного в качестве аргумента в виде такого же массива, как и в extract_tag.

note: type: textblock
en: This function returns a boolean that says if the next tag in the input stream is a breaking tag or not (inline tag).  It leaves the input stream intact.
ru: Эта функция возвращает булево значение, которое указывает, является ли следующий тег в потоке ввода разделяющим (breaking) или нет (встроенным, inline). Она не изменяет поток ввода.

note: type: textblock
en: This function translates the next tag from the input stream.  Using each tag type's custom translation functions.
ru: Эта функция переводит следующий тег из потока ввода. Она использует специфические для каждого типа тега функции перевода (см. f_translate).

note: type: textblock
en: This function returns a string value that says if the first argument (a tag hierarchy) matches any of the tags from the second argument (a list of tags or tag hierarchies). If it doesn't match, it returns 0. Else, it returns the matched tag's options (the characters in front of the tag) or 1 (if that tag doesn't have options).
ru: Эта функция возвращает строковое значение, которое указывает, сопоставляется ли её первый аргумент (иерархия тегов) какому-либо тегу из её второго аргумента (список тегов или иерархий тегов). Если не сопоставляются, то она возвращает 0. Иначе она возвращает опции сопоставленного тега (символ указанный перед этим тегом или иерархией, см. параметр «tags» ) или 1 (если у тега нет опции).

note: type: =head2
en: WORKING WITH ATTRIBUTES
ru: РАБОТА С АТТРИБУТАМИ

note: type: textblock
en: This function handles the translation of the tags' attributes. It receives the tag without the beginning / end marks, and then it finds the attributes, and it translates the translatable ones (specified by the module option B<attributes>).  This returns a plain string with the translated tag.
ru: Эта функция обеспечивает перевод атрибутов тегов. Она принимает тег без меток начала/конца (beginning/end), а затем она находит атрибуты, переводит те из них, что помечены как переводимые (указанные в параметре модуля B<attributes>). Она возвращает простую строку с переведённым тегом.

note: type: =head2
en: WORKING WITH TAGGED CONTENTS
ru: РАБОТА С СОДЕРЖИМЫМ ТЕГОВ

note: type: textblock
en: This function gets the text until the next breaking tag (not inline) from the input stream.  Translate it using each tag type's custom translation functions.
ru: Эта функция возвращает текст до следующего разделяющего тега (не встроенного) из потока ввода. Переводите его с помощью специфической функции перевода для конкретного типа тега.

note: type: =head2
en: WORKING WITH THE MODULE OPTIONS
ru: РАБОТА С ПАРАМЕТРАМИ МОДУЛЯ

note: type: textblock
en: This function fills the internal structures that contain the tags, attributes and inline data with the options of the module (specified in the command-line or in the initialize function).
ru: Эта функция заполняет внутренние структуры с информацией о тегах, атрибутах и встроенных данных на основе параметров модуля (переданных в командной строке или в функцию инициализации).

note: type: =head2
en: GETTING TEXT FROM THE INPUT DOCUMENT
ru: ПОЛУЧЕНИЕ ТЕКСТА ИЗ ИСХОДНОГО ДОКУМЕНТА

note: type: textblock
en: This function returns an array with the lines (and references) from the input document until it finds the first argument.  The second argument is an options hash. Value 0 means disabled (the default) and 1, enabled.
ru: Эта функция возвращает строки исходного документа (и их расположение), расположенные до первого вхождения, строки или регулярного выражения, переданного в первом аргументе. Второй аргумент является хешем дополнительных параметров для функции, для которых значение 0 означает, что она отключена, а значение 1 — включена.

note: type: textblock
en: The valid options are:
ru: Допустимы следующие дополнительные параметры:

note: type: textblock
en: This makes the returned array to contain the searched text
ru: Искомый текст будет включён в возвращаемый массив

note: type: textblock
en: This removes the returned stream from the input
ru: Найденный текст будет удалён из потока ввода

note: type: textblock
en: This ensures that the searched text is outside any quotes
ru: Дополнительно удостоверится, что искомый текст не включён в какие-либо кавычки

note: type: textblock
en: This denotes that the first argument is a regular expression rather than an plain string
ru: Обозначает, что первый аргумент является регулярным выражением, а не простой строкой

note: type: textblock
en: This function receives as argument the reference to a paragraph (in the format returned by get_string_until), skips his heading spaces and returns them as a simple string.
ru: Эта функция принимает ссылку на абзац (в формате возвращённом get_string_until), пропускает начальные пробелы и возвращает их (пробелы) в виде строки.

note: type: textblock
en: This function returns a simple string with the text from the argument array (discarding the references).
ru: Эта функция возвращает простую строку с текстом, составленным из массива строк и местоположений оных в исходном файле, отбрасывая последние.

note: type: textblock
en: This module can translate tags and attributes.
ru: Этот модуль может переводить теги и атрибуты.

note: type: textblock
en: DOCTYPE (ENTITIES)
ru: DOCTYPE (СУЩНОСТИ)

note: type: textblock
en: There is a minimal support for the translation of entities. They are translated as a whole, and tags are not taken into account. Multilines entities are not supported and entities are always rewrapped during the translation.
ru: Перевод сущностей (entities) на данный момент поддерживается на минимальном уровне. Они переводятся как единое целое, а теги не принимаются во внимание. Многострочные сущности не поддерживаются и во время перевода все переносы строк расставляются заново.

note: type: textblock
en: MODIFY TAG TYPES FROM INHERITED MODULES (move the tag_types structure inside the $self hash?)
ru: ИЗМЕНЯЙТЕ ТИПЫ ТЕГОВ В ПРОИЗВОДНЫХ МОДУЛЯХ (переместите структуру tag_types непосредственно в хеш $self?)

note: type: verbatim
en:  Jordi Vilalta <jvprat@gmail.com>
     Nicolas François <nicolas.francois@centraliens.net>
ru:  Жорди Вилальта (Jordi Vilalta) <jvprat@gmail.com>
     Николя Франсуа (Nicolas François) <nicolas.francois@centraliens.net>

note: type: verbatim
en:  Copyright © 2004 Jordi Vilalta  <jvprat@gmail.com>
     Copyright © 2008-2009 Nicolas François <nicolas.francois@centraliens.net>
ru:  Copyright © 2004 Жорди Вилальта (Jordi Vilalta)  <jvprat@gmail.com>
     Copyright © 2008-2009 Николя Франсуа (Nicolas François) <nicolas.francois@centraliens.net>

note: type: textblock
en: Locale::Po4a::Yaml - convert YAML files from/to PO files
ru: Locale::Po4a::Yaml: преобразование YAML-файлов из/в PO-файлы

note: type: textblock
en: Locale::Po4a::Yaml is a module to help the translation of Yaml files into other [human] languages.
ru: Locale::Po4a::Yaml — это модуль, предназначенным для помощи в переводе файлов Yaml на другие [человеческие] языки.

note: type: textblock
en: The module extracts the value of YAML hashes and arrays. Hash keys are not extracted.
ru: Этот модуль извлекает для перевода значение хешей и массивов YAML. Сами имена ключей хешей не извлекаются.

note: type: textblock
en: NOTE: This module parses the YAML file with YAML::Tiny.
ru: ЗАМЕЧАНИЕ: этот модуль парсит файлы YAML с помощью YAML::Tiny.

note: type: textblock
en: Space-separated list of hash keys to process for extraction, all other keys are skipped.  Keys are matched with a case-sensitive match.  If B<paths> and B<keys> are used together, values are included if they are matched by at least one of the options.  Arrays values are always returned unless the B<skip_array> option is provided.
ru: Список (разделяемый запятыми) ключей хешей, разделённых запятыми, которые нужно переводить. Все остальные ключи переводиться не будут. Ключи чувствительны к регистру. Если одновременно заданы и B<keys>, и B<paths>, то значения ключей будут переводиться, если они перечислены хотя бы в одном из этих параметров. Значения массивов всегда переводятся (если не задан параметр B<skip_array>).

note: type: textblock
en: Comma-separated list of hash paths to process for extraction, all other paths are skipped. Paths are matched with a case-sensitive match.  If B<paths> and B<keys> are used together, values are included if they are matched by at least one of the options.  Arrays values are always returned unless the B<skip_array> option is provided.
ru: Список (разделяемый запятыми) «путей» из ключей хешей, которые нужно переводить. Все остальные пути переводиться не будут. Пути чувствительны к регистру. Если одновременно заданы и B<keys>, и B<paths>, то значения ключей будут переводиться, если они перечислены хотя бы в одном из этих параметров. Значения массивов всегда переводятся (если не задан параметр B<skip_array>).

note: type: textblock
en: Do not translate array values.
ru: Не переводить значения массивов.

note: type: verbatim
en:  Brian Exelbierd <bex@pobox.com>
ru:  Брайан Экселбьерд (Brian Exelbierd) <bex@pobox.com>

note: type: verbatim
en:  Copyright © 2017 Brian Exelbierd.
     Copyright © 2022 Martin Quinson <mquinson#debian.org>.
ru:  Copyright © 2017 Брайан Экселбьерд (Brian Exelbierd).
    Copyright © 2022 Мартин Кенсон (Martin Quinson) <mquinson#debian.org>.
