Provided by: po4a_0.73-2ubuntu1_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 v2.0 of recenter (zie het bestand COPYING).
perl v5.38.2 2024-08-28 LOCALE::PO4A::XML.3PM(1)