Providing content in different languages

Translating pages

The simplest way of maintaining parallel English and French pages is to maintain two pages that reference each other through their front matter.

On an English language page, fr_page_url should be a reference to the URL of the parallel French language page.
On a French language page, en_page_url should be a reference to the URL of the parallel French language page.

Important! All French language pages should also contain lang: fr in their front matter.

This structure above allows the language switcher link to be appropriately generated in the header when building the site.

Maintaining locale files

For translating components used on both English and French pages, we use locale files. You can add items to src/_data/app/app-locale-strings.json and the localized string gets injected into the page with a custom filter, localeString, according to the current page language.

Content can be organized using nested keys. As seen below, you can group by page, section, element, and so-forth.

{
  "homePage": {
    "title": {
      "en": "Home Page",
      "fr": "Page d'accueil"
    }
  }
}

To inject the content into your template, use the localeString filter:

<h2>{{ "homePage.title" | localeString }}</h2>

To keep things clean, especially when dealing with images and links, markup can be added to the content file using two additional filters: markdown and safe. Using the safe filter sanitizes the markdown.

"welcome": {
  "en": "Welcome to the Ontario.ca <a href=\"https://jamstack.org/\">Jamstack</a> Application Toolkit.",
  "fr": "Bienvenue à la trousse d'outils d'application <a href=\"https://jamstack.org/\">Jamstack</a> d'Ontario.ca."
}

<p>{{ "homePage.welcome" | localeString | markdown | safe }}</p>

You can create localization strings for shared components or similar uses in src/_data/app/app-localeStrings.json, which can then be referred to in page templates using the localeString filter: {{ "[key]" | localeString }}. This filter will insert the appropriate localized string for the key based on the current page language.