", ontleed. Gemakshalve gaan we ervan uit dat het document goed is opgemaakt, d.w.z. dat '
'-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/
/ && !$first--; ) { # Niet de eerste maal dat we
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/^
//s; # - de voorafgaande tag (onvertaald) naar uitvoer sturen # evenals de rest van de alinea (vertaald) $self->pushline( "
"
. $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 geimplementeerd 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 een 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 geextraheerd 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 werd, zal UTF-8 gebruikt worden).
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 UTF-8 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 geextraheerd werden.
addendum (@)
Namenlijst van de bestanden waaruit we de addenda moeten
inlezen.
addendum_charset ($)
Tekenset voor de addenda.
new(%)
Een nieuw po4a document creeren. Mogelijke opties (in de hash die
als parameter meegegeven wordt):
verbose ($)
Stelt in hoeveel informatie gegeven wordt.
debug ($)
Stelt het debuggen in.
wrapcol ($)
De kolom waar de regelafbreking moet gebeuren in het
uitvoerdocument (standaard: 76).
Een negatieve waarde betekent dat er helemaal geen
regelafbreking moet gebeuren.
Het accepteert ook de volgende opties voor onderliggende Po-
bestanden: porefs, copyright-holder, msgid-bugs-address, package-
name, package-version, wrap-po.
Documentbestanden behandelen
read($$$)
Add another input document data at the end of the existing array
"@{$self->{TT}{doc_in}}".
This function takes two mandatory arguments and an optional one.
* The filename to read on disk;
* The name to use as filename when building the reference in the
PO file;
* The charset to use to read that file (UTF-8 by default)
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 geextraheerde 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
geinteresseerd 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 waarop de regelafbreking moet gebeuren (standaard: de
waarde van wrapcol die is opgegeven tijdens het maken van de
TransTractor of 76).
De negatieve waarde wordt afgetrokken van de standaardwaarde.
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.
get_in_charset()
Deze functie geeft de tekenset terug die als hoofdtekenset is
opgegeven
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.
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