Fixed #30585 -- Added {% translate %} and {% blocktranslate %} template tags.

6 files changed, 93 insertions, 78 deletions

diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index 75d8245499..669fc185a4 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -2695,14 +2695,14 @@ Therefore here is our new ``change_form.html`` :
     {% load i18n admin_urls %}
     {% block object-tools-items %}
         <li>
-            <a href="{% url opts|admin_urlname:'history' original.pk|admin_urlquote %}" class="historylink">{% trans "History" %}</a>
+            <a href="{% url opts|admin_urlname:'history' original.pk|admin_urlquote %}" class="historylink">{% translate "History" %}</a>
         </li>
         <li>
             <a href="mylink/" class="historylink">My Link</a>
         </li>
         {% if has_absolute_url %}
             <li>
-                <a href="{% url 'admin:view_on_site' content_type_id original.pk %}" class="viewsitelink">{% trans "View on site" %}</a>
+                <a href="{% url 'admin:view_on_site' content_type_id original.pk %}" class="viewsitelink">{% translate "View on site" %}</a>
             </li>
         {% endif %}
     {% endblock %}
diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index 2e55b66d04..4d65dc82f7 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -814,10 +814,10 @@ This would display as "It is the 4th of September".
 
 You can also use the syntax ``{% now "Y" as current_year %}`` to store the
 output (as a string) inside a variable. This is useful if you want to use
-``{% now %}`` inside a template tag like :ttag:`blocktrans` for example::
+``{% now %}`` inside a template tag like :ttag:`blocktranslate` for example::
 
     {% now "Y" as current_year %}
-    {% blocktrans %}Copyright {{ current_year }}{% endblocktrans %}
+    {% blocktranslate %}Copyright {{ current_year }}{% endblocktranslate %}
 
 .. templatetag:: regroup
 
@@ -1200,10 +1200,10 @@ image in the above example will be 88 pixels wide
 (because 175/200 = .875; .875 * 100 = 87.5 which is rounded up to 88).
 
 In some cases you might want to capture the result of ``widthratio`` in a
-variable. It can be useful, for instance, in a :ttag:`blocktrans` like this::
+variable. It can be useful, for instance, in a :ttag:`blocktranslate` like this::
 
     {% widthratio this_value max_value max_width as width %}
-    {% blocktrans %}The width is: {{ width }}{% endblocktrans %}
+    {% blocktranslate %}The width is: {{ width }}{% endblocktranslate %}
 
 .. templatetag:: with
 
@@ -2023,7 +2023,7 @@ Example::
 
     You have {{ num_cherries }} cherr{{ num_cherries|pluralize:"y,ies" }}.
 
-.. note:: Use :ttag:`blocktrans` to pluralize translated strings.
+.. note:: Use :ttag:`blocktranslate` to pluralize translated strings.
 
 .. templatefilter:: pprint
 
diff --git a/docs/ref/templates/language.txt b/docs/ref/templates/language.txt
index 62f866bbc0..d5221ad60b 100644
--- a/docs/ref/templates/language.txt
+++ b/docs/ref/templates/language.txt
@@ -414,7 +414,7 @@ Here are some tips for working with inheritance:
   tag ``as`` syntax can't be used inside the block. For example, this template
   doesn't render anything::
 
-      {% trans "Title" as title %}
+      {% translate "Title" as title %}
       {% block content %}{{ title }}{% endblock %}
 
 * For extra readability, you can optionally give a *name* to your
diff --git a/docs/releases/3.1.txt b/docs/releases/3.1.txt
index 136f2900b8..8a4d9f5326 100644
--- a/docs/releases/3.1.txt
+++ b/docs/releases/3.1.txt
@@ -260,7 +260,10 @@ Signals
 Templates
 ~~~~~~~~~
 
-* ...
+* The renamed :ttag:`translate` and :ttag:`blocktranslate` template tags are
+  introduced for internationalization in template code. The older :ttag:`trans`
+  and :ttag:`blocktrans` template tags aliases continue to work, and will be
+  retained for the foreseeable future.
 
 Tests
 ~~~~~
diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt
index a038183d0d..29ea8fb001 100644
--- a/docs/topics/cache.txt
+++ b/docs/topics/cache.txt
@@ -682,7 +682,7 @@ templates to achieve the same result:
     {% get_current_language as LANGUAGE_CODE %}
 
     {% cache 600 welcome LANGUAGE_CODE %}
