minor #14240 Translatable objects (natewiebe13)

javiereguiluz · javiereguiluz · commit 88a61129d40e · 2020-09-25T12:20:00.000+02:00
This PR was squashed before being merged into the master branch. Discussion ---------- Translatable objects Goal: Add docs for translatable objects. Feature: symfony/symfony#37670 Fixes #14145 Unsure how in-depth the docs should go. Open to feedback and collaboration. Commits ------- a2ad274 Translatable objects
diff --git 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,14 +372,18 @@ trans
     {{ message|trans(arguments = [], domain = null, locale = null) }}
 
 ``message``
-    **type**: ``string``
+    **type**: ``string`` | ``Translatable``
 ``arguments`` *(optional)*
     **type**: ``array`` **default**: ``[]``
 ``domain`` *(optional)*
     **type**: ``string`` **default**: ``null``
 ``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
@@ -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
