docs: Move i18n documentation to Markdown

Helps: #3037

docs/reference/glib/glib.toml.in

@@ -41,6 +41,8 @@ urlmap_file = "urlmap.js"
 # The same order will be used when generating the index
 content_files = [
   "character-set.md",
+  "i18n.md",
+
   "conversion-macros.md",
   "error-reporting.md",
   "reference-counting.md",

docs/reference/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.

docs/reference/glib/meson.build

@@ -154,6 +154,7 @@ endif
 expand_content_files = [
   'character-set.md',
   'error-reporting.md',
+  'i18n.md',
   'reference-counting.md',
   'threads.md',
 ]

glib/ggettext.c

@@ -462,57 +462,6 @@ g_dngettext (const gchar *domain,
   return dngettext (domain, msgid, msgid_plural, n);
 }
 
-
-/**
- * SECTION:i18n
- * @title: Internationalization
- * @short_description: gettext support macros
- * @see_also: the gettext manual
- *
- * 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:
- * |[<!-- language="C" -->
- * #define GETTEXT_PACKAGE "gtk20"
- * #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:
- * |[<!-- language="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.
- */
-
 /**
  * _:
  * @String: the string to be translated