diff --git a/Documentation/Global/Translate.rst b/Documentation/Global/Translate.rst index f74bc7b..7857c91 100644 --- a/Documentation/Global/Translate.rst +++ b/Documentation/Global/Translate.rst @@ -8,85 +8,208 @@ Translate ViewHelper `` ==================================== .. typo3:viewhelper:: translate - :source: ../Global.json - :display: tags,description,gitHubLink,arguments + :source: /Global.json + :display: tags,description,gitHubLink + :noindex: + +.. seealso:: + * `Working with XLIFF files `_ + * `Multi-language Fluid templates `_ + +.. 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 ` +argument alone works only within the Extbase context. + +.. tabs:: + + .. group-tab:: Fluid + + .. code-block:: html + + + + .. 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 + + + +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: - +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. - +.. code-block:: html -This will output the same as above. If both id and key are set, id will take precedence. + -Keep HTML tags --------------- +.. _typo3-fluid-translate-example-html: -:: +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 `_ +in the backend or the `Format.html ViewHelper `_ +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 - + + + -or + .. group-tab:: Language file example -:: + .. literalinclude:: _Translate/_locallang_html.xlf + :language: xml + :caption: packages/my_extension/Resources/Private/Language/locallang.xlf - +The entry in the `.xlf` language file must be surrounded by ``. -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) `_. + +.. _typo3-fluid-translate-example-placeholder: + +Displaying translated labels with placeholders +---------------------------------------------- + +.. tabs:: + + .. group-tab:: Fluid + + .. code-block:: html + + + + Or with several numbered placeholders: + + + + .. 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 ` +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. + +.. _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 `_. + +.. 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 `__ 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: - - Some text about a %s and a %s. - +.. code-block:: html -The output will be :html:`Some text about a dog and a fox`. + -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 `_, +use the argument :ref:`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: + -.. _sprintf: https://www.php.net/sprintf + Salutation in English: + + +.. _typo3-fluid-translate-arguments: + +Arguments of the f:translate ViewHelper +======================================= + +.. typo3:viewhelper:: translate + :source: /Global.json + :display: arguments-only diff --git a/Documentation/Global/_Translate/_locallang.xlf b/Documentation/Global/_Translate/_locallang.xlf new file mode 100644 index 0000000..306588f --- /dev/null +++ b/Documentation/Global/_Translate/_locallang.xlf @@ -0,0 +1,14 @@ + + + +
+ + + My Model + + + + diff --git a/Documentation/Global/_Translate/_locallang_arguments.xlf b/Documentation/Global/_Translate/_locallang_arguments.xlf new file mode 100644 index 0000000..ca7bcea --- /dev/null +++ b/Documentation/Global/_Translate/_locallang_arguments.xlf @@ -0,0 +1,15 @@ + + + +
+ + + + Some text about a %1$s and a %2$s. + + + + diff --git a/Documentation/Global/_Translate/_locallang_html.xlf b/Documentation/Global/_Translate/_locallang_html.xlf new file mode 100644 index 0000000..3e61d07 --- /dev/null +++ b/Documentation/Global/_Translate/_locallang_html.xlf @@ -0,0 +1,20 @@ + + + +
+ + + + + By adding class="list-unstyled" to the ol or ul tag, it + is possible to structure content in list form without the + typical list styling.]]> + + + + +