Quick start tutorial

Let's assume you maintain a program named foo which has a man page man/foo.1 written in English (the bridge language in most open-source projects, but po4a can be used from or to any language). Some times ago, someone provided a German translation named man/foo.de.1 and disappeared. This is a problem because you just got a bug report saying that your documentation contains a gravely misleading information that must be fixed in all languages, but you don't speak German so you can only modify the original, not the translation. Now, another contributor wants to contribute a translation to Japanese, a language that you don't master either.

It is time to convert your documentation to po4a to solve your documentation maintenance nightmares. You want to update the doc when needed, you want to ease the work of your fellow translators, and you want to ensure that your users never see any outdated and thus misleading documentation.

The conversion includes two steps: setup the po4a infrastructure, and convert the previous German translation to salvage the previous work. This latter part is done using po4a-gettextize, as follows. As detailed in the documentation of po4a-gettextize(1), this process rarely fully automatic, but once it's done, the de.po file containing the German translation can be integrated in your po4a workflow.

  po4a-gettextize --format man --master foo.1 --localized foo.de.1 --po de.po

Let's now configure po4a. With the appropriate file layout, your configuration file could be as simple as this:

 [po_directory] man/po4a/
 [type: man] man/foo.1 $lang:man/translated/foo.$lang.1

It specifies that all PO files (containing the work of the translators) are the man/po4a/ directory, and that you have only one master file, man/foo.1. If you had several master files, you would have several lines similar to the second one. Each such line also specify where to write the corresponding translation files. Here, the German translation of man/foo.1 is in man/translated/foo.de.1.

The last thing we need to complete the configuration of po4a is a POT file containing the template material that should be used to start a new translation. Simply create an empty file with the .pot extension in the specified po_directory (e.g. man/po4a/foo.pot), and po4a will fill it with the expected content.

Here is a recap of the files in this setup:

  ├── man/
  │   ├── foo.1        <- The original man page, in English.
  │   ├── po4a/
  │   │   ├── de.po    <- The German PO translation, from gettextization.
  │   │   └── foo.pot  <- The POT template of future translations (empty at first)
  │   └── translated/  <- Directory where the translations will be created
  └── po4a.cfg         <- The configuration file.

Once setup, executing po4a will parse your documentation, update the POT template file, use it to update the PO translation files, and use them to update the documentation translation files. All in one command:

        po4a --verbose po4a.cfg

This it. po4a is now fully configured. Once you've fixed your error in man/foo.1, the offending paragraph in the German translation will be replaced by the fixed text in English. Mixing languages is not optimal, but it's the only way to remove errors in translations that you don't even understand, and ensure that the content presented to the users is never misleading. Updating the German translation is also much easier in the corresponding PO file, so the language mix-up may not last long. Finally, when the Japanese translator gives you a jp.po translated file, just drop it in man/po4a/po/. A translated page will appear as man/translated/foo.jp.1 (provided that enough content is translated) when you run po4a again.

Options modifiant l’en-tête du POT

--porefs type

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

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

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 à newlines, po4a ne séparera les msgit et msgstr qu’après les nouvelles lignes dans le contenu. Si défini à no, 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.

Veuillez noter que cette option n’a pas d’impact sur la façon dont les msgid et msgstr sont renvoyées, c'est-à-dire sur la façon dont les nouvelles lignes sont ajoutées au contenu de ces chaînes.

--master-language

Langue des fichiers source contenant les documents à traduire. Notez que tous les fichiers maîtres doivent partager la même langue.

--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 de modification des 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 est nécessaire pour la prise en charge des 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.

Trouver les fichiers PO et POT

La solution la plus simple est de donner explicitement le chemin des fichiers POT et PO, comme ceci :

 [po4a_paths] man/po/project.pot de:man/po/de.po fr:man/po/fr.po

Cela spécifie d'abord le chemin d'accès au fichier POT, puis les chemins d'accès aux fichiers PO allemand et français.

La même information peut être écrite comme suit pour réduire le risque d'erreurs de copier/coller :

 [po4a_langs] fr de
 [po4a_paths] man/po/project.pot $lang:man/po/$lang.po

L'élément $lang est automatiquement développé à l'aide de la liste de langues fournie, ce qui réduit le risque d'erreur de copier/coller lorsqu'une nouvelle langue est ajoutée.

Vous pouvez en outre compacter les mêmes informations en fournissant uniquement le chemin d'accès au répertoire contenant votre projet de traduction, comme suit.

 [po_directory] man/po/

Le répertoire fourni doit contenir un ensemble de fichiers PO, nommés XX.po, "XX" étant le code ISO 639-1 de la langue utilisée dans ce fichier. Le répertoire doit également contenir un seul fichier POT, avec l'extension de fichier ".pot". Pour la première exécution, ce fichier peut être vide mais il doit exister (po4a ne peut pas deviner le nom à utiliser avant l'extension).

