Ubuntu manuals

Provided by: po4a_0.32-1_all

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"); # retourne ’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/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
       du programme gettext.

       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
           Ceci précise le format des références. Les valeurs valables sont
           « none » pour ne pas produire de référence, « noline » pour ne pas
           préciser les numéros de ligne et « full » pour inclure des
           références complètes.

Fonctions à propos du catalogue entier

       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 à 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 retourne « 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 retourne 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()
           Retourne 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 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 » pour un 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és 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()
           Retourne le nombre d’entrées dans le catalogue (sans compter
           l’en-tête).

       count_entries_doc()
           Retourne 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.

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

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

       get_charset()
           Retourne le jeu de caractères spécifié dans l’en-tête du po. S’il
           n’a pas été défini, il retourne « 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
           retourner avec get_charset().

AUTEURS

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

TRADUCTION

        Martin Quinson (mquinson#debian.org)