[gtk/docs-gtk-org] glib: Add the Internationalization section

[Emmanuele Bassi <ebassi src gnome org>]

commit 22b94467238c9204937bfd4aa544d33c643f7ffe
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Tue Aug 10 23:47:07 2021 +0100

    glib: Add the Internationalization section

 glib/glib/compiling.md |  6 ++++--
 glib/glib/glib.toml.in |  1 +
 glib/glib/i18n.md      | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 glib/glib/meson.build  |  1 +
 4 files changed, 55 insertions(+), 2 deletions(-)
---
diff --git a/glib/glib/compiling.md b/glib/glib/compiling.md
index cfb4ec5260..38f151787d 100644
--- a/glib/glib/compiling.md
+++ b/glib/glib/compiling.md
@@ -65,5 +65,7 @@ separately:
 
 - `gmodule.h`
 - `glib-unix.h`
-- `glib/gi18n-lib.h` or `glib/gi18n.h` (see the section on Internationalization)
-- `glib/gprintf.h` and `glib/gstdio.h` (we don't want to pull in all of stdio)
+- `glib/gi18n-lib.h` or `glib/gi18n.h` (see the section on
+  [Internationalization](i18n.html))
+- `glib/gprintf.h` and `glib/gstdio.h` (we don't want to pull in all of
+  stdio)
diff --git a/glib/glib/glib.toml.in b/glib/glib/glib.toml.in
index a7aed7a352..2a711b8093 100644
--- a/glib/glib/glib.toml.in
+++ b/glib/glib/glib.toml.in
@@ -35,6 +35,7 @@ urlmap_file = "urlmap.js"
 content_files = [
   "compiling.md",
   "error-reporting.md",
+  "i18n.md",
   "logging.md",
   "main-loop.md",
   "reference-counting.md",
diff --git a/glib/glib/i18n.md b/glib/glib/i18n.md
new file mode 100644
index 0000000000..7c99be4bf8
--- /dev/null
+++ b/glib/glib/i18n.md
@@ -0,0 +1,49 @@
+Title: Internationalization
+
+# Internationalization
+
+GLib doesn't force any particular localization method upon its users. But
+since GLib itself is localized using the `gettext()` mechanism, it seems
+natural to offer the de-facto standard `gettext()` support macros in an
+easy-to-use form.
+
+In order to use these macros in an application, you must include
+`<glib/gi18n.h>`. For use in a library, you must include `<glib/gi18n-lib.h>`
+after defining the `GETTEXT_PACKAGE` macro suitably for your library:
+
+```c
+#define GETTEXT_PACKAGE "gtk4"
+#include <glib/gi18n-lib.h>
+```
+
+For an application, note that you also have to call `bindtextdomain()`,
+`bind_textdomain_codeset()`, `textdomain()` and `setlocale()` early on in your
+`main()` to make `gettext()` work. For example:
+
+```c
+#include <glib/gi18n.h>
+#include <locale.h>
+
+int
+main (int argc, char **argv)
+{
+  setlocale (LC_ALL, "");
+  bindtextdomain (GETTEXT_PACKAGE, DATADIR "/locale");
+  bind_textdomain_codeset (GETTEXT_PACKAGE, "UTF-8");
+  textdomain (GETTEXT_PACKAGE);
+
+  // Rest of your application.
+}
+```
+
+where `DATADIR` is as typically provided by Automake or Meson.
+
+For a library, you only have to call `bindtextdomain()` and
+`bind_textdomain_codeset()` in your initialization function. If your library
+doesn't have an initialization function, you can call the functions before
+the first translated message.
+
+The [gettext
+manual](http://www.gnu.org/software/gettext/manual/gettext.html#Maintainers)
+covers details of how to integrate gettext into a project’s build system and
+workflow.
diff --git a/glib/glib/meson.build b/glib/glib/meson.build
index 078e682de4..6fc5abff0c 100644
--- a/glib/glib/meson.build
+++ b/glib/glib/meson.build
@@ -1,6 +1,7 @@
 expand_content_files = [
   'compiling.md',
   'error-reporting.md',
+  'i18n.md',
   'logging.md',
   'main-loop.md',
   'reference-counting.md',