Provided by: po4a_0.69-1_all 
NAAM
Locale::Po4a::TransTractor - generieke vertaler en extractor.
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.
Deze klasse is de voorouder van alle po4a-ontleders die gebruikt worden om een document te ontleden,
vertaalbare tekstfragmenten op te zoeken, deze naar een PO-bestand te extraheren en deze te vervangen
door hun vertaling in het uitvoerdocument.
Meer formeel neemt ze de volgende argumenten als invoer:
- een te vertalen document;
- een PO-bestand dat de te gebruiken vertalingen bevat.
Als uitvoer produceert ze:
- nog een PO-bestand als het resultaat van de extractie van vertaalbare tekstfragmenten uit het
invoerdocument;
- een vertaald document met dezelfde structuur als het invoerdocument, maar waarin alle vertaalbare
tekstfragmenten vervangen werden door de vertalingen die in het als invoer verstrekte PO-bestand
aangetroffen werden.
Hier volgt een grafische voorstelling:
Invoerdocument --\ /---> Uitvoerdocument
\ / (vertaald)
+-> ontleedfunctie() -----+
/ \
Invoer-PO --------/ \---> Uitvoer-PO
(geëxtraheerd)
FUNCTIES DIE UW ONTLEDERER MOET OVERSTIJGEN
parse()
Dit is waar al het werk gebeurt: het ontleden van invoerdocumenten, het genereren van uitvoer en het
extraheren van de vertaalbare tekstfragmenten. Dit is redelijk eenvoudig met de hieronder in de
sectie INTERNE FUNCTIES verstrekte functies. Bekijk ook het OVERZICHT met daarin een voorbeeld.
Deze functie wordt aangeroepen door de functie process() hieronder, maar indien u ervoor kiest de
functie new() te gebruiken en handmatig inhoud toe te voegen aan uw document, zult u deze functie
zelf moeten aanroepen.
docheader()
Deze functie geeft de header terug die we aan het geproduceerde document moeten toevoegen, passend
aangehaald om in de doeltaal als commentaar te gelden. Raadpleeg de sectie Ontwikkelaars onderrichten
over vertalingen van po4a(7) over waarvoor dit goed is.
OVERZICHT
Inhet volgende voorbeeld wordt een lijst alinea's die beginnen met "<p>", ontleed. Gemakshalve gaan we
ervan uit dat het document goed is opgemaakt, d.w.z. dat '<p>'-tags de enige aanwezige tags zijn, en dat
deze tag helemaal aan het begin van elke alinea staat.
sub parse {
my $self = shift;
PARAGRAPH: while (1) {
my ($paragraph,$pararef)=("","");
my $first=1;
my ($line,$lref)=$self->shiftline();
while (defined($line)) {
if ($line =~ m/<p>/ && !$first--; ) {
# Niet de eerste maal dat we <p> zien.
# Plaats de huidige regel opnieuw in invoer,
# en plaats de gebouwde alinea in uitvoer
$self->unshiftline($line,$lref);
# Nu het document gevormd is, dit vertalen:
# - De voorafgaande tag verwijderen
$paragraph =~ s/^<p>//s;
# - de voorafgaande tag (onvertaald) naar uitvoer sturen
# evenals de rest van de alinea (vertaald)
$self->pushline( "<p>"
. $self->translate($paragraph,$pararef)
);
next PARAGRAPH;
} else {
# Toevoegen aan de alinea
$paragraph .= $line;
$pararef = $lref unless(length($pararef));
}
# De lus herhalen
($line,$lref)=$self->shiftline();
}
# Geen gedefinieerde regel gekregen? Einde van invoerbestand.
return;
}
}
Nadat u de ontleedfunctie geïmplementeerd heeft, kunt u uw documentklasse gebruiken met behulp van de
openbare interface die in de volgende sectie voorgesteld wordt.
OPENBARE INTERFACE voor scripts die uw ontleder gebruiken
Constructor
process(%)
Deze functie kan in één aanroep alles doen wat u moet doen met een po4a-document. De argumenten
moeten als een hash worden verpakt. ACTIES:
a. Leest alle in po_in_name vermelde PO-bestanden
b. Leest alle in file_in_name vermelde documenten
c. Ontleedt het document
d. Leest alle opgegeven addenda en past deze toe
e. Schrijft het vertaalde document naar file_out_name (indien gespecificeerd)
f. Schrijft het geëxtraheerd PO-bestand naar po_out_name (indien gespecificeerd)
ARGUMENTEN, behalve die welke door new() geaccepteerd worden (met verwacht type):
file_in_name (@)
Lijst met namen van bestanden waaruit we het invoerdocument moeten lezen.
file_in_charset ($)
In het invoerdocument gebruikte tekenset (Indien dit niet gespecificeerd is, zal geprobeerd
worden om dit vanuit het invoerdocument te weten te komen).
file_out_name ($)
Naam van het bestand waarnaar we het uitvoerdocument moeten schrijven.
file_out_charset ($)
In het uitvoerdocument gebruikte tekenset (Indien dit niet gespecificeerd werd, zal de tekenset
van het PO-bestand gebruikt worden).
po_in_name (@)
Namenlijst van de bestanden waaruit we de invoerPO-bestanden moeten lezen, welke de vertaling
bevatten die gebruikt zal worden om het document te vertalen.
po_out_name ($)
Naam van het bestand waarin we het uitvoerPO-bestand moeten schrijven, dat de tekstfragmenten
bevat die uit het invoerdocument geëxtraheerd werden.
addendum (@)
Namenlijst van de bestanden waaruit we de addenda moeten inlezen.
addendum_charset ($)
Tekenset voor de addenda.
new(%)
Een nieuw po4a document creëren. Mogelijke opties (in de hash die als parameter meegegeven wordt):
verbose ($)
Stelt in hoeveel informatie gegeven wordt.
debug ($)
Stelt het debuggen in.
Documentbestanden behandelen
read($$)
Nog andere invoerdocumentgegevens toevoegen aan het einde van de bestaande array
"@{$self->{TT}{doc_in}}". Het argument is de naam van het in te lezen bestand. Indien een tweede
argument gegeven wordt, is dit de in de referenties te gebruiken bestandsnaam.
Deze lijst "@{$self->{TT}{doc_in}}" bevat deze invoerdocumentgegevens als een lijst van tekenreeksen
met afwisselende betekenis.
* De tekenreeks $textline bevat iedere regel van de invoertekstgegevens.
* De tekenreeks "$filename:$linenum" bevat de locatie ervan en wordt aangeroepen
via "referentie" ("linenum" begint bij 1).
Merk op dat dit niets ontleedt. U moet de functie parse() gebruiken wanneer u klaar bent met het
inladen van invoerbestanden in het document.
write($)
Het vertaalde document schrijven naar het bestand met de opgegeven naam.
Deze vertaalde-documentgegevens worden verstrekt door:
* "$self->docheader()" dat de header-tekst voor de plug-in bevat, en
* "@{$self->{TT}{doc_out}}" dat in een lijst elke regel bevat van de vertaalde hoofdtekst.
PO-bestanden manipuleren
readpo($)
De inhoud van een bestand (waarvan de naam als argument opgegeven werd) toevoegen aan het bestaande
invoerPO-bestand. De oude inhoud wordt niet verwijderd.
writepo($)
Het geëxtraheerde PO-bestand naar het bestand schrijven waarvan de naam opgegeven werd.
stats()
Geeft bepaalde statistieken weer over de tot nu toe gemaakte vertaling. Merk op dat het niet dezelfde
statistieken zijn als die welke door msgfmt --statistic getoond worden. Hier gaat het om statistieken
over het recente gebruik van het PO-bestand, terwijl msgfmt rapporteert over de toestand van het
bestand. Het is een omhulsel voor de functie Locale::Po4a::Po::stats_get, toegepast op het invoerPO-
bestand. Een gebruiksvoorbeeld:
[normaal gebruik van het po4a-document...]
($percent,$vertaald,$totaal) = $document->stats();
print "We vonden vertalingen voor $percent\% ($vertaald op $totaal) tekstfragmenten.\n";
Addenda manipuleren
addendum($)
Raadpleeg po4a(7) voor meer informatie over wat addenda zijn en hoe vertalers ze moeten schrijven. Om
een addendum toe te passen op het vertaalde document, moet u gewoon de bestandsnaam ervan doorgeven
aan deze functie en u bent klaar ;)
Deze functie zendt bij een fout een geheel getal terug dat geen nul is.
INTERNE FUNCTIES welke gebruikt worden voor het schrijven van afgeleide ontleders
Invoer krijgen, uitvoer leveren
Er staan vier functies ter beschikking om invoer te krijgen en uitvoer af te leveren. Zij zijn erg
vergelijkbaar met shift/unshift en push/pop van Perl.
* shift in Perl zendt het eerste item uit de lijst terug en haalt het weg uit de lijst.
* unshift in Perl voegt een item toe aan de lijst als het eerste item van de lijst.
* pop in Perl zendt het laatste item uit de lijst terug en haalt het weg uit de lijst.
* push in Perl voegt een item toe aan de lijst als het laatste item van de lijst.
Het eerste paar heeft betrekking op invoer, terwijl het tweede op uitvoer betrekking heeft.
Geheugensteuntje: bij invoer bent u geïnteresseerd in de eerste regel, hetgeen shift geeft, en bij
uitvoer wilt u uw resultaat toevoegen aan het einde, zoals push doet.
shiftline()
Deze functie zendt de eerste te ontleden regel terug en zijn overeenkomstige referentie (verpakt als
lijst) uit de lijst "@{$self->{TT}{doc_in}}" en verwijdert deze eerste 2 lijstitems. Hier wordt de
referentie verstrekt door een tekenreeks "$filename:$linenum" (bestandsnaam:regelnummer).
unshiftline($$)
Plaatst de laatste met shift uit het invoerdocument verwijderde regel en zijn overeenkomstige
referentie terug aan het begin van "{$self->{TT}{doc_in}}".
pushline($)
Voegt een nieuwe regel toe aan het einde van "{$self->{TT}{doc_out}}".
popline()
Verwijdert de laatste met push toegevoegde regel aan het einde van "{$self->{TT}{doc_out}}".
Tekstfragmenten als vertaalbaar markeren
Er wordt een functie verstrekt om de tekst die moet worden vertaald, te verwerken.
translate($$$)
Verplichte argumenten:
- Een te vertalen tekstfragment
- De referentie van dit tekstfragment (d.w.z. positie in het invoerbestand)
- Het type van dit tekstfragment (d.w.z. de letterlijke beschrijving van zijn structurele rol;
gebruikt in Locale::Po4a::Po::gettextization(); zie ook po4a(7), afdeling Het gettextize-proces:
hoe werkt dit?)
Aan deze functie kunnen ook enkele extra argumenten meegegeven worden. Zij moeten als een hash
georganiseerd worden. Bijvoorbeeld:
$self->translate("tekstfragment","ref","type",
'wrap' => 1);
wrap
Booleaanse operator die aangeeft of we witruimte in tekstfragmenten al dan niet als belangrijk
moeten beschouwen. Indien ja, dan canoniseert de functie het tekstfragment voordat ze op zoek
gaat naar een vertaling of voordat ze dit fragment extraheert, en past ze regelafbreking toe op
de vertaling.
wrapcol
de kolom waar de regelafbreking moet gebeuren (standaard: 76).
comment
een aan het element toe te voegen extra commentaar.
Acties:
- Duwt tekstfragment, referentie en type naar po_out.
- Zendt de vertaling van het tekstfragment (zoals gevonden in po_in) terug, zodat de ontleder het
doc_out kan bouwen.
- Gebruikt de tekensets voor het hercoderen van de tekstfragmenten vooraleer deze naar po_out
gezonden worden en voorafgaand aan het terugzenden van de vertalingen.
Diverse functies
verbose()
Geeft aan of de optie verbose opgegeven werd tijdens de creatie van de TransTractor.
debug()
Geeft aan of de optie debug opgegeven werd tijdens de creatie van de TransTractor.
detected_charset($)
Dit informeert TransTractor dat een nieuwe tekenset (het eerste argument) aangetroffen werd in het
invoerdocument. Gewoonlijk kan dit uit de header van het document gehaald worden. Enkel de eerste
tekenset blijft behouden, afkomstig van de argumenten bij de functie process() of gedetecteerd in het
document.
get_out_charset()
Deze functie zendt terug welke tekenset gebruikt moet worden in het uitvoerdocument (gewoonlijk
nuttig om de gedetecteerde karakterset van het invoerdocument te vervangen waar dit aangetroffen
werd).
De aan de commandoregel gespecificeerde tekenset zal gebruikt worden. Indien daar niets
gespecificeerd werd, wordt de tekenset van het invoerPO-bestand gebruikt, en indien in het invoerPO-
bestand het standaard "CHARSET" vermeld staat, zal de tekenset van het invoerdocument teruggezonden
worden, zodat geen tekenhercodering uitgevoerd wordt.
recode_skipped_text($)
Deze functie zendt de als argument opgegeven tekst gehercodeerd terug van de tekenset uit het
invoerdocument naar de tekenset van het uitvoerdocument. Dit is niet nodig bij de vertaling van een
tekstfragment (translate() hercodeert alles zelf), maar wel wanneer u een tekstfragment uit het
invoerdocument overslaat en u wilt dat het uitvoerdocument consistent is met de algemene codering.
RICHTINGEN VOOR DE TOEKOMST
Een tekortkoming van het huidige TransTractor is dat het niet overweg kan met vertaalde documenten welke
alle talen bevatten, zoals debconf-sjablonen of .desktop-bestanden.
Om dit probleem aan te pakken, zijn de enige noodzakelijke aanpassingen aan de interface:
- voor po_in_name het (Perl) variabeletype hash gebruiken (een lijst per taal)
- een te vertalen argument toevoegen om de doeltaal aan te geven
- een pushline_all-functie maken, die pushline zou toepassen voor zijn inhoud voor alle talen met behulp
van een kaartachtige syntaxis:
$self->pushline_all({ "Description[".$taalcode."]=".
$self->translate($regel,$ref,$taalcode)
});
We zullen zien of dit volstaat ;)
AUTEURS
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)
Jordi Vilalta <jvprat@gmail.com>
Po4a-hulpmiddelen 2023-01-03 Locale::Po4a::TransTractor(3pm)