LOCALE::PO4A::XML.3PM(1) | User Contributed Perl Documentation | LOCALE::PO4A::XML.3PM(1) |
ИМЕ
Locale::Po4a::Xml - двосмерна конверзија XML (и изведених из њега) докумената и PO фајлова
ОПИС
Циљ po4a (PO for anything – PO за било шта) пројекта је да поједностави превођење (и што је још интересантније, одржавање превода) употребом gettext алата на деловима на којима се не очекује њихова употреба, као што је документација.
Locale::Po4a::Xml је модул који помаже превод XML докумената на друге [људске] језике. Такође може да се употреби и као основа за изградњу модула који обрађују документе базиране на XML.
ПРЕВОЂЕЊЕ ПОМОЋУ PO4A::XML
Овај модул може да се користи за директну обраду генеричких XML докумената. Издвојиће сав садржај ознаке, без атрибута, јер је ро место на коме се пише текст у већини докумената базираних на XML.
Постоје неке опције (описане у наредном одељку) које могу да прилагоде ово понашање. Ако се не уклапа у формат вашег документа, најбоље је да напишете ваш сопствени модул изведен из овога, који ће да опише детаље вашег формата. Да сазнате више о том процесу, погледајте одељак ПИСАЊЕ ИЗВЕДЕНИХ МОДУЛА испод.
ОПЦИЈЕ КОЈЕ ПРИХВАТА ОВАЈ МОДУЛ
Глобална дибаг опција чини да овај модул прикаже искључене стрингове, како би се видело ако прескаче нешто важно.
Ово су опције везане само за овај модул:
- nostrip
- Спречава да модул уклони размаке око издвојених стрингова.
- wrap
- Каноникализује стринг који се преводи, сматрајући да празни карактери нису битни и обавија преведени документ. Ова опција може да се преиначи прилагођеним опцијама за ознаке. Погледајте опцију translated ниже.
- unwrap_attributes
- Атрибути се подразумевано обвијају. Ова опција искључује обавијање.
- caseinsensitive
- Чини да претрага ознака и атрибута не прави разлику између малих и великих слова. Ако је дефинисана, третираће <BooK>laNG and <BOOK>Lang као <book>lang.
- escapequotes
- Означава
знаке
навода у
излазним
стринговима.
Неопходно
је, на
пример, код
креирања
стринг
ресурса
које
користе
Андроид
алати за
изградњу
апликација.
Погледајте такође: https://developer.android.com/guide/topics/resources/string-resource.html
- includeexternal
- Када је дефинисано, спољни ентитети се прикључују у генерисани (преведени) документ, као и код издвајања стрингова. Ако није дефинисано, мораћете одвојено да преведете спољне ентитете као независне документе.
- ontagerror
- Ова опција дефинише понашање модула када наиђе на неважећу XML синтаксу (затварајућа ознака се не одговара последњој отварајућој ознаци). Може да има следеће вредности:
Будите опрезни када користите ову опцију. Најбоље би било да поправите улазни фајл.
- Напомена:
ова опција
је
застарела.
Издваја само ознаке наведене у опцији tags. Иначе, издвајаће се све ознаке осим оних наведених.
- doctype
- Стринг који ће покушати да се подудари са првом линијом doctype декларације у документу (у случају да је дефинисана). Ако није, упозорење ће да укаже на то како је могуће да је документ лошег типа.
- addlang
- Стринг који наводи путању (нпр. <bbb><aaa>) ознаке где би требало да се дода атрибут lang="...". Језик ће да се дефинише као базно име PO фајла без било какве .po екстензије.
- optionalclosingtag
- Логичка вредност која означава да ли су затварајуће ознаке опционалне (као у HTML). Подразумевано понашање је да се за затварајућу ознаку која недостаје пријави грешка која се затим обрађује сагласно са ontagerror.
- Напомена:
ова опција
је
застарела.
Требало би
да уместо
ње
користите
опције translated
и untranslated.
Листа ознака раздвојених размацима које желите да преведете или прескочите. Подразумевано, наведене ознаке се неће преводити, али ако употребите опцију „tagsonly”, наведене ознаке су и једине које ће се преводити. Ознака мора да буде у формату <aaa>, али можете неке и да спојите (<bbb><aaa>) чиме наводите да ће садржај ознаке <aaa> да се преведе само у случају да се налази у ознаци <bbb>.
Такође можете да наведете и неке опције за ознаке стављањем неких карактера испред хијерархије ознака. На пример, можете да ставите w (wrap - обавијај) или 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
- Листа
ознака
раздвојених
размацима
које би
требало да
се
третирају
као део
линије.
Подразумева
се да све
ознаке
преламају
секвенцу.
Ознаке морају да буду у облику <aaa>, али неке можете и да спојите (<bbb><aaa>), у случају да се ознака (<aaa>) разматра само онда када се налази унутар друге ознаке (<bbb>).
- placeholder
- Листа
ознака
раздвојених
размацима
које би
требало да
се
третирају
као чувари
места.
Чувари
места не
преламају
секвенцу,
али
садржај
чувара
места се
преводи
одвојено.
Локација чувара места ће у свом блоку бити означена стрингом који је сличан са:
<placeholder type=\"footnote\" id=\"0\"/>
Ознаке морају да буду у облику <aaa>, али неке можете и да спојите (<bbb><aaa>), у случају да се ознака (<aaa>) разматра само онда када се налази унутар друге ознаке (<bbb>).
- break-pi
- Подразумевано се Инструкције за Процесирање (нпр. "<? ... ?>" ознаке) обрађују као ознаке унутар линије. Проследите ову опције ако желите да се ИП обрађују као ознака која прелама. Имајте на уму да парсер обрађује непроцесиране PHP ознаке као Инструкције за Процесирање.
- nodefault
- Листа
ознака
раздвојених
размацима
које модул
не би
требало да
покуша
поставити
као
подразумеване
у било
којој
категорији.
Ако имате ознаку чије је подразумевано подешавање поставила подкласа овог модула, али желите да јој поставите алтернативно подешавање, морате ту ознаку да наведете као део nodefault стринга подешавања.
- cpp
- Подршка за C препроцесорске директиве. Када је ова опција постављена, програм po4a ће да посматра препроцесорске директиве као сепараторе пасуса. То је важно у случају када XML мора да прође препроцесирање, јер би у супротном директиве могле да се уметну у сред линија које програм po4a посматра као део текућег пасуса, па их препроцесор неће препознати. Напомена: препроцесорске директиве морају да се поставе између ознака (дакле, не смеју да преломе ознаку).
- translated
- Листа
ознака
раздвојених
размацима
које
желите да
се преведу.
Ознаке морају да буду у облику <aaa>, али неке можете и да спојите (<bbb><aaa>), у случају да се ознака (<aaa>) разматра само онда када се налази унутар друге ознаке (<bbb>).
Можете такође да наведете и неке опције за ознаке стављањем одређених карактера испред хијерархије ознака. То преиначује подразумевано понашање које задају глобалне опције wrap и defaulttranslateoption.
Интерно, XML парсеру су битне само следеће четири опције: w W i p.
* Ознаке наведене у break се постављају на w или W у зависности од опције wrap.
* Ознаке наведене у inline се постављају на i.
* Ознаке наведене у placeholder се постављају p.
* Ознакама наведеним у untranslated није постављена ниједна од ових опција.
Стварно понашање интерних параметара можете да потврдите позивајући po4a са опцијом --debug.
Пример: W<chapter><title>
Молим вас, имајте на уму да би ознака требало да се наведе или у translated, или у untranslated стрингу подешавања.
- untranslated
- Листа
ознака
раздвојених
размацима
које не
желите да
се преводе.
Ознаке морају да буду у облику <aaa>, али неке можете и да спојите (<bbb><aaa>), у случају да се ознака (<aaa>) разматра само онда када се налази унутар друге ознаке (<bbb>).
Молим вас, имајте на уму да се преводива ознака унутар линије која се налази у непреводивој ознаци третира као преламајућа ознака, 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 кључевима). Ако желите да дефинишете тип ознаке, мораћете да направите хеш са следећим кључевима:
- beginning
- Наводи почетак ознаке, након „<”.
- end
- Наводи крај ознаке, испред „>”.
- breaking
- Говори да ли је ово класа преламајућих ознака. Непреламајућа (унутар линије) ознака је она која може да се узме као део садржаја неке друге ознаке. Може да има вредности неистинито (0), истинито (1) или да буде недефинисана. Ако је оставите недефинисаном, мораћете да дефинишете функцију 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) и
логичку
вредност
која
означава
да ли би
ознака
требало да
се уклони
из улазног
тока.
Ово ради над низом "@{$self->{TT}{doc_in}}" који чува податке из улазног документа и индиректно референцира се индиректно преко "$self->shiftline()" и "$self->unshiftline($$)".
- get_tag_name(@)
- Ова функција враћа име ознаке која јој се прослеђује као аргумент, у облику низа који враћа extract_tag.
- breaking_tag()
- Ова функција враћа логичку вредност која говори да ли је наредна ознака у улазном току преламајућа ознака или није (ознака унутар линије). Улазни ток оставља нетакнут.
- treat_tag()
- Ова
функција
преводи
следећу
ознаку у
улазном
току.
Употребом
прилагођених
функција
превођења
сваког од
типова
ознака.
Ово ради над низом "@{$self->{TT}{doc_in}}" који чува податке из улазног документа и индиректно референцира се индиректно преко "$self->shiftline()" и "$self->unshiftline($$)".
- 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
укључено.
Важеће опције су:
- skip_spaces(\@)
- Ова функција прихвата као свој аргумент референцу на пасус (у облику који враћа get_string_until), прескаче њене размаке у наслову и враћа их као прост стринг.
- join_lines(@)
- Ова функција враћа прост стринг са текстом из низа који је добила као аргумент (одбацујући референце).
СТАТУС ОВОГ МОДУЛА
Овај модул може да преведе ознаке и атрибуте.
ЛИСТА СТВАРИ КОЈЕ ТРЕБА ДА СЕ УРАДЕ
DOCTYPE (ЕНТИТЕТИ)
Постоји минимална подршка за превођење ентитета. Они се преводе као целина, ознаке се не узимају у обзир. Ентитети у више линија нису подржани, а ентитети се увек поново обавијају током превођења.
ИЗМЕНА ТИПОВА ОЗНАКА ИЗ НАСЛЕЂЕНИХ МОДУЛА (померити структуру tag_types унутар $self хеша?)
ПОГЛЕДАЈТЕ ТАКОЂЕ
АУТОРИ
Жорди Вилалта<jvprat@gmail.com> Никола Франсоа <nicolas.francois@centraliens.net>
ПРАВА УМНОЖАВАЊА И ЛИЦЕНЦА
Права умножавања © 2004 Жорди Вилалта <jvprat@gmail.com> Права умножавања © 2008-2009 Никола Франсоа <nicolas.francois@centraliens.net>
Овај програм је слободан софтвер; можете да га редистрибуирате и/или мењате под условима GPL v2.0 или новије (погледајте фајл COPYING).
2024-06-26 | perl v5.38.2 |