3 files changed, 109 insertions, 1 deletions
diff --git a/Mailman/docs/acknowledge.txt b/Mailman/docs/acknowledge.txt
index 82fdd3fd3..e22bf3d57 100644
--- a/Mailman/docs/acknowledge.txt
+++ b/Mailman/docs/acknowledge.txt
@@ -12,6 +12,7 @@ acknowledgment.
     >>> from Mailman.database import flush
     >>> mlist = config.list_manager.create('_xtest@example.com')
     >>> mlist.real_name = 'XTest'
+    >>> mlist.preferred_language = 'en'
     >>> # XXX This will almost certainly change once we've worked out the web
     >>> # space layout for mailing lists now.
     >>> mlist._data.web_page_url = 'http://lists.example.com/'
diff --git a/Mailman/docs/digests.txt b/Mailman/docs/digests.txt
index 3788651f9..8f2a60ebc 100644
--- a/Mailman/docs/digests.txt
+++ b/Mailman/docs/digests.txt
@@ -418,9 +418,16 @@ Internationalized digests
 -------------------------
 
 When messages come in with a content-type character set different than that of
-the list's preferred language, recipients wil get an internationalized digest.
+the list's preferred language, recipients wil get an internationalized
+digest.  French is not enabled by default site-wide, so enable that now.
 
+XXX We also have to set the default server language to French, otherwise the
+English template will be found and the masthead won't be translated.
+
+    >>> config.languages.enable_language('fr')
+    >>> config.DEFAULT_SERVER_LANGUAGE = 'fr'
     >>> mlist.preferred_language = 'fr'
+    >>> flush()
     >>> msg = message_from_string("""\
     ... From: aperson@example.org
     ... To: _xtest@example.com
@@ -537,3 +544,9 @@ Set the digest threshold to zero so that the digests will be sent immediately.
      ('listname', '_xtest@example.com'),
      ('received_time', ...),
      ('recips', set([])), ('version', 3)]
+
+
+Clean up
+--------
+
+    >>> config.DEFAULT_SERVER_LANGUAGE = 'en'
diff --git a/Mailman/docs/languages.txt b/Mailman/docs/languages.txt
new file mode 100644
index 000000000..2c1664da3
--- /dev/null
+++ b/Mailman/docs/languages.txt
@@ -0,0 +1,94 @@
+Languages
+=========
+
+Mailman is multilingual.  A language manager handles the known set of
+languages at run time, as well as enabling those languages for use in a
+running Mailman instance.
+
+    >>> from zope.interface.verify import verifyObject
+    >>> from Mailman.interfaces import ILanguageManager
+    >>> from Mailman.languages import LanguageManager
+    >>> mgr = LanguageManager()
+    >>> verifyObject(ILanguageManager, mgr)
+    True
+
+A language manager keeps track of the languages it knows about as well as the
+languages which are enabled.  By default, none are known or enabled.
+
+    >>> sorted(mgr.known_codes)
+    []
+    >>> sorted(mgr.enabled_codes)
+    []
+    
+The language manager also keeps track of information for each known language,
+but you obviously can't get information for an unknown language.
+
+    >>> mgr.get_language_data('en')
+    Traceback (most recent call last):
+    ...
+    KeyError: 'en'
+
+
+Adding languages
+----------------
+
+Adding a new language requires three pieces of information, the 2-character
+language code, the English description of the language, and the character set
+used by the language.
+
+    >>> mgr.add_language('en', 'English', 'us-ascii')
+    >>> mgr.add_language('it', 'Italian', 'iso-8859-1')
+
+By default, added languages are also enabled.
+
+    >>> sorted(mgr.known_codes)
+    ['en', 'it']
+    >>> sorted(mgr.enabled_codes)
+    ['en', 'it']
+
+And you can get information for all known languages.
+
+    >>> mgr.get_language_data('en')
+    ('English', 'us-ascii')
+    >>> mgr.get_language_data('it')
+    ('Italian', 'iso-8859-1')
+
+You can also add a language without enabling it.
+
+    >>> mgr.add_language('pl', 'Polish', 'iso-8859-2', enable=False)
+    >>> sorted(mgr.known_codes)
+    ['en', 'it', 'pl']
+    >>> sorted(mgr.enabled_codes)
+    ['en', 'it']
+
+You can get language data for disabled languages.
+
+    >>> mgr.get_language_data('pl')
+    ('Polish', 'iso-8859-2')
+
+And of course you can enable a known language.
+
+    >>> mgr.enable_language('pl')
+    >>> sorted(mgr.enabled_codes)
+    ['en', 'it', 'pl']
+
+But you cannot enable languages that the manager does not know about.
+
+    >>> mgr.enable_language('xx')
+    Traceback (most recent call last):
+    ...
+    KeyError: 'xx'
+
+
+Other iterations
+----------------
+
+You can iterate over the descriptions (names) of all enabled languages.
+
+    >>> sorted(mgr.enabled_names)
+    ['English', 'Italian', 'Polish']
+
+You can ask whether a particular language code is enabled.
+
+    >>> 'it' in mgr.enabled_codes
+    True