
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 НАЗВАНИЕ

Locale::Po4a::Xml: преобразование документов XML и производных форматов в/из
PO-файлы

=head1 ОПИСАНИЕ

Целью проекта po4a (PO for anything, PO везде и для всего) является
облегчение процесса перевода (и что более важно — поддержки перевода),
используя инструменты gettext в тех случаях, когда их применение может
выглядеть неожиданным, например для документации.

Locale::Po4a::Xml — это модуль, предназначенный для помощи в переводе
документации в формате XML на другие [человеческие] языки. Его также можно
использовать в качестве базы для создания других модулей для документов
других форматов, основанных на XML.

=head1 ПЕРЕВОД С ПОМОЩЬЮ PO4A::XML

Этот модуль может непосредственно обрабатывать документы XML общего вида. Он
будет извлекать содержимое всех тегов, но не атрибутов т.к. именно в них
содержится текст в большинстве документов основанных на XML.

Есть нескоько параметров (описанных в следующей секции), которые могут
изменить поведение. Если для вашего формата документации этого недостаточно,
то мы рекомендуем вам написать свой собственный модуль производный от
данного, дабы лучше описать детали своего формата. Как это сделать, см. в
секции B<НАПИСАНИЕ ПРОИЗВОДНЫХ МОДУЛЕЙ> ниже.

=head1 ПАРАМЕТРЫ ПРИНИМАЕМЫЕ ЭТИМ МОДУЛЕМ

Глобальный параметр `debug` делает так, что данный модуль будет показывать
отброшенные строки, чтобы дать возможность пользователю посмотреть, не
пропустил ли он что-то важное.

Ниже приведены специфические для данного модуля параметры:

=over 4

=item B<nostrip>

Не обрезать начальные и конечные пробелы в извлекаемых строках.

=item B<wrap>

Приводить переводимые строки к каноническому виду (учитывая, что пробелы не
важны) и расставляет переносы строк в документе. Действие этого параметра
можно отменить специфическими параметрами для тегов. Смотрите описание
параметра B<translated> ниже.

=item B<unwrap_attributes>

По умолчанию в атрибуты могут добавляться переносы строк. Этот параметр
отключает оное поведение.

=item B<caseinsensitive>

Этот параметр делает поиск тегов и атрибутов нечувствительным к
регистру. Если он задан, то и «E<lt>BooKE<gt>laNG», и «E<lt>BOOKE<gt>Lang»
будут сопоставлены «E<lt>bookE<gt>lang».

=item B<escapequotes>

Экранировать кавычки в выходных строках. Необходимо, например, для создания
строковых ресурсов, используемых инструментами сборки для Android.

Смотрите также:
https://developer.android.com/guide/topics/resources/string-resource.html

=item B<includeexternal>

Когда этот параметр задан, из внешних сущностей (entities) будут извлечены
строки для перевода, и они, сущности, будут включены в сгенерированный
(переведённый) документ. В противном случае, вам придётся переводить внешние
сущности отдельно как независимые документы.

=item B<ontagerror>

Данный параметр определяет поведение модуля, когда он встречается с
недопустимым XML синтаксисом (Например, закрывающий тег, не соответствующий
последнему открывающему тегу). Он может принимать следующие значения:

=over

=item I<fail>

Это значение по умолчанию. Модуль будет завершать работу с ошибкой.

=item I<warn>

Модуль выдаст предупреждение и продолжит работу.

=item I<silent>

Модуль продолжит работу без каких-либо предупреждений.

=back

Используйте данный параметр с осторожностью. Вообще говоря, рекомендуется
исправить исходный файл.

=item B<tagsonly>

Замечание: Использование этого параметра нежелательно (deprecated).

Извлекать только теги указанные в параметре B<tags>. Иначе, будут
извлекаться все теги кроме заданных.

=item B<doctype>

Строка, которая будет сопоставляться с первой строкой doctype документа
(если задан). Если они не совпадают, то будет выведено предупреждение, что
документ может быть неправильного типа.

=item B<addlang>

Строка, задающая путь (например, E<lt>bbbE<gt>E<lt>aaaE<gt>) к тегу, в
который следует добавить атрибут lang="E<lt>языкE<gt>", где E<lt>языкE<gt> —
это имя PO-файла без расширения «.po».

=item B<optionalclosingtag>

Логическое значение, указывающее, являются ли закрывающие теги опциональными
(как в HTML). По умолчанию пропущенный закрывающий тег вызывает ошибку,
обрабатываемую в соответствии с B<ontagerror>.

