>>. Pour simplifier, nous supposons que le document est bien formate, c'est-a-dire que la balise
est la seule presente et que cette balise se trouve au debut de chaque paragraphe. 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--; ) { # Not the first time we see
. # Reput the current line in input, # and put the built paragraph to output $self->unshiftline($line,$lref); # Now that the document is formed, translate it: # - Remove the leading tag $paragraph =~ s/^
//s; # - push to output the leading tag (untranslated) and the # rest of the paragraph (translated) $self->pushline( "
"
. $self->translate($paragraph,$pararef)
);
next PARAGRAPH;
} else {
# Append to the paragraph
$paragraph .= $line;
$pararef = $lref unless(length($pararef));
}
# Reinit the loop
($line,$lref)=$self->shiftline();
}
# Did not get a defined line? End of input file.
return;
}
}
Une fois que vous avez implemente la fonction parse, vous pouvez
utiliser cette nouvelle classe en utilisant l'interface publique
presentee dans la section suivante.
INTERFACE PUBLIQUE pour les scripts utilisant votre analyseur
Constructeur
process(%)
Cette fonction peut faire tout ce dont vous avez besoin avec un
document po4a en une seule invocation. Ses parametres doivent etre
fournis sous forme de table de hachage. Voici les differentes
actions possibles :
a. Lit tous les fichiers PO specifies dans po_in_name
b. Lit tous les documents originaux specifies dans file_in_name
c. Analyse le document
d. Lit et applique tous les addendas specifies
e. Ecrit le document traduit dans file_out_name (si specifie)
f. Ecrit le fichier PO extrait dans po_out_name (si specifie)
PARAMETRES, en plus de ceux acceptes par new(), ainsi que leur type
:
file_in_name (@)
Liste de noms de fichiers d'ou lire les documents en entree.
file_in_charset ($)
Le jeu de caracteres du document d'entree (s'il n'est pas
specifie, UTF-8 sera utilise).
file_out_name ($)
Nom de fichier ou ecrire le document en sortie.
file_out_charset ($)
Le jeu de caracteres du document de sortie (s'il n'est pas
specifie, UTF-8 sera utilise).
po_in_name (@)
Liste de noms de fichiers d'ou lire les fichiers PO d'entree
(ceux contenant les traductions a utiliser pour la traduction
du document).
po_out_name ($)
Nom de fichier ou ecrire le fichier PO de sortie (celui
contenant les chaines extraites du document d'entree).
addendum (@)
Liste de noms de fichiers d'ou lire les addendas a appliquer.
addendum-charset ($)
Jeu de caracteres des addendas.
new(%)
Creer un nouveau document po4a. Options acceptees (dans le hachage
passe en tant que parametre) :
verbose ($)
Regle le niveau de bavardage.
debug ($)
Regle le niveau de debogage.
wrapcol ($)
La colonne a laquelle le texte doit etre tronque dans le
document genere (76 par defaut).
Une valeur negative signifie de ne pas du tout tronquer les
lignes.
Le logiciel accepte egalement les options suivantes pour les
fichiers Po sous-jacents: porefs, copyright-holder,
msgid-bugs-address, package-name, package-version, wrap-po.
Manipuler les documents
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)
This array "@{$self->{TT}{doc_in}}" holds this input document data
as an array of strings with alternating meanings.
* The string $textline holding each line of the input text data.
* The string "$filename:$linenum" holding its location and called
as
"reference" ("linenum" starts with 1).
Notez que cette fonction n'analyse pas le fichier donne. Il faut
utiliser parse() pour cela une fois que vous avez ajoute au
document tous les fichiers que vous souhaitez analyser.
write($)
Ecrire le document traduit dans le fichier dont le nom est passe en
parametre.
This translated document data are provided by:
* "$self->docheader()" holding the header text for the plugin, and
* "@{$self->{TT}{doc_out}}" holding each line of the main
translated text in the array.
Manipuler les fichiers PO
readpo($)
Ajouter le contenu du fichier dont le nom est passe en parametre au
PO d'entree. Notez que l'ancien contenu du PO d'entree n'est pas
efface.
writepo($)
Ecrire le PO extrait dans le fichier dont le nom est passe en
parametre.
stats()
Renvoie des statistiques a propos de la traduction. Notez que ce ne
sont pas les statistiques affichees par msgfmt --statistic. Dans ce
cas, il s'agit des statistiques concernant l'utilisation recente du
fichier PO, tandis que msgfmt renseigne sur le statut du fichier
PO. Il s'agit d'une encapsulation autour de la fonction
Locale::Po4a::Po::stats_get en utilisant le fichier PO en entree.
Voici un exemple d'utilisation:
[normal use of the po4a document...]
($percent,$hit,$queries) = $document->stats();
print "We found translations for $percent\% ($hit from $queries) of strings.\n";
Manipuler les addenda
addendum($)
Referez-vous a po4a(7) pour en savoir plus sur ce que sont les
addendas et comment les equipes de traduction doivent les ecrire.
Pour appliquer un addendum au document traduit, il suffit de
fournir le nom du fichier a cette fonction, et c'est fini ;-)
Cette fonction renvoie un entier non nul en cas d'erreur.
FONCTIONS INTERNES utilisees pour ecrire un analyseur (parser) derive
Recuperation de l'entree, generation de la sortie
Quatre fonctions sont prevues pour obtenir l'entree et retourner la
sortie. Elles sont tres similaires aux fonctions shift/unshift et
push/pop de Perl.
* Perl shift returns the first array item and drop it from the array.
* Perl unshift prepends an item to the array as the first array item.
* Perl pop returns the last array item and drop it from the array.
* Perl push appends an item to the array as the last array item.
La premiere paire concerne l'entree, et la seconde la sortie. Moyen
mnemotechnique : en entree, on veut recuperer la premiere ligne, ce que
shift permet ; en sortie on veut ajouter le resultat a la fin, ce que
fait push.
shiftline()
Cette fonction renvoie la premiere ligne a analyser et sa reference
correspondante (presentee sous forme de tableau) a partir du
tableau "<@{$self-"{TT}{doc_in}}>> et supprime ces 2 premiers
elements du tableau. Ici, la reference est fournie par une chaine
"<$filename:$linenum">.
unshiftline($$)
Remets la derniere ligne recuperee avec shiftline() au debut du
tableau "{$self->{TT}{doc_in}}".
pushline($)
Ajoute une nouvelle ligne a la fin de "{$self->{TT}{doc_out}}".
popline()
Recupere (pop) la derniere ligne poussee a la fin de
"{$self->{TT}{doc_out}}".
Marquage des chaines a traduire
Une fonction est fournie pour gerer le texte qui doit etre traduit.
translate($$$)
Parametres obligatoires :
- Une chaine a traduire
- La reference de cette chaine (c.-a-d., sa position dans le
fichier d'entree)
- le type de la chaine (c.-a-d., la description textuelle de son
role structurel ; utilise dans
Locale::Po4a::Po::gettextization() ; consultez egalement po4a(7),
section Gettextisation: Comment ca marche?).
Cette fonction peut egalement prendre des parametres
supplementaires. Ils doivent etre organises sous forme de table de
hachage. Par exemple :
$self->translate("string","ref","type",
'wrap' => 1);
wrap
booleen indiquant si on peut considerer que les espaces des
chaines ne sont pas importants. Dans ce cas, la fonction cree
une forme canonique de la chaine avant de rechercher une
traduction ou de l'extraire et ajoute des retours a la ligne a
la traduction.
wrapcol
la colonne a laquelle nous devrions tronquer (par defaut: la
valeur de B