fix the add_translation_dirs documentation to reflect the current impl

fixes #1473

1 files changed, 14 insertions, 10 deletions

diff --git a/pyramid/config/i18n.py b/pyramid/config/i18n.py
index 9538d766b..96fd30a51 100644
--- a/pyramid/config/i18n.py
+++ b/pyramid/config/i18n.py
@@ -57,15 +57,19 @@ class I18NConfiguratorMixin(object):
            config.add_translation_dirs('/usr/share/locale',
                                        'some.package:locale')
 
-        Later calls to ``add_translation_dir`` insert directories into the
-        beginning of the list of translation directories created by earlier
-        calls.  This means that the same translation found in a directory
-        added later in the configuration process will be found before one
-        added earlier in the configuration process.  However, if multiple
-        specs are provided in a single call to ``add_translation_dirs``, the
-        directories will be inserted into the beginning of the directory list
-        in the order they're provided in the ``*specs`` list argument (items
-        earlier in the list trump ones later in the list).
+        The translation directories are defined as a list in which
+        translations defined later have precedence over translations defined
+        earlier.
+
+        If multiple specs are provided in a single call to
+        ``add_translation_dirs``, the directories will be inserted in the
+        order they're provided (earlier items are trumped by later items).
+
+        .. warning::
+
+           Consecutive calls to ``add_translation_dirs`` will sort the
+           directories such that the later calls will add folders with
+           lower precedence than earlier calls.
 
         """
         introspectables = []
@@ -76,7 +80,7 @@ class I18NConfiguratorMixin(object):
 
             # defer spec resolution until register to allow for asset
             # overrides to take place in an earlier config phase
-            for spec in specs[::-1]: # reversed
+            for spec in specs[::-1]:  # reversed
                 # the trailing slash helps match asset overrides for folders
                 if not spec.endswith('/'):
                     spec += '/'