Translate ViewHelper `<f:translate>`

ViewHelper to provide a translation for language keys ("locallang"/"LLL"). By default, the files are loaded from the folder Resources/Private/Language/. Placeholder substitution (like PHP's sprintf()) can be evaluated when provided as arguments attribute.

Go to the source code of this ViewHelper: TranslateViewHelper.php (GitHub).

Using translation domains

The translation domain syntax is the recommended way to reference labels. It allows concise and clear label identifiers, without using LLL: paths and extension names.

There are two equivalent ways to use domains:

Provide the domain as a separate argument and only reference the identifier (recommended):

<f:translate domain="backend.toolbar" key="save" />
<f:translate domain="my_extension.messages" id="greeting.hello" />

Use the combined domain + identifier syntax in the key/id arguments:

<f:translate key="backend.toolbar:save" />
<f:translate id="my_extension.messages:greeting.hello" />

The domain syntax is the preferred syntax for all new templates.
If both domain and extension are set, the domain property takes precedence.
The older key="LLL:EXT:..." and extension arguments are still supported for backward compatibility.

Tip

Run the console command to list all translation domains and their language file mapping:

vendor/bin/typo3 language:domain:list

This will help you find your domains when migrating from LLL: paths to the new translation domain syntax.

Backward compatible syntax

The following forms are still supported for older templates and extensions. New code should use domains instead.

Short key - Usage in Extbase

The key argument on its own works in the Extbase context.

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

packages/my_extension/Resources/Private/Language/locallang.xlf

<?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>

Alternatively, you can use id instead of key to produce 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 in 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 Resources/Private/Language/locallang.xlf.

Short key and extension name

If the ViewHelper is called from outside Extbase, the extension name or the full LLL: key reference must be passed as arguments.

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

The default language file must be located in Resources/Private/Language/locallang.xlf of the extension.

Changed in version 14.0

The translation domain syntax is now the recommended way to reference labels. The extension argument still works for backward compatibility.

Full `LLL:` reference key

Using the LLL: language reference syntax, a language key from any .xlf file can be used.

<f:translate
    key="LLL:EXT:my_extension/Resources/Private/Language/my_locallang.xlf:domain_model.title"
/>

Note

This legacy form remains fully supported for backward compatibility. Domain syntax should be used for all new templates.

Keeping HTML tags within translations

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> in the backend or the Format.html ViewHelper <f:format.html> in the frontend.

<f:format.html>
    <f:translate
        domain="my_extension.messages"
        key="content.withHtml"
    />
</f:format.html>

packages/my_extension/Resources/Private/Language/locallang.xlf

<?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>

The entry in the .xlf language file must be surrounded by <![CDATA[...]]>.

Warning

When allowing HTML tags in translations, ensure all translators are educated about Cross-site scripting (XSS).

Displaying translated labels with placeholders

<f:translate
    domain="my_extension.domainmodel"
    key="title"
    arguments="{0: '{myVariable}'}"
/>

Or with several numbered placeholders:

<f:translate
    domain="my_extension.domainmodel"
    key="title"
    arguments="{1: '{myVariable}', 2: 'Some String'}"
/>

<?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>

The placeholder %s is used to insert dynamic values, passed as the parameter 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, which allows for more flexible and readable formatting.

Inline notation with arguments and default value

Like all the other ViewHelpers, the translate ViewHelper can be used with Inline syntax.

{f:translate(domain: 'my_extension.messages', key: 'animal.sentence', arguments: {0: 'dog', 1: 'fox'}, default: 'default value')}

This is especially useful if you want to pass the translated label to another ViewHelper, for example, as the alt parameter of an image:

<f:image src="EXT:my_extension/Resources/Public/icons/Edit.svg"
    alt="{f:translate(domain: 'my_extension.icons', key: 'edit', default: 'Edit')}"
/>

The translation ViewHelper in console/CLI context

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, use the argument languageKey to specify the desired language for the ViewHelper:

Salutation in Danish:
<f:translate
    domain="my_extension.messages"
    key="salutation"
    languageKey="da"
/>

Salutation in English:
<f:translate
    domain="my_extension.messages"
    key="salutation"
    languageKey="default"
/>

Arguments of the f:translate ViewHelper

New in version 14.0

The domain argument was added. It selects a translation domain and should be preferred over extension or extensionName. When both are given, domain takes precedence.

arguments

Type: array

Arguments to be replaced in the resulting string

default

Type: string

If the given locallang key could not be found, this value is used. If this argument is not set, child nodes will be used to render the default

domain

Type: string

Translation Domain to be used for the ID/Key. Takes precedence over "extensionName". Should also be used over "extensionName".

extensionName

Type: string

UpperCamelCased extension key (for example BlogExample)

id

Type: string

Translation ID. Same as key.

key

Type: string

Translation Key

languageKey

Type: string

Language key ("da" for example) or "default" to use. Also a Locale object is possible. If empty, use current locale from the request.

Translate ViewHelper <f:translate>

Using translation domains

Backward compatible syntax

Short key - Usage in Extbase

Short key and extension name

Full LLL: reference key

Keeping HTML tags within translations

Displaying translated labels with placeholders

Inline notation with arguments and default value

The translation ViewHelper in console/CLI context

Arguments of the f:translate ViewHelper

arguments

default

domain

extensionName

id

key

languageKey

Translate ViewHelper `<f:translate>`

Full `LLL:` reference key