Locale::Po4a::Po - Module de manipulation des fichiers PO
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');
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.
- --porefs
type
- 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).
- --wrap-po
no|newlines|nombre (par défaut : 76)
- Détermine la façon de formater le fichier po. Cela donne le
choix entre des fichiers joliment reformatés mais pouvant mener
à des conflits git, ou des fichiers plus facile à prendre en
main automatiquement, mais plus difficile à lire pour les humains.
Historiquement, la suite gettext a formaté les fichiers
po à la 77e colonne pour des raisons cosmétiques. Cette
option indique le comportement de po4a. Si défini en tant
qu’entier, po4a va restreindre la largeur du fichier après
cette colonne et après les nouvelles lignes de contenu. Si
défini à newlines, po4a ne séparera les
msgit et msgstr qu’après les nouvelles lignes dans le
contenu. Si défini à no, po4a ne restreindra pas du
tout le fichier. Les commentaires de référence sont
toujours limités par les outils gettext que nous utilisons en
interne.
Veuillez noter que cette option n’a pas d’impact
sur la façon dont les msgid et msgstr sont restreints, par
exemple sur la façon dont les nouvelles lignes sont
ajoutées au contenu de ces chaînes.
- --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 ».
- 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).
- 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.
- 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.
- 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.
- 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.
- 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.
- type_doc($)
- Retourne le type du msgid à la position donnée dans le
document. Ceci n'est probablement utile que pour la gettextisation, et il
est stocké séparément de {$msgid}{'type'} parce que
ce dernier peut être écrasé par un autre type lorsque
le $msgid est dupliqué dans le document
maître.
- 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 « UTF-8 ».
- 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 à « UTF-8
». 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().
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)
Martin Quinson (mquinson#debian.org)