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 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 type[,wrap|nowrap]

Indique le format des références. L'argument type peut-être none pour ne pas produire de référence, noline pour ne pas indiquer de numéro de ligne (plus précisément, tous les numéros de ligne sont remplacés par 1), counter pour remplacer le numéro de ligne par un décompte croissant, et full pour inclure des références complètes.

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 à 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 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 :

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 :

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.

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)