Guide 03 · Developer docs

The theme repo and the asset pipeline

Everything a developer changes on a Core dna site lives in its theme repository. This guide covers the repository and its build, printing records in templates, stylesheets and client-side code, and the parts of a site around the main content.

L1–L2
Unit 01 · Anatomy of a theme repo

Translation files in the theme repo

Anatomy of a theme repo Page 9 of 35 Updated

A site can carry XLIFF files in translations/ that replace the platform's own wording or hold its own interface strings. When a site needs them, how the files are named, which file wins for a key, and the one difference between the engines.

Who this is for. The theme developer asked to change a message the platform shows, or to give the site's own interface strings a translation. Afterwards you know whether a file in translations/ is the right tool, what to name it, and how to check it is being read. How strings are used in templates is covered in full on Interface strings.

When a site carries its own strings

The platform ships its interface strings in XLIFF files, one per domain (an area of the platform, such as admin, common, forms or products) and language. A site adds files of its own for two reasons:

  • To change the platform's wording. A message after sign-in, a form's validation text, or a label in the admin. One production site renames the platform's products to Activities throughout its admin with a few lines in translations/admin.en.xlf.
  • For its own interface strings in templates, when the site is multilingual or the wording must be editable by a developer without touching markup.

Content is not an interface string. Text an editor should change belongs in a layout area or a global component, not in a file that needs a deploy.

File names and format

A file is named translations/<domain>.<language>.xlf: admin.en.xlf, common.de.xlf. It uses the same XLIFF 2.0 layout as the platform's own files, with the key as the source and the wording as the target. List only the keys you change:

HTML translations/admin.en.xlf 
<?xml version="1.0"?>
<xliff xmlns="urn:oasis:names:tc:xliff:document:2.0" version="2.0" srcLang="en" trgLang="en">
  <file id="admin" original="admin.txt">
    <unit id="messages">
      <segment>
        <source>message.not_logged_in</source>
        <target>Please sign in to see this page</target>
      </segment>
    </unit>
  </file>
</xliff>

Which file wins

For a key in a domain, the platform looks in this order and uses the first file that has it:

  1. the site's file for the current language;
  2. the platform's file for the current language;
  3. the site's, then the platform's, file for the language set in DXP language (Globals.admin.defaultLocale);
  4. the site's, then the platform's, English file.

The current language is the visitor's choice when a language switcher has set the cdna_locale cookie, otherwise the DXP language setting, otherwise the browser's language. When no file has the key, the key itself is printed: message.not_logged_in on the page means the key or the domain is misspelt.

The domain matters as much as the key. A translation tag that names no domain uses admin, so a site's own strings in site.en.xlf are found only by tags that pass domain='site'.

Smarty and Twig

Smarty has translation tags registered by the platform; Twig has none, but the translator itself is available to Twig as __. Both read the same files:

Template code 
{_ key='message.not_logged_in' domain='admin'}

{'cart.empty'|_:'site'}
{{ __.translate('message.not_logged_in', [], 'admin') }}

{{ __.translate('cart.empty', [], 'site') }}

Changing a platform string changes it everywhere the platform shows it, on every page that uses that key. Search the platform's file for the key first, so you know what else moves with it.

Go deeper
GuideInterface strings GuideTranslated content and the language switcher How-toAdd translation to a Twig site, which has no trans filter FAQTranslation works in one site and not another

Was this page helpful?

Your answer goes to the docs team.