Skip to content

Translatable objects #14240

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 25, 2020
Merged

Translatable objects #14240

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 28 additions & 1 deletion reference/twig_reference.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
~~~~~~~~~~~~~~~~~~~~~~

Expand Down Expand Up @@ -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
~~~~~

Expand All @@ -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>`.

Expand Down
35 changes: 35 additions & 0 deletions translation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down