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'
# Ecrit 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 (connus à 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 ACCEPTEES PAR CE MODULE
porefs
Ceci précise le format des réfrences. 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($)
Ecrit 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 spcifié 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és 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 spcifié 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)