Notez bien que vous devez choisir entre "po_directory" et "po4a_paths". Le premier ("po_directory") est plus compact, réduit le risque d'erreur de copier/coller, mais vous oblige à utiliser la structure de projet et les noms de fichiers attendus. Le second ("po4a_paths"), est plus explicite, probablement plus lisible, et conseillé lorsque vous configurez votre premier projet avec po4a.

Fichier PO unique ou fractionné ?

Par défaut, po4a produit un seul fichier PO par langue cible, contenant tout le contenu de votre projet de traduction. À mesure que votre projet se développe, la taille de ces fichiers peut devenir problématique. Lors de l'utilisation de weblate, il est possible de spécifier des priorités pour chaque segment de traduction (c'est-à-dire, msgid) afin que les plus importants soient traduits en premier. Toutefois, certaines équipes de traduction préfèrent diviser le contenu en plusieurs fichiers.

Pour avoir un fichier PO par fichier maître, il vous suffit d'utiliser la chaîne $master dans le nom de vos fichiers PO sur la ligne "[po4a_paths]", comme suit.

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

With this line, po4a will produce separate POT and PO files for each document to translate. For example, if you have 3 documents and 5 languages, this will result in 3 POT files and 15 PO files. These files are named as specified on the "po4a_paths" template, with $master substituted to the basename of each document to translate. In case of name conflict, you can specify the POT file to use as follows, with the "pot=" parameter.

