--- title: "Understanding Overlays in TYPO3: Harnessing the Power of TYPO3 Core API" url: "https://b13.com/knowledge/mastering-localization-and-content-staging" description: "Explore the beauty and efficiency of TYPO3 overlays. Learn how the TYPO3 Core API automates localization and content staging, ensuring seamless content management through intelligent referencing. " image: "https://b13.com/fileadmin/_processed_/b/7/csm_OverlaysExplained_Sharing_039168d1de.png" date: 2025-03-10 modified: 2026-08-19 lastUpdated: 2026-08-19 --- # Understanding Overlays in TYPO3: Harnessing the Power of TYPO3 Core API [ Localization ](https://b13.com/knowledge/localization) [ Workspaces ](https://b13.com/knowledge/workspaces) [ TYPO3 ](https://b13.com/knowledge/typo3) The Elegant Efficiency of TYPO3 Overlays ========================================== Mastering Localization and Content Staging ![](https://b13.com/fileadmin/_processed_/c/6/csm_benni_5e519221c4.jpg)Benni Mack 09 May 2025 [ RSS Feed ](https://b13.com/rss.xml) This blog post explains the concept of the “overlays” mechanism in TYPO3, with some in-depth insights on how the TYPO3 Core Engine deals with this feature under the hood. Introducing overlays ---------------------- Overlays are used in two key features of TYPO3: - **Localization of data**. Localization in its simplest form is a 1:1 translation of every bit of content you have on your website. - **Content staging of data (“Workspaces”)**. Workspaces is a mechanism to add or modify content, preview, and have a defined publishing workflow before your visitors see new content on your website. Setting the scene for overlays -------------------------------- ### Initial set-up: English only, live content Let’s start with a simple example: a website in English, with no translations, and no workspaces. A Content Element (record of type “tt\_content”) displays on the website in the “Default Language” and as a “Live Record”. Within the database, this record has a “uid”, a numeric representation of the content which can be referenced or linked to. In our example, this record has the uid=13. ![Screenshot of original element in TYPO3 backend](https://b13.com/fileadmin/_processed_/3/a/csm_Screenshot_2025-03-10_at_16.37.47_4da945114c.webp) Content element in default language (uid=13). ### Adding a translation Let’s add a second language, for example “Hebrew”, to the site. Next we update our content element by translating the content into Hebrew. This is the “Translated Language” and it is still a “Live Record” so the content is public as soon as we hit the Save button. ![Screenshot of translated element in TYPO3 backend](https://b13.com/fileadmin/_processed_/0/a/csm_Screenshot_2025-03-10_at_16.41.22_970f666add.webp) Content element, translated into another language (uid=14). Internally, a new record, uid=14, is created, referencing uid=13 as the “Translation Parent” (typically a field called “l10n\_parent”), which is the “Default Language” record. ### Adding a Workspace to the mix Let’s add a custom Workspace called “Staging Workspace”, so we can work on unpublished content without affecting the live website. Here, we’ll see all content of the current “Live Workspace” until something is changed. When changing something in the “Default Language”, a copy of this record is created with uid=15. This copy, which we call “Versioned Record”, resides in Workspace ID=1, and has a connection to its “Live Record” which is stored inside the database in a field called “t3ver\_oid” (oid stands for Online ID). ![Screenshot of an updated element in a TYPO3 workspace](https://b13.com/fileadmin/_processed_/3/a/csm_Screenshot_2025-03-10_at_16.37.47_4da945114c.webp) Content element in default language, now edited in a TYPO3 workspace (uid=14). We can now preview the modified (“Versioned”) content, and also change the translation as well. This way, we get another copy (which is uid=16), this time from the “Translated Language” of the “Live Record”, making it the “Versioned Record of the Translation Language”. ![Screenshot of affected rows in our example in the database](https://b13.com/fileadmin/_processed_/7/a/csm_Screenshot_2025-03-10_at_16.54.41_3b7e671daa.webp) List of database records for our example from TYPO3 table "tt\_content". The mechanics and beauty of overlays -------------------------------------- Here’s where we see overlays come into action. TYPO3 uses overlays under the hood when previewing a page with content in a translation or in a workspace (or both). For this to work, TYPO3 has a [“Context” object](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Context/Index.html#context-api), where the current workspace (ID) and the language (ID) is stored. TYPO3 first always fetches the “Default Language of the Live Record” (language=0 and workspace=0). For each and every record, it then checks if there is a Versioned Record of this “Default Language” (by searching for a record with “t3ver\_oid=13” and “t3ver\_wsid=1”), and replaces all information of this record with the versioned record. However, it keeps the actual “uid”. This is what we call “Overlays” in TYPO3. If no versioned record is found, TYPO3 sticks with the live version. The technical elegance of overlays: By keeping the “uid” in place, any reference or link to this content will still connect to the “live version”, so TYPO3 does not need to replace and adapt all links when a versioned record is created. If the TYPO3 editor requests the Hebrew translation, TYPO3 then checks for a “language overlay”, checking for a record in the “Live Version” with its “Translation Parent” set to the uid=13 (the live default language). If in the staging workspace, the Hebrew version is also checked for a Versioned Record. ### A simplistic view of overlays looks like this: - Default content - Localized Hebrew content - Default content - Versioned record - Localized Hebrew content - Versioned record of localized record TYPO3 does all of this under the hood. Using the TYPO3 Core API for reading (PageRepository) and writing (DataHandler) handles all of that for you! Benefits of the overlay mechanism ----------------------------------- ### TYPO3 always queries the “Default Language” of the “Live Workspace” first. This is one of the main reasons why the concept of a “Default Language” and its connection to that exists. In addition, this allows for one further feature of TYPO3: Fallbacks. Even though you mostly read about Fallbacks in the TYPO3 ecosystem, fallbacks are actually a consequence of Overlays—a feature because TYPO3 builds on top of Overlays. ### If no Language overlay can be found, you can decide what happens. The so-called “Fallback Modes” when configuring a site language are now put into place: - **Strict Mode**: If no French translation is found, do not even think of showing the default language. The non-translated content is just not shown. - **Fallback Mode**: If no French translation is found, show the English version. - **Free mode**: Do not query the default language (= do not use the overlay technology). This is useful when your language is not bound to the default language. In addition, I coined the term “*Floating Records*“—records within a translation that do not have an overlay can still be rendered. Imagine a teaser element on a page that should only be shown in the Polish version—that’s a floating record. However, this record does not follow the sorting and ordering of the overlay mechanism. ### For Workspaces, only modified or newly created records are duplicated. Instead of cloning the full database for versioning, TYPO3 handles the versioned content automatically for you by just copying the modified content. ### Publishing a Workspace is just exchanging content. During the publishing process, TYPO3 keeps the “Live Version” in place and just swaps the modified fields into the existing live database records. Summary --------- By now you should understand why TYPO3 is so powerful. Using TYPO3’s native APIs handles everything for you. If you are interested in looking at your project together, we can see if your project is utilizing TYPO3 APIs properly. Give us a shout. [ Let’s connect! ](https://b13.com/lets-connect) ### Written by: ![Bild von Benni Mack](https://b13.com/fileadmin/_processed_/c/6/csm_benni_66cce9a81f.webp) b13 co-founder and TYPO3 CMS Core Development Lead, Benni Mack, heads our technical practices, setup and maintenance of our technical infrastructure, and coordinates our open-source contribution. His essential tool: TYPO3 Benni Mack CTO [ more from Benni Mack ](https://b13.com/team/benni-mack) Related Articles ------------------ - ![Cartoon trophy character surrounded by hands giving thumbs up and a heart gesture, set against a gear-patterned background.](https://b13.com/fileadmin/_processed_/f/7/csm_T3ppy_Design_Kit_Headerbild_b51eb9dc31.webp) ### T3ppy Gives TYPO3 a Friendly Face 06 August 2026 | Florian “Flix” Keitgen TYPO3 is powerful—but it doesn’t have to feel impersonal. Meet T3ppy, our friendly companion for the backend. [ Read more: T3ppy Gives TYPO3 a Friendly Face ](https://b13.com/knowledge/t3ppy-design-kit) - ![Gavel labeled "AI" on a circuit-patterned background with yellow stars, symbolizing regulation or legislation related to artificial intelligence in the EU.](https://b13.com/fileadmin/_processed_/1/0/csm_EUAIAct_Headerbild_510724b3de.webp) ### AI Content in TYPO3: Labelling Needs Accountability 02 August 2026 | Benni Mack The EU AI Act brings the origins of AI-generated content into focus. AI Label marks AI-generated and AI-edited content in TYPO3 and records who signed off the published version—for… [ Read more: AI Content in TYPO3: Labelling Needs Accountability ](https://b13.com/knowledge/ai-content-in-typo3-labelling-needs-accountability) - ![A series of stylized figures in various poses, each with a distinctive orange hat, depict a progression from walking to standing still while looking at a phone, set against a purple grid background.](https://b13.com/fileadmin/_processed_/d/7/csm_QueuesDDEV_Headerbild_f640931350.webp) ### Better scalability with decoupled queues: How to set up RabbitMQ with TYPO3 10 April 2024 | Jochen Roth When built-in message transports hit their limits, RabbitMQ can provide TYPO3 with a scalable, robust message queue. [ Read more: Better scalability with decoupled queues: How to set up RabbitMQ with TYPO3 ](https://b13.com/knowledge/better-scalability-with-decoupled-queues-how-to-set-up-rabbitmq-with-typo3) - ![A cartoon character resembling a shield gives a thumbs up in front of a computer interface with various menu options.](https://b13.com/fileadmin/_processed_/e/6/csm_Header_cda1f80173.webp) ### Meet T3ppy: A New Era for Editorial Work in TYPO3 01 April 2026 | Florian “Flix” Keitgen T3ppy and the AiM extension bring AI directly into the TYPO3 backend—enhancing SEO, content quality, and workflows with centralized control. [ Read more: Meet T3ppy: A New Era for Editorial Work in TYPO3 ](https://b13.com/knowledge/meet-t3ppy-a-new-era-for-editorial-work-in-typo3) - ![Retro microphone illustration with a shopping cart icon in the background, symbolizing e-commerce or online shopping.](https://b13.com/fileadmin/_processed_/f/8/csm_Marketplace_Headerbild_ee1575614c.webp) ### Why TYPO3 Needs a Marketplace for Products 25 March 2026 | Florian “Flix” Keitgen A marketplace would make TYPO3 products more discoverable, easier to compare, and benefit both agencies and clients alike. [ Read more: Why TYPO3 Needs a Marketplace for Products ](https://b13.com/knowledge/why-typo3-needs-a-marketplace-for-products) - ![A hand holding a magnifying glass over a laptop screen displaying a webpage with an image and text elements.](https://b13.com/fileadmin/_processed_/e/5/csm_BackendUserSection_Headerbild_6093c842fd.webp) ### Unlocking TYPO3’s Hidden Gem: The Backend User Section (Doktype 6) 05 March 2026 | David Steeb Discover TYPO3’s underrated doktype 6 (Backend User Section) for secure internal previews, editor training, and prototyping. Learn real use cases, common pitfalls like 403 errors… [ Read more: Unlocking TYPO3’s Hidden Gem: The Backend User Section (Doktype 6) ](https://b13.com/knowledge/backend-user-section-in-typo3-uses-pitfalls-helper) - ![Two stylized web page designs featuring a user profile, image placeholders, and text sections, set against a light blue background.](https://b13.com/fileadmin/_processed_/2/0/csm_BackendPreview_Headerbild_b4c5799cfa.webp) ### Backend Previews With a System—Why We Built EXT:backendpreviews 09 February 2026 | David Steeb EXT:backendpreviews brings structure and consistency to content previews in the TYPO3 backend using Fluid templates, layouts, and partials. [ Read more: Backend Previews With a System—Why We Built EXT:backendpreviews ](https://b13.com/knowledge/backend-previews-with-a-system-why-we-built-extbackendpreviews) - ![A human hand shakes a robotic hand against a purple background with heart patterns, symbolizing collaboration between humans and technology.](https://b13.com/fileadmin/_processed_/6/2/csm_AIbotsLoveMarkdown_Headerbild_72fe5820d6.webp) ### The Internet Is No Longer Just for Humans—AI Bots Love Markdown 28 January 2026 | Benni Mack Discover why most web traffic is now automated and how TYPO3’s structured content model prepares websites for humans, editors, and AI systems. [ Read more: The Internet Is No Longer Just for Humans—AI Bots Love Markdown ](https://b13.com/knowledge/the-internet-is-no-longer-just-for-humans-ai-bots-love-markdown) - ![Several colorful web page mockups stacked together, showcasing different layouts and design elements against a purple background.](https://b13.com/fileadmin/_processed_/e/3/csm_CaminoTheme_Headerbild_d082598009.webp) ### Camino—The Need for a Default Theme in TYPO3 Is Real 27 January 2026 | Benni Mack With TYPO3 v14, Camino introduces a default theme that removes friction from first installs. Why this matters—and how TYPO3 laid the groundwork. [ Read more: Camino—The Need for a Default Theme in TYPO3 Is Real ](https://b13.com/core-insights/blog/camino-the-need-for-a-default-theme-in-typo3-is-real) - ![Two interlocking gears with a disconnected electrical plug and a tag labeled "v13" on a purple background.](https://b13.com/fileadmin/_processed_/0/7/csm_TYPO3v13_Headerbild_14eb602ce4.webp) ### What’s New in TYPO3 v13? 20 January 2026 | Desirée Lochner TYPO3 v13 marks the beginning of a new era of user-friendliness. The version impresses with a modern, fresh, and incredibly high-performance user interface—developed for anyone who… [ Read more: What’s New in TYPO3 v13? ](https://b13.com/solutions/typo3/whats-new-in-typo3-v13)