Loading

NOM

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

SYNOPSIS

       po4a [options] <fichier_de_configuration>

       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(1) 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 suivants 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
   DEFAUTS
   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 de
       faire cela 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.

        document maitre --> fichiers PO --> 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 :

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

       Vous pouvez également utiliser $master pour faire référence au nom (sans
       le chemin) 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_cram.sgml
        [type: pod] script fr:doc/fr/script.1 de:doc/de/script.1 \
                    add_fr:doc/l10n/script.fr.add

       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_matre> (<lang>:<doc_traduit>)* \
                         (add_<lang>:<modificateurs>*<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 ê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 clé opt. Les
       paramètres du mot clé opt doivent être placés entre guillemets s'ils
       contiennent un espace (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
       clé 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 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] 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é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.

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 nom=valeur. 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éé (se référer à 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.

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

       --no-backups
           Ne génère pas les fichiers .po~ de sauvegarde.

       --rm-backups
           Supprime les fichiers .po~ de sauvegarde (implique --no-backups).

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

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

       --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(1). Elle
           permet de prendre en charge les versions de gettext(1) antérieures à
           0.16.

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

       --srcdir RP_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 RP_DEST
           Définit le répertoire de base pour tous les documents de sortie
           indiqués dans le fichier de configuration de po4a.

   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/

        [type: man] truc.1 $lang:man/truc.$lang.1 \
                   add_$lang:?man/$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/
       à l'intérieur du répertoire en cours. Ici ce répertoire contiendrait de.po,
       de.add, pt.po et sv.po.

       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 dans man/
       et la prochaine fois que le programme sera construit, la traduction
       française sera aussi automatiquement construite.

       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 dans le système de
       gestion de version, vous devriez aussi ajouter ces lignes à la cible
       clean :
               -rm -f man/truc.*.1
               -rm -f man/truc.pot

DEFAUTS

       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)

AUTEURS

       Denis Barbier <barbier@linuxfr.org>
       Nicolas François <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).