НАЗВАНИЕ¶

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

ОПИСАНИЕ¶

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

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

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

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

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

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

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

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

nostrip

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

wrap

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

unwrap_attributes

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

caseinsensitive

Этот параметр делает поиск тегов и атрибутов нечувствительным к регистру. Если он задан, то и «<BooK>laNG», и «<BOOK>Lang» будут сопоставлены «<book>lang».

escapequotes

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

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

includeexternal

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

ontagerror

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

tagsonly

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

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

doctype

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

addlang

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

optionalclosingtag

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

tags

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

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

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

Пример: W<chapter><title>

attributes

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

foldattributes

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

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

customtag

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

break

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

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

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

inline

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

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

placeholder

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

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

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

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

break-pi

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

nodefault

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

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

cpp

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

translated

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

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

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

  * Тегам заданным в B<break> устанавливается опция I<w> или I<W> в зависимости от параметра <wrap>.
  * Тегам заданным в B<inline> устанавливается опция I<i>.
  * Тегам заданным в B<placeholder> устанавливается опция I<p>.
  * Теги заданные в B<untranslated> ведут себя так, как если бы ни одна из оных опций не была задана.

untranslated

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

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

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

defaulttranslateoption

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

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

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

  $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;

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

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

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

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

Список TODO¶

DOCTYPE (СУЩНОСТИ)

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

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

СМОТРИТЕ ТАКЖЕ¶

Locale::Po4a::TransTractor(3pm), po4a(7)

АВТОРЫ¶

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

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

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

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