From f82fc06112ed9a31a94fe4a7ddfdb1b6f775a8db Mon Sep 17 00:00:00 2001
From: Chris McDonough <chrism@agendaless.com>
Date: Mon, 19 Apr 2010 09:31:49 +0000
Subject: Docstrings.

---
 docs/api/i18n.rst  | 12 +++++++++++-
 repoze/bfg/i18n.py | 14 ++++++++++++++
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/docs/api/i18n.rst b/docs/api/i18n.rst
index 48c6d09a4..d76d36383 100644
--- a/docs/api/i18n.rst
+++ b/docs/api/i18n.rst
@@ -7,7 +7,17 @@
 
   .. autofunction:: get_translator(request)
 
+  .. function:: msg(text, domain=None, default=None, mapping=None)
+
+     Create a :class:`repoze.bfg.i18n.TranslationString` instance in
+     the ``bfg`` domain.  If this is a "technical" translation, use a
+     opaque string for ``text``, and make the ``default`` the format
+     string.  if this is a nontechnical translation, pass only
+     ``text``.
+
+  .. autoclass:: InterpolationOnlyTranslator
+
 See :ref:`i18n_chapter` for more information about using
-:mod:`repoze.bfg` internationalization services in an application.
+:mod:`repoze.bfg` internationalization services within an application.
 
 
diff --git a/repoze/bfg/i18n.py b/repoze/bfg/i18n.py
index 1aa2d13eb..7fc4c0f87 100644
--- a/repoze/bfg/i18n.py
+++ b/repoze/bfg/i18n.py
@@ -18,6 +18,9 @@ from zope.interface import implements
 from zope.interface import classProvides
 
 from zope.i18nmessageid.message import Message
+from zope.i18nmessageid import MessageFactory
+
+msg = MessageFactory('bfg')
 
 from repoze.bfg.interfaces import ITranslator
 from repoze.bfg.interfaces import ITranslatorFactory
@@ -68,6 +71,17 @@ def get_translator(request, translator_factory=None):
     return translator
 
 class InterpolationOnlyTranslator(object):
+    """ A class implementing the :term:`translator factory` interface
+    as its constructor and the :term:`translator` interface as its
+    ``__call__`` method.  Useful as a minimal translator factory, this
+    class only does basic interpolation of mapping values; it does not
+    actually do any language translations.  Use::
+
+        from repoze.bfg.configuration import Configurator
+        from repoze.bfg.i18n import InterpolationOnlyTranslator
+        config = Configurator(translator_factory=InterpolationOnlyTranslator)
+
+        """
     classProvides(ITranslatorFactory)
     implements(ITranslator)
     def __init__(self, request):
-- 
cgit v1.2.3