Provided by:
po4a_0.41-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 entree
$pofile->push('msgid' => 'Hello', 'msgstr' => 'bonjour',
'flags' => "wrap", 'reference'=>'file.c:46');
# Extrait la traduction
$pofile->gettext("Hello"); # renvoie 'bonjour'
# Ecrit le resultat 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 ecrire dans ou depuis un fichier (dont
l'extension classique est po), vous pouvez construire de nouvelles
entrees ou demander la traduction d'une chaine.
Pour une description plus complete des catalogues de messages dans le
format PO et leur utilisation, veuillez vous referer a la documentation
du programme gettext.
Ce module fait partie du projet po4a, dont l'objectif est d'utiliser
les fichiers PO (concus a 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 beneficier de ces mecanismes.
OPTIONS ACCEPT'EES PAR CE MODULE
porefs
Ceci precise le format des references. Les valeurs valables sont
none pour ne pas produire de reference, noline pour ne pas preciser
les numeros de ligne et full pour inclure des references completes.
Fonctions `a propos du catalogue entier
new()
Cree un nouveau catalogue. Si un parametre est fourni, il s'agit du
nom du fichier PO a lire.
read($)
Lit un fichier PO (dont le nom est fourni en parametre). Les
entrees pre-existantes dans self ne sont pas oubliees, et les
nouvelles sont ajoutees a la fin du catalogue.
write($)
Ecrit le catalogue courant dans le fichier specifie.
write_if_needed($$)
Comme write, mais si le fichier PO ou POT existe deja, l'objet sera
ecrit dans un fichier temporaire qui sera ensuite compare avec le
fichier existant pour verifier que la mise a jour est necessaire
(ceci permet d'eviter de changer le fichier POT juste pour mettre a
jour une reference de ligne ou le champ POT-Creation-Date).
gettextize($$)
Cette fonction produit un catalogue de messages traduits a partir
de deux catalogues, l'original et la traduction. Ce processus est
decrit dans po4a(7) a la section Gettextization: Comment ,ca
marche?.
filter($)
Cette fonction extrait un catalogue d'un autre. Seules les entrees
ayant une reference dans le fichier donne seront placees dans le
catalogue resultant.
Cette fonction analyse son parametre, le convertit en une
definition de fonction Perl, evalue cette definition et filtre les
champs pour lesquels cette fonction renvoie <<true>>.
J'aime Perl par moments;)
to_utf8()
Re-encode les chaines msgstr du PO en UTF-8. Ne fait rien si le jeu
de caracteres n'est pas specifie dans le fichier PO (la valeur du
champ <<CHARSET>>) ou s'il est deja en UTF-8 ou ASCII.
Fonctions pour utiliser un catalogue de messages pour les traductions
gettext($%)
Recherche la traduction de la chaine, fournie en parametre, dans le
catalogue courant. Cette fonction renvoie la chaine originelle (non
traduite) si la chaine cherchee est introuvable.
Apres la chaine a traduire, vous pouvez passer un hachage de
parametres supplementaires. Voici la liste des valeurs valables:
wrap
booleen indiquant si les espaces et retours chariot de la
chaine peuvent etre modifies. Si oui, la fonction utilise une
forme canonique de la chaine lors de la recherche d'une
traduction, et ajoute des retours a la ligne.
wrapcol
la colonne a laquelle les retours a la ligne doivent avoir lieu
(76 par defaut).
stats_get()
Renvoie les statistiques sur le taux de reussite des requetes de
traduction depuis la derniere fois que stats_clear() a ete appele.
Notez qu'il ne s'agit pas des statistiques obtenues avec l'option
--statistic de msgfmt. Ici, ce sont les statistiques de l'usage
recent du fichier PO tandis que msgfmt indique l'etat 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 cherchees ont ete trouvees ($hit parmi $queries).\n";
stats_clear()
Oublie les statistiques sur la reussite de gettext.
Fonctions pour construire un catalogue de messages
push(%)
Ajoute une nouvelle entree dans le catalogue courant. Les
parametres doivent etre un hachage. Les valeurs de cle valides
sont:
msgid
la chaine dans la langue originale.
msgstr
la traduction.
reference
une indication de la localisation de cette chaine. Par exemple:
file.c:46 (ce qui designe la ligne 46 du fichier file.c). Il
peut s'agir d'une liste separee par des espaces dans le cas
d'occurrences multiples.
comment
un commentaire ajoute manuellement (par le traducteur). Le
format est libre.
automatic
un commentaire ajoute automatiquement par le programme
d'extraction des chaines. Veuillez vous referer a l'option
--add-comments du programme xgettext pour plus d'informations.
flags
liste de tous les drapeaux utilises pour cette entree (separes
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 parametre interne utilise lors de
la gettextisation des documents. Le but est d'analyser a 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 deroulent correctement, un type
dependant de son role syntaxique dans le document (comme
<<chapt>>, <<sect1>>, <<p>>, etc. dans DocBook) est attribue a
chaque chaine. Si deux chaines sur le point d'etre appariees
sont de types differents, cela signifie que les deux fichiers
ne partagent pas la meme structure, et le processus se termine
par une erreur.
Cette information est egalement reportee dans le fichier PO
sous forme de commentaire automatique car elle indique le
contexte des chaines a traduire.
wrap
booleen indiquant si les espaces peuvent etre modifiees lors de
remises en forme esthetiques. Si vrai, les chaines sont mises
sous forme canonique avant usage.
Cette information est reportee dans le fichier PO grace aux
drapeaux wrap (si vrai) et no-wrap (sinon).
wrapcol
la colonne a laquelle les retours a la ligne doivent avoir lieu
(76 par defaut).
Cette information n'est pas reportee dans le fichier PO.
Fonctions diverses
count_entries()
Renvoie le nombre d'entrees dans le catalogue (sans compter
l'en-tete).
count_entries_doc()
Renvoie le nombre d'entrees dans le document. Si une chaine
apparait plusieurs fois dans le document, elle sera comptee
plusieurs fois.
msgid($)
Renvoie le msgid du numero fourni.
msgid_doc($)
Renvoie le msgid qui a la position donnee dans le document.
get_charset()
Renvoie le jeu de caracteres specifie dans l'en-tete du PO. S'il
n'a pas ete defini, il renvoie <<CHARSET>>.
set_charset($)
Permet de fixer le jeu de caracteres de l'en-tete du PO a la valeur
fournie dans son premier parametre. Si vous n'appelez jamais cette
fonction (et qu'aucun fichier dont le jeu de caracteres est
specifie n'est lu), la valeur par defaut est laissee a <<CHARSET>>.
Cette valeur ne change pas le comportement du module, elle ne sert
qu'a remplir la valeur de ce champ dans l'en-tete, et a la renvoyer
avec get_charset().
AUTEURS
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)