=item B<tags>

Замечание: Использование этого параметра нежелательно (deprecated). Вместо
него вам следует использовать параметры B<translated> и B<untranslated>.

Список тегов, разделённых пробелами, которые вы хотите переводить или,
наоборот, исключить из перевода. По умолчанию указанные теги будут
исключены, но если вы укажите также параметр «tagsonly», то будут включены
только указанные теги. Теги должны быть заданы в формате E<lt>aaaE<gt>. Вы
также можете объединить несколько тегов подряд (E<lt>bbbE<gt>E<lt>aaaE<gt>),
чтобы указать, что содержимое тега E<lt>aaaE<gt> будет переводимым только
если он находится внутри тега E<lt>bbbE<gt>.

Вы также можете указать некоторые специфические параметры тегов, добавив
некоторые символы перед иерархией тегов. Например, можно добавить I<w>
(переносить строки, wrap) или I<W> (не переносить строки), чтобы
переопределить поведение по умолчанию, заданное глобальным параметром
B<wrap>.

Пример: WE<lt>chapterE<gt>E<lt>titleE<gt>

=item B<attributes>

Список атрибутов тегов, разделённых пробелами, которые вы хотите
переводить. Вы можете задавать атрибуты просто по их имени (например,
«lang»), но вы также можете предварять их иерархией тегов, чтобы указать,
что они должны быть переводимыми только когда они относятся к конкретным
тегам. Например: E<lt>bbbE<gt>E<lt>aaaE<gt>lang указывает, что «lang» будет
переводиться только если он находится внутри тега E<lt>aaaE<gt>, который в
свою очередь находится внутри тега E<lt>bbbE<gt>.

=item B<foldattributes>

Не переводить атрибуты во встроенных (inline) тегах. Вместо этого заменять
все атрибуты тегов на po4a-id=<id>.

Это полезно, когда атрибуты не должны переводиться, так как это упрощает
строки, что проще для переводчиков, и позволяет избегать опечаток.

=item B<customtag>

Список тегов, разделённых пробелами, которые не должны обрабатываться как
теги. Эти теги обрабатываются как встроенные (inline), и не требуют того,
чтобы они обязательно были закрытыми.

=item B<break>

Список тегов, разделённых пробелами, которые должны обрывать переводимые
строку. По умолчанию все теги являются таковыми.

Теги должны быть заданы в виде <aaa>, но их также можно объединять
(<bbb><aaa>) в случае, если тег <aaa> должен учитываться только если он
находится внутри тега <bbb>.

Учтите, что любой конкретный тег может быть задан только в одном из списков:
B<break>, B<inline>, B<placeholder> или B<customtag>.

=item B<inline>

Список тегов, разделённых пробелами, которые должны обрабатываться как
встроенные (inline). По умолчанию все теги обрывают переводимую строку (не
являются встроенными).

Теги должны быть заданы в виде <aaa>, но их также можно объединять
(<bbb><aaa>) в случае, если тег <aaa> должен учитываться только если он
находится внутри тега <bbb>.

=item B<placeholder>

Список тегов, разделённых пробелами, которые должны обрабатываться как
местозаполнители (placeholder). Метки-заполнители не обрывают переводимую
строку, но их содержимое переводится отдельно.

Местоположение местозаполнителей в их блоке будет помечены строкой на
подобии следующей:

  <placeholder type=\"footnote\" id=\"0\"/>

Теги должны быть заданы в виде <aaa>, но их также можно объединять
(<bbb><aaa>) в случае, если тег <aaa> должен учитываться только если он
находится внутри тега <bbb>.

=item B<break-pi>

По умолчанию, инструкция обработки (processing instruction, PI, т.е теги
вида C<E<lt>? ... ?E<gt>>) рассматриваются как встроенные теги. Добавьте
данный параметр, если вы хотите обрабатывать их как разделяющие. Заметьте,
что необработанные теги PHP также рассматриваются парсером, как инструкции
обработки.

=item B<nodefault>

Список тегов, разделённых пробелами, которые по умолчанию не будут отнесены
к какой-либо категории данным модулем.

Если в вашем документе есть теги, у которых есть какие-либо настройки по
умолчанию, установленные модулями созданными на основе данного, то это
поведение можно изменить, указав их в B<nodefault>.

=item B<cpp>

Поддержка директив препроцессора Си. Когда этот параметр установлен, po4a
будет считать директивы препроцессора разделителями абзацев. Это важно,
когда XML-файл должен быть обработан препроцессором, ибо в противном случае
директивы могут быть вставлены в середину переводимых строк, если po4a
решит, что они принадлежат текущему параграфу, так что они могут быть не
распознаны при последующей обработке. Замечание: директивы должны
располагаться между тегами (они не могут разбивать тег).

