Provided by: po4a_0.67-2_all 
NAAM
Locale::Po4a::Xml -XML-documenten en afgeleiden van/naar PO-bestanden converteren
BESCHRIJVING
Het doel van het project po4a (PO voor alles) is om de vertaalwerkzaamheden (en
interessanter nog, het onderhoud van vertalingen) te vergemakkelijken met behulp van
gettext-hulpmiddelen in domeinen waarin deze niet meteen verwacht worden, zoals
documentatie.
Locale::Po4a::Xml is een module ter ondersteuning van de vertaling van XML-documenten naar
andere [menselijke] talen. Ze kan ook gebruikt worden als basis voor het bouwen van
modules voor op XML gebaseerde documenten.
VERTALEN MET PO4A::XML
Deze module kan rechtstreeks gebruikt worden voor het verwerken van generieke XML
documenten. Zij extraheert al de inhoud uit tags zonder de attributen, omdat daar in de
meeste op XML gebaseerde documenten de tekst geschreven staat.
Er zijn bepaalde opties (die in het volgende gedeelte beschreven worden) die dit gedrag
kunnen aanpassen. Indien deze module niet beantwoordt aan de indeling van uw document,
wordt u aangemoedigd om op basis van deze module uw eigen module te schrijven, met de
beschrijving van de details van uw indeling. Raadpleeg het gedeelte AFGELEIDE MODULES
SCHRIJVEN, hieronder, voor de beschrijving van de werkwijze.
MOGELIJKE OPTIES BIJ DEZE MODULE
De algemene debug-optie doet deze module de uitgesloten tekstfragmenten weergeven, om zo
te kunnen zien of ze niets belangrijk overslaat.
De volgende opties zijn specifiek voor deze module:
nostrip
Voorkomt het wegnemen van spaties rond de geëxtraheerde tekstfragmenten.
wrap
Canoniseert het te vertalen tekstfragment vanuit de veronderstelling dat witruimte
niet belangrijk is, en past regelafbreking toe voor het vertaalde document. Deze optie
kan overstegen worden door aangepaste tag-opties. Zie de optie translated hieronder.
unwrap_attributes
Bij attributen wordt standaard regelafbreking toegepast. Deze optie zet regelafbreking
uit.
caseinsensitive
Het zorgt ervoor dat het zoeken naar tags en attributen niet hoofdlettergevoelig
gebeurt. Indien dit gedefinieerd wordt zal het <BoeK>taAL en <BOEK>Taal behandelen als
<boek>taal.
escapequotes
Aanhalingstekens in uitvoertekstfragmenten maskeren met een maskeerteken. Dit is
bijvoorbeeld nodig om tekstfragmentbronmateriaal te creëren dat gebruikt zal worden
door bouwgereedschap op Android .
Zie ook: https://developer.android.com/guide/topics/resources/string-resource.html
includeexternal
Als deze optie gedefinieerd werd, worden externe entiteiten meegenomen in het
gegenereerde (vertaalde) document en voor het extraheren van tekstfragmenten. Indien
ze niet gedefinieerd werd, zult u externe entiteiten afzonderlijk moeten vertalen als
onafhankelijke documenten.
ontagerror
Deze optie definieert het gedrag van de module wanneer zij met een ongeldige XML-
syntaxis geconfronteerd wordt (een afsluitende tag die niet overeenkomt met de laatste
openende tag). Zij kan de volgende waarden hebben:
fail
Dit is de standaardwaarde. De module zal afsluiten met een foutmelding.
warn
De module zal doorgaan en een waarschuwing geven.
silent
De module zal zonder waarschuwen doorgaan.
Wees voorzichtig met het gebruiken van deze optie. Algemeen wordt aangeraden om het
invoerbestand te repareren.
tagsonly
Opmerking: deze optie is verouderd.
Extraheert enkel die tags welke gespecificeerd werden in de optie tags. Anders zal ze
alle tags extraheren, behalve die welke gespecificeerd werden.
doctype
Tekenreeks waarmee naar een overeenkomst gezocht wordt met de eerste regel van het
doctype van het document (voor zover gedefinieerd). Is dit niet succesvol, dan wordt
de waarschuwing gegeven dat het document mogelijk van een slecht documenttype is.
addlang
Tekenreeks die het pad (bijv. <bbb><aaa>) aangeeft van een tag waaraan een attribuut
lang="..." zal toegevoegd worden. De taal zal gedefinieerd worden als de basisnaam
voor het PO-bestand zonder de extensie .po.
optionalclosingtag
Booleaanse operator die aangeeft of afsluitende tags facultatief zijn (zoals bij
HTML). Standaard geeft het ontbreken van een afsluitende tag aanleiding tot een fout,
die afgehandeld wordt volgens ontagerror.
tags
Opmerking: deze optie is verouderd. In de plaats daarvan moet u de opties translated
en untranslated gebruiken.
Door spaties gescheiden lijst met tags die u wilt vertalen of overslaan. Standaard
worden de opgegeven tags uitgesloten, maar indien u de optie "tagsonly" gebruikt,
zullen de gespecificeerde tags de enige zijn die opgenomen worden. De tags moeten de
vorm <aaa> hebben, maar u kunt er samenvoegen (<bbb><aaa>) om aan te geven dat de
inhoud van de tag <aaa> enkel vertaald zal worden wanneer deze zich binnenin tag <bbb>
bevindt.
U kunt ook tag-opties opgeven door bepaalde tekens te plaatsen vooraan aan de
tag-hiërarchie. U kunt er bijvoorbeeld w (wrap - regelafbreking) of W (don't wrap -
geen regelafbreking) plaatsen om het standaardgedrag te overstijgen dat door de
globale optie wrap gespecificeerd wordt.
Bijvoorbeeld: W<chapter><title>
attributes
Door spaties gescheiden lijst met tagattributen die u wilt vertalen. U kunt het
attribuut opgeven bij zijn naam (bijvoorbeeld "lang"), maar u kunt het laten
voorafgaan door een tag-hiërarchie, om aan te geven dat dit attribuut enkel vertaald
zal worden wanneer het zich binnen de opgegeven tag bevindt. Bijvoorbeeld:
<bbb><aaa>lang specificeert dat het attribuut lang (taal) enkel vertaald zal worden
als het zich binnen een tag <aaa> binnenin tag <bbb> bevindt.
foldattributes
Geen attributen vertalen die binnenin de in de tekst geïntegreerde tags (inline tags)
staan. In de plaats daarvan alle attributen van een tag vervangen door po4a-id=<id>.
Dit is nuttig wanneer attributen niet vertaald moeten worden, omdat dit de
tekstfragmenten voor vertalers eenvoudiger maakt en typefouten vermijdt.
customtag
Door spaties gescheiden lijst met tags die niet als tags mogen worden behandeld. Deze
tags worden behandeld als geïntegreerd in de tekst (inline tags) en moeten niet
gesloten worden.
break
Door spaties gescheiden lijst met tags die het tekstfragment afbreken. Standaard
breken alle tags het fragment af.
De tags moeten de vorm <aaa> hebben, maar u kunt er enkele samenvoegen (<bbb><aaa>),
indien enkel rekening gehouden moet worden met een tag wanneer deze zich binnen een
andere tag (<bbb>) bevindt.
Merk op dat een tag slechts vermeld mag worden bij één van de volgende
instellingsreeksen: break, inline placeholder of customtag.
inline
Door spaties gescheiden lijst met tags die behandeld moeten worden als geïntegreerd in
de tekst (inline tag). Standaard sluit elke tag een tekstfragment af.
De tags moeten de vorm <aaa> hebben, maar u kunt er enkele samenvoegen (<bbb><aaa>),
indien enkel rekening gehouden moet worden met een tag wanneer deze zich binnen een
andere tag (<bbb>) bevindt.
placeholder
Door spaties gescheiden lijst met tags die als tijdelijke aanduiding (placeholder)
moeten worden behandeld. Tijdelijke aanduidingen sluiten geen tekstfragment af, maar
de inhoud van tijdelijke aanduidingen wordt apart vertaald.
De plaats van de tijdelijke aanduiding (placeholder) in zijn tekstblok wordt
gemarkeerd met een tekenreeks die vergelijkbaar is met:
<placeholder type=\"footnote\" id=\"0\"/>
De tags moeten de vorm <aaa> hebben, maar u kunt er enkele samenvoegen (<bbb><aaa>),
indien enkel rekening gehouden moet worden met een tag wanneer deze zich binnen een
andere tag (<bbb>) bevindt.
break-pi
Standaard worden verwerkingsinstructies (d.w.z. tags in de vorm van "<? ... ?>")
behandeld als in de tekst geïntegreerde tags (inline tags). Geef deze optie mee als u
wilt dat verwerkingsinstructies behandeld worden als tags die een tekstfragment
afsluiten. Merk op dat onverwerkte PHP-tags door de ontleder behandeld worden als
verwerkingsinstructies.
nodefault
Door spaties gescheiden lijst met tags die de module niet standaard in een categorie
zou moeten proberen te plaatsen.
Als u een tag heeft die door de subklasse van deze module zijn standaardinstelling
krijgt, maar u een alternatieve instelling wilt instellen, moet u die tag vermelden
als onderdeel van de instellingsreeks nodefault.
cpp C-preprocessorinstructies ondersteunen. Indien deze optie ingesteld is, zal po4a
preprocessorinstructies beschouwen als alinea-afbrekers. Dit is belangrijk wanneer het
XML-bestand moet voorbewerkt worden, omdat deze instructies anders geplaatst zouden
kunnen worden in het midden van een regel mocht po4a ze beschouwen als behorend tot de
huidige alinea, waardoor ze niet herkend zouden worden door de preprocessor. Merk op
dat de preprocessorinstructies enkel tussen tags mogen staan (zij mogen geen tag
verbreken).
translated
Door spaties gescheiden lijst met tags die u wilt vertalen.
De tags moeten de vorm <aaa> hebben, maar u kunt er enkele samenvoegen (<bbb><aaa>),
indien enkel rekening gehouden moet worden met een tag wanneer deze zich binnen een
andere tag (<bbb>) bevindt.
U kunt ook een aantal tag-opties opgeven door bepaalde tekens te plaatsen vóór de
tag-hiërarchie. Dit overstijgt het standaardgedrag dat gespecificeerd wordt door de
algemene opties wrap en defaulttranslateoption.
w Tags moeten vertaald worden en op de inhoud kan regelafbreking toegepast worden.
W Tags moeten vertaald worden maar de regelafbreking mag niet veranderen.
i Tags moeten geïntegreerd in de tekst vertaald worden.
p Tags moeten vertaald worden als tijdelijke aanduiding (placeholder).
Intern bekommert de XML-ontleder zich enkel om deze vier opties: w W i p.
* Tags die vermeld worden in break, worden ingesteld op w of W, afhankelijk van de
optie wrap.
* Tags die vermeld worden in inline, worden ingesteld op i.
* Tags die vermeld worden in placeholder, worden ingesteld op p.
* Bij tags die vermeld worden in untranslated, worden geen van deze opties ingesteld.
U kunt het feitelijke gedrag van interne parameters nagaan door po4a aan te roepen met
de optie --debug.
Bijvoorbeeld: W<chapter><title>
Merk op dat een tag vermeld moet worden in één van de volgende instellingsreeksen:
translated of untranslated.
untranslated
Door spaties gescheiden lijst met tags die u niet wilt vertalen.
De tags moeten de vorm <aaa> hebben, maar u kunt er enkele samenvoegen (<bbb><aaa>),
indien enkel rekening gehouden moet worden met een tag wanneer deze zich binnen een
andere tag (<bbb>) bevindt.
Merk op dat een in de tekst geïntegreerde (inline) vertaalbare tag binnenin een niet-
vertaalde tag, behandeld wordt als een vertaalbare tag die een tekstfragment afsluit;
de instelling i wordt verwijderd en w of W wordt ingesteld, afhankelijk van de optie
wrap.
defaulttranslateoption
De standaardcategorieën voor tags die niet behoren tot een van deze categorieën:
translated, untranslated, break, inline, en placeholder.
Dit is een reeks letters, zoals in translated gedefinieerd, en deze instelling is
alleen geldig voor vertaalbare tags.
AFGELEIDE MODULES SCHRIJVEN
DEFINIËREN WELKE TAGS EN ATTRIBUTEN VERTAALD MOETEN WORDEN
De eenvoudigste aanpassing bestaat erin om te definiëren welke tags en attributen u wilt
laten vertalen door de ontleder. Dit moet gebeuren in de functie initialize. Eerst moet u
de hoofdfunctie initialize aanroepen om de commandoregelopties te verkrijgen en dan moet u
uw eigen definities toevoegen aan de hash met opties. Als u enkele nieuwe opties vanaf de
commandoregel wilt bewerken, moet u ze definiëren voordat u de hoofdfunctie initialize
aanroept:
$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;
In afgeleide modules zou u de opties _default_inline, _default_break,
_default_placeholder, _default_translated, _default_untranslated en _default_attributes
moeten gebruiken. Dit laat gebruikers toe met commandoregelopties het in uw module
gedefinieerde standaardgedrag te overstijgen.
MET COMMANDOREGELOPTIES HET STANDAARDGEDRAG OVERSTIJGEN
Indien u niet houdt van het standaardgedrag van deze xml-module en de ervan afgeleide
modules, kunt u voorzien in commandoregelopties om hun gedrag te wijzigen.
Zie Locale::Po4a::Docbook(3pm),
DE FUNCTIE found_string OVERSTIJGEN
Een andere eenvoudige stap bestaat erin de functie "found_string" te overstijgen. Deze
functie ontvangt de geëxtraheerde tekstfragmenten van de ontleder om ze te vertalen. Daar
kunt u sturen welke tekstfragmenten u wilt vertalen en kunt u deze transformeren voor of
na de eigenlijke vertaling.
Ze ontvangt de geëxtraheerde tekst, de referentie over de plaats ervan en een hash die
extra informatie bevat om te sturen welke tekstfragmenten vertaald moeten worden, hoe ze
vertaald moeten worden en hoe het commentaar gegenereerd moet worden.
De inhoud van deze opties is afhankelijk van het soort tekstfragment (gespecificeerd in
een item van deze hash):
type="tag"
Het aangetroffen tekstfragment is de inhoud van een vertaalbare tag. Het item
"tag_options" bevat de optie-tekens die staan vóór de taghiërarchie uit de optie
"tags" van de module.
type="attribute"
Betekent dat de gevonden tekenreeks de waarde van een vertaalbaar attribuut is. Het
element "attribute" heeft de naam van het attribuut.
Het moet de tekst teruggeven die de originele tekst in het vertaalde document zal
vervangen. Hier volgt een basaal voorbeeld van deze functie:
sub found_string {
my ($self,$text,$ref,$options)=@_;
$text = $self->translate($text,$ref,"type ".$options->{'type'},
'wrap'=>$self->{options}{'wrap'});
return $text;
}
Er is nog een ander eenvoudig voorbeeld in de nieuwe Dia-module, die enkel bepaalde
tekstfragmenten filtert.
TAG-TYPES AANPASSEN (TE DOEN)
Dit is complexer, maar het maakt een (bijna) totale aanpassing mogelijk. Het is gebaseerd
op een reeks hashes, welke elk het gedrag definiëren van een tag-type. De reeks moet
gesorteerd worden, zodat de meest algemene tags na de meer concrete komen (vooreerst
gesorteerd op de sleutel beginning en dan op de sleutel end). Om een tag-type te
definiëren moet u een hash maken met de volgende sleutels:
beginning
Specificeert het begin van de tag, na het "<".
end Specificeert het einde van de tag, voor het ">".
breaking
Dit zegt of dit een tag-klasse betreft die een tekstfragment afsluit. Een niet-
afsluitende (geïntegreerde) tag is een tag die als inhoud van een andere tag kan
beschouwd worden. Deze sleutel kan de waarden onwaar (0), waar (1) of niet-
gedefinieerd hebben. Indien u dit ongedefinieerd laat, zult u de functie f_breaking
moeten definiëren, welke zal zeggen of een concrete tag uit deze klasse een
afsluitende tag is of niet.
f_breaking
Het is een functie die zegt of de volgende tag een afsluitende tag is of niet. Ze moet
gedefinieerd worden als de optie breaking dat niet is.
f_extract
Indien u deze sleutel ongedefinieerd laat, dan zal de generieke extractiefunctie de
tag zelf moeten extraheren. Hij is nuttig voor tags die andere tags of speciale
structuren kunnen bevatten, zodat de hoofdontleder niet gek wordt. Deze functie
ontvangt een booleaanse waarde welke zegt of deze tag al of niet verwijderd moet
worden uit de invoerstroom.
f_translate
Deze functie ontvangt de tag (in de indeling get_string_until()) en zendt de vertaalde
tag terug (vertaalde attributen of alle nodige transformaties) als een enkel
tekstfragment.
INTERNE FUNCTIES welke gebruikt worden voor het schrijven van afgeleide ontleders
MET TAGS WERKEN
get_path()
Deze functie zendt het pad naar de huidige tag vanaf de documentbasis terug in de vorm
<html><body><p>.
Een extra lijst tags (zonder haakjes) kan als argument opgegeven worden. Deze
padelementen worden toegevoegd aan het einde van het huidige pad.
tag_type()
Deze functie zendt de index uit de lijst tag_types terug, welke overeenkomt met de
volgende tag in de invoerstroom, of -1 indien het om einde van het invoerbestand gaat.
Hier heeft de tag als structuur een begin met < en een einde met > en ze kan uit
verschillende regels bestaan.
Dit werkt op de lijst "@{$self->{TT}{doc_in}}" welke indirect via "$self->shiftline()"
and "$self->unshiftline($$)" data en referenties bevat van het invoerdocument.
extract_tag($$)
Deze functie zendt in de vorm van een lijst de volgende tag van de invoerstroom terug,
zonder het begin en het einde, voor het onderhoud van de referenties van het
invoerbestand. Ze heeft twee parameters: het type tag (zoals teruggezonden door
tag_type) en een booleaanse waarde welke aangeeft of de tag verwijderd moet worden uit
de invoerstroom.
Dit werkt op de lijst "@{$self->{TT}{doc_in}}" welke indirect via "$self->shiftline()"
and "$self->unshiftline($$)" data en referenties bevat van het invoerdocument.
get_tag_name(@)
Deze functie zendt de naam van de tag terug, welke als argument meegegeven werd, in de
lijstvorm welke door extract_tag teruggezonden werd.
breaking_tag()
Deze functie zendt een booleaanse waarde terug die zegt of de volgende tag uit de
invoerstroom een tag is die een tekstfragment afsluit of niet (in de tekst
geïntegreerde tag). Ze laat de invoerstroom intact.
treat_tag()
Deze functie vertaalt de volgende tag uit de invoerstroom. Ze gebruikt voor elk type
tag de geëigende vertalingsfuncties.
Dit werkt op de lijst "@{$self->{TT}{doc_in}}" welke indirect via "$self->shiftline()"
and "$self->unshiftline($$)" data en referenties bevat van het invoerdocument.
tag_in_list($@)
Deze functie zendt een waarde terug die zegt of het eerste argument (een
tag-hiërarchie) overeenkomt met een van de tags uit het tweede argument (een lijst met
tags of tag-hiërarchieën). Als er geen overeenkomst is, wordt 0 teruggezonden. Anders
zendt ze de opties (de tekens die voor de tag staan) terug van de tag die een
overeenkomst gaf of 1 (indien deze tag geen opties heeft).
MET ATTRIBUTEN WERKEN
treat_attributes(@)
Deze functie verwerkt de vertaling van de attributen van de tag. Ze ontvangt de tag
zonder de markeringen beginning / end en zoekt vervolgens de attributen en vertaald
diegene welke vertaalbaar zijn (gespecificeerd door de optie attributes) van de
module). Deze functie zendt een gewoon tekstfragment terug met de vertaalde tag.
WERKEN MET GETAGDE INHOUD
treat_content()
Deze functie krijgt uit de invoerstroom de tekst tot aan de volgende tag die een
tekstfragment afsluit (geen in de tekst geïntegreerde tag). Ze vertaalt het
tekstfragment waarbij ze voor elk type tag de geëigende vertaalfuncties gebruikt.
Dit werkt op de lijst "@{$self->{TT}{doc_in}}" welke indirect via "$self->shiftline()"
and "$self->unshiftline($$)" data en referenties bevat van het invoerdocument.
MET DE MODULEOPTIES WERKEN
treat_options()
Deze functie vult de interne structuren die de tags, attributen en geïntegreerde
gegevens bevatten, met de moduleopties (gespecificeerd aan de commandoregel of in de
functie initialize).
TEKST HALEN UIT HET INVOERDOCUMENT
get_string_until($%)
Deze functie zendt een lijst terug met de regels (en referenties) van het
invoerdocument tot ze het eerste argument aantreft. Het tweede argument is een hash
met opties. Waarde 0 betekent uitgezet (standaard) en 1 aangezet.
Geldige opties zijn:
include
Dit zorgt ervoor dat de teruggezonden lijst de gezochte tekst bevat
remove
Dit verwijdert de teruggezonden stroom uit de invoer
unquoted
Dit zorgt ervoor dat de gezochte tekst zich niet tussen aanhalingstekens bevindt
regex
Dit geeft aan dat het eerste argument een reguliere expressie is in plaats van een
gewoon tekstfragment
skip_spaces(\@)
Deze functie ontvangt als argument de verwijzing naar een paragraaf (in de door
get_string_until teruggezonden indeling), slaat de spaties vooraan over en zendt ze
terug als een gewoon tekstfragment.
join_lines(@)
Deze functie zendt een gewoon tekstfragment terug met de tekst uit de argumentenlijst
(met weglating van de referenties).
STATUS VAN DEZE MODULE
Deze module kan tags en attributen vertalen.
TO-DOLIJST
DOCTYPE (ENTITEITEN)
De vertaling van entiteiten wordt minimaal ondersteund. Entiteiten worden in hun geheel
vertaald en met tags wordt geen rekening gehouden. Entiteiten die meerdere regels beslaan
worden niet ondersteund en tijdens de vertaling wordt steeds regelafbreking toegepast.
TAG-TYPES UIT OVERGEËRFDE MODULES WIJZIGEN ( de structuur tag_type binnen de hash $self
verplaatsen?)
ZIE OOK
Locale::Po4a::TransTractor(3pm), po4a(7)
AUTEURS
Jordi Vilalta <jvprat@gmail.com>
Nicolas François <nicolas.francois@centraliens.net>
COPYRIGHT EN LICENTIE
Copyright © 2004 Jordi Vilalta <jvprat@gmail.com>
Copyright © 2008-2009 Nicolas François <nicolas.francois@centraliens.net>
Dit programma is vrije software; u kunt het verder verspreiden en/of aanpassen onder de
bepalingen van de GPL (zie het bestand COPYING).