Initial work on translations / localization

Related to https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3841

Most of the preparation for this was done by Suguru Hirahara (https://github.com/luixxiul).
I've merely reorganized/polished the scripts and instructions in the `i18n/` directory.

While translations can happen even now, more work is necessary to

- make the translation flow better (integrating Weblate), etc.

- restore the Github Actions workflows that Suguru Hirahara had already developed to
  adapt them to our new workflow

i18n/bin/build-translated-result.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+
+# This script builds the translated result (translated project) for a given language in the `translated/<language>/` directory.
+
+set -euxo pipefail
+
+if [ $# -ne 1 ]; then
+    echo "Usage: $0 <language>"
+    exit 1
+fi
+
+LANGUAGE=$1
+
+base_path="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+if [ ! -f ${base_path}/i18n/locales/${LANGUAGE}/LC_MESSAGES/README.po ]; then
+    echo "Locales for ${LANGUAGE} not found. Please run the `sync-translation-templates-to-locales.sh` script first."
+    exit 1
+fi
+
+# Prepare a clean build directory
+if [ -d ${base_path}/i18n/translated-result-build-${LANGUAGE} ]; then
+    rm -rf ${base_path}/i18n/translated-result-build-${LANGUAGE}
+fi
+mkdir -p ${base_path}/i18n/translated-result-build-${LANGUAGE}
+
+# Build the translated documentation
+sphinx-build \
+    -b markdown \
+    -D language="${LANGUAGE}" \
+    ${base_path}/ \
+    ${base_path}/i18n/translated-result-build-${LANGUAGE}
+
+# Clean up .mo files produced during the build.
+# We don't commit them to the repository anyway, so they can be left alone,
+# but we'd rather keep things clean anyway.
+find ${base_path}/i18n/locales/${LANGUAGE} -type f -name '*.mo' -delete
+
+# Clean up the build directory
+rm -rf ${base_path}/i18n/translated-result-build-${LANGUAGE}/.doctrees
+
+# Copy assets
+cp -r ${base_path}/docs/assets ${base_path}/i18n/translated-result-build-${LANGUAGE}/docs/assets/
+
+# Remove the old result directory for this language
+if [ -d ${base_path}/i18n/translated/${LANGUAGE} ]; then
+    rm -rf ${base_path}/i18n/translated/${LANGUAGE}
+fi
+
+# Make sure the `translated/` directory exists
+if [ ! -d ${base_path}/i18n/translated ]; then
+    mkdir -p ${base_path}/i18n/translated
+fi
+
+# Relocate the built result to translated/<language>
+mv ${base_path}/i18n/translated-result-build-${LANGUAGE} ${base_path}/i18n/translated/${LANGUAGE}

i18n/bin/extract-translation-templates.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+
+# This script extracts translation templates (original English strings) into the `translation-templates/` directory.
+# These templates are later used to generate locale files for each language in the `locales/` directory.
+#
+# By default `sphinx-build` extracts the templates into a `build/gettext` directory, while we'd like to have them in the `translation-templates/` directory.
+# To avoid the `POT-Creation-Date` information in templates being updated every time we extract them,
+# we restore the `translation-templates/` directory to the `build/gettext` directory before running the script.
+
+set -euxo pipefail
+
+base_path="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+# Restore the `translation-templates/` directory to the `build/gettext` directory
+if [ -d ${base_path}/i18n/build ]; then
+    rm -rf ${base_path}/i18n/build
+fi
+mkdir -p ${base_path}/i18n/build
+cp -r ${base_path}/i18n/translation-templates ${base_path}/i18n/build/gettext
+
+# Extract translation templates from the documentation into the `build/gettext` directory
+sphinx-build -M gettext ${base_path} ${base_path}/i18n/build
+
+# Clean up the build directory
+rm -rf ${base_path}/i18n/build/gettext/.doctrees
+
+# Update the `translation-templates/` directory with the new templates
+if [ -d ${base_path}/i18n/translation-templates ]; then
+    rm -rf ${base_path}/i18n/translation-templates
+fi
+mv ${base_path}/i18n/build/gettext ${base_path}/i18n/translation-templates
+
+# Get rid of the `build` directory
+rmdir ${base_path}/i18n/build

i18n/bin/sync-translation-templates-to-locales.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+# This script updates the translation files (locales/<language>/**/*.po) for a given language.
+# It uses the translation templates (translation-templates/**/*.pot) to generate the translation files.
+
+set -euxo pipefail
+
+if [ $# -ne 1 ]; then
+    echo "Usage: $0 <language>"
+    exit 1
+fi
+
+LANGUAGE=$1
+
+base_path="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+if [ ! -f ${base_path}/i18n/translation-templates/README.pot ]; then
+    echo "Translation templates not found. Please run the `extract-translation-templates.sh` script first."
+    exit 1
+fi
+
+# Create necessary directories to avoid race conditions caused by
+# Sphinx potentially trying to concurrently create them from separate threads below.
+mkdir -p ${base_path}/i18n/locales/${LANGUAGE}/LC_MESSAGES/docs
+
+# Update the translation files
+sphinx-intl update \
+    --pot-dir ${base_path}/i18n/translation-templates \
+    --locale-dir ${base_path}/i18n/locales \
+    --language ${LANGUAGE}