Linux Certif

Toute la documentation sur la certification Linux LPI

Locale::Po4a::TransTractor.3pm

NOM

Locale::Po4a::TransTractor - Traducteur/extracteur gA~XnA~Xrique.

DESCRIPTION

L'objectif du projet po4a [po for anything --- po pour tout] est de simplifier la traduction (et de faA~Xon plus intA~Xressante, la maintenance des traductions) en utilisant les outils gettext dans des domaines pour lesquels ils n'A~Xtaient pas destinA~Xs, comme la documentation.

Cette classe est l'ancA~Xtre de tous les analyseurs po4a utilisA~Xs pour lire un document, y chercher les chaA~Xnes traduisibles, les extraire dans un fichier po, et les remplacer par leur traduction dans le document gA~XnA~XrA~X.

Plus formellement, elle prend les paramA~Xtres d'entrA~Xe suivants :

-

un document A~  traduire ;

-

un fichier po contenant les traductions A~  utiliser.

En sortie, elle produit :

-

un autre fichier po, rA~Xsultat de l'extraction des chaA~Xnes traduisibles du document en entrA~Xe ;

-

un document traduit, partageant la mA~Xme structure que celui en entrA~Xe, mais dont toutes les chaA~Xnes traduisibles ont A~XtA~X remplacA~Xes par les traductions trouvA~Xes dans le fichier po fourni en entrA~Xe.

Voici une reprA~Xsentation graphique de tout cela :

   document entrA~Xe --\                             /---> document sortie
                      \                           /       (traduit)
                       +-> parse() function -----+
                      /                           \
   po entrA~Xe --------/                             \---> po sortie
                                                          (extrait)
 
 

FONCTIONS QUE VOTRE ANALYSEUR DOIT SURCHARGER

parse()

Il s'agit de la fonction principale oA~X tout le travail a lieu : la lecture des documents en entrA~Xe, la gA~XnA~Xration des documents en sortie et l'extraction des chaA~Xnes traduisibles. Tout ceci est assez simple avec les fonctions fournies et prA~XsentA~Xes dans la section AX FONCTIONS INTERNES AX ci-dessous. Veuillez aussi vous reporter A~  la section SYNOPSIS, qui prA~Xsente un exemple.

Cette fonction est appelA~Xe 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-mA~Xme.

docheader()

Cette fonction renvoie l'en-tA~Xte que nous devons ajouter au document produit, formatA~X comme il faut pour qu'il soit un commentaire pour le langage cible. Reportez-vous A~  la section AX A~Xduquer les dA~Xveloppeurs au problA~Xme des traductions AX, dans po4a(7).

SYNOPSIS

L'exemple suivant analyse une liste de paragraphes commenA~Xant par AX <p AX>. Pour simplifier, nous supposons que le document est bien formatA~X, c'est-A~ -dire que la balise <p> est la seule prA~Xsente et que cette balise se trouve au dA~Xbut 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 premiA~Xre balise <p>. 
                # Remet la ligne actuelle dans le document d'entrA~Xe,
                #  et met le paragraphe dans la sortie
                $self->unshiftline($line,$lref);
               
                # Maintenant que le document est formA~X, il faut le traduire :
                #   - Retirons les balises de tA~Xte
                $paragraphe =~ s/^<p>//s;
 
                #   - Poussons la balise de tA~Xte (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'entrA~Xe.
        return;
    }
  }
 
 

Une fois que vous avez implA~XmentA~X la fonction parse, vous pouvez utiliser cette nouvelle classe en utilisant l'interface publique prA~XsentA~Xe 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 paramA~Xtres doivent A~Xtre fournis sous forme de table de hachage. Voici les diffA~Xrentes actions possibles :

a.

Lit tous les fichiers po spA~XcifiA~Xs dans po_in_name

b.

Lit tous les documents originaux spA~XcifiA~Xs dans file_in_name

c.

Analyse le document

d.

Lit et applique tous les addenda spA~XcifiA~Xs

e.

A~Xcrit le document traduit dans file_out_name (si spA~XcifiA~X)

