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.
- 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.
- 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 <[email protected]>
Martin Quinson (mquinson#debian.org)
Martin Quinson (mquinson#debian.org)