.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "PO4A 1p" .TH PO4A 1p "2018-12-09" "Po4a Tools" "Po4a Tools" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" po4a \- update both the PO files and translated documents in one shot .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBpo4a\fR [\fIoptions\fR] \fIconfig_file\fR .SH "DESCRIPTION" .IX Header "DESCRIPTION" The po4a (\s-1PO\s0 for anything) project goal is to ease translations (and more interestingly, the maintenance of translations) using gettext tools on areas where they were not expected like documentation. .PP The \fBpo4a\fR program is useful if you want to avoid calling \&\fBpo4a\-gettextize\fR\|(1), \fBpo4a\-updatepo\fR\|(1), and \fBpo4a\-translate\fR\|(1) in complex Makefiles when you have multiple files to translate, different format, or need to specify different options for different documents. .SH "Table of content" .IX Header "Table of content" This document is organized as follow: .SS "\s-1DESCRIPTION\s0" .IX Subsection "DESCRIPTION" .SS "\s-1INTRODUCTION\s0" .IX Subsection "INTRODUCTION" .SS "\s-1CONFIGURATION FILE SYNTAX\s0" .IX Subsection "CONFIGURATION FILE SYNTAX" \fISpecifying the template languages\fR .IX Subsection "Specifying the template languages" .PP \fISpecifying the paths to translator inputs\fR .IX Subsection "Specifying the paths to translator inputs" .PP \fIAutodetection of the paths and languages\fR .IX Subsection "Autodetection of the paths and languages" .PP \fISpecifying the documents to translate\fR .IX Subsection "Specifying the documents to translate" .PP \fISpecifying options for the modules\fR .IX Subsection "Specifying options for the modules" .PP \fISpecifying aliases\fR .IX Subsection "Specifying aliases" .PP \fISplit mode\fR .IX Subsection "Split mode" .SS "\s-1OPTIONS\s0" .IX Subsection "OPTIONS" .SS "\s-1EXAMPLE\s0" .IX Subsection "EXAMPLE" .SS "\s-1SHORTCOMINGS\s0" .IX Subsection "SHORTCOMINGS" .SS "\s-1SEE ALSO\s0" .IX Subsection "SEE ALSO" .SS "\s-1AUTHORS\s0" .IX Subsection "AUTHORS" .SS "\s-1COPYRIGHT AND LICENSE\s0" .IX Subsection "COPYRIGHT AND LICENSE" \fI\fR .IX Subsection "" .SH "INTRODUCTION" .IX Header "INTRODUCTION" The \fBpo4a\fR program is in charge of updating both the \s-1PO\s0 files (to sync them to the original documents) and the translated documents (to sync them to the \s-1PO\s0 files). The main point is to make the use of po4a easier without having to remember of the command line options. .PP It also allows you to mix documents having different formats into the same \&\s-1POT\s0 file so that you can have only one such file per project. .PP This behaviour can be mimicked by the other tools of the po4a suite (for example with Makefiles), but it is rather difficult to do, and exhausting to redo the same complicated Makefiles for each project using po4a. .PP The dataflow can be summarized as follow. Any changes to the master document will be reflected in the \s-1PO\s0 files, and all changes to the \s-1PO\s0 files (either manual or caused by previous step) will be reflected in translation documents. .PP Normal case without specifying \fBpot_in\fR: .PP .Vb 1 \& <\- source files \->|<\-\-\-\-\-\-\-\-\- build results \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-> \& \& addendum \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | \& master document \-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | \& V +\-\-+\-\-> translations \& old PO files \-\-\-\-\-+\-\-> updated PO files + \& ^ | \& | V \& +<.....................+ \& (the updated PO files are manually \& copied to the source of the next \& release while manually updating \& the translation contents) .Ve .PP Special case with specifying \fBpot_in\fR: .PP .Vb 1 \& <\- source files \->|<\-\-\-\-\-\-\-\-\- build results \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-> \& \& master document \-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& : | \& external : filtered | \& filtering ========X..> master | \& program document | \& | | \& V +\-\-> translations \& old PO files \-\-\-\-\-\-\-\-\-\-+\-\-> updated PO files + \& ^ | \& | V \& +<..........................+ \& (the updated PO files are manually \& copied to the source of the next \& release while manually updating \& the translation contents) .Ve .PP The dataflow cannot be reversed in this tool, and changes in translations are overwritten by the content of the \s-1PO\s0 files. As a matter of fact, this tool cannot be used to convert existing translations to the po4a system. For that task, please refer to \fBpo4a\-gettextize\fR\|(1). .SH "CONFIGURATION FILE SYNTAX" .IX Header "CONFIGURATION FILE SYNTAX" The (mandatory) argument is the path to the configuration file to use. Its syntax aims at being simple and close to the configuration files used by the intl-tools projects. .PP Comments in these files are noted by the char '#'. It comments everything until the end of the line. Lines can be continued by escaping the end of line. All non blank lines must begin with a [] command, followed by its arguments. (sound difficult said that way, but it is rather easy, I hope ;) .SS "Specifying the template languages" .IX Subsection "Specifying the template languages" \&\fBNote:\fR It is recommended to use \fB[po_directory]\fR rather than \fB[po4a_langs]\fR and \fB[po4a_paths]\fR. See section \fBAutodetection of the paths and languages\fR below. .PP This is an optional command that can simplify the whole config file, and will make it more scalable. You have to specify a list of the languages in which you want to translate the documents. This is as simple as: .PP .Vb 1 \& [po4a_langs] fr de .Ve .PP This will enable you to expand \fB\f(CB$lang\fB\fR to all the specified languages in the rest of the config file. .SS "Specifying the paths to translator inputs" .IX Subsection "Specifying the paths to translator inputs" \&\fBNote:\fR It is recommended to use \fB[po_directory]\fR rather than \fB[po4a_langs]\fR and \fB[po4a_paths]\fR. See section \fBAutodetection of the paths and languages\fR below. .PP First, you have to specify where the translator input files (I.E. the files used by translators to do their job) are located. It can be done by such a line: .PP .Vb 2 \& [po4a_paths] doc/l10n/project.doc.pot \e \& fr:doc/l10n/fr.po de:doc/l10n/de.po .Ve .PP The command is thus \fB[po4a_paths]\fR. The first argument is the path to the \s-1POT\s0 file to use. All subsequent arguments are of the self-explanatory form: .PP .Vb 1 \& : .Ve .PP If you've defined the template languages, you can rewrite the line above this way: .PP .Vb 1 \& [po4a_paths] doc/l10n/project.doc.pot $lang:doc/l10n/$lang.po .Ve .PP You can also use \fB\f(CB$master\fB\fR to refer to the document filename. In this case, \&\fBpo4a\fR will use a split mode: one \s-1POT\s0 and one \s-1PO\s0 (for each language) will be created for each document specified in the \fBpo4a\fR configuration file. See the \fBSplit mode\fR section. .PP .Vb 1 \& [po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po .Ve .SS "Autodetection of the paths and languages" .IX Subsection "Autodetection of the paths and languages" Another command can be used to specify the name of a directory where the \&\s-1PO\s0 and \s-1POT\s0 files are located. When it is used, \fBpo4a\fR will detect the \s-1POT\s0 file as the only \fI*.pot\fR file from the specified directory. \&\fBpo4a\fR will also use the list of \fI*.po\fR files to define the list of languages (by stripping out the extension). These languages will be used for the substitution of the \fB\f(CB$lang\fB\fR variable in the rest of the configuration file. .PP This command should not be used together with the \fB[po4a_langs]\fR or \fB[po4a_paths]\fR commands. .PP When using this command, you have to create an empty \s-1POT\s0 file on the first invocation of \fBpo4a\fR to let it know the name of the \s-1POT\s0 file. .PP .Vb 1 \& [po_directory] po4a/po/ .Ve .SS "Specifying the documents to translate" .IX Subsection "Specifying the documents to translate" You now naturally have to specify which documents are translated, their format, and where to put the translations. It can be made by such lines: .PP .Vb 7 \& [type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \e \& de:doc/de/mein_kram.sgml \& [type: pod] script fr:doc/fr/script.1 de:doc/de/script.1 \e \& add_fr:doc/l10n/script.fr.add \& [type: docbook] doc/script.xml fr:doc/fr/script.xml \e \& de:doc/de/script.xml \e \& pot_in:doc/script.filtered.xml .Ve .PP This should be rather self-explanatory also. Note that in the second case, \&\fIdoc/l10n/script.fr.add\fR is an addendum to add to the French version of this document. Please refer to \fBpo4a\fR\|(7) for more information about the addenda. .PP More formally, the format is: .PP .Vb 3 \& [type: ] (:)* \e \& (pot_in:)? \e \& (add_:*)* .Ve .PP If \fBpot_in\fR is specified, \fIfiltered_master_doc\fR is used to create \s-1POT\s0 file instead of \fImaster_doc\fR. This feature allows user to create flexible ways to avoid contents which shouldn't be included in the \s-1PO\s0 files. Tools such as C preprocessor (\fBcpp\fR) or \s-1XSL\s0 Transformation utility (e.g., \fBxsltproc\fR) can be used to create the external filtering program and call it before invoking \&\fBpo4a\fR. .PP If there is no modifier, \fIaddendum_path\fR is a path to an addendum. Modifiers are .IP "\fB?\fR" 2 .IX Item "?" Include \fIaddendum_path\fR if this file does exist, otherwise do nothing. .IP "\fB@\fR" 2 .IX Item "@" \&\fIaddendum_path\fR is not a regular addendum but a file containing a list of addenda, one by line. Each addendum may be preceded by modifiers. .IP "\fB!\fR" 2 .IX Item "!" \&\fIaddendum_path\fR is discarded, it is not loaded and will not be loaded by any further addendum specification. .PP If you've defined the template languages, you can rewrite the line above this way: .PP .Vb 2 \& [type: pod] script $lang:doc/$lang/script.1 \e \& add_fr:doc/l10n/script.fr.add .Ve .PP If all the languages had addenda with similar paths, you could also write something like: .PP .Vb 2 \& [type: pod] script $lang:doc/$lang/script.1 \e \& add_$lang:doc/l10n/script.$lang.add .Ve .SS "Specifying options for the modules" .IX Subsection "Specifying options for the modules" \&\fBpo4a\fR accepts options that will be passed to the module. These options are module specific and are specified with the \fB\-o\fR switch. .PP If you need a specific option for one of the documents you want to translate, you can also specify it in the configuration file. Options are introduced by the \fBopt\fR keyword. The argument of the \fBopt\fR keyword must be quoted with double quotes if it contains a space (e.g. if you specify multiple options, or an option with an argument). You can also specify options that will only apply to a specific language by using the \fBopt_\fR\fIlang\fR keyword. .PP Here is an example: [type:man] t\-05\-config/test02_man.1 \f(CW$lang:tmp\fR/test02_man.$lang.1 \e opt:\*(L"\-k 75\*(R" opt_it:\*(L"\-L \s-1UTF\-8\*(R"\s0 opt_fr:\-v .PP Arguments may contain spaces if you use single quotes or escaped double quotes: [po4a_alias:man] man opt:\*(L"\-o \e\*(R"mdoc=NAME,SEE ALSO\e\*(L" \-k 20\*(R" .PP If you want to specify the same options for many documents, you may want to use an alias (see the \fBSpecifying aliases\fR section below). .PP You can also set options for all the documents specified in the configuration file: [options] opt:\*(L"...\*(R" opt_fr:\*(L"...\*(R" .SS "Specifying aliases" .IX Subsection "Specifying aliases" If you must specify the same options for multiple files, you may be interested in defining a module alias. This can be done this way: .PP .Vb 1 \& [po4a_alias:test] man opt:"\-k 21" opt_es:"\-o debug=splitargs" .Ve .PP This defines a module alias named \fBtest\fR, based on the \fBman\fR module, with the \fB\-k 21\fR applied to all the languages and with \fB\-o debug=splitargs\fR applied to the Spanish translation. .PP This module alias can then be used like a regular module: .PP .Vb 2 \& [type:test] t\-05\-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \e \& opt_it:"\-L UTF\-8" opt_fr:\-v .Ve .PP Note that you can specify additional options on a per file basis. .SS "Split mode" .IX Subsection "Split mode" The split mode is used when \fB\f(CB$master\fB\fR is used in the \fB[po4a_paths]\fR line. .PP When the split mode is used, a temporary big \s-1POT\s0 and temporary big POs are used. This permits to share the translations between all the POs. .PP If two POs have different translations for the same string, \fBpo4a\fR will mark this string as fuzzy and will submit both translations in all the POs which contain this string. Then, when a translator updates the translation and removes the fuzzy tag in one \s-1PO,\s0 the translation of this string will be updated in every POs automatically. .PP If there are name conflicts because several files have the same filename, the name of the master file can be specified by adding a \f(CW\*(C`master:file=\*(C'\fR\fIname\fR option: .PP .Vb 4 \& [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 master:file=foo\-gui \& [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml master:file=bar\-gui .Ve .SH "OPTIONS" .IX Header "OPTIONS" .IP "\fB\-k\fR, \fB\-\-keep\fR" 4 .IX Item "-k, --keep" Minimal threshold for translation percentage to keep (i.e. write) the resulting file (default: 80). I.e. by default, files have to be translated at least at 80% to get written. .IP "\fB\-h\fR, \fB\-\-help\fR" 4 .IX Item "-h, --help" Show a short help message. .IP "\fB\-M\fR, \fB\-\-master\-charset\fR" 4 .IX Item "-M, --master-charset" Charset of the files containing the documents to translate. Note that all master documents must use the same charset for now. This is a known limitation, and we are working on solving this. .IP "\fB\-L\fR, \fB\-\-localized\-charset\fR" 4 .IX Item "-L, --localized-charset" Charset of the files containing the localized documents. Note that all translated documents will use the same charset for now. This is a known limitation, and we are working on solving this. .IP "\fB\-A\fR, \fB\-\-addendum\-charset\fR" 4 .IX Item "-A, --addendum-charset" Charset of the addenda. Note that all the addenda should be in the same charset. .IP "\fB\-V\fR, \fB\-\-version\fR" 4 .IX Item "-V, --version" Display the version of the script and exit. .IP "\fB\-v\fR, \fB\-\-verbose\fR" 4 .IX Item "-v, --verbose" Increase the verbosity of the program. .IP "\fB\-q\fR, \fB\-\-quiet\fR" 4 .IX Item "-q, --quiet" Decrease the verbosity of the program. .IP "\fB\-d\fR, \fB\-\-debug\fR" 4 .IX Item "-d, --debug" Output some debugging information. .IP "\fB\-o\fR, \fB\-\-option\fR" 4 .IX Item "-o, --option" Extra option(s) to pass to the format plugin. Specify each option in the \&'\fIname\fR\fB=\fR\fIvalue\fR' format. See the documentation of each plugin for more information about the valid options and their meanings. .IP "\fB\-f\fR, \fB\-\-force\fR" 4 .IX Item "-f, --force" Always generate the \s-1POT\s0 and \s-1PO\s0 files, even if \fBpo4a\fR considers it is not necessary. .Sp The default behavior (when \fB\-\-force\fR is not specified) is the following: .RS 4 .Sp .RS 4 If the \s-1POT\s0 file already exists, it is regenerated if a master document or the configuration file is more recent. The \s-1POT\s0 file is also written in a temporary document and \fBpo4a\fR verifies that the changes are really needed. .Sp Also, a translation is regenerated only if its master document, the \s-1PO\s0 file, one of its addenda or the configuration file is more recent. To avoid trying to regenerate translations which do not pass the threshold test (see \fB\-\-keep\fR), a file with the \fI.po4a\-stamp\fR extension can be created (see \fB\-\-stamp\fR). .RE .RE .RS 4 .Sp If a master document includes files, you should use the \fB\-\-force\fR flag because the modification time of these included files are not taken into account. .Sp The \s-1PO\s0 files are always re-generated based on the \s-1POT\s0 with \fBmsgmerge \-U\fR. .RE .IP "\fB\-\-stamp\fR" 4 .IX Item "--stamp" Tells \fBpo4a\fR to create stamp files when a translation is not generated because it does not reach the threshold. These stamp files are named according to the expected translated document, with the \fI.po4a\-stamp\fR extension. .Sp Note: This only activates the creation of the \fI.po4a\-stamp\fR files. The stamp files are always used if they exist, and they are removed with \&\fB\-\-rm\-translations\fR or when the file is finally translated. .IP "\fB\-\-no\-translations\fR" 4 .IX Item "--no-translations" Do not generate the translated documents, only update the \s-1POT\s0 and \s-1PO\s0 files. .IP "\fB\-\-no\-update\fR" 4 .IX Item "--no-update" Do not change the \s-1POT\s0 and \s-1PO\s0 files, only the translation may be updated. .IP "\fB\-\-keep\-translations\fR" 4 .IX Item "--keep-translations" Keeps the existing translation files even if the translation doesn't meet the threshold specified by \-\-keep. This option does not create new translation files with few content, but it will save existing translations which decay because of changes to the master files. .Sp \&\s-1WARNING:\s0 This flag changes the po4a behavior in a rather drastic way: your translated files will not get updated at all until the translation improves. Only use this flag if you prefer shipping an outdated translated documentation rather than only shipping an accurate untranslated documentation. .IP "\fB\-\-rm\-translations\fR" 4 .IX Item "--rm-translations" Remove the translated files (implies \fB\-\-no\-translations\fR). .IP "\fB\-\-no\-backups\fR" 4 .IX Item "--no-backups" This flag does nothing since 0.41, and may be removed in later releases. .IP "\fB\-\-rm\-backups\fR" 4 .IX Item "--rm-backups" This flag does nothing since 0.41, and may be removed in later releases. .IP "\fB\-\-translate\-only\fR \fItranslated-file\fR" 4 .IX Item "--translate-only translated-file" Translate only the specified file. It may be useful to speed up processing if a configuration file contains a lot of files. Note that this option does not update \s-1PO\s0 and \s-1POT\s0 files. This option can be used multiple times. .IP "\fB\-\-variable\fR \fIvar\fR\fB=\fR\fIvalue\fR" 4 .IX Item "--variable var=value" Define a variable that will be expanded in the \fBpo4a\fR configuration file. Every occurrence of \fI$(var)\fR will be replaced by \fIvalue\fR. This option can be used multiple times. .IP "\fB\-\-srcdir\fR \fI\s-1SRCDIR\s0\fR" 4 .IX Item "--srcdir SRCDIR" Set the base directory for all input documents specified in the \fBpo4a\fR configuration file. .IP "\fB\-\-destdir\fR \fI\s-1DESTDIR\s0\fR" 4 .IX Item "--destdir DESTDIR" Set the base directory for all the output documents specified in the \fBpo4a\fR configuration file. .SS "\s-1OPTIONS WHICH MODIFY POT HEADER\s0" .IX Subsection "OPTIONS WHICH MODIFY POT HEADER" .IP "\fB\-\-porefs\fR \fItype\fR[,\fBwrap\fR|\fBnowrap\fR]" 4 .IX Item "--porefs type[,wrap|nowrap]" Specify the reference format. Argument \fItype\fR can be one of \fBnever\fR to not produce any reference, \fBfile\fR to only specify the file without the line number, \fBcounter\fR to replace line number by an increasing counter, and \fBfull\fR to include complete references (default: full). .Sp Argument can be followed by a comma and either \fBwrap\fR or \fBnowrap\fR keyword. References are written by default on a single line. The \fBwrap\fR option wraps references on several lines, to mimic \fBgettext\fR tools (\fBxgettext\fR and \&\fBmsgmerge\fR). This option will become the default in a future release, because it is more sensible. The \fBnowrap\fR option is available so that users who want to keep the old behavior can do so. .IP "\fB\-\-msgid\-bugs\-address\fR \fIemail@address\fR" 4 .IX Item "--msgid-bugs-address email@address" Set the report address for msgid bugs. By default, the created \s-1POT\s0 files have no Report-Msgid-Bugs-To fields. .IP "\fB\-\-copyright\-holder\fR \fIstring\fR" 4 .IX Item "--copyright-holder string" Set the copyright holder in the \s-1POT\s0 header. The default value is \&\*(L"Free Software Foundation, Inc.\*(R" .IP "\fB\-\-package\-name\fR \fIstring\fR" 4 .IX Item "--package-name string" Set the package name for the \s-1POT\s0 header. The default is \*(L"\s-1PACKAGE\*(R".\s0 .IP "\fB\-\-package\-version\fR \fIstring\fR" 4 .IX Item "--package-version string" Set the package version for the \s-1POT\s0 header. The default is \*(L"\s-1VERSION\*(R".\s0 .SS "\s-1OPTIONS TO MODIFY PO FILES\s0" .IX Subsection "OPTIONS TO MODIFY PO FILES" .IP "\fB\-\-msgmerge\-opt\fR \fIoptions\fR" 4 .IX Item "--msgmerge-opt options" Extra options for \fBmsgmerge\fR(1). .Sp Note: \fB\f(CB$lang\fB\fR will be extended to the current language. .IP "\fB\-\-no\-previous\fR" 4 .IX Item "--no-previous" This option removes \fB\-\-previous\fR from the options passed to \fBmsgmerge\fR. This permits to support versions of \fBgettext\fR earlier than 0.16. .IP "\fB\-\-previous\fR" 4 .IX Item "--previous" This option adds \fB\-\-previous\fR to the options passed to \fBmsgmerge\fR. It requires \fBgettext\fR 0.16 or later, and is activated by default. .SS "\s-1EXAMPLE\s0" .IX Subsection "EXAMPLE" Let's assume you maintain a program named \fBfoo\fR which has a man page \fIman/foo.1\fR which naturally is maintained in English only. Now you as the upstream or downstream maintainer want to create and maintain the translation. First you need to create the \s-1POT\s0 file necessary to send to translators using \fBpo4a\-gettextize\fR\|(1). .PP So for our case we would call .PP .Vb 1 \& cd man && po4a\-gettextize \-f man \-m foo.1 \-p foo.pot .Ve .PP You would then send this file to the appropriate language lists or offer it for download somewhere on your website. .PP Now let's assume you received three translations before your next release: \&\fIde.po\fR (including an addendum \fIde.add\fR), \fIsv.po\fR and \fIpt.po\fR. Since you don't want to change your \fIMakefile\fR(s) whenever a new translation arrives you can use \fBpo4a\fR with an appropriate configuration file in your \fIMakefile\fR. Let's call it \fIpo4a.cfg\fR. In our example it would look like the following: .PP .Vb 1 \& [po_directory] man/po4a/po/ \& \& [type: man] man/foo.1 $lang:man/translated/$lang/foo.1 \e \& add_$lang:?man/po4a/add_$lang/$lang.add opt:"\-k 80" .Ve .PP In this example we assume that your generated man pages (and all \s-1PO\s0 and addenda files) should be stored in \fIman/translated/$lang/\fR (respectively in \fIman/po4a/po/\fR and \&\fIman/po4a/add_$lang/\fR) below the current directory. In our example the \fIman/po4a/po/\fR directory would include \fIde.po\fR, \fIpt.po\fR and \fIsv.po\fR, and the \fIman/po4a/add_de/\fR directory would include \fIde.add\fR. .PP Note the use of the modifier \fB?\fR as only the German translation (\fIde.po\fR) is accompanied by an addendum. .PP To actually build the translated man pages you would then (once!) add the following line in the \fBbuild\fR target of the appropriate \fIMakefile\fR: .PP .Vb 1 \& po4a po4a.cfg .Ve .PP Once this is set up you don't need to touch the \fIMakefile\fR when a new translation arrives, i.e. if the French team sends you \fIfr.po\fR and \fIfr.add\fR then you simply drop them respectively in \fIman/po4a/po/\fR and \&\fIman/po4a/add_fr/\fR and the next time the program is built the French translation is automatically build as well in \fIman/translated/fr/\fR. .PP Note that you still need an appropriate target to install localized manual pages with English ones. .PP Finally if you do not store generated files into your version control system, you will need a line in your \fBclean\fR target as well: \-rm \-rf man/translated .SH "SHORTCOMINGS" .IX Header "SHORTCOMINGS" .IP "\(bu" 4 Duplicates some code with the \fBpo4a\-\fR\fI*\fR programs. .PP Patch welcome ;) .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBpo4a\-gettextize\fR\|(1), \&\fBpo4a\-normalize\fR\|(1), \&\fBpo4a\-translate\fR\|(1), \&\fBpo4a\-updatepo\fR\|(1), \&\fBpo4a\fR\|(7) .SH "AUTHORS" .IX Header "AUTHORS" .Vb 3 \& Denis Barbier \& Nicolas François \& Martin Quinson (mquinson#debian.org) .Ve .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2002\-2012 by \s-1SPI,\s0 inc. .PP This program is free software; you may redistribute it and/or modify it under the terms of \s-1GPL\s0 (see the \s-1COPYING\s0 file).