LOCALE::PO4A::XML.3PM

Section: User Contributed Perl Documentation (1)
Updated: 2024-06-17
Index Return to Main Contents

НАЗВА

Locale::Po4a::Xml — перетворення документів XML та похідних документів на файли PO, і навпаки

ОПИС

Метою проєкту po4a (PO для усього) є спрощення перекладу (та, що ще цікавіше, супровід перекладів) за допомогою інструментів gettext у областях, де такий переклад спочатку не передбачався, зокрема у документації.

Locale::Po4a::Xml — модуль, який допомагає у перекладі документів XML іншими мовами (якими розмовляють люди). Модулем можна також скористатися як основою для побудови модулів для заснованих на XML документів.

ПЕРЕКЛАД ЗА ДОПОМОГОЮ PO4A::XML

Цим модулем можна скористатися для роботи із типовими документами XML. Він видобуває увесь вміст теґів, не видобуває атрибути, оскільки текст у більшості документів на основі XML міститься саме у теґах.

Передбачено декілька параметрів (які описано у наступному розділі), за допомогою яких можна налаштувати поведінку модуля. Якщо модуль не відповідає формату вашого документа, вам варто написати власний модуль, який походитиме від цього, і у якому ви опишете параметри формату. Опис процедури написання наведено у розділі НАПИСАННЯ ПОХІДНИХ МОДУЛІВ нижче.

ПАРАМЕТРИ, ЯКІ МОЖНА ПЕРЕДАВАТИ ЦЬОМУ МОДУЛЮ

Загальний параметр діагностики призводить до того, що цей модуль виводить виключені рядки, щоб ви могли бачити, чи не пропускає він чогось важливого.

Ось параметри, які можна передавати цьому модулю:

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

Якщо визначено, замінники для включення зовнішніх файлів включатимуться за вмістом до створеного (перекладеного) документа та видобуватимуться до рядків. Якщо не визначено, вам доведеться перекладати зовнішні файли, вказані за допомогою замінників, окремо як незалежні документи.

ontagerror

Цей параметр визначає поведінку модуля, якщо буде виявлено некоректний синтаксис XML (кінцевий теґ, який не відповідає останньому початковому теґу). Може приймати такі значення:

fail: Це типове значення. Модуль завершує роботу з повідомленням про помилку.
warn: Модуль продовжуватиме роботу, але виведе попередження.
silent: Модуль продовжить роботу без жодних попереджень.

: Будьте обережні із цим параметром. Загалом, рекомендуємо просто виправити файл вхідних даних.

tagsonly

Зауваження: цей параметр вважається застарілим.

Видобувати лише з теґів, вказаних за допомогою параметра tags. Якщо не вказано, видобуватиметься вміст усіх теґів, окрім вказаних як такі, які є непридатними для видобування.

doctype

Рядок, який слід шукати у першому рядку doctype документа (якщо визначено). Якщо такий рядок не буде знайдено, модуль покаже повідомлення про те, що документ може належати до не того типу.

addlang

Рядок, який вказує шлях (наприклад, <bbb><aaa>) до теґу, до якого слід додати атрибут lang="...". Мову буде визначено на основі базової назви файла PO без суфікса .po.

optionalclosingtag

Булеве значення, яке вказує на те, чи є завершальні теґи необов'язковими (як у HTML). Типово, пропущені завершальні теґи призводять до сповіщення про помилку, обробка якого виконується відповідно до ontagerror.

tags

Зауваження: цей параметр вважається застарілим. Замість нього, вам слід користуватися параметрами translated і untranslated.

Список відокремлених пробілами теґів, вміст яких ви хочете перекласти або пропустити. Типово, вміст вказаних теґів буде виключено, але якщо вказано параметр «tagsonly», буде включено лише вміст вказаних теґів. Теґи слід вказувати у форматі <aaa>, але ви можете поєднати деякі теґи (<bbb><aaa>), щоб вказати, наприклад, що вміст теґу <aaa> перекладатиметься, лише якщо його включено до теґу <bbb>.

Ви також можете вказати деякі параметри теґів, додаючи символи перед ієрархією теґів. Наприклад, ви можете додати w (переносити) або W (не переносити), щоб перевизначити типову поведінку, вказано за допомогою загального параметра wrap.

Приклад: W<chapter><title>

attributes

