Dip a toe in the i18n waters.

7 files changed, 81 insertions, 0 deletions

diff --git a/docs/api.rst b/docs/api.rst
index 2bd5fca01..a97c79fa9 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -15,6 +15,7 @@ documentation is organized alphabetically by module name.
    api/configuration
    api/events
    api/exceptions
+   api/i18n
    api/interfaces
    api/location
    api/paster
diff --git a/docs/api/i18n.rst b/docs/api/i18n.rst
new file mode 100644
index 000000000..936f8aced
--- /dev/null
+++ b/docs/api/i18n.rst
@@ -0,0 +1,13 @@
+.. _i18n_module:
+
+:mod:`repoze.bfg.i18n`
+----------------------
+
+.. automodule:: repoze.bfg.i18n
+
+  .. autofunction:: get_translator
+
+See :ref:`i18n_chapter` for more information about using
+:mod:`repoze.bfg` internationalization services in an application.
+
+
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 14bd4fc44..537af06b9 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -667,3 +667,27 @@ Glossary
      at import time, the action usually taken by the decorator is
      deferred until a separate "scan" phase.  :mod:`repoze.bfg` relies
      on Venusian to provide a basis for its :term:`scan` feature.
+
+   Translation String
+     An instance of the :class:`repoze.bfg.i18n.TranslationString`,
+     which is a class that behaves like a Unicode string, but has
+     several extra attributes such as ``domain``, ``msgid``, and
+     ``mapping`` for use during translation.  Translation strings are
+     usually created by hand within software, but are sometimes
+     created on the behalf of the system for automatic template
+     translation.  For more information, see :ref:`i18n_chapter`.
+
+   Translator
+     A callable which receives a :term:`translation string` and
+     returns a translated Unicode object for the purposes of
+     internationalization.  A translator may be suppled to a
+     :mod:`repoze.bfg` application at startup time indirectly via the
+     ``translator_factory`` function, which is a :term:`translator
+     factory`.
+
+   Translator Factory
+     A callable which receives a :term:`request` and returns a
+     :term:`translator` for the purposes of internationalization.  A
+     translator factory may be suppled to a :mod:`repoze.bfg`
+     application at startup time via the ``translator_factory``
+     function.
diff --git a/docs/index.rst b/docs/index.rst
index ee32cf691..c1b185352 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -53,6 +53,7 @@ Narrative documentation in chapter form explaining how to use
    narr/templates
    narr/models
    narr/security
+   narr/i18n
    narr/vhosting
    narr/events
    narr/environment
diff --git a/docs/latexindex.rst b/docs/latexindex.rst
index 45438e939..5850ee06c 100644
--- a/docs/latexindex.rst
+++ b/docs/latexindex.rst
@@ -42,6 +42,7 @@ Narrative Documentation
    narr/templates
    narr/models
    narr/security
+   narr/i18n
    narr/vhosting
    narr/events
    narr/environment
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
new file mode 100644
index 000000000..e8ad0b554
--- /dev/null
+++ b/docs/narr/i18n.rst
@@ -0,0 +1,36 @@
+.. index::
+   single: i18n
+   single: internationalization
+
+.. _i18n_chapter:
+
+Using Internationalization
+==========================
+
+Setting Up Translation
+----------------------
+
+Pass a :term:`translator factory` object to your application's
+:mod:`repoze.bfg.configuration.Configurator` by supplying it with a
+``translator_factory`` argument.  A translator factory is an object
+which accepts a :term:`request` and which returns a callable.  The
+callable returned by a translator factory is a :term:`translator`; it
+must accept a single positional argument which represents a
+:term:`translation string` and should return a fully expanded
+translation of the translation string.
+
+The exact operation of a translator is left to the implementor of a
+particular translation factory.
+
+Obtaining the Translator via :func:`repoze.bfg.i18n.get_translator`
+--------------------------------------------------------------------
+
+If you need to perform translation "by hand" in an application, use
+the :func:`repoze.bfg.i18n.get_translator` function to obtain a
+translator.  A translator is a callable which accepts either a
+:term:`translation string` or a normal Unicode object and which
+returns a Unicode object representing the translation.
+
+XXX
+
+
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index a24e4b7b5..eebaa63de 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -840,6 +840,11 @@ In all cases, the message provided to the exception constructor is
 made available to the view which :mod:`repoze.bfg` invokes as
 ``request.exception.args[0]``.
 
+.. index::
+   single: exception views
+
+.. _exception_views:
+
 Exception Views
 ~~~~~~~~~~~~~~~~