Provided by: po4a_0.41-1_all bug

NOM

       po4a - Mettre a jour a 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 facon plus interessante, la maintenance
       des traductions) en utilisant les outils gettext dans des domaines pour
       lesquels ils n'etaient pas destines, comme la documentation.

       Le programme po4a permet d'eviter d'appeler po4a-gettextize(1),
       po4a-updatepo(1), et po4a-translate(1) dans des Makefiles compliques
       quand plusieurs fichiers doivent etre traduits, si differents formats
       sont utilises, ou pour indiquer des options differentes suivant les
       documents.

Table des mati`eres

       Ce document est organise de la maniere suivante:

   DESCRIPTION
   INTRODUCTION
   SYNTAXE DU FICHIER DE CONFIGURATION
       Sp'ecifier un mod`ele pour les diff'erentes langues

       Sp'ecifier les chemins des fichiers des traducteurs

       D'etection automatique des chemins et langues

       Sp'ecification des documents `a traduire

       Fournir des options aux modules

       Sp'ecifier des alias

       Mode r'eparti

   OPTIONS
   EXEMPLE
   D'EFAUTS
   VOIR AUSSI
   AUTEURS
   COPYRIGHT ET LICENCE

INTRODUCTION

       Le programme po4a est charge de mettre a jour a 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 melanger des documents de differents formats dans le
       meme fichier POT de facon a n'en avoir qu'un seul par projet.

       Ce comportement peut etre imite par les autres outils de la suite po4a
       (par exemple avec des Makefiles), mais il est relativement difficile a
       faire, et fatigant de toujours refaire les memes Makefiles compliques
       pour chaque projet utilisant po4a.

       Le flux des donnees peut se resumer de la facon suivante. Tout
       changement dans le document d'origine est reflete dans les fichiers PO,
       et tout changement dans les fichiers PO (qu'il soit manuel ou cause par
       une des etapes precedentes) sera reflete dans les documents traduits.

        document maitre --> fichiers PO --> traductions

       Le flux de donnees ne peut pas etre inverse dans cet outil, et les
       changements dans les traductions sont ecrases par le contenu des
       fichiers PO. Cet outil ne peut donc pas etre utilise pour convertir les
       traductions existantes a po4a. Pour ceci, veuillez consulter
       po4a-gettextize(1).

