Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
dirnbauer avatar

Typo3 Translations

dirnbauer/webconsulting-skills

  • 13 installs
  • 33 repo stars
  • Updated July 27, 2026
  • dirnbauer/webconsulting-skills

Manage TYPO3 13/14 localization with XLIFF 1.2/2.0, ICU messages, LLL references, and v14 translation-domain migration.

About

This skill guides TYPO3 13/14 localization with XLIFF files, ICU MessageFormat, LLL references, and translation domains. A developer uses it when handling TYPO3 translations, labels, missing or duplicate keys, or v13-to-v14 translation migration.

  • Guides locallang.xlf, labels.xlf, XLIFF 1.2/2.0, ICU MessageFormat, and LLL references
  • Covers translation domains, Content Blocks labels, and v13-to-v14 migration checks

Typo3 Translations by the numbers

  • 13 all-time installs (skills.sh)
  • Ranked #1,103 of 1,879 Documentation skills by installs in the Skillselion catalog
  • Data as of Jul 29, 2026 (Skillselion catalog sync)
npx skills add https://github.com/dirnbauer/webconsulting-skills --skill typo3-translations

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs13
repo stars★ 33
Last updatedJuly 27, 2026
Repositorydirnbauer/webconsulting-skills ↗

What it does

Manage TYPO3 13/14 localization with XLIFF 1.2/2.0, ICU messages, LLL references, and v14 translation-domain migration.

Files

SKILL.mdMarkdownGitHub ↗

TYPO3 13/14 Translations

Source: https://github.com/dirnbauer/webconsulting-skills

Use this skill for TYPO3 13 and TYPO3 14 translation files, XLIFF format decisions, localization keys, ICU strings, LLL: references, and v14 translation-domain adoption. Start from the TYPO3 13-compatible baseline, then apply TYPO3 14 upgrades when the extension or project is v14-only.

Core Rules

  • For TYPO3 13+14 compatibility, keep XLIFF 1.2 and full LLL:EXT:

references.

  • For TYPO3 14-only work, prefer XLIFF 2.0 and consider translation domains in

PHP where they improve readability.

  • Keep one source language file in English, unprefixed, for example

Resources/Private/Language/locallang.xlf or labels.xlf.

  • Store target languages beside the source with locale prefixes, for example

de.locallang.xlf, de_CH.locallang.xlf, or de.labels.xlf.

  • Do not create en.locallang.xlf; English is the unprefixed source.
  • Keep exactly one <file> element per XLIFF file.
  • Keep one target language per target file.
  • Mark approved translations with approved="yes" in XLIFF 1.2 or

state="reviewed" / state="final" in XLIFF 2.0.

  • Treat ICU MessageFormat as TYPO3 14.2+ only; do not use ICU for code that

must run unchanged on TYPO3 13.

  • Use TYPO3 localization APIs and Fluid ViewHelpers; do not add custom label

loaders.

Default Workflow