=item B<translated>

Список тегов, разделённых пробелами, которые должны быть переведены.

Теги должны быть заданы в виде <aaa>, но их также можно объединять
(<bbb><aaa>) в случае, если тег <aaa> должен учитываться только если он
находится внутри тега <bbb>.

Вы также можете задавать некоторые специальные опции для тегов, добавив
символ перед данным иерархическим списком. Это переопределяет поведение,
заданное глобальными параметрами B<wrap> и B<defaulttranslateoption>.

=over

=item I<w>

Теги будут переводиться и переносы строк будут расставляться автоматически.

=item I<W>

Теги будут переводиться и переносы строк не будут изменяться.

=item I<i>

Теги будут переводиться как встроенные (inline).

=item I<p>

Теги будут переводиться как местозаполнители (placeholders).

=back

Внутри себя парсер XML использует только эти четыре опции: I<w> I<W> I<i>
I<p>.

* Тегам, перечисленные в B<break>, задаётся опция I<w> или I<W>, в
зависимости от параметра B<wrap>.

* Тегам, перечисленные в B<inline>, задаётся опция I<i>.

* Тегам, перечисленные в B<placeholder>, задаётся опция I<p>.

* Тегам, перечисленные в B<untranslated>, не задаётся ни одна из этих опций.

Вы можете просмотреть, какие именно используются внутренние параметры
поведения, запустив B<po4a> с параметром B<--debug>.

Пример: WE<lt>chapterE<gt>E<lt>titleE<gt>

Учтите, что тег может присутствовать только в одном из списков: или в
B<translated>, или в B<untranslated>.

=item B<untranslated>

Список тегов, разделённых пробелами, которые не должны быть переведены.

Теги должны быть заданы в виде <aaa>, но их также можно объединять
(<bbb><aaa>) в случае, если тег <aaa> должен учитываться только если он
находится внутри тега <bbb>.

Учтите, что переводимый встроенный (inline) тег, расположенный внутри
непереводимого тега интерпретируется, как переводимый и разделяющий
(breaking) тег. Опция I<i> убирается и будет установлена I<w> или I<W> в
зависимости от параметра B<wrap>.

=item B<defaulttranslateoption>

Категория по умолчанию для тегов, которые не относятся ни к одной другой
категории: переводимых, непереводимых, разделяющих, встроенных или
местозаполнителей.

Это набор символов, определённых в B<translated>, и эти настройки
действительны только для переводимых тегов.

=back

=head1 СОЗДАНИЕ ПРОИЗВОДНЫХ МОДУЛЕЙ

=head2 ОПРЕДЕЛЕНИЕ, КАКИЕ ТЕГИ И АТТРИБУТЫ НУЖНО ПЕРЕВОДИТЬ

Самое простое, что вы можете изменить — это задать парсеру, какие теги и
атрибуты вы хотите переводить. Это должно быть сделано в функции
инициализации. Во-первых, вы должны вызвать основную функцию инициализации,
чтобы получить параметры командной строки, а затем добавить свои
специализированные определения в хеш параметров. Если вы хотите обрабатывать
свои параметры командной строки, то необходимо определить их до вызова
основной функции инициализации:

  $self->{options}{'new_option'}='';
  $self->SUPER::initialize(%options);
  $self->{options}{'_default_translated'}.=' <p> <head><title>';
  $self->{options}{'attributes'}.=' <p>lang id';
  $self->{options}{'_default_inline'}.=' <br>';
  $self->treat_options;

В производных модулях вам стоит использовать параметры B<_default_inline>,
B<_default_break>, B<_default_placeholder>, B<_default_translated>,
B<_default_untranslated>, и B<_default_attributes>. Это позволит
пользователю переопределить поведение по умолчанию, заданное вашем модулем
из командной строки.

=head2 ПЕРЕОПРЕДЕЛЕНИЕ ПОВЕДЕНИЯ ПО УМОЛЧАНИЮ ПАРАМЕТРАМИ КОМАНДНОЙ СТРОКИ

Если вас не устраивает поведение xml-модуля или его производных по
умолчанию, то вы можете задать параметры командной строки, которые его
изменят.

См. L<Locale::Po4a::Docbook(3pm)|Locale::Po4a::Docbook>,

=head2 ПЕРЕОПРЕДЕЛЕНИЕ ФУНКЦИИ found_string