-        {% trans "Welcome to example.com" %}
+        {% translate "Welcome to example.com" %}
     {% endcache %}
 
 The cache timeout can be a template variable, as long as the template variable
diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt
index 7a8be1eb4a..241dcea660 100644
--- a/docs/topics/i18n/translation.txt
+++ b/docs/topics/i18n/translation.txt
@@ -328,8 +328,8 @@ will appear in the ``.po`` file as:
     msgid "May"
     msgstr ""
 
-Contextual markers are also supported by the :ttag:`trans` and
-:ttag:`blocktrans` template tags.
+Contextual markers are also supported by the :ttag:`translate` and
+:ttag:`blocktranslate` template tags.
 
 .. _lazy-translations:
 
@@ -575,21 +575,22 @@ have already loaded the ``i18n`` tag.
     unchanged.
 
 .. templatetag:: trans
+.. templatetag:: translate
 
-``trans`` template tag
-----------------------
+``translate`` template tag
+--------------------------
 
-The ``{% trans %}`` template tag translates either a constant string
+The ``{% translate %}`` template tag translates either a constant string
 (enclosed in single or double quotes) or variable content::
 
-    <title>{% trans "This is the title." %}</title>
-    <title>{% trans myvar %}</title>
+    <title>{% translate "This is the title." %}</title>
+    <title>{% translate myvar %}</title>
 
 If the ``noop`` option is present, variable lookup still takes place but the
 translation is skipped. This is useful when "stubbing out" content that will
 require translation in the future::
 
-    <title>{% trans "myvar" noop %}</title>
+    <title>{% translate "myvar" noop %}</title>
 
 Internally, inline translations use an
 :func:`~django.utils.translation.gettext` call.
@@ -598,15 +599,14 @@ In case a template var (``myvar`` above) is passed to the tag, the tag will
 first resolve such variable to a string at run-time and then look up that
 string in the message catalogs.
 
-It's not possible to mix a template variable inside a string within ``{% trans
-%}``. If your translations require strings with variables (placeholders), use
-:ttag:`{% blocktrans %}<blocktrans>` instead.
-
+It's not possible to mix a template variable inside a string within
+``{% translate %}``. If your translations require strings with variables
+(placeholders), use :ttag:`{% blocktranslate %}<blocktranslate>` instead.
 
 If you'd like to retrieve a translated string without displaying it, you can
 use the following syntax::
 
-    {% trans "This is the title" as the_title %}
+    {% translate "This is the title" as the_title %}
 
     <title>{{ the_title }}</title>
     <meta name="description" content="{{ the_title }}">
@@ -615,12 +615,12 @@ In practice you'll use this to get a string you can use in multiple places in a
 template or so you can use the output as an argument for other template tags or
 filters::
 
-    {% trans "starting point" as start %}
-    {% trans "end point" as end %}
-    {% trans "La Grande Boucle" as race %}
+    {% translate "starting point" as start %}
+    {% translate "end point" as end %}
+    {% translate "La Grande Boucle" as race %}
 
     <h1>
-      <a href="/" title="{% blocktrans %}Back to '{{ race }}' homepage{% endblocktrans %}">{{ race }}</a>
+      <a href="/" title="{% blocktranslate %}Back to '{{ race }}' homepage{% endblocktranslate %}">{{ race }}</a>
     </h1>
     <p>
     {% for stage in tour_stages %}
@@ -628,50 +628,56 @@ filters::
     {% endfor %}
     </p>
 
-``{% trans %}`` also supports :ref:`contextual markers<contextual-markers>`
+``{% translate %}`` also supports :ref:`contextual markers<contextual-markers>`
 using the ``context`` keyword:
 
 .. code-block:: html+django
 
-    {% trans "May" context "month name" %}
+    {% translate "May" context "month name" %}
+
+.. versionchanged:: 3.1
+
+   The ``trans`` tag was renamed to ``translate``.  The ``trans``
+   tag is still supported as an alias for backwards compatibility.
 
 .. templatetag:: blocktrans
+.. templatetag:: blocktranslate
 
-``blocktrans`` template tag
----------------------------
+``blocktranslate`` template tag
+-------------------------------
 
-Contrarily to the :ttag:`trans` tag, the ``blocktrans`` tag allows you to mark
-complex sentences consisting of literals and variable content for translation
-by making use of placeholders::
+Contrarily to the :ttag:`translate` tag, the ``blocktranslate`` tag allows you
+to mark complex sentences consisting of literals and variable content for
+translation by making use of placeholders::
 
