Locale::Po4a::TransTractor.3pm

Autres langues

Langue: fr

Autres versions - même langue

Version: 2009-02-26 (fedora - 04/07/09)

Section: 3 (Bibliothèques de fonctions)

Sommaire

NOM

Locale::Po4a::TransTractor - Traducteur/extracteur generique.

DESCRIPTION

L'objectif du projet po4a [po for anything --- po pour tout] est de simplifier la traduction (et de facon plus interessante, la maintenance des traductions) en utilisant les outils gettext dans des domaines pour lesquels ils n'etaient pas destines, comme la documentation.

Cette classe est l'ancetre de tous les analyseurs po4a utilises pour lire un document, y chercher les chaines traduisibles, les extraire dans un fichier po, et les remplacer par leur traduction dans le document genere.

Plus formellement, elle prend les parametres d'entree suivants :

-
un document a traduire ;
-
un fichier po contenant les traductions a utiliser.

En sortie, elle produit :

-
un autre fichier po, resultat de l'extraction des chaines traduisibles du document en entree ;
-
un document traduit, partageant la meme structure que celui en entree, mais dont toutes les chaines traduisibles ont ete remplacees par les traductions trouvees dans le fichier po fourni en entree.

Voici une representation graphique de tout cela :

   document entree --\                             /---> document sortie
                      \                           /       (traduit)
                       +-> parse() function -----+
                      /                           \
   po entree --------/                             \---> po sortie
                                                          (extrait)

FONCTIONS QUE VOTRE ANALYSEUR DOIT SURCHARGER

parse()
Il s'agit de la fonction principale ou tout le travail a lieu : la lecture des documents en entree, la generation des documents en sortie et l'extraction des chaines traduisibles. Tout ceci est assez simple avec les fonctions fournies et presentees dans la section X FONCTIONS INTERNES X ci-dessous. Veuillez aussi vous reporter a la section SYNOPSIS, qui presente un exemple.

Cette fonction est appelee 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-meme.

docheader()
Cette fonction renvoie l'en-tete que nous devons ajouter au document produit, formate comme il faut pour qu'il soit un commentaire pour le langage cible. Reportez-vous a la section X Eduquer les developpeurs au probleme des traductions X, dans po4a(7).

SYNOPSIS

L'exemple suivant analyse une liste de paragraphes commencant par X <p X>. Pour simplifier, nous supposons que le document est bien formate, c'est-a-dire que la balise <p> est la seule presente et que cette balise se trouve au debut 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 premiere balise <p>. 
                # Remet la ligne actuelle dans le document d'entree,
                #  et met le paragraphe dans la sortie
                $self->unshiftline($line,$lref);
               
                # Maintenant que le document est forme, il faut le traduire :
                #   - Retirons les balises de tete
                $paragraphe =~ s/^<p>//s;
 
                #   - Poussons la balise de tete (a ne pas traduire) et le 
                #     reste du paragraphe (a traduire) dans le document de 
                #     sortie
                $self->pushline(  "<p>"
                                . $document->translate($paragraphe,$pararef)
                                );
 
                next PARAGRAPHE;
            } else {
                # Ajout a 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'entree.
        return;
    }
  }

Une fois que vous avez implemente la fonction parse, vous pouvez utiliser cette nouvelle classe en utilisant l'interface publique presentee 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 parametres doivent etre fournis sous forme de table de hachage. Voici les differentes actions possibles :
a.
Lit tous les fichiers po specifies dans po_in_name
b.
Lit tous les documents originaux specifies dans file_in_name
c.
Analyse le document
d.
Lit et applique tous les addenda specifies
e.
Ecrit le document traduit dans file_out_name (si specifie)
f.
Ecrit le fichier po extrait dans po_out_name (si specifie)

