diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi index ce510cb..33353c6 100644 --- a/doc/gnulib-tool.texi +++ b/doc/gnulib-tool.texi @@ -32,6 +32,7 @@ a real run without changing anything. * Modified imports:: Changing the import specification. * Simple update:: Tracking Gnulib development. * Source changes:: Impact of Gnulib on your source files. +* Translations:: Handling Gnulib's own translations. * VCS Issues:: Integration with Version Control Systems. @end menu @@ -370,6 +371,73 @@ used to set system dependent flags (such as @code{_GNU_SOURCE} on GNU systems), and these flags have no effect after any system header file has been included. address@hidden Translations address@hidden Handling Gnulib's own translations + +Gnulib provides some functions that emit translatable messages using GNU +gettext. The @samp{gnulib} domain at the address@hidden://translationproject.org/, Translation Project} collects +translations of these messages, which you should incorporate into your +own programs. + +There are two basic ways to achieve this. The first, and older, method +is to list all the source files you use from Gnulib in your own address@hidden/POTFILES.in} file. This will cause all the relevant +translatable strings to be included in your POT file. When you send +this POT file to the Translation Project, translators will normally fill +in the translations of the Gnulib strings from their ``translation +memory``, and send you back updated PO files. + +However, this process is error-prone: you might forget to list some +source files, or the translator might not be using a translation memory +and might make a mistake copying the translation across, or the +translation might not be kept in sync between Gnulib and your package. +It is also slow and causes substantial extra work, because a human +translator must be in the loop for each language and you will need to +incorporate their work on request. + +For these reasons, a new method was designed and is now recommended. If +you pass the @code{--po-base=DIRECTORY} and @code{--po-domain=NAME} +options to @code{gnulib-tool}, then @code{gnulib-tool} will create a +separate directory with its own @file{POTFILES.in}, and fetch current +translations directly from the Translation Project using address@hidden The POT file in this directory will be called address@hidden, depending on the @samp{NAME} you gave to the address@hidden option (typically the same as the package name). +This causes these translations to reside in a separate message domain, +so that they do not clash either with the translations for the main part +of your package nor with those of other packages on the system that use +Gnulib. When you use these options, the functions in Gnulib are built +in such a way that they will always use this domain regardless of the +default set by @code{textdomain}. + +In order to use this method, you must add an extra line to the part of +your program that initializes locale data in each program that might use +Gnulib code. Where you would normally write something like: + address@hidden address@hidden + setlocale (LC_ALL, ""); + bindtextdomain (PACKAGE, LOCALEDIR); + textdomain (PACKAGE); address@hidden group address@hidden example + address@hidden +you should add an additional @code{bindtextdomain} call to inform +gettext of where the MO files for the extra message domain may be found: + address@hidden address@hidden + bindtextdomain (PACKAGE "-gnulib", LOCALEDIR); address@hidden group address@hidden example + +Since you do not change the @code{textdomain} call, the default message +domain for your program remains the same and your own use of gettext +functions will not be affected. + + @node VCS Issues @section Issues with Version Control Systems