Skip to content

[TASK] Update translate ViewHelper page #114

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
linawolf merged 2 commits into from
Mar 19, 2025
Merged

[TASK] Update translate ViewHelper page #114

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c1baf7b
[TASK] Update translate ViewHelper page
linawolf Mar 19, 2025
58efcd2
Update Documentation/Global/_Translate/_locallang_html.xlf
sfroemkenjw Mar 19, 2025
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
213 changes: 168 additions & 45 deletions Documentation/Global/Translate.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,85 +8,208 @@ Translate ViewHelper `<f:translate>`
====================================

.. typo3:viewhelper:: translate
:source: ../Global.json
:display: tags,description,gitHubLink,arguments
:source: /Global.json
:display: tags,description,gitHubLink
:noindex:

.. seealso::
* `Working with XLIFF files <https://docs.typo3.org/permalink/t3coreapi:xliff-api>`_
* `Multi-language Fluid templates <https://docs.typo3.org/permalink/t3coreapi:extension-localization-fluid>`_

.. contents:: Table of contents

.. _typo3-fluid-translate-example:

Examples
========

Translate key
-------------
.. _typo3-fluid-translate-example-key-only:

Short key - Usage in Extbase
----------------------------

The :ref:`key <t3viewhelper:viewhelper-argument-typo3-cms-fluid-viewhelpers-translateviewhelper-key>`
argument alone works only within the Extbase context.

.. tabs::

.. group-tab:: Fluid

.. code-block:: html

<f:translate key="domain_model.title" />

.. group-tab:: Language file example

.. literalinclude:: _Translate/_locallang.xlf
:language: xml
:caption: packages/my_extension/Resources/Private/Language/locallang.xlf

Alternatively, you can use `id` instead of `key`, producing the same output.
If both `id` and `key` are set, `id` takes precedence.

If the translate ViewHelper is used with only the language key, the template
**must** be rendered within an Extbase request, usually from an Extbase
controller action. The default language file must be located in the same
extension as the Extbase controller and must be saved in the file
:file:`Resources/Private/Language/locallang.xlf`.

.. _typo3-fluid-translate-example-key-extension:

Short key and extension name
----------------------------

When the ViewHelper is called from outside Extbase, it is mandatory to either
pass the extension name or use the full `LLL:` reference for the key.

.. code-block:: html

<f:translate key="domain_model.title" extension="my_extension" />

The default language file must be saved in the extension specified in the
argument, in the file :file:`Resources/Private/Language/locallang.xlf`.

::
.. _typo3-fluid-translate-example-key-full:

<f:translate key="key1" />
Full `LLL:` reference key
-------------------------

Value of key ``key1`` in the current website language. Alternatively id can
be used instead of key::
Using the `LLL:` language reference syntax, a language key from any `.xlf`
file can be used.

<f:translate id="key1" />
.. code-block:: html

This will output the same as above. If both id and key are set, id will take precedence.
<f:translate
key="LLL:EXT:my_extension/Resources/Private/Language/my_locallang.xlf:domain_model.title"
/>

Keep HTML tags
--------------
.. _typo3-fluid-translate-example-html:

::
Keeping HTML tags within translations
-------------------------------------

<f:format.raw><f:translate key="htmlKey" /></f:format.raw>
HTML in language labels can be used when you surround the translate ViewHelper
with a ViewHelper that allows HTML output, such as the
`Sanitize.html ViewHelper <f:sanitize.html> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-sanitize-html>`_
in the backend or the `Format.html ViewHelper <f:format.html> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-format-html>`_
in the frontend.

Value of key ``htmlKey`` in the current website language, no :php:`htmlspecialchars()` applied.
.. tabs::

Translate key from custom locallang file
----------------------------------------
.. group-tab:: Fluid

::
.. code-block:: html

<f:translate key="key1" extensionName="MyExt"/>
<f:format.html>
<f:translate
key="LLL:EXT:my_extension/Resources/Private/Language/my_locallang.xlf:myKey"
/>
</f:format.html>

or
.. group-tab:: Language file example

::
.. literalinclude:: _Translate/_locallang_html.xlf
:language: xml
:caption: packages/my_extension/Resources/Private/Language/locallang.xlf

<f:translate key="LLL:EXT:myext/Resources/Private/Language/locallang.xlf:key1" />
The entry in the `.xlf` language file must be surrounded by `<![CDATA[...]]>`.

Value of key ``key1`` in the current website language.
.. warning::
When allowing HTML tags in translations, ensure all translators are
educated about `Cross-site scripting (XSS) <https://docs.typo3.org/permalink/t3coreapi:security-xss>`_.

.. _typo3-fluid-translate-example-placeholder:

Displaying translated labels with placeholders
----------------------------------------------

.. tabs::

.. group-tab:: Fluid

.. code-block:: html

<f:translate
key="LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:domain_model.title"
arguments="{0: '{myVariable}'}"
/>

Or with several numbered placeholders:

<f:translate
key="LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:domain_model.title"
arguments="{1: '{myVariable}', 2: 'Some String'}"
/>

.. group-tab:: Language file example

.. literalinclude:: _Translate/_locallang_arguments.xlf
:language: xml

