]> Savannah Git Hosting - gnulib.git/commitdiff
Document the new approach for gnulib localization.
authorBruno Haible <bruno@clisp.org>
Sun, 8 Dec 2024 17:15:49 +0000 (18:15 +0100)
committerBruno Haible <bruno@clisp.org>
Sun, 8 Dec 2024 17:15:49 +0000 (18:15 +0100)
* 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.

ChangeLog
doc/gnulib-tool.texi
gnulib-tool.sh
pygnulib/GLInfo.py

index cf714e6135f1cd0d743baa031f5f29de788e7dd4..ebe7fbee282db44cacbba9d889fd4bd6a01c3158 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
 2024-12-08  Bruno Haible  <bruno@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.
+
        Use the translation domain "gnulib".
        * lib/argmatch.c (_): Use translation domain "gnulib".
        * lib/bitset/stats.c (_): Likewise.
index 61cf643ccfdc41aed29dac480d13b84373ab4c04..87134315c3eca7ce228edcb3be7197c6aeacf36d 100644 (file)
@@ -1047,7 +1047,47 @@ Gnulib provides some functions that emit translatable messages using GNU
 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 @@ 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
+@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 @@ 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 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
index 2a5949f5844b140a0c221e241cdd8e251a2de0ea..dccea21ce85fc7ab8cd051ce3d154835f9dcd48f 100755 (executable)
@@ -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.
index 1ade11a3e1e4b8d1729ccca6ecb553797d20e172..5eaf4bd13c03a3da931eeda3ccce94f121f8dcb6 100644 (file)
@@ -262,7 +262,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
@@ -293,6 +293,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.