Provided by: po4a_0.55-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 entrée
           $pofile->push('msgid' => 'Hello', 'msgstr' => 'bonjour',
                         'flags' => "wrap", 'reference'=>'file.c:46');

           # Extrait la traduction
           $pofile->gettext("Hello"); # renvoie « bonjour »

           # Écrit le résultat 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 écrire dans ou depuis un fichier (dont l’extension classique est po), vous
       pouvez construire de nouvelles entrées ou demander la traduction d’une chaîne.

       Pour une description plus complète des catalogues de messages dans le format PO et leur
       utilisation, veuillez vous référer à la documentation au format info du programme gettext
       (section « Fichiers PO »).

       Ce module fait partie du projet po4a, dont l’objectif est d’utiliser les fichiers PO
       (conçus à 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 bénéficier de ces mécanismes.

OPTIONS ACCEPTÉES PAR CE MODULE

       --porefs type[,wrap|nowrap]
           Indique le format des références. L’argument type peut-être never pour ne pas produire
           de référence, file pour n’indiquer que le fichier sans le numéro de ligne, counter
           pour remplacer le numéro de ligne par un décompte croissant, et full pour inclure des
           références complètes (par défaut, la valeur full est utilisée).

           L’argument peut être suivi d’une virgule et d’un des mots clefs wrap ou nowrap. Les
           références sont écrites par défaut sur une seule ligne. Avec l’option wrap, les
           références sont placées sur plusieurs lignes, pour imiter le comportement des outils
           gettext (xgettext and msgmerge). Cette option deviendra la valeur par défaut dans une
           prochaine version, car elle est plus pertinente. L’option nowrap est disponible pour
           permettre aux utilisateurs de conserver l’ancien comportement s’ils le désirent.

       --msgid-bugs-address adresse@email
           Fixe l’adresse à laquelle les bogues des msgid doivent être envoyés. Par défaut, les
           fichiers POT créés n’ont pas de champ Report-Msgid-Bugs-To.

       --copyright-holder chaîne
           Fixe le détenteur du copyright dans l’en-tête du fichier POT. La valeur par défaut est
           « Free Software Foundation, Inc. ».

       --package-name chaîne
           Fixe le nom du paquet pour l’en-tête du fichier POT. La valeur par défaut est
           « PACKAGE ».

       --package-version chaîne
           Fixe la version du paquet pour l’en-tête du fichier POT. La valeur par défaut est
           « VERSION ».

Fonctions concernant les catalogues de messages entiers

       new()
           Crée un nouveau catalogue. Si un paramètre est fourni, il s’agit du nom du fichier PO
           à lire.

       read($)
           Lit un fichier PO (dont le nom est fourni en paramètre). Les entrées pré-existantes
           dans self ne sont pas oubliées, et les nouvelles sont ajoutées à la fin du catalogue.

       write($)
           Écrit le catalogue courant dans le fichier spécifié.

       write_if_needed($$)
           Comme write, mais si le fichier PO ou POT existe déjà, l’objet sera écrit dans un
           fichier temporaire qui sera ensuite comparé avec le fichier existant pour vérifier que
           la mise à jour est nécessaire (ceci permet d’éviter de changer le fichier POT juste
           pour mettre à jour une référence de ligne ou le champ POT-Creation-Date).

       gettextize($$)
           Cette fonction produit un catalogue de messages traduits à partir de deux catalogues,
           l’original et la traduction. Ce processus est décrit dans po4a(7) à la section
           Gettextization : Comment ça marche ?.

       filter($)
           Cette fonction extrait un catalogue d’un autre. Seules les entrées ayant une référence
           dans le fichier donné seront placées dans le catalogue résultant.

           Cette fonction analyse son paramètre, le convertit en une définition de fonction Perl,
           évalue cette définition et filtre les champs pour lesquels cette fonction renvoie
           « true ».

           J’aime Perl par moments ;)

       to_utf8()
           Ré-encode les chaînes msgstr du PO en UTF-8. Ne fait rien si le jeu de caractères
           n’est pas spécifié dans le fichier PO (la valeur du champ « CHARSET ») ou s’il est
           déjà en UTF-8 ou ASCII.

