
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 NOM

Locale::Po4a::Po - Module de manipulation des fichiers PO

=head1 SYNOPSIS

    use Locale::Po4a::Po;
    my $pofile=Locale::Po4a::Po->new();

    # Read PO file
    $pofile->read('file.po');

    # Add an entry
    $pofile->push('msgid' => 'Hello', 'msgstr' => 'bonjour',
                  'flags' => "wrap", 'reference'=>'file.c:46');

    # Extract a translation
    $pofile->gettext("Hello"); # returns 'bonjour'

    # Write back to a file
    $pofile->write('otherfile.po');

=head1 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 I<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, référez-vous à 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.

=head1 OPTIONS ACCEPTÉES PAR CE MODULE

=over 4

=item B<--porefs> I<type>

Indique le format des références. L’argument I<type> peut-être B<never> pour
ne pas produire de référence, B<file> pour n’indiquer que le fichier sans le
numéro de ligne, B<counter> pour remplacer le numéro de ligne par un
décompte croissant, et B<full> pour inclure des références complètes (par
défaut, la valeur full est utilisée).

=item B<--wrap-po> B<no>|B<newlines>|I<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 à
B<newlines>, po4a ne séparera les msgit et msgstr qu’après les nouvelles
lignes dans le contenu. Si défini à B<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 renvoyées, c'est-à-dire sur la façon dont les nouvelles
lignes sont ajoutées au contenu de ces chaînes.

=item B<--msgid-bugs-address> B<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.

=item B<--copyright-holder> I<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. ».

=item B<--package-name> I<chaîne>

Fixe le nom du paquet pour l’en-tête du fichier POT. La valeur par défaut
est « PACKAGE ».

=item B<--package-version> I<chaîne>

Fixe la version du paquet pour l’en-tête du fichier POT. La valeur par
défaut est « VERSION ».

=back

=head1 Fonctions concernant les catalogues de messages entiers

=over 4

=item new()

Crée un nouveau catalogue. Si un paramètre est fourni, il s’agit du nom du
fichier PO à lire.

=item 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.

=item write($)

Écrit le catalogue courant dans le fichier spécifié.

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

=item 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 S<« true »>.

J’aime Perl par S<moments ;)>

=back

=head1 Fonctions pour utiliser un catalogue de messages pour les traductions

=over 4

=item 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 :

=over

=item B<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.

=item B<wrapcol>

la colonne à laquelle les retours à la ligne doivent avoir lieu (76 par
défaut).

=back

=item 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 :

    [some use of the PO file to translate stuff]

    ($percent,$hit,$queries) = $pofile->stats_get();
    print "So far, we found translations for $percent\%  ($hit of $queries) of strings.\n";

=item stats_clear()

Oublie les statistiques sur la réussite de gettext.

=back

=head1 Fonctions pour construire un catalogue de messages

=over 4

=item push(%)

Ajoute une nouvelle entrée dans le catalogue courant. Les paramètres doivent
être un hachage. Les valeurs de clé valides sont :

=over 4

=item B<msgid>

la chaîne dans la langue originale.

=item B<msgstr>

la traduction.

=item B<reference>

une indication de la localisation de cette chaîne. Par S<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.

=item B<comment>

un commentaire ajouté manuellement (par l’équipe de traduction). Le format
est libre.

=item B<automatic>

un commentaire ajouté automatiquement par le programme d’extraction des
chaînes. Référez-vous à l’option B<--add-comments> du programme B<xgettext>
pour en savoir plus.

=item B<flags>

liste de tous les drapeaux utilisés pour cette entrée (séparés par des
espaces).

Les valeurs valides S<sont :> B<c-text>, B<python-text>, B<lisp-text>,
B<elisp-text>, B<librep-text>, B<smalltalk-text>, B<java-text>, B<awk-text>,
B<object-pascal-text>, B<ycp-text>, B<tcl-text>, B<wrap>, B<no-wrap> et
B<fuzzy>.

Voir la documentation de gettext pour leur signification.

=item B<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 S<« chapt »>, S<«
sect1 »>, S<« 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.

=item B<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 B<wrap>
(si vrai) et B<no-wrap> (sinon).

=item B<wrapcol>

ignorée ; la clef est conservée pour la rétro-compatibilité.

=back

=back

=head1 Fonctions diverses

=over 4

=item count_entries()

Renvoie le nombre d’entrées dans le catalogue (sans compter l’en-tête).

=item 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.

=item msgid($)

Renvoie le msgid du numéro fourni.

=item msgid_doc($)

Renvoie le msgid qui a la position donnée dans le document.

=item 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 d'origine.

=item 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 ».

=back

=head1 AUTEURS

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)

=head1 TRADUCTION

 Martin Quinson (mquinson#debian.org)

