From a2ad274caafaa4d4bafa5f28e6a4768519c8d0b5 Mon Sep 17 00:00:00 2001
From: Nate Wiebe <nate@northern.co>
Date: Mon, 14 Sep 2020 18:16:20 -0400
Subject: [PATCH] Translatable objects

---
 reference/twig_reference.rst | 29 ++++++++++++++++++++++++++++-
 translation.rst              | 35 +++++++++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+), 1 deletion(-)

diff --git a/reference/twig_reference.rst b/reference/twig_reference.rst
index 0a6c9db3154..ed02f32d633 100644
--- a/reference/twig_reference.rst
+++ b/reference/twig_reference.rst
@@ -304,6 +304,27 @@ impersonation_exit_url
 It's similar to the `impersonation_exit_path`_ function, but it generates
 absolute URLs instead of relative URLs.
 
+t
+~
+
+.. code-block:: twig
+
+    {{ t(message, parameters = [], domain = 'messages')|trans }}
+
+``message``
+    **type**: ``string``
+``parameters`` *(optional)*
+    **type**: ``array`` **default**: ``[]``
+``domain`` *(optional)*
+    **type**: ``string`` **default**: ``messages``
+
+.. versionadded:: 5.2
+
+    The ``t()`` function was introduced in Symfony 5.2.
+
+Creates a ``Translatable`` object that can be passed to the
+:ref:`trans filter <reference-twig-filter-trans>`.
+
 Form Related Functions
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -341,6 +362,8 @@ Makes a technical name human readable (i.e. replaces underscores by spaces
 or transforms camelCase text like ``helloWorld`` to ``hello world``
 and then capitalizes the string).
 
+.. _reference-twig-filter-trans:
+
 trans
 ~~~~~
 
@@ -349,7 +372,7 @@ trans
     {{ message|trans(arguments = [], domain = null, locale = null) }}
 
 ``message``
-    **type**: ``string``
+    **type**: ``string`` | ``Translatable``
 ``arguments`` *(optional)*
     **type**: ``array`` **default**: ``[]``
 ``domain`` *(optional)*
@@ -357,6 +380,10 @@ trans
 ``locale`` *(optional)*
     **type**: ``string`` **default**: ``null``
 
+.. versionadded:: 5.2
+
+    ``message`` accepting ``Translatable`` as a valid type was introduced in Symfony 5.2.
+
 Translates the text into the current language. More information in
 :ref:`Translation Filters <translation-filters>`.
 
diff --git a/translation.rst b/translation.rst
index 19525ea38ce..2c7fc7922b6 100644
--- a/translation.rst
+++ b/translation.rst
@@ -292,6 +292,41 @@ To manage these situations, Symfony follows the `ICU MessageFormat`_ syntax by
 using PHP's :phpclass:`MessageFormatter` class. Read more about this in
 :doc:`/translation/message_format`.
 
+Translatable Objects
+--------------------
+
+.. versionadded:: 5.2
+
+    Translatable objects were introduced in Symfony 5.2.
+
+Sometimes you may want to create a message, but at the time of creation aren't
+sure how it would be translated. For example, it could be translated multiple
+times if intended to be displayed to multiple users.
+
+Using translatable objects also allows preparing translations without having a
+dependency on an entrypoint (such as a router) where the context for performing
+the translation is provided. For example, entities could prepare translatable
+strings (such as labels) without the need for a translator.
+
+Instead of translating a string at the time of creation, a ``Translatable``
+object can be created that can then be translated when used. Later this message
+can be translated with a translator in either PHP or in Twig.
+
+PHP::
+
+    $message = new Translatable('Symfony is great!');
+    $message = t('Symfony is great!');
+
+    Translatable::trans($translator, $message);
+
+Twig:
+
+.. code-block:: html+twig
+
+    {% set message = t('Symfony is great!') %}
+
+    <h1>{{ message|trans }}</h1>
+
 .. _translation-in-templates:
 
 Translations in Templates