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 \s-1PO\s0 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 addenda 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 \s-1PO\s0 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é, il
essayera de le détecter à partir du document).
.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é, le jeu
de caractères du fichier \s-1PO\s0 sera utilisé).
.IP "po_in_name (@)" 4
.IX Item "po_in_name (@)"
Liste de noms de fichiers d’où lire les fichiers \s-1PO\s0 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 \s-1PO\s0 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 addenda à appliquer.
.IP "addendum-charset ($)" 4
.IX Item "addendum-charset ($)"
Jeu de caractères des addenda.
.RE
.RS 4
.RE
.IP "new(%)" 4
.IX Item "new(%)"
Créer un nouveau document po4a. Options acceptées (sous forme de hachage) :
.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.
.RE
.RS 4
.RE
.SS "Manipuler les documents"
.IX Subsection "Manipuler les documents"
.IP "read($$)" 4
.IX Item "read($$)"
Ajouter une nouvelle donnée de document d’entrée à la fin de la table \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR. Le paramètre est le nom du fichier à lire. Si un
second paramètre est fourni, cela sera le nom de fichier à utiliser dans les
références.
.Sp
This array \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR holds this input document data as an
array of strings with alternating meanings.
* The string \f(CW$textline\fR holding each line of the input text data.
* The string \f(CW\*(C`$filename:$linenum\*(C'\fR holding its location and called as
\*(L"reference\*(R" (\f(CW\*(C`linenum\*(C'\fR starts with 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
This translated document data are provided by:
* \f(CW\*(C`$self\->docheader()\*(C'\fR holding the header text for the plugin, and
* \f(CW\*(C`@{$self\->{TT}{doc_out}}\*(C'\fR holding each line of the main translated text in the array.
.SS "Manipuler les fichiers \s-1PO\s0"
.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 \s-1PO\s0
d’entrée. Notez que l’ancien contenu du \s-1PO\s0 d’entrée n’est pas effacé.
.IP "writepo($)" 4
.IX Item "writepo($)"
Écrire le \s-1PO\s0 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. Veuillez noter 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 \s-1PO,\s0
tandis que msgfmt renseigne sur le statut du fichier \s-1PO.\s0 Il s’agit d’une
encapsulation autour de la fonction Locale::Po4a::Po::stats_get en utilisant
le fichier \s-1PO\s0 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
.IP "\fBis_po_uptodate()\fR" 4
.IX Item "is_po_uptodate()"
Retours ($uptodate, \f(CW$diagnostic\fR) où \f(CW$uptodate\fR est si le po d’entrée et celui
de sortie correspondent (sinon, cela signifie que le po d’entrée devrait
être mis à jour) et \f(CW$diagnostic\fR est une chaîne expliquant pourquoi le
fichier po n’est pas à jour, le cas échéant.
.SS "Manipuler les addenda"
.IX Subsection "Manipuler les addenda"
.IP "addendum($)" 4
.IX Item "addendum($)"
Veuillez vous reporter à \fBpo4a\fR\|(7) pour plus d’informations sur ce
que sont les addenda et comment les traducteurs doivent les écrire. Pour
appliquer un addendum au document traduit, vous n’avez qu’à 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"
Four functions are provided to get input and return output. They are very
similar to shift/unshift and push/pop of Perl.
.PP
.Vb 4
\& * 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.
.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()"
This function returns the first line to be parsed and its corresponding
reference (packed as an array) from the array \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR
and drop these first 2 array items. Here, the reference is provided by a
string \f(CW\*(C`$filename:$linenum\*(C'\fR.
.IP "unshiftline($$)" 4
.IX Item "unshiftline($$)"
Unshifts the last shifted line of the input document and its corresponding
reference back to the head of \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 \fBGettextization : 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 les retours à la ligne doivent avoir lieu (76 par
défaut).
.IP "\fBcomment\fR" 4
.IX Item "comment"
un commentaire additionnel à ajouter à l’entrée du \s-1PO.\s0
.RE
.RS 4
.Sp
Actions :
.IP "\-" 2
Pousse la chaîne, la référence et le type dans le \s-1PO\s0 de sortie.
.IP "\-" 2
Renvoie la traduction de la chaîne (trouvée dans po_in) de façon à ce que
l’analyseur (parser) puisse construire doc_out.
.IP "\-" 2
gère les jeux de caractères pour recoder les chaînes avant de les envoyer à
po_out et avant de renvoyer la traduction.
.RE
.RS 4
.RE
.SS "Fonctions diverses"
.IX Subsection "Fonctions diverses"
.IP "\fBverbose()\fR" 4
.IX Item "verbose()"
Indique si le mode bavard a été activé lors de la création du Transtractor.
.IP "\fBdebug()\fR" 4
.IX Item "debug()"
Indique si l’option de débogage a été fournie lors de la création du
Transtractor.
.IP "detected_charset($)" 4
.IX Item "detected_charset($)"
Indique à TransTractor qu’un nouveau jeu de caractères (premier paramètre) a
été détecté dans le document d’entrée. Il est en règle général lu dans
l’en\-tête du document. Seul le premier jeu de caractères restera, qu’il soit
fourni par les paramètres de \fBprocess()\fR ou détecté dans le document.
.IP "\fBget_out_charset()\fR" 4
.IX Item "get_out_charset()"
Cette fonction renverra le jeu de caractères qui doit être utilisé dans le
document de sortie (souvent utile pour substituer le jeu de caractères qui a
été détecté dans le document d’entrée).
.Sp
Il utilisera le jeu de caractères spécifié sur la ligne de commande. S’il
n’a pas été spécifié, il utilisera le jeu de caractère du fichier \s-1PO\s0
d’entrée, et si ce fichier \s-1PO\s0 utilise la valeur par défaut « \s-1CHARSET\s0 »,
et aucun encodage n’est réalisé.
.IP "recode_skipped_text($)" 4
.IX Item "recode_skipped_text($)"
Cette fonction réencode le texte donné en paramètre, du jeu de caractères du
document d’entrée vers le jeu de caractères du document de sortie. Ce n’est
pas nécessaire quand les chaînes sont traduites (\fBtranslate()\fR réencode tout
d’elle\-même), mais ça l’est lorsque vous sautez des chaînes du document
d’entrée et que vous voulez que le document de sortie utilise un encodage
uniforme.
.SH "DIRECTIONS FUTURES"
.IX Header "DIRECTIONS FUTURES"
Une des imperfections du TransTractor actuel est qu’il ne peut pas gérer de
documents traduits contenant toutes les langues, comme les modèles debconf
ou les fichiers .desktop.
.PP
Pour répondre à ce problème, les seules modifications d’interface
nécessaires sont :
.IP "\-" 2
utiliser une table de hachage pour po_in_name (une liste par langue)
.IP "\-" 2
ajouter un paramètre à traduire pour indiquer la langue cible
.IP "\-" 2
créer une fonction pushline_all, qui utiliserait pushline pour le contenu de
toutes ses langues, en utilisant map :
.Sp
.Vb 3
\& $self\->pushline_all({ "Description[".$code_langue."]=".
\& $self\->translate($ligne,$réf,$code_langue)
\& });
.Ve
.PP
Nous verrons si c’est suffisant ;)
.SH "AUTEURS"
.IX Header "AUTEURS"
.Vb 3
\& Denis Barbier