Skip to content

Commit 3332b06

Browse files
linawolflinawolf
committed
[TASK] Update translate ViewHelper page
* Link to related topics * Demonstrate what the corresponding XLIFF files look like * use f:format.html or f:sanitize.html and not format.raw as best practice * Explain using placeholders and arguments * Demonstrate using a translation in an alt tag Releases: main, 13.4, 12.4
1 parent 49053c6 commit 3332b06

File tree

4 files changed

+214
-45
lines changed

4 files changed

+214
-45
lines changed

‎Documentation/Global/Translate.rst‎

Lines changed: 165 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -8,85 +8,205 @@ Translate ViewHelper `<f:translate>`
88
====================================
99

1010
.. typo3:viewhelper:: translate
11-
:source: ../Global.json
12-
:display: tags,description,gitHubLink,arguments
11+
:source: /Global.json
12+
:display: tags,description,gitHubLink
13+
:noindex:
14+
15+
.. seealso::
16+
* `Working with XLIFF files <https://docs.typo3.org/permalink/t3coreapi:xliff-api>`_
17+
* `Multi-language Fluid templates <https://docs.typo3.org/permalink/t3coreapi:extension-localization-fluid>`_
18+
19+
.. contents:: Table of contents
1320

1421
.. _typo3-fluid-translate-example:
1522

1623
Examples
1724
========
1825

19-
Translate key
20-
-------------
26+
.. _typo3-fluid-translate-example-key-only:
27+
28+
Short key - Usage in Extbase
29+
----------------------------
30+
31+
The :ref:`key <t3viewhelper:viewhelper-argument-typo3-cms-fluid-viewhelpers-translateviewhelper-key>`
32+
argument alone works only within the Extbase context.
33+
34+
.. tabs::
35+
36+
.. group-tab:: Fluid
37+
38+
.. code-block:: html
39+
40+
<f:translate key="domain_model.title" />
41+
42+
.. group-tab:: Language file example
43+
44+
.. literalinclude:: _Translate/_locallang.xlf
45+
:caption: packages/my_extension/Resources/Private/Language/locallang.xlf
46+
47+
Alternatively, you can use `id` instead of `key`, producing the same output.
48+
If both `id` and `key` are set, `id` takes precedence.
49+
50+
If the translate ViewHelper is used with only the language key, the template
51+
**must** be rendered within an Extbase request, usually from an Extbase
52+
controller action. The default language file must be located in the same
53+
extension as the Extbase controller and must be saved in the file
54+
:file:`Resources/Private/Language/locallang.xlf`.
55+
56+
.. _typo3-fluid-translate-example-key-extension:
57+
58+
Short key and extension name
59+
----------------------------
60+
61+
When the ViewHelper is called from outside Extbase, it is mandatory to either
62+
pass the extension name or use the full `LLL:` reference for the key.
63+
64+
.. code-block:: html
65+
66+
<f:translate key="domain_model.title" extension="my_extension" />
67+
68+
The default language file must be saved in the extension specified in the
69+
argument, in the file :file:`Resources/Private/Language/locallang.xlf`.
2170

22-
::
71+
.. _typo3-fluid-translate-example-key-full:
2372

24-
<f:translate key="key1" />
73+
Full `LLL:` reference key
74+
-------------------------
2575

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

29-
<f:translate id="key1" />
79+
.. code-block:: html
3080

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

33-
Keep HTML tags
34-
--------------
85+
.. _typo3-fluid-translate-example-html:
3586

36-
::
87+
Keeping HTML tags within translations
88+
-------------------------------------
3789

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

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

42-
Translate key from custom locallang file
43-
----------------------------------------
98+
.. group-tab:: Fluid
4499

45-
::
100+
.. code-block:: html
46101

47-
<f:translate key="key1" extensionName="MyExt"/>
102+
<f:format.html>
103+
<f:translate
104+
key="LLL:EXT:my_extension/Resources/Private/Language/my_locallang.xlf:myKey"
105+
/>
106+
</f:format.html>
48107

49-
or
108+
.. group-tab:: Language file example
50109

51-
::
110+
.. literalinclude:: _Translate/_locallang_xml.xlf
111+
:caption: packages/my_extension/Resources/Private/Language/locallang.xlf
52112

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

