1 files changed, 94 insertions, 0 deletions
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