--- title: "Label references / LLL strings" manual: "TYPO3 Explained" version: "main" permalink: "https://docs.typo3.org/permalink/t3coreapi:label-reference@main" source: "ApiOverview/Localization/Labels/Index.rst" rendered: "2026-09-20T10:22:54+00:00" --- # Label references / LLL strings {#label-reference} Translation domain mapping has been introduced as an additional, shorter syntax for label references. It complements the existing file-based LLL: notation. TYPO3 supports two equivalent formats for referencing translatable labels: - the **legacy file-based syntax** starting with `LLL:`, and - the **new translation domain-based syntax** introduced in TYPO3 v14. Both formats resolve to the same translation entries and can be used interchangeably. Examples: **EXT:my_extension/Classes/MyClass.php (excerpt)** ```php // Legacy file-based syntax $myLabel = $this->getTranslator()->label('LLL:EXT:my_extension/Resources/Private/Language/locallang_forms.xlf:submit'); // New domain-based syntax (TYPO3 v14+) $myLabel = $this->getTranslator()->label('my_extension.forms:submit'); ``` Label references are used throughout TYPO3 — in PHP, TypoScript, Fluid templates, and configuration files — to access localized strings that are translated into the current language at runtime. If a different language is set or a language file is [overridden](https://docs.typo3.org/permalink/t3coreapi:xliff-translating-custom@main), the path is automatically adjusted. **Table of contents** - [Translation domain mapping for label reference](https://docs.typo3.org/permalink/t3coreapi:translation-domain-mapping-for-label-reference@main) - [Legacy file-based lLabel references](https://docs.typo3.org/permalink/t3coreapi:legacy-file-based-llabel-references@main) - [Resolving localized labels](https://docs.typo3.org/permalink/t3coreapi:resolving-localized-labels@main) - [Replacing deprecated language labels](https://docs.typo3.org/permalink/t3coreapi:replacing-deprecated-language-labels@main) ## Translation domain mapping for label reference {#label-reference-domain} Translation domains are an additional syntax for referencing language labels in TYPO3. They provide a domain-based notation that complements the existing file-based `LLL:` syntax. The domain syntax has the form: - **package** refers to the extension key (for example, `backend` for `EXT:backend`). - **subdomain** is optional and can be used to group related labels. - **resource** usually corresponds to a translation file, such as `messages`. The domain notation removes explicit file paths and extensions, improving readability while remaining fully compatible with existing `LLL:EXT:` references. Example: **EXT:my_extension/Resources/Private/Templates/SomeTemplate.fluid.html** ```html // Domain-based reference // Equivalent file-based reference ``` The legacy file-based syntax will continue to be supported and is not deprecated. Both formats can be used interchangeably. ### Translation domain format {#translation-domain-format} The domain format defines two parts: the *package part* (extension key) and the *resource part*, separated by a dot. The resource part leaves out previous historical names, especially `locallang.xlf` and the `locallang_` prefix. The resource identifier appears before the colon in the resource part (below `comment`). **Example usage of "package.resource:identifier"** ```php $translator->label('my_extension.comment:domain_model.title'); ``` ### Translation domain resolution {#translation-domain-resolution} Translation domains are resolved deterministically and mapped to existing language files within an extension. This section describes how the mapping and name generation work internally. The command `vendor/bin/typo3 language:domain:list` lists all available translation domains with their translations and label counts: **typo3_root$** ```bash # List domains in active extensions vendor/bin/typo3 language:domain:list # Filter by extension vendor/bin/typo3 language:domain:list --extension=backend # Also list the files configured via resourceOverrides for each domain vendor/bin/typo3 language:domain:list --show-overrides ``` #### Deterministic file-based translation domain mapping {#translation-domain-mapping} TYPO3 automatically resolves translation domains to language files inside each extension. This allows you to use short, domain-based references without worrying about exact file names or paths. Language files are discovered in the `Resources/Private/Language/` directory of each installed extension. The system builds a mapping between file names and domain identifiers, ensuring that each domain corresponds to an existing file. If multiple files can map to the same domain (for example, `locallang_db.xlf` and `db.xlf` in the same directory), the simplified name takes precedence, and the prefixed variant is ignored. All mappings are cached internally for performance. Compared to traditional file-based lookups, the domain mapping approach reduces file system operations. Extension label files are discovered once during initialization, and their mapping is reused from cache for subsequent lookups. ### Domain generation rules {#translation-domain-rules} Domain names are derived from file paths using the following transformation rules: 1. The base path `Resources/Private/Language/` is omitted. 1. Standard filename patterns: - `locallang.xlf` → `.messages` - `locallang_module.xlf` → `.module` - `locallang_wizard.xlf` → `.wizard` 1. Subdirectories are converted to dot notation: - `Backend/locallang_dashboard.xlf` → `.backend.dashboard` - `Frontend/locallang_forms.xlf` → `.frontend.forms` 1. Site Set labels receive the `.sets` prefix: - `Configuration/Sets/Blog/labels.xlf` → `.sets.blog` 1. Case conversion: - UpperCamelCase → snake_case (`UserProfile` → `user_profile`) - snake_case → preserved (`user_profile` → `user_profile`) 1. Locale prefixes do not affect the resource identifier used for resolving. They are evaluated later for locale-specific translations: - `de.locallang.xlf` → `messages` - `de-AT.wizard.xlf` → `wizard` **Examples** The following examples show how typical language file paths map to translation domains in custom extensions: - [`EXT:my_site/Resources/Private/Language/locallang.xlf`](../../../ExtensionArchitecture/FileStructure/Resources/Private/Language.md#file-extension-resources-private-language-locallang-xlf) → `my_site.messages` - `EXT:my_site/Resources/Private/Language/locallang_module.xlf` → `my_site.module` - `EXT:my_blog/Resources/Private/Language/Backend/locallang_dashboard.xlf` → `my_blog.backend.dashboard` - `EXT:my_blog/Resources/Private/Language/Frontend/locallang_forms.xlf` → `my_blog.frontend.forms` - `EXT:news_comments/Configuration/Sets/Blog/labels.xlf` → `news_comments.sets.blog` ## Legacy file-based `lLabel` references {#label-reference-legacy} The legacy label reference format uses the `LLL:` prefix and an explicit path to an XLIFF translation file within an extension. The general format is: ```text LLL:EXT:/: ``` Example: ```text LLL:EXT:my_extension/Resources/Private/Language/locallang_db.xlf:mytable.myfield ``` This syntax remains fully supported and can be mixed with translation domain-based references as needed. ### File paths in legacy label references {#label-reference-storage} Localized labels are stored in files with [XLIFF format](https://docs.typo3.org/permalink/t3coreapi:xliff@main). Most XLIFF files are located in `EXT:my_extension/Resources/Private/Language/` and its subfolders. In some cases the locations are different: - **Site sets** – Localization files for site set definitions are stored in the site set folder, for example: `EXT:my_extension/Configuration/Sets/MySet/labels.xlf` - **Content blocks** – Third-party extensions can define their own structure. For example, the extension [`friendsoftypo3/content-blocks`](https://packagist.org/packages/friendsoftypo3/content-blocks) stores labels alongside the content block definitions: `EXT:my_extension/Configuration/Sets/MySet/labels.xlf` ## Resolving localized labels {#label-reference-resolve} In many cases, such as the [label of a TCA field](https://docs.typo3.org/m/typo3/reference-tca/main/en-us/Columns/Index.html#confval-columns-label), you can use a label reference, and TYPO3 will resolve it. If label references are not resolved, you can do it manually: ### Fluid: using the f:translate ViewHelper {#label-reference-resolve-fluid} Use the [f:translate](https://docs.typo3.org/other/typo3/view-helper-reference/main/en-us/Global/Translate.html#typo3-fluid-translate) ViewHelper to insert translated strings in Fluid templates. **EXT:my_extension/Resources/Private/Templates/SomeTemplate.fluid.html** ```html {f:translate(key: 'my_extension.your_file.xlf:yourKey')} ``` See also: [The translation ViewHelper f:translate](https://docs.typo3.org/permalink/t3coreapi:f-translate@main) ### TypoScript: using the `getText` property {#label-reference-resolve-typoscript} The [getText property LLL](https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/Functions/Data.html#data-type-gettext-lll) can be used to fetch translations from a language file and render them in the current language. **EXT:site_package/Configuration/Sets/SitePackage/setup.typoscript** ```typoscript lib.blogListTitle = TEXT lib.blogListTitle { data = LLL : my_extension.your_file.xlf:yourKey } ``` Make sure to leave spaces around the colon following `LLL` (as required by general getText syntax). See also: [Output localized strings with TypoScript](https://docs.typo3.org/permalink/t3coreapi:extension-localization-typoscript-gettext@main) ### PHP: using a translator {#label-reference-resolve-php} In PHP localized labels can be retrieved via a `TranslatorInterface` instance, which can be created using the `LanguageServiceFactory`. The recommended way to determine the correct `TranslatorInterface` instance depends on the context: - **Frontend:** use the language in the current request object (`ServerRequestInterface`) or the default site language. - **Backend:** use the language of the logged-in backend user. - **CLI:** determine the language programmatically depending on your use case (for example, when sending emails via scheduler tasks). For more details, see [Localization in PHP](https://docs.typo3.org/permalink/t3coreapi:extension-localization-php@main). Once you have the correct translator instance, you can resolve labels as follows: **EXT:my_extension/Classes/MyClass.php (excerpt)** ```php use TYPO3\CMS\Core\Localization\TranslatorInterface; private function translateSomething( TranslatorInterface $translator, string $labelReference ): string { return $translator->label($labelReference); } ``` ## Replacing deprecated language labels {#label-reference-deprecated} With TYPO3 v14 a number of labels and localization files have been deprecated. The first time after deleting a cache, deprecated labels are written into the deprecation log, as explained below. (See [Enabling the deprecation log](https://docs.typo3.org/permalink/t3coreapi:deprecation-enable-errors@main)). The Extension Scanner does not detect deprecated localization labels. Developers must rely on runtime deprecation logs to identify these occurrences. Deprecated labels are marked with attribute `x-unused-since="14.0"` in the XLIFF 1.2 localization file and with `subState="deprecated"` in XLIFF 2.0. They will be removed in the next major TYPO3 version. It is possible to use these tags to deprecate labels in third party extensions as well. To ease migration for extension developers and projects, the command `vendor/bin/typo3 language:domain:search` can be used to search for specific label content ([`typo3/cms-lowlevel`](https://packagist.org/packages/typo3/cms-lowlevel) needs to be installed). For example, if you used the now deprecated label reference `LLL:EXT:core/Resources/Private/Language/locallang_general.xlf:LGL.starttime` Use the following command: **typo3_root$** ```bash vendor/bin/typo3 language:domain:search --search starttime core.db.general file EXT:core/Resources/Private/Language/db/general.xlf ======================================================================= +-----------------+--------------------+ | Label Reference | Label Content (en) | +-----------------+--------------------+ | starttime | Publish Date | +-----------------+--------------------+ ``` to search for label reference keys or content containing "starttime". If the label content fits your purpose you can switch your label reference to the new location: **Fluid Template (diff)** ```diff - + ``` **TCA definition (diff)** ```diff 'my_special_starttime' => [ - 'label' => 'LLL:EXT:core/Resources/Private/Language/locallang_general.xlf:LGL.starttime', + 'label' => 'core.db.general:starttime', 'config' => [ 'type' => 'datetime', 'default' => 0, ], ], ``` **PHP controller or service (diff)** ```diff - $languageService->sL('LLL:EXT:core/Resources/Private/Language/locallang_general.xlf:LGL.starttime') + $languageService->label('core.db.general:starttime') ``` If you cannot find a suitable label for your use case, consider moving the label to your own extension's XLIFF localization files.