docs: convert TRANSLATORS to Markdown

Also expand it to cover typical tasks of creating new translations, updating
existing ones and compiling them (which can be useful to check syntax.)

3 files changed, 75 insertions, 28 deletions

diff --git a/docs/TRANSLATORS b/docs/TRANSLATORS
deleted file mode 100644
index 873ec7b01c..0000000000
--- a/docs/TRANSLATORS
+++ /dev/null
@@ -1,27 +0,0 @@
-Notes for translators
-=====================
-
-systemd depends on gettext for multilingual support.
-In po/ directory you'll find the needed files.
-
-POT (Portable Object Template)
-------------------------------
-A text file with .pot extension, with all the extracted labels from code.
-
-To update the template:
-
-$ cd systemd/
-$ ninja -C build systemd-pot
-
-To start a new translation:
-
-$ cd po/
-$ cp systemd.pot <YOUR-LANG-CODE>.po
-
-Replace <YOUR-LANG-CODE> with the two-letters codes of ISO 639 standard.
-
-PO (Portable Object)
---------------------
-A text file with .po extension, with all the available labels and some additional
-metadata fields. Any editor is ok, but a good standard is 'poedit', a graphical
-application specifically designed for this kind of task.
diff --git a/docs/TRANSLATORS.md b/docs/TRANSLATORS.md
new file mode 100644
index 0000000000..38c2487b90
--- /dev/null
+++ b/docs/TRANSLATORS.md
@@ -0,0 +1,74 @@
+# Notes for Translators
+
+systemd depends on the `gettext` package for multilingual support.
+
+You'll find the i18n files in the `po/` directory.
+
+The build system (meson/ninja) can be used to generate a template (`*.pot`),
+which can be used to create new translations.
+
+It can also merge the template into the existing translations (`*.po`), to pick
+up new strings in need of translation.
+
+Finally, it is able to compile the translations (to `*.gmo` files), so that
+they can be used by systemd software. (This step is also useful to confirm the
+syntax of the `*.po` files is correct.)
+
+# Creating a New Translation
+
+To create a translation to a language not yet available, start by creating the
+initial template:
+
+```
+$ ninja -C build/ systemd-pot
+```
+
+This will generate file `po/systemd.pot` in the source tree.
+
+Then simply copy it to a new <code><i>${lang_code}</i>.po</code> file, where
+<code><i>${lang_code}</i></code> is the two-letter code for a language
+(possibly followed by a two-letter uppercase country code), according to the
+ISO 639 standard.
+
+In short:
+
+<pre>
+$ cp po/systemd.pot po/<i>${lang_code}</i>.po
+</pre>
+
+Then edit the new <code>po/<i>${lang_code}</i>.po</code> file (for example,
+using the `poedit` GUI editor.)
+
+# Updating an Existing Translation
+
+Start by updating the `*.po` files from the latest template:
+
+```
+$ ninja -C build/ systemd-update-po
+```
+
+This will touch all the `*.po` files, so you'll want to pay attention when
+creating a git commit from this change, to only include the one translation
+you're actually updating.
+
+Edit the `*.po` file, looking for empty translations and translations marked as
+"fuzzy" (which means the merger found a similar message that needs to be
+reviewed as it's expected not to match exactly.)
+
+You can use any text editor to update the `*.po` files, but a good choice is
+the `poedit` editor, a graphical application specifically designed for this
+purpose.
+
+Once you're done, create a git commit for the update of the `po/*.po` file you
+touched. Remember to undo the changes to the other `*.po` files (for instance,
+using `git checkout -- po/` after you commit the changes you do want to keep.)
+
+# Recompiling Translations
+
+You can recompile the `*.po` files using the following command:
+
+```
+$ ninja -C build/ systemd-gmo
+```
+
+The resulting files will be saved in the `build/po/` directory.
diff --git a/meson.build b/meson.build
index 3003eb3dc4..394de96dfb 100644
--- a/meson.build
+++ b/meson.build
@@ -2771,7 +2771,7 @@ install_data('LICENSE.GPL2',
              'docs/ENVIRONMENT.md',
              'docs/HACKING',
              'docs/TRANSIENT-SETTINGS.md',
-             'docs/TRANSLATORS',
+             'docs/TRANSLATORS.md',
              'docs/UIDS-GIDS.md',
              'src/libsystemd/sd-bus/GVARIANT-SERIALIZATION',
              install_dir : docdir)