And this patch finally documents approach (a) from
<https://lists.gnu.org/archive/html/bug-gnulib/2024-12/msg00034.html>.
2024-12-08 Bruno Haible <br...@clisp.org>
Document the new approach for gnulib localization.
* doc/gnulib-tool.texi (Localization): Recommend to use the gnulib-l10n
package. Deprecate the two previous approaches.
* gnulib-tool.sh (func_usage): Deprecate the --po-base and --po-domain
options.
* pygnulib/GLInfo.py (GLInfo.usage): Likewise.
diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi
index 61cf643ccf..87134315c3 100644
--- a/doc/gnulib-tool.texi
+++ b/doc/gnulib-tool.texi
@@ -1047,7 +1047,47 @@
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
+The recommended way to achieve this is that
+your package depends on the package @samp{gnulib-l10n}.
+This package contains the Gnulib localizations as @code{.mo} files.
+
+In order to use this method, you must
+-- in each program that might use Gnulib code --
+add an extra line to the part of the program
+that initializes locale-dependent behavior.
+Where you would normally write something like:
+
+@example
+@group
+ setlocale (LC_ALL, "");
+ bindtextdomain (PACKAGE, LOCALEDIR);
+ textdomain (PACKAGE);
+@end group
+@end example
+
+@noindent
+you should add an additional @code{bindtextdomain} call to inform gettext of
+where the MO files for the extra message domain may be found:
+
+@example
+@group
+ bindtextdomain ("gnulib", GNULIB_LOCALEDIR);
+@end group
+@end 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 @code{gettext} functions will not be affected.
+
+If your package has a @code{DEPENDENCIES} file,
+for the ease of installers and distributors,
+you should add the @samp{gnulib-l10n} dependency in this file.
+
+Two older methods to use Gnulib localizations are deprecated:
+
+@itemize
+@item
+The first, and older, method
is to list all the source files you use from Gnulib in your own
@file{po/POTFILES.in} file. This will cause all the relevant
translatable strings to be included in your POT file. When you send
@@ -1063,12 +1103,12 @@
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
+@item
+The second method is that
you pass the @code{--po-base=@var{directory}} and
@code{--po-domain=@var{domain}}
-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
-@command{rsync} or @command{wget}, whichever is available).
+options to @code{gnulib-tool}, then @code{gnulib-tool} creates a
+separate directory with its own @file{POTFILES.in}, and fetches current
+translations directly from the Translation Project (using @command{wget}).
The POT file in this directory will be called
@file{@var{domain}-gnulib.pot}, depending on the @var{domain} you gave to the
@code{--po-domain} option (typically the same as the package name).
@@ -1080,37 +1120,10 @@
in such a way that they will always use this domain regardless of the
default domain set by @code{textdomain}.
-In order to use this method, you must---in each program that might use
-Gnulib code---add an extra line to the part of the program that
-initializes locale-dependent behavior. Where you would normally write
-something like:
-
-@example
-@group
- setlocale (LC_ALL, "");
- bindtextdomain (PACKAGE, LOCALEDIR);
- textdomain (PACKAGE);
-@end group
-@end example
-
-@noindent
-you should add an additional @code{bindtextdomain} call to inform
-gettext of where the MO files for the extra message domain may be found:
-
-@example
-@group
- bindtextdomain (PACKAGE "-gnulib", LOCALEDIR);
-@end group
-@end example
-
-(This example assumes that the @var{domain} that you specified
-to @code{gnulib-tool} is the same as the value of the @code{PACKAGE}
-preprocessor macro.)
-
-Since you do not change the @code{textdomain} call, the default message
-domain for your program remains the same and your own use of @code{gettext}
-functions will not be affected.
-
+This method is deprecated because it adds complexity to your package
+and, additionally, mixes the ``autopull'' and ``autogen'' phases of
+package source preparation.
+@end itemize
@node VCS Issues
@section Integration with Version Control Systems
diff --git a/gnulib-tool.sh b/gnulib-tool.sh
index 2a5949f584..dccea21ce8 100755
--- a/gnulib-tool.sh
+++ b/gnulib-tool.sh
@@ -285,7 +285,7 @@ Options for --import, --add/remove-import:
--m4-base=DIRECTORY Directory relative to --dir where *.m4 macros are
placed (default \"m4\").
--po-base=DIRECTORY Directory relative to --dir where *.po files are
- placed (default \"po\").
+ placed (default \"po\"). Deprecated.
--doc-base=DIRECTORY Directory relative to --dir where doc files are
placed (default \"doc\").
--tests-base=DIRECTORY
@@ -314,6 +314,7 @@ Options for --import, --add/remove-import:
'gl_INIT'. Default is 'gl'.
--po-domain=NAME Specify the prefix of the i18n domain. Usually use
the package name. A suffix '-gnulib' is appended.
+ Deprecated.
--witness-c-macro=NAME Specify the C macro that is defined when the
sources in this directory are compiled or used.
--vc-files Update version control related files.
diff --git a/pygnulib/GLInfo.py b/pygnulib/GLInfo.py
index 1ade11a3e1..5eaf4bd13c 100644
--- a/pygnulib/GLInfo.py
+++ b/pygnulib/GLInfo.py
@@ -262,7 +262,7 @@ def usage(self) -> str:
--m4-base=DIRECTORY Directory relative to --dir where *.m4 macros are
placed (default \"m4\").
--po-base=DIRECTORY Directory relative to --dir where *.po files are
- placed (default \"po\").
+ placed (default \"po\"). Deprecated.
--doc-base=DIRECTORY Directory relative to --dir where doc files are
placed (default \"doc\").
--tests-base=DIRECTORY
@@ -293,6 +293,7 @@ def usage(self) -> str:
'gl_INIT'. Default is 'gl'.
--po-domain=NAME Specify the prefix of the i18n domain. Usually use
the package name. A suffix '-gnulib' is appended.
+ Deprecated.
--witness-c-macro=NAME Specify the C macro that is defined when the
sources in this directory are compiled or used.
--vc-files Update version control related files.
