Guide for developers¶

For everyone who builds site templates, recipes or themes for Drupal CMS.

Default Content Locale Extended translates a template during installation. How well that works depends on how the template is built. This page shows how to make your template translatable from the start, and how to check it.

How the module works with your template¶

When the module is installed, its translation files (translations/<template>.<langcode>.po) are loaded into Drupal's translation database.
While the template imports its content, the module replaces the English texts with the translation: nodes, terms, media, menu links, Canvas pages, image descriptions.
After the template has been applied, it translates configuration Drupal does not cover on its own: Canvas headers and footers, forms (Webform), URL aliases and some module settings.

Translations are keyed by the English source text. When a text changes in a new version of your template, only that text needs a new translation; all others remain valid.

Requirement: the module must be active before the content

The module must be installed before the template imports its content. drush dcle:site-templates takes care of that: for every template it creates a recipe <template>_localized that first applies the helper recipe localize_site_template (installs dcle and, if Canvas is present, dcle_canvas) and then the template. The Drupal CMS installer lists these recipes as "… (localized)". This is tested with Haven in German and French.

A template cannot be translated afterwards: once it is installed, its content stays English. If you want to add dcle to your template's own install: list, please talk to us in the issue queue first.

Checklist: making your template translatable¶

Every item is based on a bug we found in real templates.

Themes and components¶

No hard-coded text in templates. Every visible text in Twig needs |t or {% trans %}, including aria-label, alt, title and fallback texts like "Your browser does not support the video tag."
Actually render your props. A component that offers props for its texts but ignores them and hard-codes the English text can be neither edited nor translated.
Don't hide names in icons. When a link title is replaced by an icon, the accessible name (e.g. "Follow us on @network") must still contain the title.
Example values are not content. The examples or default values of Canvas components are versioned and cannot be translated. Texts visitors should see belong in the page's inputs.
Store inputs as data. Canvas inputs belong in the export as structures, not as JSON strings. Five templates could not be installed for a while because of JSON strings.

Sample content¶

Export with a language. Every content item needs a langcode. Content without a language broke the installer's language detection for Summit.
Make text fields translatable. Fields that contain prose should be configured as translatable.
Link to content, not to paths. Menu links and links pointing to a hard-coded alias like /about-us break once the alias is translated. The module then creates redirects, but linking to the content itself is cleaner.
No hard-coded IDs. Settings pointing to /node/12 (e.g. the 404 page) often hit the wrong content after an import.
Safe HTML. Drupal's translation system drops texts with tags outside its allow-list, such as <u> or <div>. Use simple HTML in translatable texts.

Configuration and recipes¶

Translatable schema types. Texts in the configuration of your own modules and themes need the schema type label or text, not string. Otherwise Drupal does not know they may be translated.
Don't change the site language. A recipe must not set the site's default language to English. Otherwise all content ends up in a language that no longer exists after installation.

Checking your template¶

The module ships a tool that lists all translatable texts of a template: content, Canvas pages and configuration, each with the place where it is used. The template must be installed on the site.

# All texts of the template as a translation template (.pot)
drush dcle:template-pot my_template --output=my_template.pot

# After installing in German: only the texts that are still missing
drush dcle:template-pot my_template --language=de --untranslated-only

my_template is the recipe's machine name, i.e. the name of its folder under recipes/. A path to the recipe folder works as well.

The .pot file is also a good inventory: if a text visitors see is missing from it, it is probably hard-coded in a template. The checklist above helps then.

A template counts as fully translated when both hold:

--untranslated-only reports 0 open texts.
No English text is visible on the finished pages, including header and footer, forms and image descriptions.

Contributing translations¶

Translations are currently maintained centrally in Default Content Locale Extended, one file per template and language. How to submit one is described in the guide for translators.

Please report bugs in Drupal CMS, Canvas or a template that you find while checking to the project they belong to. Bugs in this module go to the Default Content Locale Extended issue queue.