Enable translations (via GNU gettext, sphinx-intl, and transifex)

Change-Id: I4335d5c6e35b8c6dde1643569c13cfdf3572c534

.tx/config

+[main]
+host = https://www.transifex.com
+
+[o:savoirfairelinux:p:jami:r:docs-user]
+file_filter = locales/<lang>/LC_MESSAGES/user.po
+source_file = _build/gettext/user.pot
+source_lang = en
+type        = PO
+
+[o:savoirfairelinux:p:jami:r:docs-build]
+file_filter = locales/<lang>/LC_MESSAGES/build.po
+source_file = _build/gettext/build.pot
+source_lang = en
+type        = PO
+
+[o:savoirfairelinux:p:jami:r:docs-developer]
+file_filter = locales/<lang>/LC_MESSAGES/developer.po
+source_file = _build/gettext/developer.pot
+source_lang = en
+type        = PO
+
+[o:savoirfairelinux:p:jami:r:docs-index]
+file_filter = locales/<lang>/LC_MESSAGES/index.po
+source_file = _build/gettext/index.pot
+source_lang = en
+type        = PO
+
+[o:savoirfairelinux:p:jami:r:docs-contribute]
+file_filter = locales/<lang>/LC_MESSAGES/contribute.po
+source_file = _build/gettext/contribute.pot
+source_lang = en
+type        = PO
+
+[o:savoirfairelinux:p:jami:r:docs-sphinx]
+file_filter = locales/<lang>/LC_MESSAGES/sphinx.po
+source_file = _build/gettext/sphinx.pot
+source_lang = en
+type        = PO

Makefile

@@ -7,9 +7,16 @@
 # without any warranty.
 
 CMD ?= sphinx-build
+AUTOBUILD_CMD ?= sphinx-autobuild
+INTL_CMD ?= sphinx-intl
 OPTS ?=
 SRC  = .
 OUT  = _build
+RSYNC_DEST ?= $(OUT)/docs
+RSYNC_OPTS ?= --verbose --archive --recursive --delete
+
+# Translation languages (other than English)
+LANGS = fr fa
 
 # default rule
 help:
@@ -19,8 +26,43 @@ help:
 
 # specific rule to use sphinx-autobuild
 watch: Makefile
-	@sphinx-autobuild -b html "$(SRC)" "$(OUT)"/html $(OPTS)
+	@$(AUTOBUILD_CMD) -b html "$(SRC)" "$(OUT)"/html $(OPTS)
+
+# Avoid manual (non-gettext) French translations getting picked up by
+# by sphinx for translation.  This is temporary, until these pages are
+# properly (re)translated into French and these files are dropped.
+gettext-pre:
+	-@for f in user/*-fr.md; do \
+	  if [ -f "$$f" ]; then mv "$$f" "$$f.bk"; fi; \
+	done
+	-@for f in developer/*-fr.md; do \
+	  if [ -f "$$f" ]; then mv "$$f" "$$f.bk"; fi; \
+	done
+
+gettext: gettext-pre
+
+po-pre:
+# shouldn't translate the GNU FDL
+	-rm $(OUT)/gettext/fdl.pot
+po: gettext po-pre
+	@for l in $(LANGS); do \
+	  $(INTL_CMD) update -p "$(OUT)"/gettext -l $$l; \
+	done
+
+deploy:
+	rsync $(RSYNC_OPTS) "$(OUT)"/html/ "$(RSYNC_DEST)"
+	for l in $(LANGS); do \
+	  rsync $(RSYNC_OPTS) "$(OUT)/$$l"/html/ "$(RSYNC_DEST)"/"$$l"; \
+	done
 
 # anything else
 %: Makefile
 	@$(CMD) -M $@ "$(SRC)" "$(OUT)" $(OPTS)
+	@for l in $(LANGS); do \
+	  $(CMD) -M $@ "$(SRC)" "$(OUT)/$$l" \
+	    -D language="$$l" \
+	    -D html_baseurl="https://docs.jami.net/$$l" \
+	    $(OPTS); \
+	done
+
+.PHONY: gettext-pre po-pre po deploy

_templates/message.pot_t

+# LANGUAGE translation of FILENAME.pot
+# Copyright (C) {{ copyright }}
+# This file is distributed under the same license as the {{ project }} documentation.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: {{ project|e }}\n"
+"Report-Msgid-Bugs-To: https://git.jami.net/savoirfairelinux/jami-docs/-/issues\n"
+"POT-Creation-Date: {{ ctime|e }}\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: {{ last_translator|e }}\n"
+"Language-Team: {{ language_team|e }}\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+{% for message in messages %}
+{% if display_location -%}
+{% for source, line in message.locations -%}
+#: {{ relpath(source) }}:{{ line }}
+{% endfor -%}
+{% endif -%}
+
+{% if display_uuid -%}
+{% for uuid in message.uuids -%}
+#: {{ uuid }}
+{% endfor -%}
+{% endif -%}
+
+msgid "{{ message.text|e }}"
+msgstr ""
+{% endfor -%}

conf.py

@@ -8,14 +8,18 @@
 # for a full list of Sphinx configuration options, see:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import sphinx_rtd_theme
+
 project = 'Jami'
 copyright = '2018-2022 Savoir-faire Linux Inc. and contributors'
 author = 'Savoir-faire Linux Inc. and contributors'
+html_baseurl = 'https://docs.jami.net'
 
 extensions = [
     'myst_parser',
     'sphinx.ext.autosectionlabel',
     'sphinx.ext.extlinks',
+    'sphinx_rtd_theme',
 ]
 
 extlinks = {
@@ -85,3 +89,7 @@ html_theme_options = {
 # (copied after the builtin static files, so a "default.css"
 #  file there would overwrite the builtin "default.css")
 html_static_path = ['_static']
+
+# internationalization / translations
+locale_dirs = ['locales']
+gettext_compact = True

index.rst

@@ -10,6 +10,11 @@ respects the freedom and privacy of its users.  Jami is available
 across operating systems and platforms including GNU/Linux, macOS,
 Windows, Android/Replicant, and iOS.
 
+.. admonition:: Translations
+
+   This documentation is available in `English </>`_,
+   `French </fr/>`_, and `Persian (Farsi) </fa/>`_.
+
 Jami is an official GNU package and you can redistribute it and/or
 modify it under the terms of the `GNU General Public License
 <https://www.gnu.org/licenses/gpl.html>`_ as published by the Free