Guide 02 · Developer docs

Core dna renders server-side sites with Smarty or with Twig, one engine per site, and treats the two as peers. This guide is the one place both are documented: what they share, each engine's language and the platform's additions and limits, the two side by side, and translation.

L1–L2

Unit 05 of 05 4 pages

Translation and internationalisation

Updated 23/10/2026 01:49

A multi-language site translates two things: the interface strings its templates print, from translation files, and the content editors write, as linked records. The one place the engines differ is how a template calls the translator; everything else is the same platform behaviour in both.

Translation is where the two engines look most different on paper, and the difference is smaller in practice. Smarty has four registered translation forms; Twig has none, but every Twig template receives the same translator and reads the same files, so a Twig site writes one macro and is done. Content translation, the language a visitor gets and language-aware links are platform behaviour, identical in both engines.

Read Interface strings first: where the files live, how the visitor's interface language is chosen, the order a key is looked up in, and why a printed key is a diagnosis. Then the page for your engine, Translating in Smarty or Translating in Twig. Translated content and the language switcher covers the content half: linked records, hreflang, and a switcher that keeps the visitor on the same page. Decide which languages and which approach before the first template is written; retrofitting keys into finished templates costs far more.

In this unit

Read in order

01 Interface strings The words a template prints, as opposed to the content editors write, come from XLIFF files looked up by domain and key, in both engines. Where the files live and how they are named, how the visitor's interface language is chosen, the order a key is looked up in, shared domains, missing keys, and the spelling of keys. 02 Translating in Smarty The platform registers four ways to translate in Smarty: the |_ modifier, the same modifier with a domain, the {_} function and the {__} block. A worked example of each, which to reach for when, parameters, setting a default domain, escaping what goes in, and strings for JavaScript. 03 Translating in Twig The platform registers no translation filter or tag for Twig, but every Twig template receives the platform's translator as __, reading the same files as a Smarty site. One complete approach, from the files to a macro library and its use in templates, attributes and scripts, including what prints nothing when the import is missing. 04 Translated content and the language switcher Content is translated as linked records, not through translation files, and it works identically in Smarty and Twig. How a translated record relates to its source, getOtherLanguageVersions() for hreflang links, a language switcher that finds the equivalent record, and why URLs carry no language of their own.

Objects ReferenceGenerated from the platform, so it is always current

API ReferenceEvery REST endpoint, in cURL, PHP, Python and JavaScript

Translation and internationalisation

In this unit