Ticket #18108: docs_translation.diff

docs/Makefile

@@ -6 +6 @@
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
+LANGUAGE      =
+TRANSDIR      = translations
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees -D language=$(LANGUAGE) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+POFILES         = $(wildcard $(TRANSDIR)/*/LC_MESSAGES/*.po)
+MOFILES         = $(POFILES:.po=.mo)
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext translations
 
 help:
         @echo "Please use \`make <target>' where <target> is one of"
@@ -32 +36 @@
         @echo "  text       to make text files"
         @echo "  man        to make manual pages"
         @echo "  gettext    to make PO message catalogs"
+        @echo "  translations to compile PO files into MO files"
         @echo "  changes    to make an overview of all changed/added/deprecated items"
         @echo "  linkcheck  to check all external links for integrity"
         @echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
 clean:
         -rm -rf $(BUILDDIR)/*
+        -rm $(TRANSDIR)/*/*.mo
 
 html:
         $(SPHINXBUILD) -b djangohtml $(ALLSPHINXOPTS) $(BUILDDIR)/html
@@ -121 +127 @@
         @echo
         @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
 
+translations: $(MOFILES)
+        @echo "Translations compiled into .mo files."
+
+%.mo: %.po
+        @msgfmt -o $@ $<
+
 changes:
         $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
         @echo

docs/README

@@ -14 +14 @@
 
 The documentation in _build/html/index.html can then be viewed in a web browser.
 
+Building translated versions
+----------------------------
+
+To build translated versions of the Django documentation, use the following
+make commands and specify your language code in the LANGUAGE variable. For
+example:
+
+    $ make translations
+    $ make html LANGUAGE=fr
+
+This uses available translations in docs/translations. Those .po files are
+obtained through the Transifex django-docs project [3].
+This is currently only supported on Unix-based platforms.
+
 [1] http://docutils.sourceforge.net/rst.html
 [2] http://sphinx.pocoo.org/
+[3] https://www.transifex.net/projects/p/django-docs/

docs/conf.py

@@ -60 +60 @@
 # for a list of supported languages.
 #language = None
 
+locale_dirs = ['translations']
+
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
 #today = ''

docs/internals/contributing/localizing.txt

@@ -60 +60 @@
 * Open a ticket in Django's ticket system, set its ``Component`` field to
   ``Translations``, and attach the patch to it.
 
+Documentation
+-------------
+
+The Django documentation can also be translated on Transifex `Django-docs
+project page`_.
+
+To learn how to build a translated version of the Django documentation in your
+language, see the README file in the docs directory of the Django source tree.
+
 .. _Transifex: https://www.transifex.net/
 .. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
 .. _Django project page: https://www.transifex.net/projects/p/django/
+.. _Django-docs project page: https://www.transifex.net/projects/p/django-docs/
 .. _Transifex User Guide: http://help.transifex.net/