Provided by: po4a_0.52-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"); # 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]
Specify the reference format. Argument type can be one of never to not produce any reference, file to
only specify the file without the line number, counter to replace line number by an increasing
counter, and full to include complete references (default: full).
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)
Returns ($uptodate, $diagnostic) with $uptodate indicating whether all msgid of the current po file
are also present in the one passed as parameter (all other fields are ignored in the file
comparison). Informally, if $uptodate returns false, then the po files would be changed when going
through po4a-updatepo.
If $uptodate is false, then $diagnostic contains a diagnostic of why this is so.
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)
Outils po4a 2017-08-26 Locale::Po4a::Po(3pm)