Provided by: po4a_0.57-2_all bug

NOM

       po4a - Mettre à jour à la fois les fichiers PO et les documents traduits

SYNOPSIS

       po4a [options] fichier_de_configuration

DESCRIPTION

       L’objectif du projet po4a [PO for anything — PO pour tout] est de simplifier la traduction
       (et de façon plus intéressante, la maintenance des traductions) en utilisant les outils
       gettext dans des domaines pour lesquels ils n’étaient pas destinés, comme la
       documentation.

       Le programme po4a permet d’éviter d’appeler po4a-gettextize(1), po4a-updatepo(1), et
       po4a-translate(1) dans des Makefiles compliqués quand plusieurs fichiers doivent être
       traduits, si différents formats sont utilisés, ou pour indiquer des options différentes
       suivant les documents.

Table des matières

       Ce document est organisé de la manière suivante :

   DESCRIPTION
   INTRODUCTION
   SYNTAXE DU FICHIER DE CONFIGURATION
       Spécifier un modèle pour les différentes langues

       Spécifier les chemins des fichiers des traducteurs

       Détection automatique des chemins et langues

       Spécification des documents à traduire

       Fournir des options aux modules

       Spécifier des alias

       Mode réparti

   OPTIONS
   EXEMPLE
   DÉFAUTS
   VOIR AUSSI
   AUTEURS
   COPYRIGHT ET LICENCE

INTRODUCTION

       Le programme po4a est chargé de mettre à jour à la fois les fichiers PO (les synchroniser
       avec les documents originaux) et les documents traduits (les synchroniser avec les
       fichiers PO). Le principal avantage est de faciliter l’utilisation de po4a sans avoir
       besoin de se souvenir des options en ligne de commande.

       Il vous permet de mélanger des documents de différents formats dans le même fichier POT de
       façon à n’en avoir qu’un seul par projet.

       Ce comportement peut être imité par les autres outils de la suite po4a (par exemple avec
       des Makefiles), mais il est relativement difficile à faire, et fatigant de toujours
       refaire les mêmes Makefiles compliqués pour chaque projet utilisant po4a.

       Le flux des données peut se résumer de la façon suivante. Tout changement dans le document
       d’origine est reflété dans les fichiers PO, et tout changement dans les fichiers PO (qu’il
       soit manuel ou causé par une des étapes précédentes) sera reflété dans les documents
       traduits.

       Cas normal sans spécifier pot_in :

        <- fichiers source ->|<--------- résultat de la compilation --------------->

        addendum ----------------------------------+
                                                   |
        document maître --+---------------------+  |
                          V                     +--+--> traductions
        anciens fichiers PO -----+-→ fichiers PO mis à jour +
             ^                      |
             |                      V
             +<.....................+
           (les fichiers PO mis à jour sont copiés
            manuellement vers la source de la version
            suivante tout en mettant à jour manuellement
            le contenu des traductions)

       Cas spécial en spécifiant pot_in :

        <- fichiers source ->|<--------- résultats de la compilation ----------------->

        document maître --+--------------+
                          :              |
        prog de           :     doc      v
        filtrage =========X--> maître    |
        externe                filtré    +----> traductions
                                 |       ^
                                 V       |
        anciens fichiers PO ->---+--> fichiers PO à jour
             ^                           |
             |                           V
             +<..........................+
           (les fichiers PO mis à jour sont copiés
            manuellement vers la source de la version
            suivante tout en mettant à jour manuellement
            le contenu des traductions)

       Le flux de données ne peut pas être inversé dans cet outil, et les changements dans les
       traductions sont écrasés par le contenu des fichiers PO. Cet outil ne peut donc pas être
       utilisé pour convertir les traductions existantes à po4a. Pour ceci, veuillez consulter
       po4a-gettextize(1).