-    {% blocktrans %}This string will have {{ value }} inside.{% endblocktrans %}
+    {% blocktranslate %}This string will have {{ value }} inside.{% endblocktranslate %}
 
 To translate a template expression -- say, accessing object attributes or
 using template filters -- you need to bind the expression to a local variable
 for use within the translation block. Examples::
 
-    {% blocktrans with amount=article.price %}
+    {% blocktranslate with amount=article.price %}
     That will cost $ {{ amount }}.
-    {% endblocktrans %}
+    {% endblocktranslate %}
 
-    {% blocktrans with myvar=value|filter %}
+    {% blocktranslate with myvar=value|filter %}
     This will have {{ myvar }} inside.
-    {% endblocktrans %}
+    {% endblocktranslate %}
 
-You can use multiple expressions inside a single ``blocktrans`` tag::
+You can use multiple expressions inside a single ``blocktranslate`` tag::
 
-    {% blocktrans with book_t=book|title author_t=author|title %}
+    {% blocktranslate with book_t=book|title author_t=author|title %}
     This is {{ book_t }} by {{ author_t }}
-    {% endblocktrans %}
+    {% endblocktranslate %}
 
 .. note:: The previous more verbose format is still supported:
-   ``{% blocktrans with book|title as book_t and author|title as author_t %}``
+   ``{% blocktranslate with book|title as book_t and author|title as author_t %}``
 
 Other block tags (for example ``{% for %}`` or ``{% if %}``) are not allowed
-inside a ``blocktrans`` tag.
+inside a ``blocktranslate`` tag.
 
-If resolving one of the block arguments fails, ``blocktrans`` will fall back to
-the default language by deactivating the currently active language
+If resolving one of the block arguments fails, ``blocktranslate`` will fall
+back to the default language by deactivating the currently active language
 temporarily with the :func:`~django.utils.translation.deactivate_all`
 function.
 
@@ -681,43 +687,43 @@ This tag also provides for pluralization. To use it:
   be the one used to select the right plural form.
 
 * Specify both the singular and plural forms separating them with the
-  ``{% plural %}`` tag within the ``{% blocktrans %}`` and
-  ``{% endblocktrans %}`` tags.
+  ``{% plural %}`` tag within the ``{% blocktranslate %}`` and
+  ``{% endblocktranslate %}`` tags.
 
 An example::
 
-    {% blocktrans count counter=list|length %}
+    {% blocktranslate count counter=list|length %}
     There is only one {{ name }} object.
     {% plural %}
     There are {{ counter }} {{ name }} objects.
-    {% endblocktrans %}
+    {% endblocktranslate %}
 
 A more complex example::
 
-    {% blocktrans with amount=article.price count years=i.length %}
+    {% blocktranslate with amount=article.price count years=i.length %}
     That will cost $ {{ amount }} per year.
     {% plural %}
     That will cost $ {{ amount }} per {{ years }} years.
-    {% endblocktrans %}
+    {% endblocktranslate %}
 
 When you use both the pluralization feature and bind values to local variables
-in addition to the counter value, keep in mind that the ``blocktrans``
+in addition to the counter value, keep in mind that the ``blocktranslate``
 construct is internally converted to an ``ngettext`` call. This means the
 same :ref:`notes regarding ngettext variables <pluralization-var-notes>`
 apply.
 
-Reverse URL lookups cannot be carried out within the ``blocktrans`` and should
-be retrieved (and stored) beforehand::
+Reverse URL lookups cannot be carried out within the ``blocktranslate`` and
+should be retrieved (and stored) beforehand::
 
     {% url 'path.to.view' arg arg2 as the_url %}
-    {% blocktrans %}
+    {% blocktranslate %}
     This is a URL: {{ the_url }}
-    {% endblocktrans %}
+    {% endblocktranslate %}
 
 If you'd like to retrieve a translated string without displaying it, you can
 use the following syntax::
 
-    {% blocktrans asvar the_title %}The title is {{ title }}.{% endblocktrans %}
+    {% blocktranslate asvar the_title %}The title is {{ title }}.{% endblocktranslate %}
     <title>{{ the_title }}</title>
     <meta name="description" content="{{ the_title }}">
 
@@ -725,32 +731,38 @@ In practice you'll use this to get a string you can use in multiple places in a
 template or so you can use the output as an argument for other template tags or
 filters.
 
