Extbase and Translations: The Full Picture

Earlier this year, TYPO3 Association members voted to fund an overhaul of the Extbase documentation. We rebuilt it from the ground up and delivered the promised scope in August. But documentation is never finished — and the next chapters should come from the questions developers actually keep asking.

In the third round of community budget ideas for 2026, the Documentation Team put forward a proposal naming three frequently requested topics: translations and language overlays across different storage configurations, reliable backend modules, and Extbase output for AJAX applications and headless frontends. The aim is a complete, technically reviewed chapter for each. TYPO3 Association members voted to fund it, and the first chapter is now live.

The new Localization chapter explains how Extbase decides which records you get in which language — across every site configuration, not just the common one.

It starts where most projects start: with a fallbackType that someone probably set on your site years ago, and what each of its three values actually returns. From there it works towards the parts you control in code — the language aspect, the overlay types, and how to make a single query depart from the site's setting without changing the site.

The chapter is deliberate about two things:

• Relations follow different rules than the records that own them, so translation handling off only affects the roots of your object graph.
• Extbase now follows fallbackType instead of ignoring it, which means a strict site returns fewer records than it did before. If you are upgrading to TYPO3 v14.3, the Site Configuration section is the one to read first.

One topic grew large enough to earn a chapter of its own: reading records across site boundaries. It deals with the shared storage folder that several sites consume, each with its own language configuration.

The trap here is easy to miss. Pointing a query at another site's storage folder settles which pages are read, but not which language — and a language UID outside the site that assigned it is just a number without any meaning. The query succeeds, returns records, and shows them in the wrong language. The chapter covers matching languages by locale instead, and what to watch for when writing into a folder that other sites read.

Language handling assumes a frontend request that has resolved a site and a language. Backend modules, CLI commands, and middlewares have no such thing, so the chapter now states what each context provides and what you have to establish yourself.

The next topic we'll focus on documenting is how to build reliable backend modules with Extbase. The work we did earlier this year covered how to register a backend module, so the new chapter will explain how modules work at runtime.

Documentation gets better when it reflects real-world pain. If Extbase translations have ever surprised you — a list that came back shorter than expected, a relation that stayed stubbornly in the default language, a shared folder that showed the wrong locale — tell us. Open an issue or a pull request. It might become the section that saves the next developer a day.

This work is a community budget idea funded by the TYPO3 Association on behalf of its members. Thank you for voting for it.