Список відокремлених пробілами атрибутів теґів, які ви хочете перекласти. Ви можете вказати атрибути за назвою (наприклад, «lang»), а можете додати префікс із ієрархії теґів, щоб вказати, що певний атрибути перекладатиметься, лише якщо він перебуває у вказаному тезі. Приклад: запис <bbb><aaa>lang означає, що атрибут lang перекладатиметься, лише якщо він перебуває у тезі <aaa>, який перебуває у тезі <bbb>.

foldattributes

Не перекладати атрибути у вбудованих в абзац теґах. Замість цього, замінити усі атрибути теґу записом po4a-id=<id>.

Корисно, якщо атрибути не слід перекладати, оскільки спрощує роботу перекладача і надає змогу уникнути друкарських помилок.

customtag

Список відокремлених пробілами теґів, які не слід вважати теґами. Ці теґи вважатимуться вбудованими у текст теґами, які не потребують закриття.

break

Список відокремлених пробілами теґів, які розривають послідовність обробки. Типово, усі теґи розривають послідовність обробки.

Теґи слід вказувати у форматі <aaa>, але ви можете об'єднати декілька (<bbb><aaa>), якщо один теґ (<aaa>) слід брати до уваги, лише якщо він перебуває усередині іншого теґу (<bbb>).

Будь ласка, зауважте, що теґ має бути вказано лише у одному зі списків параметрів break, inline placeholder або customtag.

inline

Список відокремлених пробілами теґів, які слід вважати вбудованими до абзацу. Типово, усі теґи розривають послідовність обробки тексту.

placeholder

Список відокремлених пробілами теґів, які слід вважати замінниками. до абзацу Замінники не розривають послідовність обробки тексту, але вміст замінників перекладається окремо.

Розташування замінника у його блоці буде позначено рядком, подібним до такого:

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

break-pi

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

nodefault

Список відокремлених пробілами теґів, які модуль не повинен типово встановлювати у будь-якій категорії.

Якщо у вашому тексті є теґ, для якого передбачено типові параметри обробки у підкласі цього модуля, ви можете змінити параметри. Для цього вам слід вказати теґ як частину рядка параметра nodefault.

cpp

Підтримка директив попередньої обробки C. Якщо встановлено цей параметр, po4a вважатиме директиви попередньої обробки роздільниками абзаців. Це важливо, якщо файл XML має бути попередньо оброблено, оскільки, якщо цього не зробити, директиви може бути вставлено у рядки, якщо po4a вважатиме їх належними до поточного абзацу, а отже, вставлені директиви може бути не розпізнано засобом попередньої обробки. Зауваження: директиви попередньої обробки мають з'являтися лише між теґами (вони не повинні порушувати послідовність теґів).

translated

Список відокремлених пробілами теґів, вміст яких ви хочете перекладати.

Ви також можете вказати деякі параметри теґів, додаючи символи перед ієрархією теґів. Ці параметри перевизначають типову поведінку, вказану за допомогою загальних параметрів wrap і defaulttranslateoption.

w: Теґи слід перекладати, а дані може бути переформатовано.
W: Теґи має бути перекладено, а дані не слід переформатовувати.
i: Теґи має бути перекладено у тексті.
p: Теґи має бути перекладено як замінники.

На внутрішньому рівні обробник XML працює з цими 4 параметрами: w W i p.

* Для теґів зі списку break буде встановлено w або W, залежно від параметра wrap.

* Для теґів зі списку inline буде встановлено i.

* Для теґів зі списку placeholder буде встановлено p.

* Для теґів зі списку untranslated не буде встановлено жодного з цих параметрів.

Ви можете перевірити, як працює обробка параметрів на внутрішньому рівні, за допомогою виклику po4a з параметром --debug.

Приклад: W<chapter><title>

Зауважте, що теґ має бути або у списку параметра translated, або у списку параметра untranslated.

untranslated

Список відокремлених пробілами теґів, вміст яких ви не хочете перекладати.

Будь ласка, зауважте, що придатний до перекладу вбудований теґ у даних теґу, який не перекладається, вважається теґом зміни режиму перекладу, параметр i скидається, і використовується параметр w або W, залежно від значення параметра wrap.

defaulttranslateoption

Типові категорії для теґів, які не належать до категорій translated, untranslated, break, inline або placeholder.

Це набір літер, які визначено у 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;

Вам слід використовувати параметри _default_inline, _default_break, _default_placeholder, _default_translated, _default_untranslated, і _default_attributes у похідних модулях. Це надасть змогу користувачам перевизначати типову поведінку, визначену у вашому модулі, за допомогою параметрів рядка команди.

