Document internationalization mechanisms.

doc/builders.rst

@@ -223,10 +223,10 @@ Note that a direct PDF builder using ReportLab is available in `rst2pdf
 .. module:: sphinx.builders.intl
 .. class:: MessageCatalogBuilder
 
-   This builder produces a message catalog file for each reST file or
-   subdirectory.
+   This builder produces gettext-style message catalos.  Each top-level file or
+   subdirectory grows a single ``.pot`` catalog template.
 
-   See the documentation on :ref:`internationalization <intl>` for further reference.
+   See the documentation on :ref:`intl` for further reference.
 
    Its name is ``gettext``.
 

doc/config.rst

@@ -143,20 +143,6 @@ General configuration
    .. deprecated:: 1.0
       Use :confval:`exclude_patterns` instead.
 
-.. confval:: locale_dirs
-
-   .. versionadded:: 0.5
-
-   Directories in which to search for additional Sphinx message catalogs (see
-   :confval:`language`), relative to the source directory.  The directories on
-   this path are searched by the standard :mod:`gettext` module for a text
-   domain of ``sphinx``; so if you add the directory :file:`./locale` to this
-   settting, the message catalogs (compiled from ``.po`` format using
-   :program:`msgfmt`) must be in
-   :file:`./locale/{language}/LC_MESSAGES/sphinx.mo`.
-
-   The default is ``[]``.
-
 .. confval:: templates_path
 
    A list of paths that contain extra templates (or templates that overwrite
@@ -272,40 +258,6 @@ Project information
    If you don't need the separation provided between :confval:`version` and
    :confval:`release`, just set them both to the same value.
 
-.. confval:: language
-
-   The code for the language the docs are written in.  Any text automatically
-   generated by Sphinx will be in that language.  Also, in the LaTeX builder, a
-   suitable language will be selected as an option for the *Babel* package.
-   Default is ``None``, which means that no translation will be done.
-
-   .. versionadded:: 0.5
-
-   Currently supported languages are:
-
-   * ``bn`` -- Bengali
-   * ``ca`` -- Catalan
-   * ``cs`` -- Czech
-   * ``da`` -- Danish
-   * ``de`` -- German
-   * ``en`` -- English
-   * ``es`` -- Spanish
-   * ``fi`` -- Finnish
-   * ``fr`` -- French
-   * ``hr`` -- Croatian
-   * ``it`` -- Italian
-   * ``lt`` -- Lithuanian
-   * ``nl`` -- Dutch
-   * ``pl`` -- Polish
-   * ``pt_BR`` -- Brazilian Portuguese
-   * ``ru`` -- Russian
-   * ``sl`` -- Slovenian
-   * ``sv`` -- Swedish
-   * ``tr`` -- Turkish
-   * ``uk_UA`` -- Ukrainian
-   * ``zh_CN`` -- Simplified Chinese
-   * ``zh_TW`` -- Traditional Chinese
-
 .. confval:: today
              today_fmt
 
@@ -381,6 +333,68 @@ Project information
    .. versionadded:: 1.0
 
 
+.. _intl-options:
+
+Options for internationalization
+--------------------------------
+
+These options influence Sphinx' *Native Language Support*.  See the
+documentation on :ref:`intl` for details.
+
+.. confval:: language
+
+   The code for the language the docs are written in.  Any text automatically
+   generated by Sphinx will be in that language.  Also, Sphinx will try to
+   substitute individual paragraphs from your documents with the translation
+   sets obtained from :confval:`locale_dirs`.  In the LaTeX builder, a suitable
+   language will be selected as an option for the *Babel* package.  Default is
+   ``None``, which means that no translation will be done.
+
+   .. versionadded:: 0.5
+
+   Currently supported languages by Sphinx are:
+
+   * ``bn`` -- Bengali
+   * ``ca`` -- Catalan
+   * ``cs`` -- Czech
+   * ``da`` -- Danish
+   * ``de`` -- German
+   * ``en`` -- English
+   * ``es`` -- Spanish
+   * ``fi`` -- Finnish
+   * ``fr`` -- French
+   * ``hr`` -- Croatian
+   * ``it`` -- Italian
+   * ``lt`` -- Lithuanian
+   * ``nl`` -- Dutch
+   * ``pl`` -- Polish
+   * ``pt_BR`` -- Brazilian Portuguese
+   * ``ru`` -- Russian
+   * ``sl`` -- Slovenian
+   * ``sv`` -- Swedish
+   * ``tr`` -- Turkish
+   * ``uk_UA`` -- Ukrainian
+   * ``zh_CN`` -- Simplified Chinese
+   * ``zh_TW`` -- Traditional Chinese
+
+.. confval:: locale_dirs
+
+   .. versionadded:: 0.5
+
+   Directories in which to search for additional message catalogs (see
+   :confval:`language`), relative to the source directory.  The directories on
+   this path are searched by the standard :mod:`gettext` module.
+   
+   Internal messages are fetched from a text domain of ``sphinx``; so if you
+   add the directory :file:`./locale` to this settting, the message catalogs
+   (compiled from ``.po`` format using :program:`msgfmt`) must be in
+   :file:`./locale/{language}/LC_MESSAGES/sphinx.mo`.  The text domain of
+   individual documents depends on their docname if they are top-level project
+   files and on their base directory otherwise.
+
+   The default is ``[]``.
+
+
 .. _html-options:
 
 Options for HTML output

doc/intl.rst

@@ -7,7 +7,63 @@ Internationalization
 
 Complementary to translations provided for Sphinx-generated messages such as
 navigation bars, Sphinx provides mechanisms facilitating *document* translations
-in itself.  It relies on the existing configuration values :confval:`language`
-and :confval:`locale_dirs`.
+in itself.  See the :ref:`intl-options` for details on configuration.
 
-.. XXX write more!
+.. figure:: translation.png
+   :width: 100%
+
+   Workflow visualization of translations in Sphinx. [1]_
+
+**gettext** [2]_ is an established standard for internationalization and
+localization.  It naïvely maps messages in a program to a translated string.
+Sphinx uses these facilities to translate whole documents.
+
+Initially project maintainers have to collect all translatable strings (also
+referred to as *messages*) to make them known to translators.  Sphinx extracts
+these through invocation of ``sphinx-build -b gettext``.
+
+Every single element in the doctree will end up in a single message which
+results in lists being equally split into different chunks while large
+paragraphs will remain as coarsely-grained as they were in the original
+document.  This grants seamless document updates while still providing a little
+bit of context for translators in free-text passages.  It is the maintainer's
+task to split up paragraphs which are too large as there is no sane automated
+way to do that.
+
+After Sphinx successfully ran the
+:class:`~sphinx.builders.intl.MessageCatalogBuilder` you will find a collection
+of ``.pot`` files in your output directory.  These are **catalog templates**
+and contain messages in your original language *only*.
+
+They can be delivered to translators which will transform them to ``.po`` files
+--- so called **message catalogs** --- containing a mapping from the original
+messages to foreign-language strings.  
+
+Gettext compiles them into a binary format known as **binary catalogs** through
+:program:`msgfmt` for efficiency reasons.  If you make these files discoverable
+with :confval:`locale_dirs` for your :confval:`language`, Sphinx will pick them
+up automatically.
+
+An example: you have a document ``usage.rst`` in your Sphinx project.  The
+gettext builder will put its messages into ``usage.pot``.  Image you have
+Spanish translations [3]_ on your hands in ``usage.po`` --- for your builds to
+be translated you need to follow these instructions:
+
+* Compile your message catalog to a locale directory, say ``translated``, so it
+  ends up in ``./translated/es/LC_MESSAGES/usage.mo`` in your source directory
+  (where ``es`` is the language code for Spanish.) ::
+
+        msgfmt "usage.po" -o "translated/es/LC_MESSAGES/usage.mo"
+
+* Set :confval:`locale_dirs` to ``["translated/"]``.
+* Set :confval:`language` to ``es`` (also possible via :option:`-D`).
+* Run your desired build.
+
+
+.. rubric:: Footnotes
+
+.. [1] The stick-figure is taken from an `XKCD comic <http://xkcd.com/779/>`_.
+.. [2] See the `GNU gettext utilites
+       <http://www.gnu.org/software/gettext/manual/gettext.html#Introduction>`_
+       for details on that software suite.
+.. [3] Because nobody expects the Spanish Inquisition!

doc/invocation.rst

@@ -43,6 +43,9 @@ The :program:`sphinx-build` script has several options:
    **text**
       Build plain text files.
 
+   **gettext**
+      Build gettext-style message catalogs (``.pot`` files).
+
    **doctest**
       Run all doctests in the documentation, if the :mod:`~sphinx.ext.doctest`
       extension is enabled.