Skip to content

[FEATURE] Configure default image conversion/preview formats #181

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
linawolf wants to merge 1 commit into from
Closed

[FEATURE] Configure default image conversion/preview formats #181

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 97 additions & 14 deletions Documentation/Global/Translate.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,77 @@ 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 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

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

2. **Use the combined domain + identifier syntax** directly in `key`/`id`:

.. code-block:: html

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

* 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:

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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>

Expand All @@ -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::

Expand All @@ -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'}"
/>

Expand All @@ -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
`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.
Expand All @@ -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