Другой простой шаг, который вы можете предпринять — это переопределить
функцию «found_string», которая получает от парсера извлечённые строки,
которые нужно перевести. Здесь вы можете контролировать, какие строки вы
хотите переводить и преобразовать их произвольным образом до или после
перевода.

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

Содержимое этих параметров зависит от того, что именно это за строка
(указано в вышеупомянутом хеше):

=over

=item type="tag"

Найденная строка является содержимым переводимого тега. По ключу
«tag_options» в хеше будет указан символ опции, заданный перед иерархией
тегов в параметре «tags».

=item type="attribute"

Найденная строка является значением переводимого атрибута. Имя атрибута
будет доступно в хеше по ключу «attribute».

=back

Она должна возвращать текст перевода, который заменит исходную строку
(значение функции «translate()» из Locale::Po4a::TransTractor,
прим. переводчика). Базовый пример подобной функции:

  sub found_string {
    my ($self,$text,$ref,$options)=@_;
    $text = $self->translate($text,$ref,"type ".$options->{'type'},
      'wrap'=>$self->{options}{'wrap'});
    return $text;
  }

Другой простой пример можно посмотреть в модуле перевода диаграмм Dia,
который только фильтрует некоторые строки.

=head2 ИЗМЕНЕНИЕ ТИПОВ ТЕГОВ (TODO)

Хотя этот подход и сложнее, зато он позволяет обрабатывать документ
(практически) как угодно. В основе оного лежит список хешей каждый из
которых определяет поведение «типа тега». Список должен быть отсортирован
так, чтобы самые общие теги следовали после самых конкретных (сначала
отсортированы по началу ключей (B<begining>), а затем по завершению
(B<end>)). Для того чтобы определить тип тега, нужно создать хеш со
следующими ключами:

=over 4

=item B<beginning>

Задаёт начало тега, то что следует после символа «E<lt>».

=item B<end>

Задаёт окончание тега, то что следует перед символом «E<gt>».

=item B<breaking>

Задаёт, является ли данный класс тегов прерывающим. Не прерывающие
(встроенные, inline) теги — это теги, которые могут являться частью или
содержимым других тегов. Значениями данного ключа могут быть false (0), true
(1) или он может быть не определён (undefined). В последнем случае вы должны
будете определить функцию f_breaking, которая будет выдавать, является ли
конкретный тег прерывающим или нет.

=item B<f_breaking>

Это функция, которая должна возвращать, является ли следующие тег
прерывающим или нет. Она должна быть определена, когда B<breaking> не
определено..

=item B<f_extract>

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

=item B<f_translate>

Эта функция принимает текущий тег (в формате get_string_until()) и
возвращает переведённый тег (включая переведённые атрибуты и все необходимые
преобразования исходного тега) в виде одной строки.

=back

=head1 ВНУТРЕННИЕ ФУНКЦИИ, используемые при создании производных парсеров

=head2 РАБОТА С ТЕГАМИ

=over 4

=item get_path()

Эта функция возвращает путь от корня документа до текущего тега в формате
E<lt>htmlE<gt>E<lt>bodyE<gt>E<lt>pE<gt>.

Дополнительный массив тегов (без угловых скобок) может быть передан в
качестве необязательного аргумента. Эти теги будут добавлены в конец
текущего пути.

=item tag_type()

Эта функция возвращает порядковый номер типа тега в списке tag_types,
который соответствует следующему тегу во входном потоке или -1 при
достижении конца входного файла.

В данном случае структура тега начинается с E<lt> и заканчивается E<gt> и
может содержать несколько строк.

Это делается через обработку массива C<< @{$self->{TT}{doc_in}} >>,
содержащего исходные данные документа, посредством получения неявных ссылок
на него через C<< $self->shiftline() >> и C<< $self->unshiftline($$) >>.

=item extract_tag($$)

Эта функция возвращает следующий тег из потока ввода без начальной и
конечной строки (beginning и end) в виде массива, дабы сохранить их
местоположение в исходном файле. Она принимает два параметра: тип тега (как
в tag_type) и булево значение, которое указывает, удалять ли этот тег из
потока ввода.

Это делается через обработку массива C<< @{$self->{TT}{doc_in}} >>,
содержащего исходные данные документа, посредством получения неявных ссылок
на него через C<< $self->shiftline() >> и C<< $self->unshiftline($$) >>.

=item get_tag_name(@)

Эта функция возвращает имя тега переданного в качестве аргумента в виде
такого же массива, как и в extract_tag.

=item breaking_tag()

