.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Locale::Po4a::Po 3pm"
.TH Locale::Po4a::Po 3pm "2023-01-03" "Outils po4a" "Outils po4a"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NOM"
.IX Header "NOM"
Locale::Po4a::Po \- Module de manipulation des fichiers \s-1PO\s0
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Locale::Po4a::Po;
\&    my $pofile=Locale::Po4a::Po\->new();
\&
\&    # Lit un fichier PO
\&    $pofile\->read(\*(Aqfichier.po\*(Aq);
\&
\&    # Ajoute une entrée
\&    $pofile\->push(\*(Aqmsgid\*(Aq => \*(AqHello\*(Aq, \*(Aqmsgstr\*(Aq => \*(Aqbonjour\*(Aq,
\&                  \*(Aqflags\*(Aq => "wrap", \*(Aqreference\*(Aq=>\*(Aqfile.c:46\*(Aq);
\&
\&    # Extrait la traduction
\&    $pofile\->gettext("Hello"); # renvoie « bonjour »
\&
\&    # Écrit le résultat dans un fichier
\&    $pofile\->write(\*(Aqautrefichier.po\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "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 \fIpo\fR), vous pouvez construire de nouvelles entrées ou demander la traduction d’une chaîne.
.PP
Pour une description plus complète des catalogues de messages dans le format \s-1PO\s0 et leur utilisation, veuillez vous référer à la documentation au format info du programme gettext (section « Fichiers \s-1PO\s0 »).
.PP
Ce module fait partie du projet po4a, dont l’objectif est d’utiliser les fichiers \s-1PO\s0 (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.
.SH "OPTIONS ACCEPTÉES PAR CE MODULE"
.IX Header "OPTIONS ACCEPTÉES PAR CE MODULE"
.IP "\fB\-\-porefs\fR \fItype\fR" 4
.IX Item "--porefs type"
Indique le format des références. L’argument \fItype\fR peut\-être \fBnever\fR pour ne pas produire de référence, \fBfile\fR pour n’indiquer que le fichier sans le numéro de ligne, \fBcounter\fR pour remplacer le numéro de ligne par un décompte croissant, et \fBfull\fR pour inclure des références complètes (par défaut, la valeur full est utilisée).
.IP "\fB\-\-wrap\-po\fR \fBno\fR|\fBnewlines\fR|\fInombre\fR (par défaut : 76)" 4
.IX Item "--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.
.Sp
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 à \fBnewlines\fR, po4a ne séparera les msgit et msgstr qu’après les nouvelles lignes dans le contenu. Si défini à \fBno\fR, 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.
.Sp
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.
.IP "\fB\-\-msgid\-bugs\-address\fR \fBadresse@email\fR" 4
.IX Item "--msgid-bugs-address adresse@email"
Fixe l’adresse à laquelle les bogues des msgid doivent être envoyés. Par défaut, les fichiers \s-1POT\s0 créés n’ont pas de champ Report-Msgid-Bugs-To.
.IP "\fB\-\-copyright\-holder\fR \fIchaîne\fR" 4
.IX Item "--copyright-holder chaîne"
Fixe le détenteur du copyright dans l’en\-tête du fichier \s-1POT.\s0 La valeur par défaut est « Free Software Foundation, Inc. ».
.IP "\fB\-\-package\-name\fR \fIchaîne\fR" 4
.IX Item "--package-name chaîne"
Fixe le nom du paquet pour l’en\-tête du fichier \s-1POT.\s0 La valeur par défaut est « \s-1PACKAGE\s0 ».
.IP "\fB\-\-package\-version\fR \fIchaîne\fR" 4
.IX Item "--package-version chaîne"
Fixe la version du paquet pour l’en\-tête du fichier \s-1POT.\s0 La valeur par défaut est « \s-1VERSION\s0 ».
.SH "Fonctions concernant les catalogues de messages entiers"
.IX Header "Fonctions concernant les catalogues de messages entiers"
.IP "\fBnew()\fR" 4
.IX Item "new()"
Crée un nouveau catalogue. Si un paramètre est fourni, il s’agit du nom du fichier \s-1PO\s0 à lire.
.IP "read($)" 4
.IX Item "read($)"
Lit un fichier \s-1PO\s0 (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.
.IP "write($)" 4
.IX Item "write($)"
Écrit le catalogue courant dans le fichier spécifié.
.IP "write_if_needed($$)" 4
.IX Item "write_if_needed($$)"
Comme write, mais si le fichier \s-1PO\s0 ou \s-1POT\s0 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 \s-1POT\s0 juste pour mettre à jour une référence de ligne ou le champ POT-Creation-Date).
.IP "filter($)" 4
.IX 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.
.Sp
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 ».
.Sp
J’aime Perl par moments ;)
.IP "\fBto_utf8()\fR" 4
.IX Item "to_utf8()"
Ré\-encode les chaînes msgstr du \s-1PO\s0 en \s-1UTF\-8.\s0 Ne fait rien si le jeu de caractères n’est pas spécifié dans le fichier \s-1PO\s0 (la valeur du champ « \s-1CHARSET\s0 ») ou s’il est déjà en \s-1UTF\-8\s0 ou \s-1ASCII.\s0
.SH "Fonctions pour utiliser un catalogue de messages pour les traductions"
.IX Header "Fonctions pour utiliser un catalogue de messages pour les traductions"
.IP "gettext($%)" 4
.IX 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.
.Sp
Après la chaîne à traduire, vous pouvez passer un hachage de paramètres supplémentaires. Voici la liste des valeurs valables :
.RS 4
.IP "\fBwrap\fR" 4
.IX Item "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.
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
la colonne à laquelle les retours à la ligne doivent avoir lieu (76 par défaut).
.RE
.RS 4
.RE
.IP "\fBstats_get()\fR" 4
.IX Item "stats_get()"
Renvoie les statistiques sur le taux de réussite des requêtes de traduction depuis la dernière fois que \fBstats_clear()\fR 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 \s-1PO\s0 tandis que msgfmt indique l’état du fichier. Exemple d’utilisation :
.Sp
.Vb 1
\&    [une utilisation quelconque du fichier PO pour des traductions]
\&
\&    ($percent,$hit,$queries) = $pofile\->stats_get();
\&    print "Pour l’instant, $percent\e% des traductions cherchées ont été trouvées ($hit parmi $queries).\en";
.Ve
.IP "\fBstats_clear()\fR" 4
.IX Item "stats_clear()"
Oublie les statistiques sur la réussite de gettext.
.SH "Fonctions pour construire un catalogue de messages"
.IX Header "Fonctions pour construire un catalogue de messages"
.IP "push(%)" 4
.IX Item "push(%)"
Ajoute une nouvelle entrée dans le catalogue courant. Les paramètres doivent être un hachage. Les valeurs de clé valides sont :
.RS 4
.IP "\fBmsgid\fR" 4
.IX Item "msgid"
la chaîne dans la langue originale.
.IP "\fBmsgstr\fR" 4
.IX Item "msgstr"
la traduction.
.IP "\fBreference\fR" 4
.IX Item "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.
.IP "\fBcomment\fR" 4
.IX Item "comment"
un commentaire ajouté manuellement (par le traducteur). Le format est libre.
.IP "\fBautomatic\fR" 4
.IX Item "automatic"
un commentaire ajouté automatiquement par le programme d’extraction des chaînes. Veuillez vous référer à l’option \fB\-\-add\-comments\fR du programme \fBxgettext\fR pour plus d’informations.
.IP "\fBflags\fR" 4
.IX Item "flags"
liste de tous les drapeaux utilisés pour cette entrée (séparés par des espaces).
.Sp
Les valeurs valides sont : \fBc\-text\fR, \fBpython-text\fR, \fBlisp-text\fR, \fBelisp-text\fR, \fBlibrep-text\fR, \fBsmalltalk-text\fR, \fBjava-text\fR, \fBawk-text\fR, \fBobject-pascal-text\fR, \fBycp-text\fR, \fBtcl-text\fR, \fBwrap\fR, \fBno-wrap\fR et \fBfuzzy\fR.
.Sp
Voir la documentation de gettext pour leur signification.
.IP "\fBtype\fR" 4
.IX Item "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 \s-1PO,\s0 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.
.Sp
Cette information est également reportée dans le fichier \s-1PO\s0 sous forme de commentaire automatique car elle indique le contexte des chaînes à traduire.
.IP "\fBwrap\fR" 4
.IX Item "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.
.Sp
Cette information est reportée dans le fichier \s-1PO\s0 grâce aux drapeaux \fBwrap\fR (si vrai) et \fBno-wrap\fR (sinon).
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
la colonne à laquelle les retours à la ligne doivent avoir lieu (76 par défaut).
.Sp
Cette information n’est pas reportée dans le fichier \s-1PO.\s0
.RE
.RS 4
.RE
.SH "Fonctions diverses"
.IX Header "Fonctions diverses"
.IP "\fBcount_entries()\fR" 4
.IX Item "count_entries()"
Renvoie le nombre d’entrées dans le catalogue (sans compter l’en\-tête).
.IP "\fBcount_entries_doc()\fR" 4
.IX 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.
.IP "msgid($)" 4
.IX Item "msgid($)"
Renvoie le msgid du numéro fourni.
.IP "msgid_doc($)" 4
.IX Item "msgid_doc($)"
Renvoie le msgid qui a la position donnée dans le document.
.IP "type_doc($)" 4
.IX 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 \f(CW$msgid\fR est dupliqué dans le document maître.
.IP "\fBget_charset()\fR" 4
.IX Item "get_charset()"
Renvoie le jeu de caractères spécifié dans l’en\-tête du \s-1PO.\s0 S’il n’a pas été défini, il renvoie « \s-1UTF\-8\s0 ».
.IP "set_charset($)" 4
.IX Item "set_charset($)"
Permet de fixer le jeu de caractères de l’en\-tête du \s-1PO\s0 à 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 à « \s-1UTF\-8\s0 ». 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 \fBget_charset()\fR.
.SH "AUTEURS"
.IX Header "AUTEURS"
.Vb 2
\& Denis Barbier <barbier@linuxfr.org>
\& Martin Quinson (mquinson#debian.org)
.Ve
.SH "TRADUCTION"
.IX Header "TRADUCTION"
.Vb 1
\& Martin Quinson (mquinson#debian.org)
.Ve