`typo3_translation_domain_lookup`

Compute a translation domain

Compute the translation domain an XLF file resolves to, from its path. The domain is the canonical way to reference a label (backend.alt_doc:key) in TCA, LanguageService::sL() and f:translate, and nothing registers it. It follows from the path by the rules the core itself applies, in TranslationDomainMapper on one branch and TranslationDomainResolver on the next. Because the tool computes it, it also answers for a file outside the core and for one a patch is about to add. On a version older than translation domains it answers with the full LLL:EXT: reference instead. The domain form renders nothing there and fails at runtime rather than at build time. That version is targetVersion, or the installation this server started in where the call states none. State one when the work is on another branch than the installed one. It computes a reference from a path and reads no label: whether the installation already registers one to reuse, and under which id, is typo3_label_lookup. The answer also carries the specifier a backend JavaScript module imports that domain under, which is the same value in the form that module needs. Answers from: knowledge.

readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Answers from knowledge.

Takes#

yaml

# The XLF file path, either as an EXT: reference
# ("EXT:backend/Resources/Private/Language/locallang_alt_doc.xlf") or relative
# to a core checkout
# ("typo3/sysext/backend/Resources/Private/Language/locallang_alt_doc.xlf").
path: string
# The TYPO3 version the label is for, for example "13.4" or "14". It decides one
# thing here and it decides it entirely. Below the version that resolves domains
# the domain form renders nothing, so the answer is the LLL:EXT: reference
# instead. Defaults to the installation this server started in, which is the
# wrong answer for a backport branch or a second checkout; state it there.
targetVersion: string  # optional

Answers with#

yaml

# The XLF path the domain comes from.
path: string
# The TYPO3 major the answer is for, stated by the caller or read from the
# installation. Null means neither said, and the domain comes back unqualified:
# it is the form from 14 onwards, and nothing placed this call on a version.
targetVersion: integer or null  # optional
# The translation domain it resolves to. Null when the path names no extension,
# and also when the version the answer is for is too old to resolve domains at
# all. There the full LLL:EXT: reference is the answer.
domain: string or null
# Set only in that second case: what the domain would be on a version that has
# them. It is not usable on this installation.
domainOnNewerVersions: string or null  # optional
# The specifier a backend JavaScript module imports the same domain under:
# import labels from '~labels/<domain>', read with labels.get(). Returned where
# the answer carries a domain, and absent where it carries none. The import map
# prefix arrived with the domains themselves, so there is nothing to write on a
# version below them.
moduleImport: string or null  # optional

Answered#

Recorded on 2026-09-23 by bin/cli tools:record. Answered against core-checkout, TYPO3 14.3.8-dev, the 14.3 core checkout below .checkouts/. Its console is out of reach: <installation> has no TYPO3 console — none of bin/typo3, vendor/bin/typo3 exists. Its dependencies are not installed — vendor/autoload.php is not there either, and composer install writes both. Nothing checks what is below this heading; everything above it is derived from the class that answers the call, and bin/cli tools:check holds it.

domain: EXT reference#

Called with:

json

{
    "path": "EXT:backend/Resources/Private/Language/locallang_alt_doc.xlf"
}

Text:

text

EXT:backend/Resources/Private/Language/locallang_alt_doc.xlf resolves to the translation domain:

  backend.alt_doc

Reference a label in it as "backend.alt_doc:<trans-unit id>" — in TCA, in LanguageService::sL(), and in f:translate as separate domain and key attributes.
A backend JavaScript module writes the same value as an import: import labels from "~labels/backend.alt_doc", then labels.get("<trans-unit id>").
Composed for the installation here, TYPO3 14.3.8-dev. State targetVersion where the label is being written for another branch.
Which trans-units the file actually holds is a property of your checkout: read the file, and remember that an installation can override it through LANG/resourceOverrides.

Data:

json

{
    "path": "EXT:backend/Resources/Private/Language/locallang_alt_doc.xlf",
    "targetVersion": 14,
    "domain": "backend.alt_doc",
    "domainOnNewerVersions": null,
    "moduleImport": "~labels/backend.alt_doc"
}

domain: checkout path#

Called with:

json

{
    "path": "typo3/sysext/core/Resources/Private/Language/locallang.xlf"
}

Text:

text

typo3/sysext/core/Resources/Private/Language/locallang.xlf resolves to the translation domain:

  core.messages

Reference a label in it as "core.messages:<trans-unit id>" — in TCA, in LanguageService::sL(), and in f:translate as separate domain and key attributes.
A backend JavaScript module writes the same value as an import: import labels from "~labels/core.messages", then labels.get("<trans-unit id>").
Composed for the installation here, TYPO3 14.3.8-dev. State targetVersion where the label is being written for another branch.
Which trans-units the file actually holds is a property of your checkout: read the file, and remember that an installation can override it through LANG/resourceOverrides.

Data:

json

{
    "path": "typo3/sysext/core/Resources/Private/Language/locallang.xlf",
    "targetVersion": 14,
    "domain": "core.messages",
    "domainOnNewerVersions": null,
    "moduleImport": "~labels/core.messages"
}

domain: on an older target#

Called with:

json

{
    "path": "EXT:backend/Resources/Private/Language/locallang_alt_doc.xlf",
    "targetVersion": "13.4"
}

Text:

text

TYPO3 13, which you asked about, has no translation domains: the API that resolves them arrived after it. Reference the file itself instead:

  LLL:EXT:backend/Resources/Private/Language/locallang_alt_doc.xlf:<trans-unit id>

For the record, the domain this path would resolve to on a version that has them is "backend.alt_doc". Writing it into a label there renders nothing, and fails at runtime rather than at build time.

Data:

json

{
    "path": "EXT:backend/Resources/Private/Language/locallang_alt_doc.xlf",
    "targetVersion": 13,
    "domain": null,
    "domainOnNewerVersions": "backend.alt_doc"
}

domain: miss#

Called with:

json

{
    "path": "somewhere/else.xlf"
}

Text:

text

"somewhere/else.xlf" names no extension, so no translation domain follows from it.
Pass either an EXT: reference ("EXT:backend/Resources/Private/Language/locallang_alt_doc.xlf") or a checkout path ("typo3/sysext/backend/Resources/Private/Language/locallang_alt_doc.xlf").

Data:

json

{
    "path": "somewhere/else.xlf",
    "targetVersion": 14,
    "domain": null
}