Update docs

CHANGES

@@ -41,6 +41,8 @@ Features added
 * Add :confval:`author` as a configuration value
 * #2852: imgconverter: Support to convert GIF to PNG
 * ``sphinx-build`` command supports i18n console output
+* Add ``app.add_message_catalog()`` and ``sphinx.locale.get_translations()`` to
+  support translation for 3rd party extensions
 
 Bugs fixed
 ----------

doc/extdev/appapi.rst

@@ -93,6 +93,8 @@ package.
 
 .. automethod:: Sphinx.add_html_theme(name, theme_path)
 
+.. automethod:: Sphinx.add_message_catalog(catalog, locale_dir)
+
 .. automethod:: Sphinx.is_parallel_allowed(typ)
 
 .. exception:: ExtensionError

doc/extdev/i18n.rst

@@ -0,0 +1,17 @@
+.. _i18n-api:
+
+i18n API
+========
+
+.. currentmodule:: sphinx.locale
+
+.. autofunction:: init
+
+.. autofunction:: init_console
+
+.. autofunction:: get_translation
+
+.. autofunction:: _
+
+.. autofunction:: __
+

doc/extdev/index.rst

@@ -93,3 +93,4 @@ APIs used for writing extensions
    parserapi
    nodes
    logging
+   i18n

sphinx/application.py

@@ -1119,7 +1119,7 @@ class Sphinx(object):
 
         The *catalog* is a name of catalog, and *locale_dir* is a base path
         of message catalog.  For more details, see
-        :func:`sphinx.locales.get_translation()`.
+        :func:`sphinx.locale.get_translation()`.
 
         .. versionadded:: 1.8
         """

sphinx/locale/__init__.py

@@ -249,7 +249,10 @@ def init(locale_dirs, language, catalog='sphinx', namespace='general'):
 
 def init_console(locale_dir, catalog):
     # type: (unicode, unicode) -> None
-    """Initialize locale for console."""
+    """Initialize locale for console.
+
+    .. versionadded:: 1.8
+    """
     language, _ = locale.getlocale(locale.LC_MESSAGES)  # encoding is ignored
     return init([locale_dir], language, catalog, 'console')
 
@@ -275,7 +278,7 @@ def _lazy_translate(catalog, namespace, message):
 
 def get_translation(catalog, namespace='general'):
     # type: (unicode, unicode) -> Callable[[unicode, *Any], unicode]
-    """Get a translation function based on the *catalog*, *locale_dir*.
+    """Get a translation function based on the *catalog* and *namespace*.
 
     The extension can use this API to translate the messages on the
     extension::
@@ -314,7 +317,11 @@ def get_translation(catalog, namespace='general'):
 
 
 # A shortcut for sphinx-core
+#: Translation function for messages on documentation (menu, labels, themes and so on).
+#: This function follows :confval:`language` setting.
 _ = get_translation('sphinx')
+#: Translation function for console messages
+#: This function follows locale setting (`LC_ALL`, `LC_MESSAGES` and so on).
 __ = get_translation('sphinx', 'console')