From c1374524655ac9da42c6f45281f5e11b086f5973 Mon Sep 17 00:00:00 2001
From: Michael Merickel <michael@merickel.org>
Date: Tue, 17 Jan 2017 01:07:58 -0600
Subject: [PATCH] fix the add_translation_dirs documentation to reflect the
 current impl

fixes #1473
---
 pyramid/config/i18n.py | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/pyramid/config/i18n.py b/pyramid/config/i18n.py
index 9538d766bd..96fd30a519 100644
--- a/pyramid/config/i18n.py
+++ b/pyramid/config/i18n.py
@@ -57,15 +57,19 @@ def add_translation_dirs(self, *specs):
            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 @@ def register():
 
             # 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 += '/'