[FEATURE] TranslateViewHelper supports new Translation Domain syntax (#182)

* [FEATURE] TranslateViewHelper supports new Translation Domain syntax

Resolves: TYPO3-Documentation/Changelog-To-Doc#1382
Releases: main

* [TASK] Language checks

Releases: main

---------

Co-authored-by: Sarah McCarthy <sarahmccarthy123@yahoo.com>

Author: linawolf

Documentation/Global/Translate.rst

@@ -15,21 +15,85 @@ Translate ViewHelper `<f:translate>`
 ..  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>`_
+    *   `Label references / Translation domains <https://docs.typo3.org/permalink/t3coreapi:label-reference>`_
+    *   `Feature: #107759 - TranslateViewHelper supports Translation Domain syntax <https://docs.typo3.org/permalink/changelog:feature-107759-1729433323>`_
 
 ..  contents:: Table of contents
 
+..  note::
+    ..  versionadded:: 14.0
+        The translate ViewHelper supports `translation domains <https://docs.typo3.org/permalink/t3coreapi:label-reference>`_,
+        a short and convenient way to reference language labels without
+        requiring `LLL:` paths or extension names.
+
+        Translation domain syntax is the **recommended** and **future-proof** way
+        to reference translations.
+
+        The older `LLL:` and `extension` arguments are still valid for
+        **backward compatibility**.
+
+        All existing syntax remains 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** 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:
+
+1.  **Provide the domain as a separate argument** and only reference the identifier
+    (recommended):
+
+    ..  code-block:: html
+
+        <f:translate domain="backend.toolbar" key="save" />
+        <f:translate domain="my_extension.messages" id="greeting.hello" />
+
+2.  **Use the combined domain + identifier syntax** in the `key`/`id` arguments:
+
+    ..  code-block:: html
 
-Examples
-========
+        <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:
+
+    ..  code-block:: bash
+
+        vendor/bin/typo3 language:domain:list
+
+    This will help you find your domains when migrating from `LLL:` paths
+    to the new translation domain syntax.
+
+..  _typo3-fluid-translate-example-backward:
+
+Backward compatible syntax
+==========================
+
+The following forms are still supported for older templates and extensions.
+New code should use domains instead.
 
 ..  _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.
+argument on its own works in the Extbase context.
 
 ..  tabs::
 
@@ -45,29 +109,34 @@ argument alone works only within the Extbase context.
             :language: xml
             :caption: packages/my_extension/Resources/Private/Language/locallang.xlf
 
-Alternatively, you can use `id` instead of `key`, producing the same output.
+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 within an Extbase request, usually from an Extbase
+**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 the file
+extension as the Extbase controller and must be saved in
 :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.
+If the ViewHelper is called from outside Extbase, the extension name or the
+full `LLL:` key reference must be passed as arguments.
 
 ..  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`.
+The default language file must be located in
+:file:`Resources/Private/Language/locallang.xlf` of the extension.
+
+..  versionchanged:: 14.0
+    The translation domain syntax is now the recommended way
+    to reference labels. The `extension` argument still works for
+    backward compatibility.
 
 ..  _typo3-fluid-translate-example-key-full:
 
@@ -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.
+    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.
 
             <f:format.html>
                 <f:translate
-                    key="LLL:EXT:my_extension/Resources/Private/Language/my_locallang.xlf:myKey"
+                    domain="my_extension.messages"
+                    key="content.withHtml"
                 />
             </f:format.html>
 
@@ -121,7 +194,7 @@ The entry in the `.xlf` language file must be surrounded by `<![CDATA[...]]>`.
 ..  _typo3-fluid-translate-example-placeholder:
 
 Displaying translated labels with placeholders
-----------------------------------------------
+==============================================
 
 ..  tabs::
 
@@ -130,14 +203,16 @@ Displaying translated labels with placeholders
         ..  code-block:: html
 
             <f:translate
-                key="LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:domain_model.title"
+                domain="my_extension.domainmodel"
+                key="title"
                 arguments="{0: '{myVariable}'}"
             />
 
             Or with several numbered placeholders:
 
             <f:translate
-                key="LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:domain_model.title"
+                domain="my_extension.domainmodel"
+                key="title"
                 arguments="{1: '{myVariable}', 2: 'Some String'}"
             />
 
@@ -154,34 +229,34 @@ 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>`,
+`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
+Like all the other ViewHelpers, the translate ViewHelper can be used with
 `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(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:
 
 ..  code-block:: html
 
     <f:image src="EXT:my_extension/Resources/Public/icons/Edit.svg"
-        alt="{f:translate(key: 'icons.edit', default: 'Edit')}"
+        alt="{f:translate(domain: 'my_extension.icons', key: 'edit', default: 'Edit')}"
     />
 
 ..  _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:
     <f:translate
-        key="LLL:EXT:my_extension/Resources/Private/Language/my_locallang.xlf:salutation"
+        domain="my_extension.messages"
+        key="salutation"
         languageKey="da"
     />
 
     Salutation in English:
     <f:translate
-        key="LLL:EXT:my_extension/Resources/Private/Language/my_locallang.xlf:salutation"
+        domain="my_extension.messages"
+        key="salutation"
         languageKey="default"
     />
 
+
 ..  _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