SYNTAXE DU FICHIER DE CONFIGURATION

       Le paramètre (obligatoire) indique le chemin du fichier de configuration à utiliser. Sa
       syntaxe a vocation d’être simple et proche des autres fichiers de configuration utilisés
       par les projets d’internationalisation.

       Des commentaires peuvent être ajoutés à ce fichier avec le caractère « # ». Tout ce qui
       suit ce caractère sur une ligne est considéré comme un commentaire. Les lignes peuvent se
       poursuivre en ajoutant un caractère d’échappement à la fin de la ligne. Toute ligne non
       vide doit débuter par une commande entre crochets, suivie de ses paramètres. (Ça peut
       paraître difficile à première vue, mais c’est en fait assez simple, enfin je l’espère ;)

   Spécifier un modèle pour les différentes langues
       Note : L’utilisation de [po_directory] est préférable à [po4a_langs] et [po4a_paths] (voir
       Détection automatique des chemins et langues plus bas).

       C’est une commande optionnelle qui permet de simplifier le fichier de configuration
       lorsqu’il est utilisé pour de nombreuses langues. Il vous suffit de spécifier les langues
       vers lesquelles vous voulez traduire les documents, ce qui se fait aussi simplement que :

        [po4a_langs] fr de

       Ceci vous permettra de développer $lang dans toutes les langues spécifiées pour le reste
       du fichier de configuration.

   Spécifier les chemins des fichiers des traducteurs
       Note : L’utilisation de [po_directory] est préférable à [po4a_langs] et [po4a_paths] (voir
       Détection automatique des chemins et langues plus bas).

       D’abord, vous devez spécifier où se trouvent les fichiers fournis aux traducteurs. Ceci
       peut être fait de la façon suivante :

        [po4a_paths] doc/l10n/project.doc.pot \
                     fr:doc/l10n/fr.po de:doc/l10n/de.po

       La commande est donc [po4a_paths]. Le premier paramètre est le chemin du fichier POT à
       utiliser. Les autres paramètres se comprennent par eux-mêmes :

           <langue>:<chemin vers le fichier PO de cette langue>

       Si vous avez défini un modèle pour les langues, vous pouvez écrire la ligne précédente de
       cette façon :

        11 [po4a_paths] doc/l10n/project.doc.pot $lang:doc/l10n/$lang.po

       Vous pouvez également utiliser $master pour faire référence au nom de fichier du document.
       Dans ce cas, po4a utilisera un mode réparti : un POT et un PO (par langue) sera créé pour
       chaque document présent dans le fichier de configuration de po4a. Consultez la section
       Mode réparti.

        [po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po

   Détection automatique des chemins et langues
       Une autre commande peut être utilisée pour indiquer le nom d’un répertoire où se trouvent
       les fichiers PO et POT. Quand elle est utilisée, po4a détectera le fichier POT comme le
       seul fichier *.pot du répertoire indiqué. po4a utilisera aussi la liste de tous les
       fichiers *.po pour définir la liste des langues (en enlevant l’extension). Ces langues
       seront utilisées pour la substitution de la variable $lang dans le reste du fichier de
       configuration.

       Cette commande ne doit pas être utilisée avec les commandes [po4a_langs] ou [po4a_paths].

       Lors de l’utilisation de cette commande, il est nécessaire de créer un fichier POT vide
       pour le premier appel à po4a afin qu’il connaisse le nom du fichier POT.

        [po_directory] po4a/po/

   Spécification des documents à traduire
       Vous devez maintenant spécifier quels documents doivent être traduits, leur format et où
       placer leurs traductions. Ceci peut être fait par ces lignes :

        [type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
                     de:doc/de/mein_kram.sgml
        [type: pod] script fr:doc/fr/script.1 de:doc/de/script.1 \
                    add_fr:doc/l10n/script.fr.add
        [type: docbook] doc/script.xml fr:doc/fr/script.xml \
                    de:doc/de/script.xml \
                    pot_in:doc/script.filtered.xml

       Ceci est plutôt explicite. Notez que dans le second cas, doc/l10n/script.fr.add est un
       addendum à ajouter à la version française du document. Veuillez vous référer à po4a(7)
       pour plus d’informations à propos des addenda.

       Plus formellement, le format est le suivant :

        [type: <format>] <doc_maître> (<lang>:<doc_traduit>)* \
                         (pot_in:<doc_maître_filtré>)? \
                         (add_<lang>:<modificateur>*<addendum>)*

       Si pot_in est spécifié, doc_maître_filtré est utilisé à la place de doc_maître pour
       produire le fichier POT. Cela offre une grande flexibilité pour s'assurer que certain
       contenus ne seront pas inclus dans le fichier PO. Vous pouvez utiliser l'outil de votre
       choix pour ce filtrage, comme par exemple le préprocesseur C (cpp) ou un utilitaire de
       transformation XSL (tel que xslproc). Assurez-vous simplement d'effectuer ce filtrage
       avant d'invoquer po4a.

       En absence de modificateurs, addendum est le chemin vers un addendum. Les modificateurs
       sont :

       ? Inclure l’addendum si le fichier existe, rien sinon.

       @ addendum n’est pas un fichier addendum normal mais un fichier contenant une liste
         d’addenda, un par ligne. Chaque addendum peut être précédé de modificateurs.

       ! addendum n’est pas pris en compte, il n’est pas chargé et ne le sera pas lors de toute
         autre indication d’addendum.

       Si vous avez défini un modèle pour les langues, vous pouvez écrire la ligne précédente de
       cette façon :

        [type: pod] script $lang:doc/$lang/script.1 \
                    add_fr:doc/l10n/script.fr.add

       Si toutes les langues ont des addenda situés dans des chemins similaires, vous pourriez
       également écrire quelque chose comme :

        [type: pod] script $lang:doc/$lang/script.1 \
                    add_$lang:doc/l10n/script.$lang.add

   Fournir des options aux modules
       po4a accepte des options qui seront fournies au module. Ces options sont spécifiques au
       module et sont spécifiées avec l’option -o.

       Si vous voulez fournir une option spécifique pour un des documents que vous voulez
       traduire, vous pouvez la préciser dans le fichier de configuration. Les options sont
       introduites par le mot clef opt. Les paramètres du mot clef opt doivent être placés entre
       guillemets s’ils contiennent des espaces (par exemple si vous précisez plusieurs options,
       ou une option avec un paramètre). Vous pouvez également spécifier des options qui ne
       s’appliqueront qu’à une seule langue en utilisant le mot clef opt_lang.

       Voici un exemple :
        [type:man] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
                   opt:"-k 75" opt_it:"-L UTF-8" opt_fr:-v

       Les arguments peuvent contenir des espaces si vous utilisez des guillemets simples ou si
       vous protégez les guillemets doubles comme ceci :
        [po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\" -k 20"

       Pour préciser les mêmes options pour un jeu de documents, vous pouvez utiliser un alias
       (consultez la section Spécifier des alias ci-dessous).

       Vous pouvez aussi définir des options pour tous les documents du fichier de
       configuration :
        [options] opt:"..." opt_fr:"..."

   Spécifier des alias
       Si vous devez fournir les mêmes options pour plusieurs fichiers, vous avez intérêt à
       définir un alias de module. Ceci se fait de cette façon :

        [po4a_alias:test] man opt:"-k 21" opt_es:"-o debug=splitargs"

       Ceci définit un alias de module nommé test, basé sur le module man. L’option -k 21
       s’appliquera à toutes les langues et l’option -o debug=splitargs uniquement à l’espagnol.

       Cet alias de module peut ensuite être utilisé comme un module normal :

        [type:test] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
                    opt_it:"-L UTF-8" opt_fr:-v

       Remarquez que vous pouvez encore ajouter des options fichier par fichier.

   Mode réparti
       Le mode réparti est utilisé quand $master est utilisé dans la ligne [po4a_paths].

       Quand le mode réparti est utilisé, un gros POT et de gros POs sont créés temporairement.
       Ceci permet de partager les traductions entre tous les POs.

       Si deux POs ont deux traductions différentes pour la même chaîne, po4a marquera cette
       chaîne comme étant approximative (fuzzy) et proposera les deux traductions dans tous les
       POs qui contiennent cette chaîne. Ensuite, lorsqu’un traducteur mettra à jour la chaîne
       dans un PO et retirera l’étiquette fuzzy, la traduction de cette chaîne sera mise à jour
       dans tous les POs automatiquement.

       Si des noms sont en conflit parce que plusieurs fichiers ont le même nom, le nom du
       fichier maître peut être indiqué en ajoutant une option "master:file="nom :

        [po4a_langs] de fr ja
        [po4a_paths] l10n/po/$master.pot $lang:l10n/po/$master.$lang.po
        [type: xml] truc/interface.xml $lang:foo/gui.$lang.xml master:file=truc-interface
        [type: xml] bidule/interface.xml $lang:bar/gui.$lang.xml master:file=bidule-interface

OPTIONS

       -k, --keep
           Seuil à dépasser afin que le fichier généré soit conservé et écrit sur disque (80 par
           défaut). C’est-à-dire que par défaut, les fichiers générés doivent être traduits à
           plus de 80% pour être écrits.

       -h, --help
           Affiche un message d’aide.

       -M, --master-charset
           Jeu de caractères des fichiers contenant les documents à traduire. Notez que tous les
           documents maîtres doivent partager le même jeu de caractères pour l’instant. C’est une
           limitation connue ; nous travaillons à sa résolution.

       -L, --localized-charset
           Jeu de caractères des fichiers contenant les documents traduits. Notez que tous les
           documents traduits doivent partager le même jeu de caractères pour l’instant. C’est
           une limitation connue ; nous travaillons à sa résolution.

       -A, --addendum-charset
           Jeu de caractères des addenda. Notez que tous les ajouts doivent partager le même jeu
           de caractères.

       -V, --version
           Affiche la version du script et quitte.

       -v, --verbose
           Rend le programme plus bavard.

       -q, --quiet
           Rend le programme moins bavard.

       -d, --debug
           Affiche quelques informations de débogage.

       -o, --option
           Passe une ou des options supplémentaires au greffon de format. Spécifiez chaque option
           en utilisant le format name=value. Veuillez vous référer à la documentation de chaque
           greffon pour la liste des options valides et leurs significations.

       -f, --force
           Génère toujours les fichiers POT et PO, même si po4a considère que ce n’est pas
           nécessaire.

           Le comportement par défaut (quand l’option --force n’est pas utilisée) est le
           suivant :

               Si le fichier POT existe déjà, il est recréé si un document maître ou le fichier
               de configuration est plus récent. De plus, le fichier POT est écrit dans un
               document temporaire, et po4a vérifie que les modifications valent le coup.

               De plus, une traduction est mise à jour seulement si le document maître, le
               fichier PO, un de ses addenda ou le fichier de configuration est plus récent. Pour
               éviter de retenter de créer une traduction qui ne passe pas le test du seuil (voir
               l’option --keep), un fichier avec une extension .po4a-stamp peut être créé (voir
               l’option --stamp).

           Si un document maître inclut d’autres fichiers, vous devriez utiliser l’option --force
           parce que les dates de modification de ces fichiers ne sont pas prises en compte.

           Les fichiers PO sont toujours recréés en fonction du POT avec msgmerge -U.

       --stamp
           Indique à po4a de créer des fichiers d’horodatage quand une traduction n’a pas été
           générée parce qu’elle ne dépasse pas le seuil de traduction. Ces fichiers d’horodatage
           sont nommés en ajoutant l’extension .po4a-stamp au nom du fichier à générer.

           Note : Cette option ne concerne que la création des fichiers .po4a-stamp. Ces fichiers
           d’horodatage sont toujours utilisés s’ils existent et sont retirés quand l’option
           --rm-translations est utilisée ou quand le fichier est finalement traduit.

       --no-translations
           Ne génère pas les documents traduits, ne met à jour que les fichiers POT et PO.

       --no-update
           Ne modifiez pas les fichiers POT et PO, seule la traduction peut être changée.

       --keep-translations
           Garde les traductions existantes même si la traduction de satisfait pas le seuil
           spécifié par --keep. Cette option ne va pas créer de fichiers peu traduits, mais elle
           préservera les fichiers existants dont la quantité de traduction décroît à cause de
           changements dans les fichiers maîtres.

           ATTENTION ! Cette option change profondément le comportement de po4a. Vos fichiers
           traduits ne seront plus modifiés jusqu'à ce que la traduction soit améliorée.
           N'utilisez cette option que si vous préférez distribuer une traduction obsolète bien
           traduite plutôt qu'une traduction à jour mais mal traduite.

       --rm-translations
           Supprime les documents traduits (implique --no-translations).

       --no-backups
           Cette option ne fait rien depuis la version 0.41, et pourra être enlevée des
           prochaines versions.

       --rm-backups
           Cette option ne fait rien depuis la version 0.41, et pourra être enlevée des
           prochaines versions.

       --translate-only fichier-traduit
           Traduit uniquement le fichier indiqué. Il est parfois utile d’accélérer le processus
           si le fichier de configuration contient beaucoup de fichiers. Remarquez qu’avec cette
           option, les fichiers PO et POT ne seront pas mis à jour. Cette option peut être
           utilisée plusieurs fois.

       --variable var=valeur
           Définit une variable dont toutes les occurrences seront remplacées dans le fichier de
           configuration de po4a. Les occurrences de $(var) seront remplacées par valeur. Cette
           option peut être utilisée plusieurs fois.

       --srcdir RÉP_SRC
           Définit le répertoire de base pour tous les documents d’entrée indiqués dans le
           fichier de configuration de po4a.

       --destdir RÉP_DEST
           Définit le répertoire de base pour tous les documents de sortie indiqués dans le
           fichier de configuration de po4a.

   OPTIONS POUR MODIFIER L’EN-TÊTE POT
       --porefs type[,wrap|nowrap]
           Indique le format des références. L’argument type peut-être never pour ne pas produire
           de référence, file pour n’indiquer que le fichier sans le numéro de ligne, counter
           pour remplacer le numéro de ligne par un décompte croissant, et full pour inclure des
           références complètes (par défaut, la valeur full est utilisée).

           L’argument peut être suivi d’une virgule et d’un des mots clefs wrap ou nowrap. Les
           références sont écrites par défaut sur une seule ligne. Avec l’option wrap, les
           références sont placées sur plusieurs lignes, pour imiter le comportement des outils
           gettext (xgettext and msgmerge). Cette option deviendra la valeur par défaut dans une
           prochaine version, car elle est plus pertinente. L’option nowrap est disponible pour
           permettre aux utilisateurs de conserver l’ancien comportement s’ils le désirent.

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

       --copyright-holder 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. ».

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

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

   OPTIONS POUR MODIFIER LES FICHIERS PO
       --msgmerge-opt options
           Options additionnelles pour msgmerge(1).

           Note : $lang sera remplacé par la langue en cours.

       --no-previous
           Cette option supprime --previous des options passées à msgmerge. Elle permet de
           prendre en charge les versions de gettext antérieures à 0.16.

       --previous
           Cette option ajoute --previous aux options passées à msgmerge. Elle nécessite une
           version 0.16 ou ultérieure de gettext et est activée par défaut.

   EXEMPLE
       Considérons que vous soyez responsable d’un programme truc avec sa page de manuel
       man/truc.1 naturellement maintenue seulement en anglais. Maintenant, en tant que
       développeur amont ou responsable aval, vous désirez créer et maintenir la traduction. Vous
       devez d’abord créer le fichier POT nécessaire à envoyer au traducteur avec
       po4a-gettextize(1).

       Ainsi dans notre cas, nous ferons

        cd man && po4a-gettextize -f man -m truc.1 -p truc.pot

       Vous pourrez alors envoyer ce fichier aux listes de traductions adéquates ou le rendre
       disponible au téléchargement quelque part.

       Considérons maintenant que vous receviez trois traductions avant la prochaine
       publication : de.po (avec un addendum de.add), sv.po et pt.po. Puisque vous n’avez pas
       l’intention de modifier le ou les fichiers Makefile à chaque nouvelle traduction reçue,
       vous pouvez utiliser po4a avec le fichier de configuration adéquat dans chaque Makefile.
       Ce fichier de configuration peut s’appeler po4a.cfg, dans cet exemple, il ressemblerait
       à :

        [po_directory] man/po4a/po/

        [type: man] man/truc.1 $lang:man/translated/$lang/truc.1 \
                   add_$lang:?man/po4a/add_$lang/$lang.add opt:"-k 80"

       Dans cet exemple, nous considérons que les pages de manuel créées (ainsi que tous les
       fichiers PO et addenda) devraient être gardés dans man/translated/$lang/ (respectivement
       dans man/po4a/po/ et man/po4a/add_$lang/) à l’intérieur du répertoire en cours. Ici le
       répertoire man/po4a/po/ contiendrait de.po, pt.po et sv.po et le répertoire
       man/po4a/add_de/ contiendrait de.add.

       Remarquez l’utilisation du modificateur ? car seule la traduction allemande (de.po) est
       accompagnée d’un addendum.

       Pour vraiment construire les pages de manuel traduites, vous devrez alors (une seule fois)
       ajouter la ligne suivante dans la cible build du Makefile adéquat :

               po4a po4a.cfg

       Une fois configuré, il ne sera plus nécessaire de modifier le Makefile à chaque nouvelle
       traduction reçue. Si par exemple l’équipe de traduction française vous envoie fr.po et
       fr.add, il suffit de les déposer respectivement dans  man/po4a/po/ et man/po4a/add_fr/ et
       la prochaine fois que le programme sera construit, la traduction française sera aussi
       automatiquement construite dans man/translated/fr/.

       Notez que vous avez toujours besoin d’une cible adéquate pour installer les pages de
       manuel traduites en plus de celles en anglais.

       Enfin, si vous ne voulez pas garder les fichiers créés dans le système de gestion de
       version, vous devriez aussi ajouter cette ligne à la cible clean :
               -rm -rf man/translated

DÉFAUTS

       •   Duplique du code des autres programmes de la suite po4a.

       Toute rustine est la bienvenue ;)

VOIR AUSSI

       po4a-gettextize(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7)

AUTEURS

        Denis Barbier <barbier@linuxfr.org>
        Nicolas François <nicolas.francois@centraliens.net>
        Martin Quinson (mquinson#debian.org)

TRADUCTION

        Martin Quinson (mquinson#debian.org)

COPYRIGHT ET LICENCE

       Copyright 2002-2012 par SPI, inc.

       Ce programme est un logiciel libre ; vous pouvez le copier et / ou le modifier sous les
       termes de la GPL (voir le fichier COPYING).