\ ». Pour simplifier, nous supposons que le document est bien formaté, c’est\-à\-dire que la balise
est la seule présente et que cette balise se trouve au début de chaque paragraphe. .PP .Vb 2 \& 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 première balise
. \& # Remet la ligne actuelle dans le document d’entrée, \& # et met le paragraphe dans la sortie \& $self\->unshiftline($line,$lref); \& \& # Maintenant que le document est formé, il faut le traduire : \& # \- Retirons les balises de tête \& $paragraphe =~ s/^
//s; \& \& # \- pousser la balise de tête en sortie (non\-traduite) et le \& # reste du paragraphe (traduit) \& $self\->pushline( "
"
\& . $self\->translate($paragraphe,$pararef)
\& );
\&
\& next PARAGRAPHE;
\& } else {
\& # Ajout à 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’entrée.
\& return;
\& }
\& }
.Ve
.PP
Une fois que vous avez implémenté la fonction parse, vous pouvez utiliser cette nouvelle classe en utilisant l’interface publique présentée dans la section suivante.
.SH "INTERFACE PUBLIQUE pour les scripts utilisant votre analyseur"
.IX Header "INTERFACE PUBLIQUE pour les scripts utilisant votre analyseur"
.SS Constructeur
.IX Subsection "Constructeur"
.IP process(%) 4
.IX Item "process(%)"
Cette fonction peut faire tout ce dont vous avez besoin avec un document po4a en une seule invocation. Ses paramètres doivent être fournis sous forme de table de hachage. Voici les différentes actions possibles :
.RS 4
.IP a. 3
.IX Item "a."
Lit tous les fichiers PO spécifiés dans po_in_name
.IP b. 3
.IX Item "b."
Lit tous les documents originaux spécifiés dans file_in_name
.IP c. 3
.IX Item "c."
Analyse le document
.IP d. 3
.IX Item "d."
Lit et applique tous les addendas spécifiés
.IP e. 3
.IX Item "e."
Écrit le document traduit dans file_out_name (si spécifié)
.IP f. 3
.IX Item "f."
Écrit le fichier PO extrait dans po_out_name (si spécifié)
.RE
.RS 4
.Sp
PARAMÈTRES, en plus de ceux acceptés par \fBnew()\fR, ainsi que leur type :
.IP "file_in_name (@)" 4
.IX Item "file_in_name (@)"
Liste de noms de fichiers d’où lire les documents en entrée.
.IP "file_in_charset ($)" 4
.IX Item "file_in_charset ($)"
Le jeu de caractères du document d'entrée (s’il n’est pas spécifié, UTF\-8 sera utilisé).
.IP "file_out_name ($)" 4
.IX Item "file_out_name ($)"
Nom de fichier où écrire le document en sortie.
.IP "file_out_charset ($)" 4
.IX Item "file_out_charset ($)"
Le jeu de caractères du document de sortie (s’il n’est pas spécifié, UTF\-8 sera utilisé).
.IP "po_in_name (@)" 4
.IX Item "po_in_name (@)"
Liste de noms de fichiers d’où lire les fichiers PO d’entrée (ceux contenant les traductions à utiliser pour la traduction du document).
.IP "po_out_name ($)" 4
.IX Item "po_out_name ($)"
Nom de fichier où écrire le fichier PO de sortie (celui contenant les chaînes extraites du document d’entrée).
.IP "addendum (@)" 4
.IX Item "addendum (@)"
Liste de noms de fichiers d’où lire les addendas à appliquer.
.IP "addendum-charset ($)" 4
.IX Item "addendum-charset ($)"
Jeu de caractères des addendas.
.RE
.RS 4
.RE
.IP new(%) 4
.IX Item "new(%)"
Créer un nouveau document po4a. Options acceptées (dans le hachage passé en tant que paramètre) :
.RS 4
.IP "verbose ($)" 4
.IX Item "verbose ($)"
Règle le niveau de bavardage.
.IP "debug ($)" 4
.IX Item "debug ($)"
Règle le niveau de débogage.
.IP "wrapcol ($)" 4
.IX Item "wrapcol ($)"
La colonne à laquelle le texte doit être tronqué dans le document généré (76 par défaut).
.Sp
Une valeur négative signifie de ne pas du tout tronquer les lignes.
.RE
.RS 4
.Sp
Le logiciel accepte également les options suivantes pour les fichiers Po sous-jacents : \fBporefs\fR, \fBcopyright-holder\fR, \fBmsgid-bugs-address\fR, \fBpackage-name\fR, \fBpackage-version\fR, \fBwrap-po\fR.
.RE
.SS "Manipuler les documents"
.IX Subsection "Manipuler les documents"
.IP read($$$) 4
.IX Item "read($$$)"
Add another input document data at the end of the existing array \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR.
.Sp
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)
.Sp
Ce tableau \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR contient les données des documents d'entrée
comme un ensemble de chaînes de caractères dont les significations alternent.
* La chaîne \f(CW$textline\fR contenant chaque ligne des données du texte d'entrée.
* La chaîne \f(CW\*(C`$filename:$linenum\*(C'\fR contenant son emplacement et appelée
"reference" (\f(CW\*(C`linenum\*(C'\fR commence par 1).
.Sp
Notez que cette fonction n’analyse pas le fichier donné. Il faut utiliser \fBparse()\fR pour cela une fois que vous avez ajouté au document tous les fichiers que vous souhaitez analyser.
.IP write($) 4
.IX Item "write($)"
Écrire le document traduit dans le fichier dont le nom est passé en paramètre.
.Sp
Les données de ce document traduit sont fournies par :
* \f(CW\*(C`$self\->docheader()\*(C'\fR contenant le texte d'en\-tête du plugin, et
* \f(CW\*(C`@{$self\->{TT}{doc_out}}\*(C'\fR contenant chaque ligne du texte principal traduit dans le tableau.
.SS "Manipuler les fichiers PO"
.IX Subsection "Manipuler les fichiers PO"
.IP readpo($) 4
.IX Item "readpo($)"
Ajouter le contenu du fichier dont le nom est passé en paramètre au PO d’entrée. Notez que l’ancien contenu du PO d’entrée n’est pas effacé.
.IP writepo($) 4
.IX Item "writepo($)"
Écrire le PO extrait dans le fichier dont le nom est passé en paramètre.
.IP \fBstats()\fR 4
.IX Item "stats()"
Renvoie des statistiques à propos de la traduction. Notez que ce ne sont pas les statistiques affichées par msgfmt \-\-statistic. Dans ce cas, il s’agit des statistiques concernant l’utilisation récente 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 entrée. Voici un exemple d’utilisation :
.Sp
.Vb 1
\& [utilisation normal d’un document po4a...]
\&
\& ($pourcent,$traduit,$total) = $document\->stats();
\& print "Des traductions ont été trouvées pour $pourcent\e% ($traduit sur $total) des chaînes.\en";
.Ve
.SS "Manipuler les addenda"
.IX Subsection "Manipuler les addenda"
.IP addendum($) 4
.IX Item "addendum($)"
Référez\-vous à \fBpo4a\fR\|(7) pour en savoir plus sur ce que sont les addendas et comment les équipes de traduction doivent les écrire. Pour appliquer un addendum au document traduit, il suffit de fournir le nom du fichier à cette fonction, et c’est fini\ \ ;\-)
.Sp
Cette fonction renvoie un entier non nul en cas d’erreur.
.SH "FONCTIONS INTERNES utilisées pour écrire un analyseur (parser) dérivé"
.IX Header "FONCTIONS INTERNES utilisées pour écrire un analyseur (parser) dérivé"
.SS "Récupération de l’entrée, génération de la sortie"
.IX Subsection "Récupération de l’entrée, génération de la sortie"
Quatre fonctions sont prévues pour obtenir l'entrée et retourner la sortie. Elles sont très similaires aux fonctions shift/unshift et push/pop de Perl.
.PP
.Vb 4
\& * shift de Perl renvoie le premier élément du tableau et le supprime du tableau.
\&\ * unshift de Perl ajoute un élément au tableau comme premier élément du tableau.
\&\ * pop de Perl renvoie le dernier élément du tableau et le supprime du tableau.
\&\ * push de Perl ajoute un élément au tableau comme dernier élément du tableau.
.Ve
.PP
La première paire concerne l’entrée, et la seconde la sortie. Moyen mnémotechnique\ : en entrée, on veut récupérer la première ligne, ce que shift permet\ ; en sortie on veut ajouter le résultat à la fin, ce que fait push.
.IP \fBshiftline()\fR 4
.IX Item "shiftline()"
Cette fonction renvoie la première ligne à analyser et sa référence correspondante (présentée sous forme de tableau) à partir du tableau \f(CW\*(C`<@{$self\-\*(C'\fR{TT}{doc_in}}>> et supprime ces 2 premiers éléments du tableau. Ici, la référence est fournie par une chaîne \f(CW\*(C`<$filename:$linenum\*(C'\fR>.
.IP unshiftline($$) 4
.IX Item "unshiftline($$)"
Remets la dernière ligne récupérée avec \fBshiftline()\fR au début du tableau \f(CW\*(C`{$self\->{TT}{doc_in}}\*(C'\fR.
.IP pushline($) 4
.IX Item "pushline($)"
Ajoute une nouvelle ligne à la fin de \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR.
.IP \fBpopline()\fR 4
.IX Item "popline()"
Récupère (pop) la dernière ligne poussée à la fin de \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR.
.SS "Marquage des chaînes à traduire"
.IX Subsection "Marquage des chaînes à traduire"
Une fonction est fournie pour gérer le texte qui doit être traduit.
.IP translate($$$) 4
.IX Item "translate($$$)"
Paramètres obligatoires :
.RS 4
.IP \- 2
Une chaîne à traduire
.IP \- 2
La référence de cette chaîne (c.\-à\-d., sa position dans le fichier d’entrée)
.IP \- 2
le type de la chaîne (c.\-à\-d., la description textuelle de son rôle structurel\ ; utilisé dans \fBLocale::Po4a::Po::gettextization()\fR\ ; consultez également \fBpo4a\fR\|(7), section \fBGettextisation : Comment ça marche ?\fR).
.RE
.RS 4
.Sp
Cette fonction peut également prendre des paramètres supplémentaires. Ils doivent être organisés sous forme de table de hachage. Par exemple :
.Sp
.Vb 2
\& $self\->translate("chaîne","référence","type",
\& \*(Aqwrap\*(Aq => 1);
.Ve
.IP \fBwrap\fR 4
.IX Item "wrap"
booléen indiquant si on peut considérer que les espaces des chaînes ne sont pas importants. Dans ce cas, la fonction crée une forme canonique de la chaîne avant de rechercher une traduction ou de l’extraire et ajoute des retours à la ligne à la traduction.
.IP \fBwrapcol\fR 4
.IX Item "wrapcol"
la colonne à laquelle nous devrions tronquer (par défaut : la valeur de B