On Thu, Jan 03, 2008 at 12:36:38AM +0100, Bruno Haible wrote:
> Hello Colin and Benno,
> > Bruno, is the scheme I outlined in the quoted text above a
> > reasonable way to handle translations of gnulib strings in a client
> > package?
>
> Yes, absolutely.
Excellent.
> > I'm trying to avoid having to import the strings by hand or come up
> > with complicated merging schemes.
>
> The scheme was designed not only to save the maintainers from merging
> PO files, but particularly to save translation teams from translating
> the same strings multiple times (if they don't use translation
> memory).
Right, though I didn't mention that, I was certainly conscious of it. I
don't know to what extent the use of translation memory is common, and
even then I'm not certain that corrections to translations in the gnulib
domain would reliably propagate elsewhere.
> > > > When the --po-base and --po-domain options are passed to gnulib-tool
> > > > (as I do), gettext is redefined within gnulib to call dgettext with
> > > > DEFAULT_TEXT_DOMAIN as the first argument; in this case
> > > > DEFAULT_TEXT_DOMAIN is "man-db-gnulib". The one thing that remained
> > > > in order for this to work perfectly was to add a single line to all
> > > > my main functions:
> > > >
> > > > bindtextdomain (PACKAGE "-gnulib", LOCALEDIR);
>
> Thanks for reminding me that this should be documented like this.
>
> > the maintainer of gettext also appears to be
> > the one who implemented --po-base and --po-domain in gnulib-tool, and I
> > can conceive of no other use for them, particularly not the very
> > specific way in which it was done with dgettext.
>
> The reason for the confusion is that the --po-base and --po-domain is a rather
> recent addition to gnulib-tool. It's not even fully documented yet, and
> gettext
> itself is not yet using this option in its gnulib-tool invocations.
I decided to write some documentation for this (diff attached), which I
hope you can review and add to Gnulib. What do you think? If you require
a copyright assignment for this, I can certainly do that, though there
may be a short delay in getting a signature from my employer (I work
from home so it would have to wait until I'm in the office later this
month).
Thanks,
--
Colin Watson [EMAIL PROTECTED]
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.
[EMAIL PROTECTED] Translations
[EMAIL PROTECTED] Handling Gnulib's own translations
+
+Gnulib provides some functions that emit translatable messages using GNU
+gettext. The @samp{gnulib} domain at the
[EMAIL PROTECTED]://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
[EMAIL PROTECTED]/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
[EMAIL PROTECTED] The POT file in this directory will be called
[EMAIL PROTECTED], depending on the @samp{NAME} you gave to the
[EMAIL PROTECTED] 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:
+
[EMAIL PROTECTED]
[EMAIL PROTECTED]
+ setlocale (LC_ALL, "");
+ bindtextdomain (PACKAGE, LOCALEDIR);
+ textdomain (PACKAGE);
[EMAIL PROTECTED] group
[EMAIL PROTECTED] example
+
[EMAIL PROTECTED]
+you should add an additional @code{bindtextdomain} call to inform
+gettext of where the MO files for the extra message domain may be found:
+
[EMAIL PROTECTED]
[EMAIL PROTECTED]
+ bindtextdomain (PACKAGE "-gnulib", LOCALEDIR);
[EMAIL PROTECTED] group
[EMAIL PROTECTED] 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
