Update to make documentation working with Sphinx i18n system in order to facilitate translation process

Author: ThomasG77

Makefile

@@ -9,6 +9,7 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 TRANSLATIONS  = de fr it es zh_cn
+TRANSLATIONI18N  =
 LANGUAGES     = en $(TRANSLATIONS) 
 
 # On mapserver.org we need to write alternate links for the language switcher.
@@ -20,14 +21,21 @@ LANGUAGES     = en $(TRANSLATIONS)
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees/$$lang $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) -c . -A language=$$lang -D language=$$lang -A target=$(TARGET) -A languages='$(LANGUAGES)'
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees/$$lang $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) -c . -A language=$$lang -D language=$$lang -A target=$(TARGET) -A languages='$(LANGUAGES) $(TRANSLATIONI18N)'
+
+ALLSPHINXOPTSI18N = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) -c . -a -A language=$$lang -D language=$$lang -A target=$(TARGET) -A languages='$(LANGUAGES) $(TRANSLATIONI18N)'
+
+# Only for Gettext
+I18NSPHINXOPTS   = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) -c . -A language=en -D language=en -A target=$(TARGET) -A languages='en'
 
 .PHONY: help clean html web pickle htmlhelp latex changes linkcheck
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html      to make standalone HTML files"
-	@echo "  init	   to preprocess translation directories"
+	@echo "  init      to preprocess translation directories"
+	@echo "  compile_messages    to compile po to mo files"
+	@echo "  generate_po_from_tmpl    to duplicate pot to po files for a language, e.g from translated\pot directory to translated\lang"
 	@echo "  pickle    to make pickle files"
 	@echo "  json      to make JSON files"
 	@echo "  htmlhelp  to make HTML files and a HTML help project"
@@ -36,6 +44,8 @@ help:
 	@echo "  all-ps    to make PS file"
 	@echo "  changes   to make an overview over all changed/added/deprecated items"
 	@echo "  linkcheck to check all external links for integrity"
