Provided by: po4a_0.41-1_all bug

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"); # renvoie '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 ou 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 ACCEPT'EES PAR CE MODULE

       porefs
           Ceci precise le format des references. Les valeurs valables sont
           none pour ne pas produire de reference, noline pour ne pas preciser
           les numeros de ligne et full 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 de 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 renvoie <<true>>.

           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 <<CHARSET>>) 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 renvoie 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()
           Renvoie 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 PO 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
               <<chapt>>, <<sect1>>, <<p>>, etc. dans 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 modifiees 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 wrap (si vrai) et no-wrap (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()
           Renvoie le nombre d'entrees dans le catalogue (sans compter
           l'en-tete).

       count_entries_doc()
           Renvoie le nombre d'entrees dans le document. Si une chaine
           apparait plusieurs fois dans le document, elle sera comptee
           plusieurs fois.

       msgid($)
           Renvoie le msgid du numero fourni.

       msgid_doc($)
           Renvoie le msgid qui a la position donnee dans le document.

       get_charset()
           Renvoie le jeu de caracteres specifie dans l'en-tete du PO. S'il
           n'a pas ete defini, il renvoie <<CHARSET>>.

       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 <<CHARSET>>.
           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 renvoyer
           avec get_charset().

AUTEURS

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