ПЕРЕВИЗНАЧЕННЯ ТИПОВОЇ ПОВЕДІНКИ ЗА ДОПОМОГОЮ ПАРАМЕТРІВ КОМАНДНОГО РЯДКА

Якщо вам не до вподоби типова поведінка модуля xml та похідних від нього модулів, ви можете змінити її за допомогою параметрів командного рядка.

Див. Locale::Po4a::Docbook(3pm),

ПЕРЕВИЗНАЧЕННЯ ФУНКЦІЇ found_string

Іншим простим кроком є перевизначення функції «found_string», яка отримує видобуті рядки від засобу обробки з метою їх перекладу. Ви можете керувати тим, які рядки слід перекладати, і виконувати їхнє перетворення до чи після самого перекладу.

Функція отримує видобутий текст, посилання на місце у документі, звідки видобуто текст, та хеш, у якому містяться додаткові дані щодо того, які рядки слід перекладати, як їх слід перекладати і як створювати коментар.

Вміст цих параметрів залежить від типу рядка (вказаного у записі цього хешу):

type="tag": Знайдений рядок є вмістом придатного для перекладу теґу. Запис «tag_options» містить додаткові символи перед записом теґу у ієрархії тегів параметра «tags» модуля.
type="attribute": Означає, що знайдений рядок є значенням придатного до перекладу атрибута. Запис «attribute» містить назву атрибута.

Має повертати текст, який замінить оригінал у перекладеному документі. Ось базовий приклад цієї функції:

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

Ще один простий приклад можна знайти у модулі Dia. Там фільтруються лише деякі рядки.

ВНЕСЕННЯ ЗМІН ДО ТИПІВ ТЕҐІВ (ЩЕ НЕ НАПИСАНО)

Це доволі складно, але надасть змогу налаштовувати (майже) усе. Засновано на списку хешів, кожен з яких визначає поведінку для певного типу теґів. Список має бути упорядковано так, щоб найзагальніші теґи стояли у ньому після найконкретніших (упорядковані спочатку за початковими, а потім за кінцевими ключами). Щоб визначити тип теґів, вам доведеться створити хеш із такими ключами:

beginning: Задає початок теґу, після «<».
end: Задає кінець теґу, до «>».
breaking: Повідомляє, чи є клас теґів роздільним. Нероздільним (вбудованим) теґом буде теґ, який можна вважати вмістом іншого теґу. Може приймати значення false (0), true (1) або undefined (не визначено). Якщо ви лишите його невизначеним, вам слід визначити функцію f_breaking, яка повідомлятиме, належить певний теґ цього класу до роздільних чи ні.
f_breaking: Це функція, яка повідомлятиме, є наступний теґ роздільним чи ні. Її слід визначити, якщо параметр breaking не визначено.
f_extract: Якщо ви не визначатимете цей ключ, загальна функція видобування видобуватиме і сам теґ. Це корисно для теґів, які можуть містити інші теґи або спеціальні структури, щоб забезпечити притомну поведінку основного засобу обробки. Ця функція отримує булеве значення, яке повідомляє, слід вилучати теґ із вхідного потоку даних чи ні.
f_translate: Ця функція отримує теґ (у форматі get_string_until()) і повертає перекладений теґ (перекладені атрибути або усі потрібні перетворення) як один рядок.

ВНУТРІШНІ ФУНКЦІЇ, які використовуються для написання похідних обробників

РОБОТА З ТЕҐАМИ

get_path()

Ця функція повертає шлях до поточного теґу від кореневого теґу документа у формі <html><body><p>.

Можна передати як аргумент додатковий масив теґів (без дужок). Ці елементи шляху буде додано наприкінці поточного шляху.

tag_type()

Ця функція повертає індекс у списку tag_types, який відповідає наступному теґу у потоці вхідних даних, або -1, якщо це кінець файла вхідних даних.

Тут теґ має конструкцію, яка починається з < і завершується >, а також може складатися з декількох рядків.

Функція працює з масивом "@{$self->{TT}{doc_in}}", який містить дані вхідного документа, і здійснює прив'язку опосередковано, на основі "$self->shiftline()" і "$self->unshiftline($$)".

extract_tag($$)

