Locale::Po4a::Xml

ИМЕ

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 синтаксу (затварајућа ознака се не одговара последњој отварајућој ознаци). Може да има следеће вредности:

tagsonly

Напомена: ова опција је застарела. Издваја само ознаке наведене у опцији tags. Иначе, издвајаће се све ознаке осим оних наведених.

doctype

Стринг који ће покушати да се подудари са првом линијом doctype декларације у документу (у случају да је дефинисана). Ако није, упозорење ће да укаже на то како је могуће да је документ лошег типа.

addlang

Стринг који наводи путању (нпр. <bbb><aaa>) ознаке где би требало да се дода атрибут lang="...". Језик ће да се дефинише као базно име PO фајла без било какве .po екстензије.

optionalclosingtag

Логичка вредност која означава да ли су затварајуће ознаке опционалне (као у HTML). Подразумевано понашање је да се за затварајућу ознаку која недостаје пријави грешка која се затим обрађује сагласно са ontagerror.

tags

Напомена: ова опција је застарела. Требало би да уместо ње користите опције 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.

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 хеша?)

ПОГЛЕДАЈТЕ ТАКОЂЕ

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

АУТОРИ

 Жорди Вилалта<[email protected]>
 Никола Франсоа <[email protected]>

ПРАВА УМНОЖАВАЊА И ЛИЦЕНЦА

 Права умножавања © 2004 Жорди Вилалта <[email protected]>
 Права умножавања © 2008-2009 Никола Франсоа <[email protected]>

Овај програм је слободан софтвер; можете да га редистрибуирате и/или мењате под условима GPL (погледајте фајл COPYING).