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.
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
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.
document maître --> 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).
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 ;)
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.
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 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
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/
[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
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>)* \
(add_<lang>:<modificateur>*<addendum>)*
En absence de modificateurs, addendum est le chemin vers un addendum. Les modificateurs sont :
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
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] 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:``...''
[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
Remarquez que vous pouvez encore ajouter des options fichier par fichier.
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
Le comportement par défaut (quand l'option --force n'est pas utilisée) est le suivant :
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.
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.
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.
Note : $lang sera remplacé par la langue en cours.
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
Toute rustine est la bienvenue ;)
Denis Barbier <barbier@linuxfr.org> Nicolas François <nicolas.francois@centraliens.net> Martin Quinson (mquinson#debian.org)
Martin Quinson (mquinson#debian.org)
Ce programme est un logiciel libre ; vous pouvez le copier et / ou le modifier sous les termes de la GPL (voir le fichier COPYING).