55-
Value of key ``key1`` in the current website language.
115+
.. warning::
116+
When allowing HTML tags in translations, ensure all translators are
117+
educated about `Cross-site scripting (XSS) <https://docs.typo3.org/permalink/t3coreapi:security-xss>`_.
118+
119+
.. _typo3-fluid-translate-example-placeholder:
120+
121+
Displaying translated labels with placeholders
122+
----------------------------------------------
123+
124+
.. tabs::
125+
126+
.. group-tab:: Fluid
127+
128+
.. code-block:: html
129+
130+
<f:translate
131+
key="LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:domain_model.title"
132+
arguments="{0: '{myVariable}'}"
133+
/>
134+
135+
Or with several numbered placeholders:
136+
137+
<f:translate
138+
key="LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:domain_model.title"
139+
arguments="{1: '{myVariable}', 2: 'Some String'}"
140+
/>
141+
142+
.. group-tab:: Language file example
143+
144+
.. literalinclude:: _Translate/_locallang_xml.xlf
145+
146+
The placeholder `%s` is used to insert dynamic values, passed as the parameter
147+
:ref:`arguments <t3viewhelper:viewhelper-argument-typo3-cms-fluid-viewhelpers-translateviewhelper-arguments>`
148+
to the translate ViewHelper. If `%s` appears multiple times, it references
149+
subsequent array entries in order.
150+
151+
To avoid dependency on order, use indexed placeholders like `%1$s`. This
152+
explicitly refers to the first value and ensures that it is treated as a string
153+
(`$s`). This method is based on PHP’s
154+
`vsprintf function <https://www.php.net/manual/en/function.vsprintf.php>`,
155+
which allows for more flexible and readable formatting.
156+
157+
.. _typo3-fluid-translate-example-inline:
56158

57159
Inline notation with arguments and default value
58160
------------------------------------------------
59161

60-
::
162+
Like all other ViewHelpers, the translate ViewHelper can be used with the
163+
`Inline syntax <https://docs.typo3.org/permalink/typo3fluid/fluid:viewhelper-inline-notation>`_.
164+
165+
.. code-block:: html
61166

62-
{f:translate(key: 'someKey', arguments: {0: 'dog', 1: 'fox'}, default: 'default value')}
167+
{f:translate(key: 'someKey', arguments: {0: 'dog', 1: 'fox'}, default: 'default value')}
63168

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

69-
<trans-unit id="someKey">
70-
<source>Some text about a %s and a %s.</source>
71-
</trans-unit>
172+
.. code-block:: html
72173

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

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

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

82-
Inline notation with extension name
83-
-----------------------------------
183+
The translation ViewHelper determines the target language based on the current
184+
frontend or backend request.
84185

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

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

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

92-
.. _sprintf: https://www.php.net/sprintf
199+
Salutation in English:
200+
<f:translate
201+
key="LLL:EXT:my_extension/Resources/Private/Language/my_locallang.xlf:salutation"
202+
languageKey="default"
203+
/>
204+
205+
.. _typo3-fluid-translate-arguments:
206+
207+
Arguments of the f:translate ViewHelper
208+
=======================================
209+
210+
.. typo3:viewhelper:: translate
211+
:source: /Global.json
212+
:display: arguments-only

‎Documentation/Global/_Translate/_locallang.xlf‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
3+
<file source-language="en" datatype="plaintext"
4+
original="EXT:my_extension/Resources/Private/Language/locallang.xlf"
5+
date="2020-10-18T18:20:51Z" product-name="my_extension"
6+
>
7+
<header />
8+
<body>
9+
<trans-unit id="domain_model.title">
10+
<source>My Model</source>
11+
</trans-unit>
12+
</body>
13+
</file>
14+
</xliff>

‎Documentation/Global/_Translate/_locallang_arguments.xlf‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
3+
<file source-language="en" datatype="plaintext"
4+
original="EXT:my_extension/Resources/Private/Language/locallang.xlf"
5+
date="2020-10-18T18:20:51Z" product-name="my_extension"
6+
>
7+
<header />
8+
<body>
9+
<label index="domain_model.title">Title of: %s</label>
10+
<trans-unit id="domain_model.description">
11+
<source>Some text about a %1$s and a %2$s.</source>
12+
</trans-unit>
13+
</body>
14+
</file>
15+
</xliff>

‎Documentation/Global/_Translate/_locallang_html.xlf‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
3+
<file source-language="en" datatype="plaintext"
4+
original="EXT:my_extension/Resources/Private/Language/locallang.xlf"
5+
date="2020-10-18T18:20:51Z" product-name="my_extension"
6+
>
7+
<header />
8+
<body>
9+
<trans-unit id="myKey">
10+
<source>
11+
<![CDATA[By default, ordered and unordered lists are formatted
12+
with bullets and decimals. <br>
13+
By adding <code>class="list-unstyled"</code> to the ol or ul tag, it
14+
is possible to structure content in list form without the
15+
typical list styling.]]>
16+
</source>
17+
</trans-unit>
18+
</body>
19+
</file>
20+
</xliff>

0 commit comments

Comments
 (0)