Locale::Po4a::Xml(3pm) Po4a-hulpmiddelen Locale::Po4a::Xml(3pm)

Locale::Po4a::Xml -XML-documenten en afgeleiden van/naar PO-bestanden converteren

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.

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.

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:

Voorkomt het wegnemen van spaties rond de geëxtraheerde tekstfragmenten.
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.
Bij attributen wordt standaard regelafbreking toegepast. Deze optie zet regelafbreking uit.
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.
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

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.
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:
Dit is de standaardwaarde. De module zal afsluiten met een foutmelding.
De module zal doorgaan en een waarschuwing geven.
De module zal zonder waarschuwen doorgaan.

Wees voorzichtig met het gebruiken van deze optie. Algemeen wordt aangeraden om het invoerbestand te repareren.

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.

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.
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.
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.
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>

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.
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.

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.
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.

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.

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.

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.
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.

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).
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.

Tags moeten vertaald worden en op de inhoud kan regelafbreking toegepast worden.
Tags moeten vertaald worden maar de regelafbreking mag niet veranderen.
Tags moeten geïntegreerd in de tekst vertaald worden.
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.

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.

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.

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):

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.
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.

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:

Specificeert het begin van de tag, na het "<".
Specificeert het einde van de tag, voor het ">".
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.
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.
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.
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.

MET TAGS WERKEN

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.

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.

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.

Deze functie zendt de naam van de tag terug, welke als argument meegegeven werd, in de lijstvorm welke door extract_tag teruggezonden werd.
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.
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.

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

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

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

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

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:

Dit zorgt ervoor dat de teruggezonden lijst de gezochte tekst bevat
Dit verwijdert de teruggezonden stroom uit de invoer
Dit zorgt ervoor dat de gezochte tekst zich niet tussen aanhalingstekens bevindt
Dit geeft aan dat het eerste argument een reguliere expressie is in plaats van een gewoon tekstfragment
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.
Deze functie zendt een gewoon tekstfragment terug met de tekst uit de argumentenlijst (met weglating van de referenties).

Deze module kan tags en attributen vertalen.

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?)

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

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


 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).

2023-01-03 Po4a-hulpmiddelen