NOM¶
Locale::Po4a::TransTractor - Traducteur et extracteur générique
DESCRIPTION¶
L'objectif du projet po4a [PO for anything -- PO pour tout] est de simplifier la
traduction (et de façon plus intéressante, la maintenance des
traductions) en utilisant les outils gettext dans des domaines pour lesquels
ils n'étaient pas destinés, comme la documentation.
Cette classe est l'ancêtre de tous les analyseurs po4a utilisés pour
lire un document, y chercher les chaînes traduisibles, les extraire dans
un fichier PO, et les remplacer par leur traduction dans le document
généré.
Plus formellement, elle prend les paramètres d'entrée suivants :
- -
- un document à traduire ;
- -
- un fichier PO contenant les traductions à
utiliser.
En sortie, elle produit :
- -
- un autre fichier PO, résultat de l'extraction des
chaînes traduisibles du document en entrée ;
- -
- un document traduit, partageant la même structure que
celui en entrée, mais dont toutes les chaînes traduisibles ont
été remplacées par les traductions trouvées dans le
fichier PO fourni en entrée.
Voici une représentation graphique de tout cela :
document entrée --\ /---> document sortie
\ / (traduit)
+-> parse() function -----+
/ \
PO entrée --------/ \---> PO sortie
(extrait)
FONCTIONS QUE VOTRE ANALYSEUR DOIT SURCHARGER¶
- parse()
- Il s'agit de la fonction principale où tout le travail
a lieu : la lecture des documents en entrée, la
génération des documents en sortie et l'extraction des
chaînes traduisibles. Tout ceci est assez simple avec les fonctions
fournies et présentées dans la section FONCTIONS INTERNES
ci-dessous. Veuillez aussi vous reporter à la section
SYNOPSIS, qui présente un exemple.
Cette fonction est appelée par la fonction process() ci-dessous,
mais si vous choisissez d'utiliser la fonction new(), et d'ajouter
le contenu manuellement, vous devrez appeler cette fonction
vous-même.
- docheader()
- Cette fonction renvoie l'en-tête que nous devons
ajouter au document produit, formaté comme il faut pour qu'il soit un
commentaire pour le langage cible. Reportez-vous à la section
Éduquer les développeurs au problème des
traductions, dans po4a(7).
SYNOPSIS¶
L'exemple suivant analyse une liste de paragraphes commençant par
« <p ».> Pour simplifier, nous supposons que le document
est bien formaté, c'est-à-dire que la balise <p> est la seule
présente et que cette balise se trouve au début 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/<p>/ && !$premier--; ) {
# Ce n'est pas la première balise <p>.
# 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/^<p>//s;
# - Poussons la balise de tête (à ne pas traduire) et le
# reste du paragraphe (à traduire) dans le document de
# sortie
$self->pushline( "<p>"
. $document->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;
}
}
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.
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 paramètres doivent
être fournis sous forme de table de hachage. Voici les
différentes actions possibles :
- a.
- lit tous les fichiers PO spécifiés dans
po_in_name ;
- b.
- lit tous les documents originaux spécifiés dans
file_in_name ;
- c.
- analyse le document ;
- d.
- lit et applique tous les addenda
spécifiés ;
- e.
- écrit le document traduit dans file_out_name (si
spécifié) ;
- f.
- écrit le fichier PO extrait dans po_out_name (si
spécifié).
PARAMÈTRES, en plus de ceux acceptés par
new(), ainsi que leur
type :
- file_in_name (@)
- Liste de noms de fichiers d'où lire les documents en
entrée.
- 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).
- file_out_name ($)
- Nom de fichier où écrire le document en
sortie.
- 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 PO sera
utilisé).
- 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).
- po_out_name ($)
- Nom de fichier où écrire le fichier PO de sortie
(celui contenant les chaînes extraites du document
d'entrée).
- addendum (@)
- Liste de noms de fichiers d'où lire les addenda à
appliquer.
- addendum-charset ($)
- Jeu de caractères des addenda.
- new(%)
- Créer un nouveau document po4a. Options acceptées
(sous forme de hachage) :
- verbose ($)
- Règle le niveau de bavardage.
- debug ($)
- Règle le niveau de débogage.
Manipuler les documents¶
- read($)
- Ajouter un nouveau document d'entrée après ceux
déjà ajoutés. Le paramètre est le nom du fichier
à lire.
Notez que cette fonction n'analyse pas le fichier donné. Il faut
utiliser parse() pour cela une fois que vous avez ajouté au
document tous les fichiers que vous souhaitez analyser.
- write($)
- Écrire le document traduit dans le fichier dont le nom
est passé en paramètre.
Manipuler les fichiers PO¶
- 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é.
- writepo($)
- Écrire le PO extrait dans le fichier dont le nom est
passé en paramètre.
- 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 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 :
[utilisation normal d'un document po4a...]
($pourcent,$traduit,$total) = $document->stats();
print "Des traductions ont été trouvées pour $pourcent\% ($traduit sur $total) des chaînes.\n";
Manipuler les addenda¶
- addendum($)
- Veuillez vous reporter à po4a(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 ;)
Cette fonction renvoie un entier non nul en cas d'erreur.
FONCTIONS INTERNES utilisées pour dériver un analyseur
(parser)¶
Récupération de l'entrée, génération de
la sortie¶
Quatre fonctions sont fournies pour récupérer l'entrée et
renvoyer la sortie. Elles sont très similaires aux couples shift/unshift
et push/pop. 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.
- shiftline()
- Cette fonction renvoie le ligne suivante du document
d'entrée qui est analysé, ainsi que sa référence (les
deux étant placées dans un tableau).
- unshiftline($$)
- Récupère une ligne du document d'entrée,
ainsi que sa référence.
- pushline($)
- Ajoute une nouvelle ligne dans le document de sortie.
- popline()
- Récupère (pop) la dernière ligne
poussée dans le document de sortie.
Marquage des chaînes à traduire¶
Une fonction est fournie pour gérer le texte qui doit être traduit.
- translate($$$)
- Paramètres obligatoires :
- -
- la chaîne à traduire ;
- -
- la référence de cette chaîne (c.-à-d.,
sa position dans le fichier d'entrée) ;
- -
- le type de la chaîne (c.-à-d., la description
textuelle de son rôle structurel ; utilisé dans
Locale::Po4a::Po::gettextization() ; consultez également
po4a(7), section Gettextization : Comment ça
marche ?).
Cette fonction peut également prendre des paramètres
supplémentaires. Ils doivent être organisés sous forme de table
de hachage. Par exemple :
$self->translate("chaîne","référence","type",
'wrap' => 1);
- 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.
- wrapcol
- la colonne à laquelle les retours à la ligne
doivent avoir lieu (76 par défaut).
- comment
- un commentaire additionnel à ajouter à
l'entrée du PO.
Action :
- -
- pousse la chaîne, la référence et le type
dans le PO de sortie ;
- -
- renvoie la traduction de la chaîne (trouvée dans
po_in) de façon à ce que l'analyseur (parser) puisse construire
doc_out ;
- -
- gère les jeux de caractères pour recoder les
chaînes avant de les envoyer à po_out et avant de renvoyer la
traduction.
Fonctions diverses¶
- verbose()
- Indique si le mode bavard a été activé lors
de la création du Transtractor.
- debug()
- Indique si l'option de débogage a été
fournie lors de la création du Transtractor.
- 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 process() ou
détecté dans le document.
- 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).
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 PO d'entrée, et si ce fichier PO
utilise la valeur par défaut « CHARSET », et
aucun encodage n'est réalisé.
- 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 ( translate()
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.
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.
Pour répondre à ce problème, les seules modifications d'interface
nécessaires sont :
- -
- utiliser une table de hachage pour po_in_name (une liste
par langue) ;
- -
- ajouter un paramètre à traduire pour indiquer la
langue cible ;
- -
- créer une fonction pushline_all, qui utiliserait
pushline pour le contenu de toutes ses langues, en utilisant map :
$self->pushline_all({ "Description[".$code_langue."]=".
$self->translate($ligne,$réf,$code_langue)
});
Nous verrons si c'est suffisant ;)
AUTEURS¶
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)
Jordi Vilalta <jvprat@gmail.com>