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
- 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 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.
- 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)