NOM¶

DESCRIPTION¶

-

un document à traduire ;

-

un fichier PO contenant les traductions à utiliser.

-

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.

  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¶

 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;
   }
 }

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 :

new(%)

Créer un nouveau document po4a. Options acceptées (sous forme de hachage) :

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¶

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¶

translate($$$)

Paramètres obligatoires :

  $self->translate("chaîne","référence","type",
                   'wrap' => 1);

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¶

-

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) 
                        });
    

AUTEURS¶

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)
 Jordi Vilalta <jvprat@gmail.com>