Fonctions pour utiliser un catalogue de messages pour les traductions

       gettext($%)
           Recherche la traduction de la chaîne, fournie en paramètre, dans le catalogue courant.
           Cette fonction renvoie la chaîne originelle (non traduite) si la chaîne cherchée est
           introuvable.

           Après la chaîne à traduire, vous pouvez passer un hachage de paramètres
           supplémentaires. Voici la liste des valeurs valables :

           wrap
               booléen indiquant si les espaces et retours chariot de la chaîne peuvent être
               modifiés. Si oui, la fonction utilise une forme canonique de la chaîne lors de la
               recherche d’une traduction, et ajoute des retours à la ligne.

           wrapcol
               la colonne à laquelle les retours à la ligne doivent avoir lieu (76 par défaut).

       stats_get()
           Renvoie les statistiques sur le taux de réussite des requêtes de traduction depuis la
           dernière fois que stats_clear() a été appelé. Notez qu’il ne s’agit pas des
           statistiques obtenues avec l’option --statistic de msgfmt. Ici, ce sont les
           statistiques de l’usage récent du fichier PO tandis que msgfmt indique l’état 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 cherchées ont été trouvées ($hit parmi $queries).\n";

       stats_clear()
           Oublie les statistiques sur la réussite de gettext.

Fonctions pour construire un catalogue de messages

       push(%)
           Ajoute une nouvelle entrée dans le catalogue courant. Les paramètres doivent être un
           hachage. Les valeurs de clé valides sont :

           msgid
               la chaîne dans la langue originale.

           msgstr
               la traduction.

           reference
               une indication de la localisation de cette chaîne. Par exemple : file.c:46 (ce qui
               désigne la ligne 46 du fichier file.c). Il peut s’agir d’une liste séparée par des
               espaces dans le cas d’occurrences multiples.

           comment
               un commentaire ajouté manuellement (par le traducteur). Le format est libre.

           automatic
               un commentaire ajouté automatiquement par le programme d’extraction des chaînes.
               Veuillez vous référer à l’option --add-comments du programme xgettext pour plus
               d’informations.

           flags
               liste de tous les drapeaux utilisés pour cette entrée (séparés 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 paramètre interne utilisé lors de la gettextisation
               des documents. Le but est d’analyser à 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 déroulent correctement, un type dépendant de son rôle syntaxique dans le
               document (comme « chapt », « sect1 », « p », etc. dans DocBook) est attribué à
               chaque chaîne. Si deux chaînes sur le point d’être appariées sont de types
               différents, cela signifie que les deux fichiers ne partagent pas la même
               structure, et le processus se termine par une erreur.

               Cette information est également reportée dans le fichier PO sous forme de
               commentaire automatique car elle indique le contexte des chaînes à traduire.

           wrap
               booléen indiquant si les espaces peuvent être modifiées lors de remises en forme
               esthétiques. Si vrai, les chaînes sont mises sous forme canonique avant usage.

               Cette information est reportée dans le fichier PO grâce aux drapeaux wrap (si
               vrai) et no-wrap (sinon).

           wrapcol
               la colonne à laquelle les retours à la ligne doivent avoir lieu (76 par défaut).

               Cette information n’est pas reportée dans le fichier PO.

Fonctions diverses

       count_entries()
           Renvoie le nombre d’entrées dans le catalogue (sans compter l’en-tête).

       count_entries_doc()
           Renvoie le nombre d’entrées dans le document. Si une chaîne apparaît plusieurs fois
           dans le document, elle sera comptée plusieurs fois.

       equals_msgid(po)
           Retourne ($ajour, $diagnostic) avec $ajour indiquant si toutes msgid de l’actuel
           fichier po sont également présents dans celui passé en paramètre (tous les autres
           champs sont ignorés lors de la comparaison). De manière informelle, si $ajour renvoie
           la valeur false, alors les fichiers po seraient changés lors de l’exécution de
           po4a-updatepo.

           Si $ajour est faux, alors $diagnostic contient un diagnostique de pourquoi il en est
           ainsi.

       msgid($)
           Renvoie le msgid du numéro fourni.

       msgid_doc($)
           Renvoie le msgid qui a la position donnée dans le document.

       get_charset()
           Renvoie le jeu de caractères spécifié dans l’en-tête du PO. S’il n’a pas été défini,
           il renvoie « CHARSET ».

       set_charset($)
           Permet de fixer le jeu de caractères de l’en-tête du PO à la valeur fournie dans son
           premier paramètre. Si vous n’appelez jamais cette fonction (et qu’aucun fichier dont
           le jeu de caractères est spécifié n’est lu), la valeur par défaut est laissée à
           « CHARSET ». Cette valeur ne change pas le comportement du module, elle ne sert qu’à
           remplir la valeur de ce champ dans l’en-tête, et à la renvoyer avec get_charset().

AUTEURS

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

TRADUCTION

        Martin Quinson (mquinson#debian.org)