Guide for translators¶

For everyone who wants to translate a Drupal CMS template into their language.

You don't need programming skills. You need a drupal.org account, an editor for translation files (for example Poedit) and a Drupal CMS test installation, or someone who creates the list of texts for you. Ideally, you are also a member of your language's translation team on localize.drupal.org.

localize.drupal.org and your language team¶

localize.drupal.org is the online service the Drupal community uses to translate Drupal. There is a team for every language. Right in the browser, the teams translate the texts of Drupal core, of modules and themes, and of Drupal CMS itself – including the template descriptions in the installer. Websites download these translations automatically.

How to join:

1. Log in to localize.drupal.org with your drupal.org account.
2. Open the page of your language, for example German, and join the team.
3. At first you can suggest translations. The team's moderators review them and give you more permissions over time.

The team matters for the templates for two reasons:

• Consistent terms: every team maintains a glossary and a style guide, e.g. for the form of address. When template and interface use the same terms, the website feels all of a piece.
• What is missing there shows at once: texts that a template's theme outputs with |t, and the descriptions in the installer, are translated on localize.drupal.org. If they are missing there, they stay English.

What you translate¶

For each template and language there are up to two files in the translations/ folder of Default Content Locale Extended:

<template> is the machine name of the template, e.g. haven, byte or summit. <langcode> is the language code, e.g. fr, nl or pl. The German files (*.de.po) are good examples.

Some files apply to several templates:

• drupal_cms_site_template_base.<langcode>.po: the base recipe of all templates (dashboard, editorial workflow),
• mercury_themes.<langcode>.po: texts of the Mercury themes many templates are based on.

Step 1: Create the list of texts¶

Install Drupal CMS with the template and enable Default Content Locale Extended. Then this command creates the list of all texts of the template:

drush dcle:template-pot haven --language=fr --output=haven.fr.po

The file contains every text once, with the place where it is used. Whatever Drupal can already translate is filled in.

After installing in your language, --untranslated-only shows only the texts that are still missing:

drush dcle:template-pot haven --language=fr --untranslated-only --output=haven.fr.todo.po

Step 2: Translate¶

Open the file in Poedit or another PO editor. Above each text there is a marker that tells you where it belongs:

Please note:

• Keep placeholders and HTML unchanged. @name, %name, !name, [node:title] and HTML tags must appear exactly as they are in the translation.
• Use your language team's style. Follow the form of address and the terms of your team's glossary on localize.drupal.org. Then template and interface match. The German translations, for example, use the formal "Sie".
• Don't mix up the main file and content-only. The main file affects the whole site, including the admin interface. If a word means something different in the template than in the interface, its translation belongs in the content-only/ file. Example: "Media" on the Convivial Gov home page means "Presse" (press) in German, but must stay "Medien" in the admin UI.
• Don't translate technical values. The tool leaves icon names, paths, file names or colour values out of the list in the first place. Whatever is in it may be translated.
• You may fix obvious mistakes. If the original contains a typo, translate what was meant.

Then save the entries in the matching file, e.g. translations/haven.fr.po and, if needed, translations/content-only/haven.fr.po.

Step 3: Check¶

Reinstall the site in your language with the template and run the list with --untranslated-only again. It should report 0 open texts. Then look at the pages: home page, menus, forms, header and footer.

A script that comes with the module does part of that for you. It visits the home page, the navigation and all content pages and reports texts that look English, including placeholders, screen reader labels and image descriptions:

php web/modules/contrib/dcle/scripts/check-pages.php --language=fr \
  --drush=vendor/bin/drush http://localhost

For --language it currently knows de and fr.

If English text is still visible although the list is complete, it is usually hard-coded in the theme. That is a bug in the template, not in your translation. Feel free to report it in the issue queue.

Step 4: Submit via git.drupalcode.org¶

Contributions to drupal.org projects are submitted as a merge request on git.drupalcode.org. You can do everything in the browser.

1. Create an issue. Open the Default Content Locale Extended issue queue and create an issue, e.g. "Add French translation for Haven". Category: Feature request.
2. Create an issue fork. Click Create issue fork on the issue page. The first time, you need to request push access once (Get push access) and accept the Git terms of use.
3. Upload the files. Follow the link to your fork on git.drupalcode.org, select your branch and open the translations/ folder. Upload your .po file via + → Upload file. The content-only file goes into translations/content-only/. Write a short commit message, e.g. "Add French translation for Haven".
4. Open a merge request. After the upload GitLab offers Create merge request; the link is also on the issue page next to the fork. Then set the issue status to Needs review.

If you prefer working with Git on your own computer: the issue page lists all commands for cloning and pushing the fork under Show commands.

A maintainer reviews your contribution, possibly with questions, and then merges it. With the next release, Default Content Locale Extended ships your translation to everyone.

Thank you for your help!