Эта функция возвращает булево значение, которое указывает, является ли
следующий тег в потоке ввода разделяющим (breaking) или нет (встроенным,
inline). Она не изменяет поток ввода.

=item treat_tag()

Эта функция переводит следующий тег из потока ввода. Она использует
специфические для каждого типа тега функции перевода (см. f_translate).

Это делается через обработку массива C<< @{$self->{TT}{doc_in}} >>,
содержащего исходные данные документа, посредством получения неявных ссылок
на него через C<< $self->shiftline() >> и C<< $self->unshiftline($$) >>.

=item tag_in_list($@)

Эта функция возвращает строковое значение, которое указывает, сопоставляется
ли её первый аргумент (иерархия тегов) какому-либо тегу из её второго
аргумента (список тегов или иерархий тегов). Если не сопоставляются, то она
возвращает 0. Иначе она возвращает опции сопоставленного тега (символ
указанный перед этим тегом или иерархией, см. параметр «tags» ) или 1 (если
у тега нет опции).

=back

=head2 РАБОТА С АТТРИБУТАМИ

=over 4

=item treat_attributes(@)

Эта функция обеспечивает перевод атрибутов тегов. Она принимает тег без
меток начала/конца (beginning/end), а затем она находит атрибуты, переводит
те из них, что помечены как переводимые (указанные в параметре модуля
B<attributes>). Она возвращает простую строку с переведённым тегом.

=back

=head2 РАБОТА С СОДЕРЖИМЫМ ТЕГОВ

=over 4

=item treat_content()

Эта функция возвращает текст до следующего разделяющего тега (не
встроенного) из потока ввода. Переводите его с помощью специфической функции
перевода для конкретного типа тега.

Это делается через обработку массива C<< @{$self->{TT}{doc_in}} >>,
содержащего исходные данные документа, посредством получения неявных ссылок
на него через C<< $self->shiftline() >> и C<< $self->unshiftline($$) >>.

=back

=head2 РАБОТА С ПАРАМЕТРАМИ МОДУЛЯ

=over 4

=item treat_options()

Эта функция заполняет внутренние структуры с информацией о тегах, атрибутах
и встроенных данных на основе параметров модуля (переданных в командной
строке или в функцию инициализации).

=back

=head2 ПОЛУЧЕНИЕ ТЕКСТА ИЗ ИСХОДНОГО ДОКУМЕНТА

=over

=item get_string_until($%)

Эта функция возвращает строки исходного документа (и их расположение),
расположенные до первого вхождения, строки или регулярного выражения,
переданного в первом аргументе. Второй аргумент является хешем
дополнительных параметров для функции, для которых значение 0 означает, что
она отключена, а значение 1 — включена.

Допустимы следующие дополнительные параметры:

=over 4

=item B<include>

Искомый текст будет включён в возвращаемый массив

=item B<remove>

Найденный текст будет удалён из потока ввода

=item B<unquoted>

Дополнительно удостоверится, что искомый текст не включён в какие-либо
кавычки

=item B<regex>

Обозначает, что первый аргумент является регулярным выражением, а не простой
строкой

=back

=item skip_spaces(\@)

Эта функция принимает ссылку на абзац (в формате возвращённом
get_string_until), пропускает начальные пробелы и возвращает их (пробелы) в
виде строки.

=item join_lines(@)

Эта функция возвращает простую строку с текстом, составленным из массива
строк и местоположений оных в исходном файле, отбрасывая последние.

=back

=head1 СОСТОЯНИЕ ЭТОГО МОДУЛЯ

Этот модуль может переводить теги и атрибуты.

=head1 Список TODO

DOCTYPE (СУЩНОСТИ)

Перевод сущностей (entities) на данный момент поддерживается на минимальном
уровне. Они переводятся как единое целое, а теги не принимаются во
внимание. Многострочные сущности не поддерживаются и во время перевода все
переносы строк расставляются заново.

ИЗМЕНЯЙТЕ ТИПЫ ТЕГОВ В ПРОИЗВОДНЫХ МОДУЛЯХ (переместите структуру tag_types
непосредственно в хеш $self?)

=head1 СМОТРИТЕ ТАКЖЕ

L<Locale::Po4a::TransTractor(3pm)|Locale::Po4a::TransTractor>,
L<po4a(7)|po4a.7>

=head1 АВТОРЫ

 Жорди Вилальта (Jordi Vilalta) <jvprat@gmail.com>
 Николя Франсуа (Nicolas François) <nicolas.francois@centraliens.net>

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

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

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