Skip to content

CMS Localization

Important

Localization via Wagtail is something we are ramping up on, so please do not assume the following notes are final, or that the workflows are currently all rock-solid. We're learning as we go.

Page-tree concept

Our Wagtail setup uses the official wagtail-localize package to manage localization of pages.

This package supports page-level localization rather than field-level localization, which means that each locale has its own distinct tree of pages, rather than each page having a stack of duplicate fields, one per destination language.

These language-specific trees can be "synchronised" with the default en-US page tree, so would have the same page structure, field by field) --- or they can not be synchronised, so can have their own extra pages, or some specific pages in the tree can be made not "synchronised", while others are.

Basically, there is plenty of flexibility. The flipside of that flexibility is we may also create an edge-case situation that wagtail-localize won't work with, but we'll have to see and deal with it.

Note

It's worth investing 15 mins in watching the Wagtail Localize original demo to get a good feel of how it can work.

Locale configuration within Wagtail

While the list of available overall locales is defined in code in settings.base.WAGTAIL_CONTENT_LANGUAGES, any locale also needs enabling via the Wagtail Admin UI before it can be used.

When you go to Settings > Locales in the Wagtail fly-out menu, you will see which locales are currenly enabled. You can add new ones via the + icon.

Warning

When you add/edit a Locale in this part of the admin, you will see an option to enable syncronisation between locales. Do not enable this. If it is enabled, for every new page added in en-US, it will auto-create page aliases in every other enabled locale and these will deliver the en-US content under locale-specific paths, which is not what we want.

Localization process

Manual updates

At its most basic, there's nothing stopping us using copy-and-paste to enter translations into lang-specific pages, which might work well if we have a page in just one non-en-US lang and an in-house colleague doing the translation.

Automated via Smartling

However, we also have automation available to send source strings to translation vendor Smartling. This uses the wagtail-localize-smartling package.

Here's the overall workflow:

  1. CMS page "MyPage" is created in the default lang (en-US)

  2. The "Translate this page" option is triggered for MyPage, and relevant langs are selected from the configured langs that Smartling supports. (We don't have to translate into all of them)

  3. A translation Job is created in Smartling, awaiting authorization by our L10N team.

  4. A L10N team colleague authorizes the Job and selects the relevant translation workflow(s) for the relevant lang(s)

    • Note that one Wagtail Page (or one Wagtail Snippet) creates one single Job, so if you select mutiple target languages for that Job and submit it, you won't get it back from Smartling until all languages involved are submitted by translators. One way around this is to submit each language as a separate Job, but that creates more work for our L10N team to coordinate. (We are looking to refine that experience in the future and to make it better for everyone.)

  5. Once the job is completed, the localised strings flow back to Wagtail and populate a draft version of each language-specific page.

  6. A human reviews these draft pages and publishes them

    • When a translation flows back, by default the relevant pages are not automatically published. At the moment, CMS admins are emailed for each language in a Job when it is synced back from Smartling, reminding them of this. (We may well move this to in-dashboard Wagtail Tasks for better UX.)
    • The CMS admin sidebar has a link to Smartling Jobs. You can use this to see what translations have landed, and also follow the link to the localized version of the page, which you can then Preview, visually check, then Publish like a regular page.

Notes:

  • Smartling/wagtail-localize-smartling will only translate pages from the base lang (en-US) to another lang - it won't treat, say, a Page in fr as a source-language document.
  • If a string is received from Smartling into the CMS and then manually edited on the CMS side, the change will not be overwritten by subsequent Smartling syncs and the manual edit needs to be added on the Smartling side for consistency and stability.
  • If a page is translated from en-US once, then has new en-US content added that is sent for translation, that will trigger a new Smartling Job. When that job is complete, it will overwrite any manual edits made to a translation within the CMS. This is why it's important to make sure Smartling contains any manual tweaks done to translations in the CMS.

Automated via Pontoon

It should also be possible to use Pontoon with wagtail-localize. (There are notes on the Pontoon integration here, but we have not yet tried to enable this alongside wagtail-localize-smartling).

Additionally using Pontoon would let us benefit from community translations across a broad range of languages. However, we have yet to try to set this up and would need to agree which parts of the site do and do not use Pontoon.