TranslationDomainMapper

Read onlyYes

Maps between translation domains and label resource file paths.

Translation domains provide a shorter, semantic alternative to verbose file paths for referencing label resources (XLF files).

Domain Format: package[.subdomain[.subdomain...]].resource

Domain Generation Rules:

  • Extension language files: [package].[subdir].[filename]

  • Site Set files: [package].sets.[setName]

  • Subdirectories are represented as dot-separated parts

  • Special handling for locale-prefixed files

  • subdirectory "Resources/Private/Language" is omitted

  • subdirectory "Configuration/Sets/{set-name}/labels.xlf" is replaced with "sets.{set-name}"

UpperCamelCase is converted to snake_case.

"locallang.xlf" is mapped to "messages" "locallang_{mysuffix}.xlf" is replaced via "mysuffix" (keeping underscores)

Locale prefixes (e.g. "de.locallang.xlf") are ignored in the domain name.

Package Identifier Resolution:

  • Uses extension keys: "core", "backend"
  • Composer package names can be used as input and will be resolved to extension keys

Once a domain for a package is requested, the cache for this package is built.

Internal

not part of TYPO3's public API.

Table of Contents

Properties

$eventDispatcher  : EventDispatcherInterface
$labelCache  : FrontendInterface
$labelFileResolver  : LabelFileResolver
$packageManager  : PackageManager

Methods

__construct()  : mixed
findLabelResourcesInPackage()  : array<string|int, mixed>
Fetches all found label files, this way, we can use the domain to populate the label cache of a Package, as it also COULD include the package.
findLabelResourcesInPackageGroupedByLocale()  : array<string, array<string, string>>
Find label resources in a package grouped by locale.
isValidDomainName()  : bool
A valid domain consists of lowercase letters, numbers, underscores only and at least one dot in between.
mapDomainToFileName()  : string
Maps a translation domain to a label resource file reference.
mapFileNameToDomain()  : string
Maps a label resource file reference to a translation domain.
extractExtensionKey()  : string
Extracts the extension key from an EXT: file reference.
getFilePriority()  : int
Determine file priority for domain collision resolution.
getRelativePath()  : string
transformFilePathToResource()  : string
Transforms a file path to a resource name (for domain).
upperCamelCaseToSnakeCase()  : string
Converts UpperCamelCase to snake_case.

Properties

$eventDispatcher

protected EventDispatcherInterface $eventDispatcher

Methods

findLabelResourcesInPackage()

Fetches all found label files, this way, we can use the domain to populate the label cache of a Package, as it also COULD include the package.

public findLabelResourcesInPackage(string $packageKey) : array<string|int, mixed>

When multiple files map to the same domain (e.g., locallang.xlf and messages.xlf both map to ".messages"), files without the "locallang" prefix/suffix have precedence.

Precedence order:

  1. Files without "locallang" prefix (e.g., messages.xlf, tabs.xlf)
  2. Files with "locallang_" prefix (e.g., locallang_toolbar.xlf)
  3. Plain locallang.xlf
Parameters
$packageKey : string
Return values
array<string|int, mixed>

findLabelResourcesInPackageGroupedByLocale()

Find label resources in a package grouped by locale.

public findLabelResourcesInPackageGroupedByLocale(string $packageKey) : array<string, array<string, string>>

Returns an array where keys are locale codes and values are arrays of domain => resource mappings. Applies the same precedence rules as findLabelResourcesInPackage().

Parameters
$packageKey : string
Return values
array<string, array<string, string>> —

Array grouped by locale, then domain => resource

isValidDomainName()

A valid domain consists of lowercase letters, numbers, underscores only and at least one dot in between.

public isValidDomainName(string $domain) : bool
Parameters
$domain : string
Return values
bool

mapDomainToFileName()

Maps a translation domain to a label resource file reference.

public mapDomainToFileName(string $domain) : string

Examples:

  • "core.messages" -> "EXT:core/Resources/Private/Language/locallang.xlf"
  • "backend.toolbar" -> "EXT:backend/Resources/Private/Language/locallang_toolbar.xlf"
  • "core.form.tabs" -> "EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf"
  • "felogin.sets.felogin" -> "EXT:felogin/Configuration/Sets/Felogin/labels.xlf"

Invalid domain names return their values directly.

  1. More than one ":" included
  2. Domain Name contains other than [a-z0-9_.] characters
Parameters
$domain : string
Return values
string

mapFileNameToDomain()

Maps a label resource file reference to a translation domain.

public mapFileNameToDomain(string $fileName) : string

Examples:

  • "EXT:core/Resources/Private/Language/locallang.xlf" -> "core.messages"
  • "EXT:backend/Resources/Private/Language/locallang_toolbar.xlf" -> "backend.toolbar"
  • "EXT:felogin/Configuration/Sets/Felogin/labels.xlf" -> "felogin.sets.felogin"
Parameters
$fileName : string
Return values
string

extractExtensionKey()

Extracts the extension key from an EXT: file reference.

protected extractExtensionKey(string $filePath) : string
Parameters
$filePath : string
Return values
string

getFilePriority()

Determine file priority for domain collision resolution.

protected getFilePriority(string $filePath) : int

Higher priority wins when multiple files map to the same domain.

Priority levels:

  • 3: Files without "locallang" prefix (messages.xlf, tabs.xlf)
  • 2: Files with "locallang_" prefix (locallang_toolbar.xlf)
  • 1: Plain locallang.xlf

This ensures modern naming (messages.xlf) takes precedence over legacy (locallang.xlf).

Parameters
$filePath : string
Return values
int

getRelativePath()

protected getRelativePath(string $file, string $packageKey, PackageInterface $package) : string
Parameters
$file : string
$packageKey : string
$package : PackageInterface
Return values
string

transformFilePathToResource()

Transforms a file path to a resource name (for domain).

protected transformFilePathToResource(string $filePath, string $extensionKey) : string

Examples:

  • "Resources/Private/Language/locallang.xlf" -> "messages"
  • "Resources/Private/Language/locallang_toolbar.xlf" -> "toolbar"
  • "Resources/Private/Language/Form/locallang_tabs.xlf" -> "form.tabs"
  • "Configuration/Sets/Felogin/labels.xlf" -> "sets.felogin"
Parameters
$filePath : string
$extensionKey : string
Return values
string

upperCamelCaseToSnakeCase()

Converts UpperCamelCase to snake_case.

protected upperCamelCaseToSnakeCase(string $input) : string

Examples: "SudoMode" -> "sudo_mode", "Form" -> "form"

Parameters
$input : string
Return values
string 

        

        
    




    

    

                            

            

                            
    

        On this page

        
    


            

                    

        

    

        

            
Search results