PARAMETRES, en plus de ceux acceptes par new(), ainsi que leur type :
file_in_name (@)
Liste de noms de fichiers d'ou lire les documents en entree.
file_in_charset ($)
Le jeu de caracteres du document d'entree (s'il n'est pas specifie, il essayera de le detecter a partir du document).
file_out_name ($)
Nom de fichier ou ecrire le document en sortie.
file_out_charset ($)
Le jeu de caracteres du document de sortie (s'il n'est pas specifie, le jeu de caracteres du fichier po sera utilise).
po_in_name (@)
Liste de noms de fichiers d'ou lire les fichiers po d'entree (ceux contenant les traductions a utiliser pour la traduction du document).
po_out_name ($)
Nom de fichier ou ecrire le fichier po de sortie (celui contenant les chaines extraites du document d'entree).
addendum (@)
Liste de noms de fichiers d'ou lire les addenda a appliquer.
addendum-charset ($)
Jeu de caracteres des addenda.
new(%)
Creer un nouveau document Po4a. Options acceptees (sous forme de hachage) :
verbose ($)
Regle le niveau de bavardage.
debug ($)
Regle le niveau de debogage.

Manipuler les documents

read($)
Ajouter un nouveau document d'entree apres ceux deja ajoutes. Le parametre est le nom du fichier a lire.

Notez que cette fonction n'analyse pas le fichier donne. Il faut utiliser parse() pour cela une fois que vous avez ajoute au document tous les fichiers que vous souhaitez analyser.

write($)
Ecrire le document traduit dans le fichier dont le nom est passe en parametre.

Manipuler les fichiers po

readpo($)
Ajouter le contenu du fichier dont le nom est passe en parametre au po d'entree. Notez que l'ancien contenu du po d'entree n'est pas efface.
writepo($)
Ecrire le po extrait dans le fichier dont le nom est passe en parametre.
stats()
Renvoie des statistiques a propos de la traduction. Veuillez noter que ce ne sont pas les statistiques affichees par msgfmt --statistic. Dans ce cas, il s'agit des statistiques concernant l'utilisation recente 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 entree. Voici un exemple d'utilisation : 
     [utilisation normal d'un document po4a...]
 
     ($pourcent,$traduit,$total) = $document->stats();
     print "Des traductions ont ete trouvees pour $pourcent\%  ($traduit sur $total) des chaines.\n";

Manipuler les addenda

addendum($)
Veuillez vous reporter a po4a(7) pour plus d'informations sur ce que sont les addenda et comment les traducteurs doivent les ecrire. Pour appliquer un addendum au document traduit, vous n'avez qu'a fournir le nom du fichier a cette fonction, et c'est fini ;)

Cette fonction retourne un entier non nul en cas d'erreur.

FONCTIONS INTERNES utiliser pour deriver un analyseur (parser)


Recuperation de l'entree, generation de la sortie

Quatre fonctions sont fournies pour recuperer l'entree et renvoyer la sortie. Elles sont tres similaires aux couples shift/unshift et push/pop. La premiere paire concerne l'entree, et la seconde la sortie. Moyen mnemotechnique : en entree, on veut recuperer la premiere ligne, ce que shift permet ; en sortie on veut ajouter le resultat a la fin, ce que fait push.

shiftline()
Cette fonction renvoie le ligne suivante du document d'entree qui est analyse, ainsi que sa reference (les deux etant placees dans un tableau).
unshiftline($$)
Recupere une ligne du document d'entree, ainsi que sa reference.
pushline($)
Ajoute une nouvelle ligne dans le document de sortie.
popline()
Recupere (pop) la derniere ligne poussee dans le document de sortie.

Marquage des chaines a traduire

Une fonction est fournie pour gerer le texte qui doit etre traduit.

translate($$$)
Parametres obligatoires :
-
La chaine a traduire
-
La reference de cette chaine (c.-a-d., sa position dans le fichier d'entree)
-
Le type de la chaine (c.-a-d., la description textuelle de son role structurel ; utilise dans Locale::Po4a::Po::gettextization() ; consultez egalement po4a(7), section Gettextization : Comment ca marche ?)

Cette fonction peut egalement prendre des parametres supplementaires. Ils doivent etre organises sous forme de table de hachage. Par exemple :
   $self->translate("chaine","reference","type",
                    'wrap' => 1);
wrap
Booleen indiquant si on peut considerer que les espaces des chaines ne sont pas importants. Dans ce cas, la fonction cree une forme canonique de la chaine avant de rechercher une traduction ou de l'extraire et ajoute des retours a la ligne a la traduction.
wrapcol
La colonne a laquelle les retours a la ligne doivent avoir lieu (76 par defaut).
comment
Un commentaire additionnel a ajouter a l'entree du po.

Action :
-
Pousse la chaine, la reference et le type dans le po de sortie.
-
Renvoie la traduction de la chaine (trouvee dans po_in) de facon a ce que l'analyseur (parser) puisse construire doc_out.
-
Gere les jeux de caracteres pour recoder les chaines avant de les envoyer a po_out et avant de renvoyer la traduction.

Fonctions diverses

verbose()
Indique si le mode bavard a ete active lors de la creation du Transtractor.
debug()
Indique si l'option de debogage a ete fournie lors de la creation du Transtractor.
detected_charset($)
Indique a TransTractor qu'un nouveau jeu de caracteres (premier parametre) a ete detecte dans le document d'entree. Il est en regle general lu dans l'en-tete du document. Seul le premier jeu de caracteres restera, qu'il soit fourni par les parametres de process() ou detecte dans le document.
get_out_charset()
Cette fonction retournera le jeu de caracteres qui doit etre utilise dans le document de sortie (souvent utile pour substituer le jeu de caracteres qui a ete detecte dans le document d'entree).

Il utilisera le jeu de caracteres specifie sur la ligne de commande. S'il n'a pas ete specifie, il utilisera le jeu de caractere du fichier po d'entree, et si ce fichier po utilise la valeur par defaut X CHARSET X, et aucun encodage n'est realise.

recode_skipped_text($)
Cette fonction reencode le texte donne en parametre, du jeu de caracteres du document d'entree vers le jeu de caracteres du document de sortie. Ce n'est pas necessaire quand les chaines sont traduites (translate() reencode tout d'elle-meme), mais ca l'est lorsque vous sautez des chaines du document d'entree 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 gerer de documents traduits contenant toutes les langues, comme les modeles debconf ou les fichier .desktop.

Pour repondre a ce probleme, les seules modifications d'interface necessaires sont :

-
utiliser une table de hachage pour po_in_name (une liste par langue)
-
ajouter un parametre a traduire pour indiquer la langue cible
-
creer 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,$ref,$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)