Linux Certif

Toute la documentation sur la certification Linux LPI

Locale::Po4a::Po.3pm

NOM

Locale::Po4a::Po - module de manipulation des fichiers po

SYNOPSIS

     use Locale::Po4a::Po;
     my $pofile=Locale::Po4a::Po->new();
 
     # Lit un fichier po
     $pofile->read('fichier.po');
 
     # Ajoute une entree
     $pofile->push('msgid' => 'Hello', 'msgstr' => 'bonjour', 
                   'flags' => "wrap", 'reference'=>'file.c:46');
 
     # Extrait la traduction
     $pofile->gettext("Hello"); # retourne 'bonjour'
 
     # Ecrit le resultat dans un fichier
     $pofile->write('autrefichier.po');
 
 

DESCRIPTION

Locale::Po4a::Po est un module qui permet de manipuler des catalogues de messages. Vous pouvez lire et ecrire dans/depuis un fichier (dont l'extension classique est po), vous pouvez construire de nouvelles entrees ou demander la traduction d'une chaine.

Pour une description plus complete des catalogues de messages dans le format po et leur utilisation, veuillez vous referer a la documentation du programme gettext.

Ce module fait partie du projet po4a, dont l'objectif est d'utiliser les fichiers po (concus a l'origine pour la traduction des programmes) pour la traduction d'autres formats tels que la documentation (pages de manuel, manuels info), la description des paquets, les questionnaires debconf et toute chose pouvant beneficier de ces mecanismes.

OPTIONS ACCEPTEES PAR CE MODULE

porefs

Ceci precise le format des references. Les valeurs valables sont X none X pour ne pas produire de reference, X noline X pour ne pas preciser les numeros de ligne et X full X pour inclure des references completes.

Fonctions a propos du catalogue entier

new()

Cree un nouveau catalogue. Si un parametre est fourni, il s'agit du nom du fichier po a lire.

read($)

Lit un fichier po (dont le nom est fourni en parametre). Les entrees pre-existantes dans self ne sont pas oubliees, et les nouvelles sont ajoutees a la fin du catalogue.

write($)

Ecrit le catalogue courant dans le fichier specifie.

write_if_needed($$)

Comme write, mais si le fichier PO ou POT existe deja, l'objet sera ecrit dans un fichier temporaire qui sera ensuite compare avec le fichier existant pour verifier que la mise a jour est necessaire (ceci permet d'eviter a changer le fichier POT juste pour mettre a jour une reference de ligne ou le champ POT-Creation-Date).

gettextize($$)

Cette fonction produit un catalogue de messages traduits a partir de deux catalogues, l'original et la traduction. Ce processus est decrit dans po4a(7) a la section Gettextization : Comment ca marche ?.

filter($)

Cette fonction extrait un catalogue d'un autre. Seules les entrees ayant une reference dans le fichier donne seront placees dans le catalogue resultant.

Cette fonction analyse son parametre, le convertit en une definition de fonction Perl, evalue cette definition et filtre les champs pour lesquels cette fonction retourne X true X.

J'aime Perl par moments ;)

to_utf8()

Re-encode les chaines msgstr du po en UTF-8. Ne fait rien si le jeu de caracteres n'est pas specifie dans le fichier po (la valeur du champ X CHARSET X) ou s'il est deja en UTF-8 ou ASCII.

Fonctions pour utiliser un catalogue de messages pour les traductions

gettext($%)

Recherche la traduction de la chaine, fournie en parametre, dans le catalogue courant. Cette fonction retourne la chaine originelle (non traduite) si la chaine cherchee est introuvable.

Apres la chaine a traduire, vous pouvez passer un hachage de parametres supplementaires. Voici la liste des valeurs valables :

wrap

booleen indiquant si les espaces et retours chariot de la chaine peuvent etre modifies. Si oui, la fonction utilise une forme canonique de la chaine lors de la recherche d'une traduction, et ajoute des retours a la ligne.

wrapcol

La colonne a laquelle les retours a la ligne doivent avoir lieu (76 par defaut).

stats_get()

Retourne les statistiques sur le taux de reussite des requetes de traduction depuis la derniere fois que stats_clear() a ete appele. Notez qu'il ne s'agit pas des statistiques obtenues avec l'option --statistic de msgfmt. Ici, ce sont les statistiques de l'usage recent du fichier tandis que msgfmt indique l'etat du fichier. Exemple d'utilisation :

     [une utilisation quelconque du fichier po pour des traductions]
 
     ($percent,$hit,$queries) = $pofile->stats_get();
     print "Pour l'instant, $percent\% des traductions cherchees ont ete trouvees ($hit parmi $queries).\n";
 
 

stats_clear()

Oublie les statistiques sur la reussite de gettext.

Fonctions pour construire un catalogue de messages

push(%)

Ajoute une nouvelle entree dans le catalogue courant. Les parametres doivent etre un hachage. Les valeurs de cle valides sont :

msgid

la chaine dans la langue originale.

msgstr

la traduction.

reference

une indication de la localisation de cette chaine. Par exemple : file.c:46 (ce qui designe la ligne 46 du fichier file.c). Il peut s'agir d'une liste separee par des espaces dans le cas d'occurrences multiples.

comment

un commentaire ajoute manuellement (par le traducteur). Le format est libre.

automatic

un commentaire ajoute automatiquement par le programme d'extraction des chaines. Veuillez vous referer a l'option --add-comments du programme xgettext pour plus d'informations.

flags

liste de tous les drapeaux utilises pour cette entree (separes par des espaces).

Les valeurs valides sont : c-text, python-text, lisp-text, elisp-text, librep-text, smalltalk-text, java-text, awk-text, object-pascal-text, ycp-text, tcl-text, wrap, no-wrap et fuzzy.

Voir la documentation de gettext pour leur signification.

type

Il s'agit principalement d'un parametre interne utilise lors de la gettextisation des documents. Le but est d'analyser a la fois le document d'origine et la traduction sous la forme d'objet po, et de les combiner en utilisant les msgid de l'un comme msgid et les msgid de l'autre comme msgstr. Afin de s'assurer que les choses se deroulent correctement, un type dependant de son role syntaxique dans le document (comme X chapt X, X sect1 X, X p X pour un docbook) est attribue a chaque chaine. Si deux chaines sur le point d'etre appariees sont de types differents, cela signifie que les deux fichiers ne partagent pas la meme structure, et le processus se termine par une erreur.

Cette information est egalement reportee dans le fichier po sous forme de commentaire automatique car elle indique le contexte des chaines a traduire.

wrap

booleen indiquant si les espaces peuvent etre modifies lors de remises en forme esthetiques. Si vrai, les chaines sont mises sous forme canonique avant usage.

Cette information est reportee dans le fichier po grace aux drapeaux X wrap X (si vrai) et X no-wrap X (sinon).

wrapcol

La colonne a laquelle les retours a la ligne doivent avoir lieu (76 par defaut).

Cette information n'est pas reportee dans le fichier po.

Fonctions diverses

count_entries()

Retourne le nombre d'entrees dans le catalogue (sans compter l'en-tete).

count_entries_doc()

Retourne le nombre d'entrees dans le document. Si une chaine apparait plusieurs fois dans le document, elle sera comptee plusieurs fois.

msgid($)

Retourne le msgid du numero fourni.

msgid_doc($)

Retourne le msgid qui a la position donnee dans le document.

get_charset()

Retourne le jeu de caracteres specifie dans l'en-tete du po. S'il n'a pas ete defini, il retourne X CHARSET X.

set_charset($)

Permet de fixer le jeu de caracteres de l'en-tete du po a la valeur fournie dans son premier parametre. Si vous n'appelez jamais cette fonction (et qu'aucun fichier dont le jeu de caracteres est specifie n'est lu), la valeur par defaut est laissee a X CHARSET X. Cette valeur ne change pas le comportement du module, elle ne sert qu'a remplir la valeur de ce champ dans l'en-tete, et a la retourner avec get_charset().

AUTEURS

  Denis Barbier <barbier@linuxfr.org>
  Martin Quinson (mquinson#debian.org)
 
 

TRADUCTION

  Martin Quinson (mquinson#debian.org)