| Locale::Po4a::TransTractor(3pm) | Outils po4a | Locale::Po4a::TransTractor(3pm) |
Locale::Po4a::TransTractor - Traducteur et extracteur générique.
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 :
En sortie, elle produit :
Voici une représentation graphique de tout cela :
document entrée --\ /---> document sortie
\ / (traduit)
+-> parse() function -----+
/ \
PO entrée --------/ \---> PO sortie
(extrait)
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.
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.
PARAMÈTRES, en plus de ceux acceptés par new(), ainsi que leur type :
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.
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.
[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";
Cette fonction renvoie un entier non nul en cas d’erreur.
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.
Une fonction est fournie pour gérer le texte qui doit être traduit.
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);
Actions :
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é.
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 :
$self->pushline_all({ "Description[".$code_langue."]=".
$self->translate($ligne,$réf,$code_langue)
});
Nous verrons si c’est suffisant ;)
Denis Barbier <barbier@linuxfr.org> Martin Quinson (mquinson#debian.org) Jordi Vilalta <jvprat@gmail.com>
Martin Quinson (mquinson#debian.org)
| 2023-01-03 | Outils po4a |