Ця функція повертає наступний теґ із потоку вхідних даних без початку і кінця у формі масиву, щоб зберегти посилання на файл вхідних даних. Функція має два параметри: тип теґу (у формі, яку повертає tag_type) та булеве значення, яке вказує на те, чи слід вилучати теґ із потоку вхідних даних.

get_tag_name(@)

Ця функція повертає назву теґу, переданого як аргумент, у формі масиву, повернутого extract_tag.

breaking_tag()

Ця функція повертає булеве значення, яке повідомляє, є наступний теґ у потоці вхідних даних роздільним чи ні (вбудованим теґом). Не змінює вхідний потік даних.

treat_tag()

Ця функція перекладає наступний теґ з потоку вхідних даних. Використовує нетипові функції перекладу для кожного типу теґів.

tag_in_list($@)

Ця функція повертає рядкове значення, яке повідомляє, чи відповідає перший аргумент (ієрархія теґів) будь-якому теґу з другого аргументу (списку теґів або ієрархій теґів). Якщо не відповідає, функція повертає 0. Якщо відповідає, повертає параметри відповідного теґу (символи перед теґом) або 1 (якщо у теґу немає параметрів).

РОБОТА З АТРИБУТАМИ

treat_attributes(@): Ця функція обробляє переклад атрибутів теґу. Вона отримує теґ без позначок початку і кінця, а потім визначає атрибути і перекладає ті з них, які слід перекласти (вказані за допомогою параметра модуля attributes). Функція повертає простий рядок із перекладеним теґом.

РОБОТА З ДАНИМИ У ТЕҐАХ

treat_content(): Ця функція отримує фрагмент тексту до наступного теґу (не вбудованого) з потоку вхідних даних. Використовує нетипові функції перекладу для кожного типу теґів.
Функція працює з масивом "@{$self->{TT}{doc_in}}", який містить дані вхідного документа, і здійснює прив'язку опосередковано, на основі "$self->shiftline()" і "$self->unshiftline($$)".

РОБОТА З ПАРАМЕТРАМИ МОДУЛІВ

treat_options(): Ця функція заповнює внутрішні структури, які містять теґи, атрибути і вбудовані дані із використанням параметрів модуля (вказаний у рядку команди або у функції ініціалізації).

ОТРИМАННЯ ТЕКСТУ ІЗ ВХІДНОГО ДОКУМЕНТА

get_string_until($%)

Ця функція повертає масив рядків (і посилань) з вхідного документа, розташованих до першого аргументу функції. Другим аргументом є хеш параметрів. Значення 0 означає «вимкнено» (типове значення), а значення 1 — увімкнено.

Коректні значення параметрів:

include: Робить так, що повернути масив міститиме текст, який шукали
remove: Вилучає повернутий потік даних з вхідних даних.
unquoted: Забезпечує, щоб шуканий текст був поза лапками.
regex: Вказує, що першим аргументом є формальний вираз, а не звичайний текстовий рядок

skip_spaces(\@)

Ця функція отримує як аргумент посилання на абзац (у форматі, який повертає get_string_until), пропускає початкові пробіли і повертає абзац як простий рядок.

join_lines(@)

Ця функція повертає простий рядок із текстом з масиву аргументів (з відкиданням посилань).

СТАН ЦЬОГО МОДУЛЯ

Цей модуль може перекладати теґи і атрибути.

СПИСОК ЗАВДАНЬ

DOCTYPE (ЗАПИСИ)

Передбачено мінімальну підтримку перекладу замінників. Вони перекладаються як ціле, теґи не беруться до уваги. Підтримки багаторядкових замінників не передбачено, замінники завжди переносяться під час перекладу.

ВНЕСЕННЯ ЗМІН ДО ТИПІВ ТЕҐІВ З УСПАДКОВАНИХ МОДУЛІВ (пересунути структуру tag_types до $self hash?)

ТАКОЖ ПЕРЕГЛЯНЬТЕ

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

АВТОРИ

 © Jordi Vilalta <jvprat@gmail.com>
 © Nicolas François <nicolas.francois@centraliens.net>

АВТОРСЬКІ ПРАВА ТА ЛІЦЕНЗУВАННЯ

 © Jordi Vilalta  <jvprat@gmail.com>, 2004
 © Nicolas François <nicolas.francois@centraliens.net>, 2008—2009

Ця програма є вільним програмним забезпеченням; ви можете поширювати її і/або вносити до неї зміни за умов дотримання GPL версії 2.0 або пізнішої (див. файл COPYING).