From 0329d06528be7dd75bca2436e4b8f38b3349babb Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Sun, 26 Oct 2025 11:19:20 +0100 Subject: [PATCH] [FEATURE] Configure default image conversion/preview formats Wait for https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-CoreApi/pull/6136 to be merged so the link can work. References: https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/1380 Releases: main --- Documentation/Global/Translate.rst | 111 +++++++++++++++++++++++++---- 1 file changed, 97 insertions(+), 14 deletions(-) diff --git a/Documentation/Global/Translate.rst b/Documentation/Global/Translate.rst index 7857c91..be7365b 100644 --- a/Documentation/Global/Translate.rst +++ b/Documentation/Global/Translate.rst @@ -15,13 +15,77 @@ Translate ViewHelper `` .. seealso:: * `Working with XLIFF files `_ * `Multi-language Fluid templates `_ + * `Label references / Translation domains `_ + * `Feature: #107759 - TranslateViewHelper supports Translation Domain syntax `_ .. contents:: Table of contents +.. note:: + .. versionadded:: 14.0 + The translate ViewHelper supports `translation domains `_, + a short and convenient way to reference language labels without + requiring `LLL:` paths or explicit extension names. + + The translation domain syntax is the **preferred** and **future-proof** way + to reference translations. + + The traditional `LLL:` and `extension` arguments remain available for + **backward compatibility**. + + All existing syntax forms remain fully supported, ensuring backward + compatibility. The new syntax can be adopted incrementally within a + project, and both old and new forms can coexist in the same template. + .. _typo3-fluid-translate-example: +.. _typo3-fluid-translate-example-domain: + +Using translation domains +========================= + +The translation domain syntax is the **recommended** and preferred way to +reference labels. It allows concise and clear label identifiers without +`LLL:` paths or extension names. + +There are two equivalent ways to use domains: + +1. **Provide the domain separately** and reference only the identifier + (recommended): + + .. code-block:: html + + + + +2. **Use the combined domain + identifier syntax** directly in `key`/`id`: + + .. code-block:: html -Examples -======== + + + +* The **domain** syntax is the preferred way for all new templates. +* If both `domain` and `extension` are set, property **domain takes precedence**. +* Traditional `key="LLL:EXT:..."` or `extension` arguments are still supported for + backward compatibility. + +.. tip:: + You can list all available translation domains and their corresponding + language file mappings by running the console command: + + .. code-block:: bash + + vendor/bin/typo3 language:domain:list + + This helps identify existing domains when migrating from `LLL:` paths + to the new translation domain syntax. + +.. _typo3-fluid-translate-example-backward: + +Backward compatible syntax +========================== + +The following forms remain supported for older templates and extensions. +New code should use translation domains instead. .. _typo3-fluid-translate-example-key-only: @@ -69,6 +133,11 @@ pass the extension name or use the full `LLL:` reference for the key. The default language file must be saved in the extension specified in the argument, in the file :file:`Resources/Private/Language/locallang.xlf`. +.. versionchanged:: 14.0 + The translation domain syntax replaces this form as the preferred way + to reference labels. The `extension` argument continues to work for + backward compatibility. + .. _typo3-fluid-translate-example-key-full: Full `LLL:` reference key @@ -83,10 +152,13 @@ file can be used. key="LLL:EXT:my_extension/Resources/Private/Language/my_locallang.xlf:domain_model.title" /> +.. note:: + This legacy form remains fully supported for backward compatibility. + The domain syntax should be used for all new templates. .. _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 @@ -102,7 +174,8 @@ in the frontend. @@ -121,7 +194,7 @@ The entry in the `.xlf` language file must be surrounded by ``. .. _typo3-fluid-translate-example-placeholder: Displaying translated labels with placeholders ----------------------------------------------- +============================================== .. tabs:: @@ -130,14 +203,16 @@ Displaying translated labels with placeholders .. code-block:: html Or with several numbered placeholders: @@ -154,20 +229,20 @@ 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 `, +`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(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: @@ -175,13 +250,13 @@ ViewHelper, for example, as the `alt` parameter of an image: .. code-block:: html .. _typo3-fluid-translate-example-console: The translation ViewHelper in console/CLI context -------------------------------------------------- +================================================= The translation ViewHelper determines the target language based on the current frontend or backend request. @@ -195,21 +270,29 @@ to specify the desired language for the ViewHelper: Salutation in Danish: Salutation in English: + .. _typo3-fluid-translate-arguments: Arguments of the f:translate ViewHelper ======================================= +.. versionadded:: 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. + .. typo3:viewhelper:: translate :source: /Global.json :display: arguments-only