This feature can also be used to group several translated files into the same POT file. The following example only produces 2 POT files: l10n/po/foo.pot (containing the material from foo/gui.xml) and l10n/po/bar.pot (containing the material from both bar/gui.xml and bar/cli.xml).

 [po4a_langs] de fr ja
 [po4a_paths] l10n/po/$master.pot $lang:l10n/po/$master.$lang.po
 [type: xml] foo/gui.xml $lang:foo/gui.$lang.xml pot=foo
 [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml pot=bar
 [type: xml] bar/cli.xml $lang:bar/cli.$lang.xml pot=bar

En mode réparti, po4a construit un compendium temporaire pendant la mise à jour des PO afin de partager les traductions entre l’ensemble des fichiers PO. Si deux fichiers PO ont des traductions différentes pour la même chaîne, po4a marquera ces deux chaînes comme étant approximatives (fuzzy) et ajoutera les deux traductions dans tous les fichiers PO contenant cette chaîne. Une fois corrigée par le traducteur, la traduction sera automatiquement utilisée dans tous les fichiers PO.

Spécification des documents à traduire

Vous devez également lister les documents à traduire. Pour chaque fichier maître, vous devez spécifier l'analyseur de format à utiliser, l'emplacement du document traduit et éventuellement une configuration. Voici un exemple :

 [type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
              de:doc/de/mein_kram.sgml
 [type: man] script fr:doc/fr/script.1 de:doc/de/script.1
 [type: docbook] doc/script.xml fr:doc/fr/script.xml \
             de:doc/de/script.xml

Mais là aussi, ces lignes complexes sont difficiles à lire et à modifier, par ex. lors de l'ajout d'une nouvelle langue. Il est beaucoup plus simple de réorganiser les choses en utilisant le modèle $lang comme ceci :

 [type: sgml]    doc/mon_truc.sgml $lang:doc/$lang/mon_truc.sgml
 [type: man]     script.1          $lang:po/$lang/script.1
 [type: docbook] doc/script.xml    $lang:doc/$lang/script.xml

Renseigner les options

Il y a deux types d'options : les options po4a sont les valeurs par défaut des options de ligne de commande po4a tandis que les options de format sont utilisées pour changer le comportement des analyseurs de format. En tant qu' options po4a, vous pouvez par exemple spécifier dans votre fichier de configuration que la valeur par défaut du paramètre de ligne de commande --keep est 50% au lieu de 80%. Les <Options de format> sont documentées sur la page spécifique de chaque module d'analyse, par ex. Locale::Po4a::Xml(3pm). Vous pouvez par exemple passer nostrip à l'analyseur XML pour ne pas supprimer les espaces autour des chaînes extraites.

Vous pouvez transmettre ces options pour un fichier maître spécifique, ou même pour une traduction spécifique de ce fichier, en utilisant "opt:" et "opt_XX:" pour la langue "XX". Dans l'exemple suivant, l'option nostrip est passée à l'analyseur XML (pour toutes les langues), tandis que le seuil sera réduit à 0% pour la traduction française (qui est donc toujours conservée).

 [type:xml] toto.xml $lang:toto.$lang.xml opt:"-o nostrip" opt_fr:"--keep 0"

Dans tous les cas, ces blocs de configuration doivent être situés à la fin de la ligne. La déclaration des fichiers doit venir en premier, puis l'addendum le cas échéant (voir plus loin), et ensuite seulement les options. Le regroupement des blocs de configuration n'est pas très important, car les éléments sont concaténés en interne sous forme de chaînes. Les exemples suivants sont tous équivalents :

  [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20" opt:"-o nostrip" opt_fr:"--keep 0"
  [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20 -o nostrip" opt_fr:"--keep 0"
  [type:xml] toto.xml $lang:toto.$lang.xml opt:--keep opt:20 opt:-o opt:nostrip opt_fr:--keep opt_fr:0

Notez que les options spécifiques à la langue ne sont pas utilisées lors de la création du fichier POT. Il est par exemple impossible de passer nostrip à l'analyseur uniquement lors de la construction de la traduction française, car le même fichier POT est utilisé pour mettre à jour toutes les langues. Ainsi, les seules options qui peuvent être spécifiques à la langue sont celles qui sont utilisées lors de la production de la traduction, comme l'option "--keep".

Configuration des alias

Pour transmettre les mêmes options à plusieurs fichiers, le mieux est de définir un alias de type comme suit. Dans l'exemple suivant, "--keep 0" est passé à chaque traduction italienne en utilisant ce type "test", qui est une extension du type "man".

  [po4a_alias:test] man opt_it:"--keep 0"
  [type: test] man/page.1 $lang:man/$lang/page.1

Vous pouvez également étendre un type existant en réutilisant le même nom pour l'alias comme suit. Cela n’est pas interprété en tant que définition récursive erronée.

  [po4a_alias:man] man opt_it:"--keep 0"
  [type: man] man/page.1 $lang:man/$lang/page.1

Options globales par défaut

Vous pouvez également utiliser les lignes d’"[options]" pour définir des options devant être utilisées pour tous les fichiers, indépendamment de leur type.

  [options] --keep 20 --option nostrip

Comme pour les options en ligne de commande, vous pouvez abbréger les paramètres passés dans le fichier de configuration :

  [options] -k 20 -o nostrip

Priorités des options

Les options de toutes les sources sont concaténées, assurant que les valeurs par défaut puissent facilement être remplacées par des options plus spécifiques. L’ordre est le suivant :

• Les lignes "[options]" fournissent les valeurs par défaut pouvant être remplacées par n’importe quel autre source.
• Puis les alias de types sont utilisés. Les paramètres spécifiques de langue remplacent ceux applicables à toutes les langues.
• Les paramètres étant spécifiques à un fichier master remplacement celles par défaut et celles venant du type alias. Dans ce cas également, les paramètres spécifiques de langue remplacent les globaux.
• Enfin, les paramètres fournis via la ligne de commande po4a remplacement tout paramètre du fichier de configuration.

Exemple

Voici un exemple montrant comment renseigner les espaces et apostrophes :

 [po_directory] man/po/
 
 [options] --master-charset UTF-8
 
 [po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\""
 [type:man] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
            opt:"-k 75" opt_it:"-L UTF-8" opt_fr:--verbose

Addendum : Ajouter des contenus dans la traduction

Si vous souhaitez ajouter une section supplémentaire à la traduction, par exemple pour donner du crédit au traducteur, vous devez définir un addendum à la ligne définissant votre fichier maître. Veuillez vous référer à la page po4a(7) pour plus de détails sur la syntaxe des fichiers addendum.

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

Vous pouvez également utiliser des modèles de langue comme suit :

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

Si l'application d'un addendum échoue, la traduction est rejetée.

Modificateurs pour la déclaration d'un addendum

Les modificateurs d'addendum peuvent simplifier le fichier de configuration dans le cas où toutes les langues ne fournissent pas d'addendum, ou lorsque la liste des addenda change d'une langue à l'autre. Le modificateur est un seul caractère situé avant le nom du fichier.

?

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.

Ce qui suit inclut un addendum dans n'importe quelle langue, mais seulement s'il existe. Aucune erreur n'est signalée si l'addendum n'existe pas.

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

Ce qui suit inclut un addendum pour chaque langue :

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

Filtrer les chaînes traduites

Parfois, vous souhaitez masquer certaines chaînes au processus de traduction. Pour cela, vous pouvez donner un paramètre "pot_in" à votre fichier maître pour spécifier le nom du fichier à utiliser à la place du vrai maître lors de la construction du fichier POT. Voici un exemple :

  [type:docbook] book.xml          \
          pot_in:book-filtered.xml \
          $lang:book.$lang.xml

Avec ce paramètre, les chaînes à traduire seront extraites du book-filtered.xml (qui doit être créé avant d'appeler po4a) tandis que les fichiers traduits seront construits à partir de book.xml. Par conséquent, toute chaîne qui fait partie de book.xml mais pas de book-filtered.xml ne sera pas incluse dans les fichiers PO, empêchant les traducteurs de fournir une traduction pour eux. Ainsi, ces chaînes ne seront pas modifiées lors de la production des documents traduits. Cela diminue naturellement le niveau de traduction, vous pouvez donc avoir besoin de l'option "--keep" pour vous assurer que le document est produit dans tous les cas.