Provided by: po4a_0.66-1_all 
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;
# - pousser la balise de tête en sortie (non-traduite) et le
# reste du paragraphe (traduit)
$self->pushline( "<p>"
. $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;
}
}
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(%)
Create a new po4a document. Accepted options (in the hash passed as a parameter):
verbose ($)
Règle le niveau de bavardage.
debug ($)
Règle le niveau de débogage.
Manipuler les documents
read($$)
Ajouter une nouvelle donnée de document d’entrée à la fin de la table "@{$self->{TT}{doc_in}}". 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.
Ce tableau "@{$self->{TT}{doc_in}}" 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 $textline contenant chaque ligne des données du texte d'entrée.
* La chaîne "$filename:$linenum" contenant son emplacement et appelée
"reference" ("linenum" commence par 1).
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.
Les données de ce document traduit sont fournies par :
* "$self->docheader()" contenant le texte d'en-tête 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 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";
is_po_uptodate()
Retours ($uptodate, $diagnostic) où $uptodate 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 $diagnostic est une chaîne
expliquant pourquoi le fichier po n’est pas à jour, le cas échéant.
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 écrire un analyseur (parser) dérivé
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.
* 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.
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 la première ligne à analyser et sa référence correspondante (présentée sous
forme de tableau) à partir du tableau "<@{$self-"{TT}{doc_in}}>> et supprime ces 2 premiers éléments
du tableau. Ici, la référence est fournie par une chaîne "<$filename:$linenum">.
unshiftline($$)
Remets la dernière ligne récupérée avec shiftline() au début du tableau "{$self->{TT}{doc_in}}".
pushline($)
Ajoute une nouvelle ligne à la fin de "{$self->{TT}{doc_out}}".
popline()
Récupère (pop) la dernière ligne poussée à la fin de "{$self->{TT}{doc_out}}".
Marquage des chaînes à traduire
Une fonction est fournie pour gérer le texte qui doit être traduit.
translate($$$)
Paramètres obligatoires :
- Une 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.
Actions :
- 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>
TRADUCTION
Martin Quinson (mquinson#debian.org)
Outils po4a 2022-01-02 Locale::Po4a::TransTractor(3pm)