1. Inventory source files in Resources/Private/Language/*.xlf and ContentBlocks/**/language/*.xlf. 2. Inventory consumers in PHP, TCA, YAML, Fluid, TypoScript, TSconfig, and Content Blocks configuration. 3. Decide the compatibility mode:

  • TYPO3 13+14: stay on XLIFF 1.2 and LLL:EXT:.
  • TYPO3 14-only: migrate selected catalogs to XLIFF 2.0 and optionally use

domains/ICU. 4. Normalize paths, filenames, XML namespaces, and key namespaces. 5. Add or migrate labels with natural target-language copy. 6. Validate XML, duplicate IDs, source/target parity, and LLL: resolution. 7. Flush TYPO3 caches and smoke-test backend and frontend language contexts.

TYPO3 13-Compatible Baseline

Use this baseline when an extension must support TYPO3 13 and 14.

<?xml version="1.0" encoding="UTF-8"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
  <file source-language="en" datatype="plaintext" original="EXT:my_extension/Resources/Private/Language/locallang.xlf" product-name="my_extension">
    <header/>
    <body>
      <trans-unit id="button.save">
        <source>Save</source>
      </trans-unit>
      <trans-unit id="items.count">
        <source>Items: %d</source>
      </trans-unit>
    </body>
  </file>
</xliff>

Target file:

<?xml version="1.0" encoding="UTF-8"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
  <file source-language="en" target-language="de" datatype="plaintext" original="EXT:my_extension/Resources/Private/Language/locallang.xlf" product-name="my_extension">
    <header/>
    <body>
      <trans-unit id="button.save" approved="yes">
        <source>Save</source>
        <target>Speichern</target>
      </trans-unit>
      <trans-unit id="items.count" approved="yes">
        <source>Items: %d</source>
        <target>Eintraege: %d</target>
      </trans-unit>
    </body>
  </file>
</xliff>

TYPO3 13 notes:

  • Use source-language="en" and target-language="<locale>".
  • Use <trans-unit> inside <body>.
  • Use approved="yes" for reviewed translations when approval state matters.
  • Use %s / %d style placeholders and runtime formatting, not ICU.
  • Use full LLL:EXT: references; translation domains are a TYPO3 14 feature.

TYPO3 14 Changes

Use these changes when the project is TYPO3 14-only, or when preparing a v14 branch while keeping the v13 branch on the baseline above.

XLIFF 2.0

Use this source shape for v14-only catalogs:

<?xml version="1.0" encoding="UTF-8"?>
<xliff version="2.0" xmlns="urn:oasis:names:tc:xliff:document:2.0" srcLang="en">
  <file id="messages">
    <unit id="button.save">
      <segment>
        <source>Save</source>
      </segment>
    </unit>
    <unit id="items.count">
      <segment>
        <source>{count, plural, one {# item} other {# items}}</source>
      </segment>
    </unit>
  </file>
</xliff>

Use this target shape:

<?xml version="1.0" encoding="UTF-8"?>
<xliff version="2.0" xmlns="urn:oasis:names:tc:xliff:document:2.0" srcLang="en" trgLang="de">
  <file id="messages">
    <unit id="button.save">
      <segment state="final">
        <source>Save</source>
        <target>Speichern</target>
      </segment>
    </unit>
    <unit id="items.count">
      <segment state="final">
        <source>{count, plural, one {# item} other {# items}}</source>
        <target>{count, plural, one {# Eintrag} other {# Eintraege}}</target>
      </segment>
    </unit>
  </file>
</xliff>

Migrating XLIFF 1.2 To 2.0

Use this checklist only after the affected label family no longer needs TYPO3 13 compatibility:

1. Confirm composer.json and ext_emconf.php no longer support TYPO3 13. 2. Create a branch and convert one label family first. 3. Change <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2"> to <xliff version="2.0" xmlns="urn:oasis:names:tc:xliff:document:2.0" srcLang="en">. 4. Remove the XLIFF 1.2 <header> and <body> wrapper. 5. Convert each <trans-unit id="key"> to <unit id="key"><segment>.... 6. Move <source> and <target> inside <segment>. 7. Convert source-language/target-language attributes to srcLang/trgLang. 8. Convert approved="yes" to state="reviewed" or state="final". 9. Split files that contain more than one <file> or more than one target language. 10. Preserve unit IDs exactly; change references only when deliberately renaming keys. 11. Validate XML and compare unit IDs between source and every target file. 12. Flush TYPO3 caches and verify labels in all affected backend/frontend views.

Do not migrate to a newer XLIFF dialect just because tooling can emit it. For a TYPO3 14-only branch, use the documented XLIFF 2.0 shape unless the project has verified support for another 2.x variant.

ICU MessageFormat

TYPO3 14.2+ supports ICU MessageFormat when translation calls pass named arguments. Store ICU strings as normal XLIFF source and target text.

For TYPO3 13+14 compatibility, avoid ICU and keep classic placeholders. Add ICU only in v14-only code paths or v14-only label files.

Rules:

  • Use named placeholders such as {count} and {name}.
  • Do not translate placeholder names.
  • Include other in every plural and select expression.
  • Test plural messages with 0, 1, and multiple values.
  • Use LanguageService::translate(), LocalizationUtility::translate(), or

Fluid <f:translate arguments="{...}">; sL() resolves plain labels only.

PHP:

$label = $languageService->translate(
    'items.count',
    'my_extension.messages',
    ['count' => 5],
);

Fluid:

<f:translate key="items.count" arguments="{count: itemCount}" />

Paths, Namespaces, And Domains

Use stable file paths and key namespaces so references remain readable during v13-to-v14 upgrades.

File Paths

  • Shared extension labels:

EXT:my_extension/Resources/Private/Language/messages.xlf

  • Traditional extension labels:

EXT:my_extension/Resources/Private/Language/locallang.xlf

  • Database/TCA labels:

EXT:my_extension/Resources/Private/Language/locallang_db.xlf

  • Content Blocks labels:

ContentBlocks/<Type>/<name>/language/labels.xlf

Use full LLL:EXT: references where configuration is loaded outside an Extbase context:

'label' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang_db.xlf:tx_my_table.title',

XML Namespace

Use the XLIFF 2.0 namespace exactly:

xmlns="urn:oasis:names:tc:xliff:document:2.0"

XLIFF IDs Versus TYPO3 14 Domains

Keep the XLIFF unit ID independent from the file/domain reference:

  • XLIFF unit ID: top, button.save, field.ctaText.label.
  • TYPO3 14 domain: my_extension.messages, my_extension.label,

my_extension.backend.dashboard.

  • Combined v14 reference: my_extension.label:top.

Do not write my_extension.label.top when you mean a TYPO3 14 domain reference. Without the colon, it is just a dotted label ID in the current Extbase/default context.

TYPO3 14 derives domains from language file paths:

FileDomain
Resources/Private/Language/locallang.xlfmy_extension.messages
Resources/Private/Language/messages.xlfmy_extension.messages
Resources/Private/Language/label.xlfmy_extension.label
Resources/Private/Language/locallang_label.xlfmy_extension.label
Resources/Private/Language/Backend/locallang_dashboard.xlfmy_extension.backend.dashboard
Configuration/Sets/Blog/labels.xlfmy_extension.sets.blog

If two files map to the same domain, such as label.xlf and locallang_label.xlf, the simplified filename wins. Avoid these conflicts.

TYPO3 14 Fluid And API Syntax

Use domains for v14-only Fluid templates:

<f:translate domain="my_extension.label" key="top" />
<f:translate key="my_extension.label:top" />
{f:translate(domain: 'my_extension.messages', key: 'button.save')}

Use the same combined syntax in PHP:

$languageService->sL('my_extension.label:top');
$languageService->sL('my_extension.messages:button.save');

For TYPO3 13 compatibility, keep:

<f:translate key="top" extensionName="MyExtension" />
<f:translate key="LLL:EXT:my_extension/Resources/Private/Language/label.xlf:top" />

The v14 domain argument takes precedence over extensionName. Inspect domains with php bin/typo3 language:domain:list when EXT:lowlevel is available.

TYPO3 API First

Use LanguageServiceFactory when a language service must be created explicitly.

use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Core\Localization\LanguageServiceFactory;

final readonly class LabelService
{
    public function __construct(
        private LanguageServiceFactory $languageServiceFactory,
    ) {}

    public function saveLabel(ServerRequestInterface $request): string
    {
        $languageService = $this->languageServiceFactory->createFromSiteLanguage(
            $request->getAttribute('language'),
        );

        return $languageService->sL(
            'LLL:EXT:my_extension/Resources/Private/Language/messages.xlf:button.save',
        );
    }
}

For backend-only code, $GLOBALS['LANG'] can be used when the backend bootstrap has initialized it. Keep access wrapped in a helper so the dependency is obvious.

Content Blocks Labels

Content Blocks labels commonly live beside the block in ContentBlocks/<Type>/<name>/language/labels.xlf. The source file is labels.xlf; translated files use locale prefixes such as de.labels.xlf.

1. Put editor-facing title and description in the block language file. 2. Use field IDs such as <field>.label and <field>.description. 3. Generate or inspect expected keys before editing:

   vendor/bin/typo3 content-blocks:language:generate vendor/block --print
   vendor/bin/typo3 content-blocks:language:generate vendor/block --extension=my_extension

4. Remember that labels.xlf overrides inline labels from config.yaml. 5. Convert generated v14-only catalogs to XLIFF 2.0 after the key list is known.

Detailed Reference

Read the full guide when the task needs detailed examples, long templates, troubleshooting matrices, appendices, or sections not included above. Keep this file unloaded for narrow tasks so the skill follows progressive disclosure.

Related skills

open.feishu.cnLark MarkdownInstantly turn any markdown file into clean, formatted Lark/Figma-compatible documents without manual reformatting.488klarksuiteLark DocCreate, read, update, summarize, rewrite and manage Feishu/Lark cloud documents directly from agent workflows.401k16.1klarksuiteLark WikiCreate, organize, query, and manage documents, spaces, and members inside Lark (Feishu) knowledge bases directly from AI agent workflows.397k16.1kmattpocockDomain ModelingBuild and sharpen a project's domain model: pin down domain terminology in a glossary and record architectural decisions as ADRs.318k202kxixu-meOpensource Guide CoachGet expert, attribution-safe guidance on launching and sustaining an open-source project.270k71xixu-meReadme I18nMaintain consistent, updatable language selector blocks across every README variant in a multilingual repository.270k71
Documentationdocsbackend
Browse by category
AI & AgentsFrontend & DesignBackend & DataDev ToolsAutomationTesting & ReviewSecurityMonitoring & CloudDocs & Planning
Design & frontend
Design systemsAnimation & motionAccessibility (a11y)CSS & TailwindUI designUXDesign to codeshadcn/uiLanding pagesBest design skills
Most searched skills
find-skillscavemanfrontend-designbrainstormingsystematic-debuggingstop-slopemil-design-engui-ux-pro-maxkarpathy-guidelinesweb-design-guidelinesreact-best-practicesgrill-meimprovemicrosoft-foundryagent-browser
Browse all listings
All agent skillsAll MCP serversAll marketplacesAll plugins

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.