f.

A~Xcrit le fichier po extrait dans po_out_name (si spA~XcifiA~X)

PARAMA~XTRES, en plus de ceux acceptA~Xs par new(), ainsi que leur type :

file_in_name (@)

Liste de noms de fichiers d'oA~X lire les documents en entrA~Xe.

file_in_charset ($)

Le jeu de caractA~Xres du document d'entrA~Xe (s'il n'est pas spA~XcifiA~X, il essayera de le dA~Xtecter A~  partir du document).

file_out_name ($)

Nom de fichier oA~X A~Xcrire le document en sortie.

file_out_charset ($)

Le jeu de caractA~Xres du document de sortie (s'il n'est pas spA~XcifiA~X, le jeu de caractA~Xres du fichier po sera utilisA~X).

po_in_name (@)

Liste de noms de fichiers d'oA~X lire les fichiers po d'entrA~Xe (ceux contenant les traductions A~  utiliser pour la traduction du document).

po_out_name ($)

Nom de fichier oA~X A~Xcrire le fichier po de sortie (celui contenant les chaA~Xnes extraites du document d'entrA~Xe).

addendum (@)

Liste de noms de fichiers d'oA~X lire les addenda A~  appliquer.

addendum-charset ($)

Jeu de caractA~Xres des addenda.

new(%)

CrA~Xer un nouveau document Po4a. Options acceptA~Xes (sous forme de hachage) :

verbose ($)

RA~Xgle le niveau de bavardage.

debug ($)

RA~Xgle le niveau de dA~Xbogage.

Manipuler les documents

read($)

Ajouter un nouveau document d'entrA~Xe aprA~Xs ceux dA~XjA~  ajoutA~Xs. Le paramA~Xtre est le nom du fichier A~  lire.

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

write($)

A~Xcrire le document traduit dans le fichier dont le nom est passA~X en paramA~Xtre.

Manipuler les fichiers po

readpo($)

Ajouter le contenu du fichier dont le nom est passA~X en paramA~Xtre au po d'entrA~Xe. Notez que l'ancien contenu du po d'entrA~Xe n'est pas effacA~X.

writepo($)

A~Xcrire le po extrait dans le fichier dont le nom est passA~X en paramA~Xtre.

stats()

Renvoie des statistiques A~  propos de la traduction. Veuillez noter que ce ne sont pas les statistiques affichA~Xes par msgfmt --statistic. Dans ce cas, il s'agit des statistiques concernant l'utilisation rA~Xcente 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 entrA~Xe. Voici un exemple d'utilisation :

     [utilisation normal d'un document po4a...]
 
     ($pourcent,$traduit,$total) = $document->stats();
     print "Des traductions ont A~XtA~X trouvA~Xes pour $pourcent\%  ($traduit sur $total) des chaA~Xnes.\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 A~Xcrire. 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 dA~Xriver un analyseur (parser)

RA~XcupA~Xration de l'entrA~Xe, gA~XnA~Xration de la sortie

Quatre fonctions sont fournies pour rA~XcupA~Xrer l'entrA~Xe et renvoyer la sortie. Elles sont trA~Xs similaires aux couples shift/unshift et push/pop. La premiA~Xre paire concerne l'entrA~Xe, et la seconde la sortie. Moyen mnA~Xmotechnique : en entrA~Xe, on veut rA~XcupA~Xrer la premiA~Xre ligne, ce que shift permet ; en sortie on veut ajouter le rA~Xsultat A~  la fin, ce que fait push.

shiftline()

Cette fonction renvoie le ligne suivante du document d'entrA~Xe qui est analysA~X, ainsi que sa rA~XfA~Xrence (les deux A~Xtant placA~Xes dans un tableau).

unshiftline($$)

RA~XcupA~Xre une ligne du document d'entrA~Xe, ainsi que sa rA~XfA~Xrence.

pushline($)

Ajoute une nouvelle ligne dans le document de sortie.

popline()

RA~XcupA~Xre (pop) la derniA~Xre ligne poussA~Xe dans le document de sortie.

Marquage des chaA~Xnes A~  traduire

Une fonction est fournie pour gA~Xrer le texte qui doit A~Xtre traduit.

translate($$$)

ParamA~Xtres obligatoires :

-

La chaA~Xne A~  traduire

-

La rA~XfA~Xrence de cette chaA~Xne (c.-A~ -d., sa position dans le fichier d'entrA~Xe)

-

Le type de la chaA~Xne (c.-A~ -d., la description textuelle de son rA~Xle structurel ; utilisA~X dans Locale::Po4a::Po::gettextization() ; consultez A~Xgalement po4a(7), section Gettextization : Comment A~Xa marche ?)

Cette fonction peut A~Xgalement prendre des paramA~Xtres supplA~Xmentaires. Ils doivent A~Xtre organisA~Xs sous forme de table de hachage. Par exemple :

   $self->translate("chaA~Xne","rA~XfA~Xrence","type",
                    'wrap' => 1);
 
 

wrap

BoolA~Xen indiquant si on peut considA~Xrer que les espaces des chaA~Xnes ne sont pas importants. Dans ce cas, la fonction crA~Xe une forme canonique de la chaA~Xne 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 dA~Xfaut).

comment

Un commentaire additionnel A~  ajouter A~  l'entrA~Xe du po.

Action :

-

Pousse la chaA~Xne, la rA~XfA~Xrence et le type dans le po de sortie.

-

Renvoie la traduction de la chaA~Xne (trouvA~Xe dans po_in) de faA~Xon A~  ce que l'analyseur (parser) puisse construire doc_out.

-

GA~Xre les jeux de caractA~Xres pour recoder les chaA~Xnes avant de les envoyer A~  po_out et avant de renvoyer la traduction.

Fonctions diverses

verbose()

Indique si le mode bavard a A~XtA~X activA~X lors de la crA~Xation du Transtractor.

debug()

Indique si l'option de dA~Xbogage a A~XtA~X fournie lors de la crA~Xation du Transtractor.

detected_charset($)

Indique A~  TransTractor qu'un nouveau jeu de caractA~Xres (premier paramA~Xtre) a A~XtA~X dA~XtectA~X dans le document d'entrA~Xe. Il est en rA~Xgle gA~XnA~Xral lu dans l'en-tA~Xte du document. Seul le premier jeu de caractA~Xres restera, qu'il soit fourni par les paramA~Xtres de process() ou dA~XtectA~X dans le document.

get_out_charset()

Cette fonction retournera le jeu de caractA~Xres qui doit A~Xtre utilisA~X dans le document de sortie (souvent utile pour substituer le jeu de caractA~Xres qui a A~XtA~X dA~XtectA~X dans le document d'entrA~Xe).

Il utilisera le jeu de caractA~Xres spA~XcifiA~X sur la ligne de commande. S'il n'a pas A~XtA~X spA~XcifiA~X, il utilisera le jeu de caractA~Xre du fichier po d'entrA~Xe, et si ce fichier po utilise la valeur par dA~Xfaut AX CHARSET AX, et aucun encodage n'est rA~XalisA~X.

recode_skipped_text($)

Cette fonction rA~Xencode le texte donnA~X en paramA~Xtre, du jeu de caractA~Xres du document d'entrA~Xe vers le jeu de caractA~Xres du document de sortie. Ce n'est pas nA~Xcessaire quand les chaA~Xnes sont traduites (translate() rA~Xencode tout d'elle-mA~Xme), mais A~Xa l'est lorsque vous sautez des chaA~Xnes du document d'entrA~Xe 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 gA~Xrer de documents traduits contenant toutes les langues, comme les modA~Xles debconf ou les fichier .desktop.

Pour rA~Xpondre A~  ce problA~Xme, les seules modifications d'interface nA~Xcessaires sont :

-

utiliser une table de hachage pour po_in_name (une liste par langue)

-

ajouter un paramA~Xtre A~  traduire pour indiquer la langue cible

-

crA~Xer 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,$rA~Xf,$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)