>>. 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; PARAGRAPHE: while (1) { my ($paragraphe,$pararef)=("",""); my $premier=1; ($ligne,$lref)=$self->shiftline(); while (defined($ligne)) { if ($ligne =~ m/
/ && !$premier--; ) { # Ce n'est pas la premiere balise
. # Remet la ligne actuelle dans le document d'entree, # et met le paragraphe dans la sortie $self->unshiftline($line,$lref); # Maintenant que le document est forme, il faut le traduire : # - Retirons les balises de tete $paragraphe =~ s/^
//s; # - pousser la balise de tete en sortie (non-traduite) et le # reste du paragraphe (traduit) $self->pushline( "
"
. $self->translate($paragraphe,$pararef)
);
next PARAGRAPHE;
} else {
# Ajout a la fin du paragraphe
$paragraphe .= $ligne;
$pararef = $lref unless(length($pararef));
}
# Re-initialise la boucle
($ligne,$lref)=$self->shiftline();
}
# Aucune nouvelle ligne ? C'est la fin du fichier d'entree.
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)
Ce tableau "@{$self->{TT}{doc_in}}" contient les donnees des
documents d'entree comme un ensemble de chaines de caracteres dont
les significations alternent.
* La chaine $textline contenant chaque ligne des donnees du texte
d'entree.
* La chaine "$filename:$linenum" contenant son emplacement et
appelee
"reference" ("linenum" commence par 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.
Les donnees de ce document traduit sont fournies par :
* "$self->docheader()" contenant le texte d'en-tete du plugin, et
* "@{$self->{TT}{doc_out}}" contenant chaque ligne du texte
principal traduit dans le tableau.
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:
[utilisation normal d'un document po4a...]
($pourcent,$traduit,$total) = $document->stats();
print "Des traductions ont ete trouvees pour $pourcent\% ($traduit sur $total) des chaines.\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.
* shift de Perl renvoie le premier element du tableau et le supprime du tableau.
* unshift de Perl ajoute un element au tableau comme premier element du tableau.
* pop de Perl renvoie le dernier element du tableau et le supprime du tableau.
* push de Perl ajoute un element au tableau comme dernier element du tableau.
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("chaine","reference","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