+	@echo "  gettext   to generate pot files from en rst files"
+	@echo "  gettext_copy   to duplicate pot files from gettext dir to translated\pot"
 
 clean:
 	-rm -rf $(BUILDDIR)/*
@@ -59,22 +69,68 @@ init:
 	done
 	@echo "Init finished. Other target can now be build.";\
 
+compile_messages:
+	@for lang in $(TRANSLATIONI18N) ;\
+	do \
+		echo "Compiling messages for $$lang..."; \
+		for f in `find ./translated/$$lang -name \*.po -printf "%f\n"`; \
+		do \
+		echo "Compiling messages for $$f"; \
+		msgfmt ./translated/$$lang/$$f -o ./translated/$$lang/LC_MESSAGES/$${f%.*}.mo; \
+		done; \
+	done
+	@echo "Messages compiled. Now you can build updated version for html and pdf.";\
+
+generate_po_from_tmpl:
+	@for lang in $(TRANSLATIONI18N) ;\
+	do \
+		echo "Generate po files from pot files for $$lang..."; \
+		for f in `find ./translated/pot/ -name \*.pot -printf "%f\n"`; \
+		do \
+		echo "Copy pot files to po file for $$f"; \
+		cp ./translated/pot/$$f ./translated/$$lang/$${f%.*}.po; \
+		done; \
+	done
+	@echo "*.pot files copy to *.po files. Now you can start your translation.";\
+
 html:
 	@for lang in $(LANGUAGES);\
 	do \
 		mkdir -p $(BUILDDIR)/html/$$lang $(BUILDDIR)/doctrees/$$lang; \
 		echo "$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $$lang $(BUILDDIR)/html/$$lang";\
 		$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $$lang $(BUILDDIR)/html/$$lang;\
 	done
+	@for lang in $(TRANSLATIONI18N);\
+	do \
+		echo "$(SPHINXBUILD) -b html $(ALLSPHINXOPTSI18N) en build/html/$$lang";\
+		$(SPHINXBUILD) -b html $(ALLSPHINXOPTSI18N) en build/html/$$lang;\
+	done
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/<language>.";\
 
+gettext:
+		mkdir -p $(BUILDDIR)/gettext/en $(BUILDDIR)/doctrees/en; \
+		echo "$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) en $(BUILDDIR)/gettext/en";\
+		$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) en $(BUILDDIR)/gettext/en;\
+
+	@echo "Build finished. The pot files pages are in $(BUILDDIR)/gettext/en.";\
+
+gettext_copy:
+	    cp $(BUILDDIR)/gettext/en/*.pot translated/pot/; \
+
+	@echo "Build finished. The pot files pages are in $(BUILDDIR)/gettext/en.";\
+
 singlehtml:
 	@for lang in $(LANGUAGES);\
 	do \
 		mkdir -p $(BUILDDIR)/singlehtml/$$lang $(BUILDDIR)/doctrees/$$lang; \
 		$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $$lang $(BUILDDIR)/singlehtml/$$lang;\
 	done
+	@for lang in $(TRANSLATIONI18N);\
+	do \
+		mkdir -p $(BUILDDIR)/singlehtml/$$lang $(BUILDDIR)/doctrees/$$lang; \
+		$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTSI18N) en $(BUILDDIR)/singlehtml/$$lang;\
+	done
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/singlehtml/<language>.";\
 
@@ -84,6 +140,11 @@ pickle:
 		mkdir -p $(BUILDDIR)/pickle/$$lang $(BUILDDIR)/doctrees/$$lang; \
 		$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $$lang $(BUILDDIR)/pickle/$$lang;\
 	done
+	@for lang in $(TRANSLATIONI18N);\
+	do \
+		mkdir -p $(BUILDDIR)/pickle/$$lang $(BUILDDIR)/doctrees/$$lang; \
+		$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTSI18N) en $(BUILDDIR)/pickle/$$lang;\
+	done
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
@@ -95,6 +156,11 @@ json:
 		mkdir -p $(BUILDDIR)/json/$$lang $(BUILDDIR)/doctrees/$$lang; \
 		$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $$lang $(BUILDDIR)/json/$$lang;\
 	done
+	@for lang in $(TRANSLATIONI18N);\
+	do \
+		mkdir -p $(BUILDDIR)/json/$$lang $(BUILDDIR)/doctrees/$$lang; \
+		$(SPHINXBUILD) -b json $(ALLSPHINXOPTSI18N) en $(BUILDDIR)/json/$$lang;\
+	done
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
@@ -114,6 +180,11 @@ latex:
 		mkdir -p $(BUILDDIR)/latex/$$lang $(BUILDDIR)/doctrees/$$lang; \
 		$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $$lang $(BUILDDIR)/latex/$$lang;\
 	done
+	@for lang in $(TRANSLATIONI18N);\
+	do \
+		mkdir -p $(BUILDDIR)/latex/$$lang $(BUILDDIR)/doctrees/$$lang; \
+		$(SPHINXBUILD) -b latex $(ALLSPHINXOPTSI18N) en $(BUILDDIR)/latex/$$lang;\
+	done
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex/<language>."\
 	@echo "Run \`make all-pdf' or \`make all-ps'"
@@ -124,6 +195,11 @@ pdf:
 		mkdir -p $(BUILDDIR)/pdf/$$lang $(BUILDDIR)/doctrees/$$lang; \
 		$(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) $$lang $(BUILDDIR)/pdf/$$lang;\
 	done
+	@for lang in $(TRANSLATIONI18N);\
+	do \
+		mkdir -p $(BUILDDIR)/pdf/$$lang $(BUILDDIR)/doctrees/$$lang; \
+		$(SPHINXBUILD) -b pdf $(ALLSPHINXOPTSI18N) en $(BUILDDIR)/pdf/$$lang;\
+	done
 	@echo
 	@echo "Build finished; the PDF files are in $(BUILDDIR)/pdf/<language>."\
 	@echo "Run \`make pdf' "
@@ -146,6 +222,13 @@ all-pdf:
 		mv -f $(BUILDDIR)/latex/$$lang/MapServer.pdf $(BUILDDIR)/html/$$lang ; \
 		fi \
 	done
+	@for lang in $(TRANSLATIONI18N);\
+	do \
+		/usr/bin/make -C $(BUILDDIR)/latex/$$lang all-pdf ; \
+		if [ -d $(BUILDDIR)/html/$$lang ]; then \
+		mv -f $(BUILDDIR)/latex/$$lang/MapServer.pdf $(BUILDDIR)/html/$$lang ; \
+		fi \
+	done
 
 all-ps:
 	@for lang in $(LANGUAGES);\

conf.py

@@ -258,6 +258,9 @@
 # A list of files that should not be packed into the epub file.
 #epub_exclude_files = []
 
+# Path for sphinx to find *.mo files for translation
+locale_dirs = ['../translated']
+
 from pygments.lexer import RegexLexer, bygroups,combined, include
 from pygments.token import *
 from pygments import highlight

i18n_win.py

@@ -0,0 +1,33 @@
+#! /usr/bin/env python
+# -*- coding: iso-8859-1 -*-
+
+import os
+import sys
+import glob
+# Add path to be able to append msgfmt as a module
+i18n_utils_path = os.path.join(os.path.dirname(sys.executable), "Tools", "i18n")
+sys.path.append(i18n_utils_path)
+import msgfmt
+
+from optparse import OptionParser
+
+def main():
+    parser = OptionParser(usage="usage: %prog [options]",
+                          version="%prog 1.0")
+    parser.add_option("-l", "--lang",
+                      action="store", # optional because action defaults to "store"
+                      dest="lang",
+                      help="Choose a language for compiling *.po files to *.mo",)
+    (options, args) = parser.parse_args()
+
+    if len(args) != 0:
+        parser.error("wrong number of arguments, you only have to use lang option")
+
+    os.chdir(os.path.join(os.getcwd(), "translated", options.lang))
+    for filename in glob.glob("*.po"):
+        msgfmt.make(filename, os.path.join("LC_MESSAGES", filename.split(".")[0] + ".mo"))
+
+
+if __name__ == '__main__':
+    main()
+

make.bat

@@ -6,14 +6,22 @@ setlocal enableextensions enabledelayedexpansion
 
 REM ...build a list of directories to be processed (language directories)
 SET TRANSLATIONS=de es fr zh_cn
+SET TRANSLATIONI18N=
 SET LANGUAGES=en %TRANSLATIONS%
 
 set SPHINXBUILD=sphinx-build
 set ALLSPHINXOPTS= -d _build/doctrees/%%L -c . -A language=%%L -D language=%%L -A languages="%LANGUAGES%"
+set ALLSPHINXOPTSI18N= -d _build/doctrees/%%L -c . -A language=%%L -D language=%%L -A languages="%LANGUAGES% %TRANSLATIONI18N%"
+
 if NOT "%PAPER%" == "" (
 	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+	set ALLSPHINXOPTSI18N=-D latex_paper_size=%PAPER% %ALLSPHINXOPTSI18N%
 )
 
+REM Only for Gettext
+set I18NSPHINXOPTS   = -D latex_paper_size=%PAPER% -d _build/doctrees/en -c . -A language=en -D language=en -A languages="en"
+
+
 if "%1" == "" goto help
 
 if "%1" == "help" (
@@ -22,6 +30,10 @@ if "%1" == "help" (
   echo.  init      to preprocess translation directories 
 	echo.  html      to make standalone HTML files
 	echo.  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  gettext     to generate pot files from en rst files
+	echo.  gettext_copy     to duplicate pot files from gettext dir to translated\pot
+	echo.  compile_messages    to compile po to mo files
+	echo.  generate_po_from_tmpl    to duplicate pot to po files for a language, e.g from translated\pot directory to translated\lang
 	echo.  changes   to make an overview over all changed/added/deprecated items
 	echo.  linkcheck to check all external links for integrity
 	goto end
@@ -45,6 +57,9 @@ if "%1" == "html" (
   FOR  %%L in (%LANGUAGES%) DO (
   	%SPHINXBUILD% -b html  %ALLSPHINXOPTS% %%L _build/html/%%L
 	)
+  FOR  %%L in (%TRANSLATIONI18N%) DO (
+  	%SPHINXBUILD% -b html  %ALLSPHINXOPTSI18N% en _build/html/%%L
+	)
 	echo.
 	echo.Build finished. The HTML pages are in _build/html.
 	goto end
@@ -54,11 +69,67 @@ if "%1" == "latex" (
   FOR  %%L in (%LANGUAGES%) DO (
   	%SPHINXBUILD% -b latex  %ALLSPHINXOPTS% %%L _build/latex/%%L
 	)
+  FOR  %%L in (%TRANSLATIONI18N%) DO (
+  	%SPHINXBUILD% -b latex  %ALLSPHINXOPTSI18N% en _build/latex/%%L
+	)
 	echo.
 	echo.Build finished; the LaTeX files are in _build/latex.
 	goto end
 )
 
+if "%1" == "gettext" (
+		mkdir _build\gettext\en
+		mkdir _build\doctrees\en
+		%SPHINXBUILD% -b gettext  %ALLSPHINXOPTS% en _build/gettext/en
+)
+
+if "%1" == "gettext_copy" (
+        xcopy _build\gettext\en translated\pot /y /s /e
+)
+		
+if "%1" == "compile_messages" (
+REM Add text below in C:\PythonXX\Lib\site-packages\sitecustomize.py if you get an error about encoding
+REM and/or python -c "import sys;print sys.getdefaultencoding()" send you ascii (or fail on accents)
+
+REM #!/usr/bin/env python
+REM # -*- coding: iso-8859-1 -*-
+
+REM # Retrieve default 'locale'.
+REM import locale, sys
+REM loc = locale.getdefaultlocale()
+REM if loc[1]:
+REM     encoding = loc[1]
+
+REM # A non-Unicode version will return AttributeError...
+REM if encoding:
+REM     sys.setdefaultencoding(encoding)
+  if "%2" == "" (
+  FOR  %%L in (%TRANSLATIONI18N%) DO (
+  	python i18n_win.py --lang %%L
+	)
+	echo.
+	echo.Messages compiled using TRANSLATIONI18N for lang. Now you can build updated version for html and pdf.
+  ) else (
+  FOR  %%L in (%2) DO (
+  	python i18n_win.py --lang %%L
+	)
+	echo.
+	echo.Messages compiled using command line var for lang. Now you can build updated version for html and pdf.
+  )
+  goto end
+)
+
+if "%1" == "generate_po_from_tmpl" (
+  if "%2" NEQ "" (
+  FOR  %%L in (%2%) DO (
+  	xcopy translated\pot\*.pot translated\%%L\*.po /s /e
+	)
+	echo.
+	echo."*.pot files copy to *.po files. Now you can start your translation."
+  )
+  goto end
+)
+
 if "%1" == "changes" (
   FOR  %%L in (%LANGUAGES%) DO (
   	%SPHINXBUILD% -b changes  %ALLSPHINXOPTS% %%L _build/changes/%%L