Fixed #27067 -- Deprecated string_concat() in favor of format_lazy().

4 files changed, 22 insertions, 9 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index e5151ebadc..7aa58e4ee7 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -25,6 +25,8 @@ details on these changes.
 
 * ``django.test.runner.setup_databases()`` will be removed.
 
+* ``django.utils.translation.string_concat()`` will be removed.
+
 .. _deprecation-removed-in-2.0:
 
 2.0
diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index 07fa53990e..893ecb5792 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -1107,6 +1107,12 @@ For a complete discussion on the usage of the following see the
 
 .. function:: string_concat(*strings)
 
+    .. deprecated:: 1.11
+
+        Use :meth:`django.utils.text.format_lazy` instead.
+        ``string_concat(*strings)`` can be replaced by
+        ``format_lazy('{}' * len(strings), *strings)``.
+
     Lazy variant of string concatenation, needed for translations that are
     constructed from multiple parts.
 
diff --git a/docs/releases/1.11.txt b/docs/releases/1.11.txt
index 7d9af8d132..498b3ee09f 100644
--- a/docs/releases/1.11.txt
+++ b/docs/releases/1.11.txt
@@ -477,3 +477,7 @@ Miscellaneous
 
 * ``django.test.runner.setup_databases()`` is moved to
   :func:`django.test.utils.setup_databases`. The old location is deprecated.
+
+* ``django.utils.translation.string_concat()`` is deprecated in
+  favor of :func:`django.utils.text.format_lazy`. ``string_concat(*strings)``
+  can be replaced by ``format_lazy('{}' * len(strings), *strings)``.
diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt
index 11b62ea4ac..c632c41920 100644
--- a/docs/topics/i18n/translation.txt
+++ b/docs/topics/i18n/translation.txt
@@ -489,21 +489,22 @@ directly with the ``number`` argument::
                 raise forms.ValidationError(self.error_message % number)
 
 
-Joining strings: ``string_concat()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Formatting strings: ``format_lazy()``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Standard Python string joins (``''.join([...])``) will not work on lists
-containing lazy translation objects. Instead, you can use
-:func:`django.utils.translation.string_concat()`, which creates a lazy object
-that concatenates its contents *and* converts them to strings only when the
-result is included in a string. For example::
+Python's :meth:`str.format()` method will not work when either the
+``format_string`` or any of the arguments to :meth:`str.format()`
+contains lazy translation objects. Instead, you can use
+:func:`django.utils.text.format_lazy()`, which creates a lazy object
+that runs the ``str.format()`` method only when the result is included
+in a string. For example::
 
-    from django.utils.translation import string_concat
+    from django.utils.text import format_lazy
     from django.utils.translation import ugettext_lazy
     ...
     name = ugettext_lazy('John Lennon')
     instrument = ugettext_lazy('guitar')
-    result = string_concat(name, ': ', instrument)
+    result = format_lazy('{name}: {instrument}', name=name, instrument=instrument)
 
 In this case, the lazy translations in ``result`` will only be converted to
 strings when ``result`` itself is used in a string (usually at template