The placeholder `%s` is used to insert dynamic values, passed as the parameter
:ref:`arguments <t3viewhelper:viewhelper-argument-typo3-cms-fluid-viewhelpers-translateviewhelper-arguments>`
to the translate ViewHelper. If `%s` appears multiple times, it references
subsequent array entries in order.

To avoid dependency on order, use indexed placeholders like `%1$s`. This
explicitly refers to the first value and ensures that it is treated as a string
(`$s`). This method is based on PHP’s
`vsprintf function <https://www.php.net/manual/en/function.vsprintf.php>`,
which allows for more flexible and readable formatting.

.. _typo3-fluid-translate-example-inline:

Inline notation with arguments and default value
------------------------------------------------

::
Like all other ViewHelpers, the translate ViewHelper can be used with the
`Inline syntax <https://docs.typo3.org/permalink/fluid:viewhelper-inline-notation>`_.

.. code-block:: html

{f:translate(key: 'someKey', arguments: {0: 'dog', 1: 'fox'}, default: 'default value')}
{f:translate(key: 'someKey', arguments: {0: 'dog', 1: 'fox'}, default: 'default value')}

Value of key ``someKey`` in the current website language
with the given arguments (``dog`` and ``fox``) assigned for the specified
``%s`` conversions, using `PHP sprintf() notation <https://www.php.net/sprintf>`__ in the
language file::
This is especially useful if you want to pass the translated label to another
ViewHelper, for example, as the `alt` parameter of an image:

<trans-unit id="someKey">
<source>Some text about a %s and a %s.</source>
</trans-unit>
.. code-block:: html

The output will be :html:`Some text about a dog and a fox`.
<f:image src="EXT:my_extension/Resources/Public/icons/Edit.svg"
alt="{f:translate(key: 'icons.edit', default: 'Edit')}"
/>

If the key ``someKey`` is not found in the language file, the output is :html:`default value`.
.. _typo3-fluid-translate-example-console:

As in PHP's :php:`sprintf()` you can order placeholders (:php:`Second %2$s, first %1$s`)
or use specific types like :php:`A padded number: %'.09d`, returning ``000000123`` for a number
passed as ``123``.
See the `sprintf`_ PHP Documentation for more information on possible formatting.
The translation ViewHelper in console/CLI context
-------------------------------------------------

Inline notation with extension name
-----------------------------------
The translation ViewHelper determines the target language based on the current
frontend or backend request.

::
If you are rendering your template from a console/CLI context, for example,
when you `Send emails with FluidEmail <https://docs.typo3.org/permalink/t3coreapi:mail-fluid-email>`_,
use the argument :ref:`languageKey <t3viewhelper:viewhelper-argument-typo3-cms-fluid-viewhelpers-translateviewhelper-languagekey>`
to specify the desired language for the ViewHelper:

{f:translate(key: 'someKey', extensionName: 'SomeExtensionName')}
.. code-block:: html

Value of key ``someKey`` in the current website language.
The locallang file of extension "some_extension_name" will be used.
Salutation in Danish:
<f:translate
key="LLL:EXT:my_extension/Resources/Private/Language/my_locallang.xlf:salutation"
languageKey="da"
/>

.. _sprintf: https://www.php.net/sprintf
Salutation in English:
<f:translate
key="LLL:EXT:my_extension/Resources/Private/Language/my_locallang.xlf:salutation"
languageKey="default"
/>

.. _typo3-fluid-translate-arguments:

Arguments of the f:translate ViewHelper
=======================================

.. typo3:viewhelper:: translate
:source: /Global.json
:display: arguments-only
14 changes: 14 additions & 0 deletions Documentation/Global/_Translate/_locallang.xlf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
<?xml version="1.0" encoding="UTF-8" ?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
<file source-language="en" datatype="plaintext"
original="EXT:my_extension/Resources/Private/Language/locallang.xlf"
date="2020-10-18T18:20:51Z" product-name="my_extension"
>
<header />
<body>
<trans-unit id="domain_model.title">
<source>My Model</source>
</trans-unit>
</body>
</file>
</xliff>
15 changes: 15 additions & 0 deletions Documentation/Global/_Translate/_locallang_arguments.xlf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
<?xml version="1.0" encoding="UTF-8" ?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
<file source-language="en" datatype="plaintext"
original="EXT:my_extension/Resources/Private/Language/locallang.xlf"
date="2020-10-18T18:20:51Z" product-name="my_extension"
>
<header />
<body>
<label index="domain_model.title">Title of: %s</label>
<trans-unit id="domain_model.description">
<source>Some text about a %1$s and a %2$s.</source>
</trans-unit>
</body>
</file>
</xliff>
20 changes: 20 additions & 0 deletions Documentation/Global/_Translate/_locallang_html.xlf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
<?xml version="1.0" encoding="UTF-8" ?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
<file source-language="en" datatype="plaintext"
original="EXT:my_extension/Resources/Private/Language/locallang.xlf"
date="2020-10-18T18:20:51Z" product-name="my_extension"
>
<header />
<body>
<trans-unit id="myKey">
<source>
<![CDATA[By default, ordered and unordered lists are formatted
with bullets and decimals. <br>
By adding <code>class="list-unstyled"</code> to the ol or ul tag, it
is possible to structure content in list form without the
typical list styling.]]>
</source>
</trans-unit>
</body>
</file>
</xliff>
Loading