SYNTAXE DU FICHIER DE CONFIGURATION

       Le parametre (obligatoire) indique le chemin du fichier de
       configuration a utiliser. Sa syntaxe a vocation d'etre simple et proche
       des autres fichiers de configuration utilises par les projets
       d'internationalisation.

       Des commentaires peuvent etre ajoutes a ce fichier avec le caractere
       <<#>>. Tout ce qui suit ce caractere sur une ligne est considere comme
       un commentaire. Les lignes peuvent se poursuivre en ajoutant un
       caractere d'echappement a la fin de la ligne. Toute ligne non vide doit
       debuter par une commande entre crochets, suivie de ses parametres. (Ca
       peut paraitre difficile a premiere vue, mais c'est en fait assez
       simple, enfin je l'espere;)

   Sp'ecifier un mod`ele pour les diff'erentes langues
       Note: L'utilisation de [po_directory] est preferable a [po4a_langs] et
       [po4a_paths] (voir D'etection automatique des chemins et langues plus
       bas).

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

        [po4a_langs] fr de

       Ceci vous permettra de developper $lang dans toutes les langues
       specifiees pour le reste du fichier de configuration.

   Sp'ecifier les chemins des fichiers des traducteurs
       Note: L'utilisation de [po_directory] est preferable a [po4a_langs] et
       [po4a_paths] (voir D'etection automatique des chemins et langues plus
       bas).

       D'abord, vous devez specifier ou se trouvent les fichiers fournis aux
       traducteurs. Ceci peut etre fait de la facon 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 parametre est le chemin
       du fichier POT a utiliser. Les autres parametres se comprennent par
       eux-memes:

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

       Si vous avez defini un modele pour les langues, vous pouvez ecrire la
       ligne precedente de cette facon:

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

       Vous pouvez egalement utiliser $master pour faire reference au nom
       (sans le chemin) du document. Dans ce cas, po4a utilisera un mode
       reparti: un POT et un PO (par langue) sera cree pour chaque document
       present dans le fichier de configuration de po4a. Consultez la section
       Mode r'eparti.

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

   D'etection automatique des chemins et langues
       Une autre commande peut etre utilisee pour indiquer le nom d'un
       repertoire ou se trouvent les fichiers PO et POT. Quand elle est
       utilisee, po4a detectera le fichier POT comme le seul fichier *.pot du
       repertoire indique. po4a utilisera aussi la liste de tous les fichiers
       *.po pour definir la liste des langues (en enlevant l'extension). Ces
       langues seront utilisees pour la substitution de la variable $lang dans
       le reste du fichier de configuration.

       Cette commande ne doit pas etre utilisee avec les commandes
       [po4a_langs] ou [po4a_paths].

       Lors de l'utilisation de cette commande, il est necessaire de creer un
       fichier POT vide pour le premier appel a po4a afin qu'il connaisse le
       nom du fichier POT.

        [po_directory] po4a/po/

   Sp'ecification des documents `a traduire
       Vous devez maintenant specifier quels documents doivent etre traduits,
       leur format et ou placer leurs traductions. Ceci peut etre fait par ces
       lignes:

        [type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
                     de:doc/de/mein_cram.sgml
        [type: pod] script fr:doc/fr/script.1 de:doc/de/script.1 \
                    add_fr:doc/l10n/script.fr.add

       Ceci est plutot explicite. Notez que dans le second cas,
       doc/l10n/script.fr.add est un addendum a ajouter a la version francaise
       du document. Veuillez vous referer a po4a(7) pour plus d'informations a
       propos des addenda.

       Plus formellement, le format est le suivant:

        [type: <format>] <doc_maitre> (<lang>:<doc_traduit>)* \
                         (add_<lang>:<modificateur>*<addendum>)*

       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
         etre precede de modificateurs.

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

       Si vous avez defini un modele pour les langues, vous pouvez ecrire la
       ligne precedente de cette facon:

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

       Si toutes les langues ont des addenda situes dans des chemins
       similaires, vous pourriez egalement ecrire 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 specifiques au module et sont specifiees avec l'option -o.

       Si vous voulez fournir une option specifique pour un des documents que
       vous voulez traduire, vous pouvez la preciser dans le fichier de
       configuration. Les options sont introduites par le mot cle opt. Les
       parametres du mot cle opt doivent etre places entre guillemets s'ils
       contiennent des espaces (par exemple si vous precisez plusieurs
       options, ou une option avec un parametre). Vous pouvez egalement
       specifier des options qui ne s'appliqueront qu'a une seule langue en
       utilisant le mot cle opt_lang.

       Voici un exemple:
        [type:man] data-05/test2_man.1 $lang:tmp/test2_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 protegez les guillemets doubles comme
       ceci:
        [po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\" -k 20"

       Pour preciser les memes options pour un jeu de documents, vous pouvez
       utiliser un alias (consultez la section Sp'ecifier des alias ci-
       dessous).

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

   Sp'ecifier des alias
       Si vous devez fournir les memes options pour plusieurs fichiers, vous
       avez interet a definir un alias de module. Ceci se fait de cette facon:

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

       Ceci definit un alias de module nomme test, base sur le module man.
       L'option -k 21 s'appliquera a toutes les langues et l'option -o
       debug=splitargs uniquement a l'espagnol.

       Cet alias de module peut ensuite etre utilise comme un module normal:

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

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

   Mode r'eparti
       Le mode reparti est utilise quand $master est utilise dans la ligne
       [po4a_paths].

       Quand le mode reparti est utilise, un gros POT et de gros POs sont
       crees temporairement. Ceci permet de partager les traductions entre
       tous les POs.

       Si deux POs ont deux traductions differentes pour la meme chaine, po4a
       marquera cette chaine comme etant approximative (fuzzy) et proposera
       les deux traductions dans tous les POs qui contiennent cette chaine.
       Ensuite, lorsqu'un traducteur mettra a jour la chaine dans un PO et
       retirera l'etiquette fuzzy, la traduction de cette chaine sera mise a
       jour dans tous les POs automatiquement.

OPTIONS

       -k, --keep
           Seuil a depasser afin que le fichier genere soit conserve et ecrit
           sur disque (80 par defaut). C'est-a-dire que par defaut, les
           fichiers generes doivent etre traduits a plus de 80% pour etre
           ecrits.

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

       -M, --master-charset
           Jeu de caracteres des fichiers contenant les documents a traduire.
           Notez que tous les documents maitres doivent partager le meme jeu
           de caracteres pour l'instant. C'est une limitation connue; nous
           travaillons a sa resolution.

       -L, --localized-charset
           Jeu de caracteres des fichiers contenant les documents traduits.
           Notez que tous les documents traduits doivent partager le meme jeu
           de caracteres pour l'instant. C'est une limitation connue; nous
           travaillons a sa resolution.

       -A, --addendum-charset
           Jeu de caracteres des addenda. Notez que tous les ajouts doivent
           partager le meme jeu de caracteres.

       -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 debogage.

       -o, --option
           Passe une ou des options supplementaires au greffon de format.
           Specifiez chaque option en utilisant le format name=value. Veuillez
           vous referer a la documentation de chaque greffon pour la liste des
           options valides et leurs significations.

       -f, --force
           Genere toujours les fichiers POT et PO, meme si po4a considere que
           ce n'est pas necessaire.

           Le comportement par defaut (quand l'option --force n'est pas
           utilisee) est le suivant:

               Si le fichier POT existe deja, il est recree si un document
               maitre ou le fichier de configuration est plus recent. De plus,
               le fichier POT est ecrit dans un document temporaire, et po4a
               verifie que les modifications valent le coup.

               De plus, une traduction est mise a jour seulement si le
               document maitre, le fichier PO, un de ses addenda ou le fichier
               de configuration est plus recent. Pour eviter de retenter de
               creer une traduction qui ne passe pas le test du seuil (voir
               l'option --keep), un fichier avec une extension .po4a-stamp
               peut etre cree (voir l'option --stamp).

           Si un document maitre 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 recrees en fonction du POT avec
           msgmerge -U.

       --stamp
           Indique a po4a de creer des fichiers d'horodatage quand une
           traduction n'a pas ete generee parce qu'elle ne depasse pas le
           seuil de traduction. Ces fichiers d'horodatage sont nommes en
           ajoutant l'extension .po4a-stamp au nom du fichier a generer.

           Note: Cette option ne concerne que la creation des fichiers
           .po4a-stamp. Ces fichiers d'horodatage sont toujours utilises s'ils
           existent et sont retires quand l'option --rm-translations est
           utilisee ou quand le fichier est finalement traduit.

       --no-translations
           Ne genere pas les documents traduits, ne met a jour que les
           fichiers POT et PO.

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

       --no-backups
           Cette option ne fait rien depuis la version0.41, et pourra etre
           enlevee des prochaines versions.

       --rm-backups
           Cette option ne fait rien depuis la version0.41, et pourra etre
           enlevee des prochaines versions.

       --translate-only fichier-traduit
           Traduit uniquement le fichier indique. Il est parfois utile
           d'accelerer 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 a jour. Cette option peut etre utilisee
           plusieurs fois.

       --variable var=valeur
           Definit une variable dont toutes les occurrences seront remplacees
           dans le fichier de configuration de po4a. Les occurrences de $(var)
           seront remplacees par valeur. Cette option peut etre utilisee
           plusieurs fois.

       --msgid-bugs-address adresse@email
           Fixe l'adresse a laquelle les bogues des msgid doivent etre
           envoyes. Par defaut, les fichiers POT crees n'ont pas de champ
           Report-Msgid-Bugs-To.

       --copyright-holder cha^ine
           Fixe le detenteur du copyright dans l'en-tete du fichier POT. La
           valeur par defaut est <<Free Software Foundation, Inc.>>.

       --package-name cha^ine
           Fixe le nom du paquet pour l'en-tete du fichier POT. La valeur par
           defaut est <<PACKAGE>>.

       --package-version cha^ine
           Fixe la version du paquet pour l'en-tete du fichier POT. La valeur
           par defaut est <<VERSION>>.

       --msgmerge-opt options
           Options additionnelles pour msgmerge.

           Note: $lang sera remplace par la langue en cours.

       --no-previous
           Cette option supprime --previous des options passees a msgmerge.
           Elle permet de prendre en charge les versions de gettext
           anterieures a 0.16.

       --previous
           Cette option ajoute --previous aux options passees a msgmerge. Elle
           necessite une version 0.16 ou ulterieure de gettext et est activee
           par defaut.

       --srcdir R'EP_SRC
           Definit le repertoire de base pour tous les documents d'entree
           indiques dans le fichier de configuration de po4a.

       --destdir R'EP_DEST
           Definit le repertoire de base pour tous les documents de sortie
           indiques dans le fichier de configuration de po4a.

   EXEMPLE
       Considerons 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 developpeur amont ou responsable aval, vous
       desirez creer et maintenir la traduction. Vous devez d'abord creer le
       fichier POT necessaire a 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
       adequates ou le rendre disponible au telechargement quelque part.

       Considerons 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 a chaque nouvelle traduction recue, vous pouvez utiliser po4a
       avec le fichier de configuration adequat dans chaque Makefile. Ce
       fichier de configuration peut s'appeler po4a.cfg, dans cet exemple, il
       ressemblerait a:

        [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 considerons que les pages de manuel creees
       (ainsi que tous les fichiers PO et addenda) devraient etre gardes dans
       man/translated/$lang/ (respectivement dans man/po4a/po/ et
       man/po4a/add_$lang/) a l'interieur du repertoire en cours. Ici le
       repertoire man/po4a/po/ contiendrait de.po, pt.po et sv.po et le
       repertoire man/po4a/add_de/ contiendrait de.add.

       Remarquez l'utilisation du modificateur ? car seule la traduction
       allemande (de.po) est accompagnee 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 adequat:

               po4a po4a.cfg

       Une fois configure, il ne sera plus necessaire de modifier le Makefile
       a chaque nouvelle traduction recue. Si par exemple l'equipe de
       traduction francaise vous envoie fr.po et fr.add, il suffit de les
       deposer respectivement dans  man/po4a/po/ et man/po4a/add_fr/ et la
       prochaine fois que le programme sera construit, la traduction francaise
       sera aussi automatiquement construite dans man/translated/fr/.

       Notez que vous avez toujours besoin d'une cible adequate pour installer
       les pages de manuel traduites en plus de celles en anglais.

       Enfin, si vous ne voulez pas garder les fichiers crees dans le systeme
       de gestion de version, vous devriez aussi ajouter cette ligne a la
       cible clean:
               -rm -rf man/translated

D'EFAUTS

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

       Toute rustine est la bienvenue;)

VOIR AUSSI

       po4a(7), po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1),
       po4a-normalize(1), po4a-build(1), po4a-build.conf(5).

AUTEURS

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

COPYRIGHT ET LICENCE

       Copyright 2002-2010 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).