-``{% blocktrans %}`` also supports :ref:`contextual
+``{% blocktranslate %}`` also supports :ref:`contextual
 markers<contextual-markers>` using the ``context`` keyword:
 
 .. code-block:: html+django
 
-    {% blocktrans with name=user.username context "greeting" %}Hi {{ name }}{% endblocktrans %}
+    {% blocktranslate with name=user.username context "greeting" %}Hi {{ name }}{% endblocktranslate %}
 
-Another feature ``{% blocktrans %}`` supports is the ``trimmed`` option. This
-option will remove newline characters from the beginning and the end of the
-content of the ``{% blocktrans %}`` tag, replace any whitespace at the beginning
-and end of a line and merge all lines into one using a space character to
-separate them. This is quite useful for indenting the content of a ``{%
-blocktrans %}`` tag without having the indentation characters end up in the
-corresponding entry in the PO file, which makes the translation process easier.
+Another feature ``{% blocktranslate %}`` supports is the ``trimmed`` option.
+This option will remove newline characters from the beginning and the end of
+the content of the ``{% blocktranslate %}`` tag, replace any whitespace at the
+beginning and end of a line and merge all lines into one using a space
+character to separate them. This is quite useful for indenting the content of a
+``{% blocktranslate %}`` tag without having the indentation characters end up
+in the corresponding entry in the PO file, which makes the translation process
+easier.
 
-For instance, the following ``{% blocktrans %}`` tag::
+For instance, the following ``{% blocktranslate %}`` tag::
 
-    {% blocktrans trimmed %}
+    {% blocktranslate trimmed %}
       First sentence.
       Second paragraph.
-    {% endblocktrans %}
+    {% endblocktranslate %}
 
 will result in the entry ``"First sentence. Second paragraph."`` in the PO file,
 compared to ``"\n  First sentence.\n  Second sentence.\n"``, if the ``trimmed``
 option had not been specified.
 
+.. versionchanged:: 3.1
+
+   The ``blocktrans`` tag was renamed to ``blocktranslate``. The ``blocktrans``
+   tag is still supported as an alias for backwards compatibility.
+
 String literals passed to tags and filters
 ------------------------------------------
 
@@ -782,21 +794,21 @@ tag:
 .. code-block:: html+django
 
     {% comment %}Translators: View verb{% endcomment %}
-    {% trans "View" %}
+    {% translate "View" %}
 
     {% comment %}Translators: Short intro blurb{% endcomment %}
-    <p>{% blocktrans %}A multiline translatable
-    literal.{% endblocktrans %}</p>
+    <p>{% blocktranslate %}A multiline translatable
+    literal.{% endblocktranslate %}</p>
 
 or with the ``{#`` ... ``#}`` :ref:`one-line comment constructs <template-comments>`:
 
 .. code-block:: html+django
 
     {# Translators: Label of a button that triggers search #}
-    <button type="submit">{% trans "Go" %}</button>
+    <button type="submit">{% translate "Go" %}</button>
 
     {# Translators: This is a text of the base template #}
-    {% blocktrans %}Ambiguous translatable block of text{% endblocktrans %}
+    {% blocktranslate %}Ambiguous translatable block of text{% endblocktranslate %}
 
 .. note:: Just for completeness, these are the corresponding fragments of the
     resulting ``.po`` file:
@@ -841,12 +853,12 @@ If you want to select a language within a template, you can use the
 
     {% get_current_language as LANGUAGE_CODE %}
     <!-- Current language: {{ LANGUAGE_CODE }} -->
-    <p>{% trans "Welcome to our page" %}</p>
+    <p>{% translate "Welcome to our page" %}</p>
 
     {% language 'en' %}
         {% get_current_language as LANGUAGE_CODE %}
         <!-- Current language: {{ LANGUAGE_CODE }} -->
-        <p>{% trans "Welcome to our page" %}</p>
+        <p>{% translate "Welcome to our page" %}</p>
     {% endlanguage %}
 
 While the first occurrence of "Welcome to our page" uses the current language,
@@ -1450,7 +1462,7 @@ template tag. It enables the given language in the enclosed template section:
 
     {% get_available_languages as languages %}
 
-    {% trans "View this category in:" %}
+    {% translate "View this category in:" %}
     {% for lang_code, lang_name in languages %}
         {% language lang_code %}
         <a href="{% url 'category' slug=category.slug %}">{{ lang_name }}</a>