Localisation support in GOV.UK Frontend

[vanitabarrett]

Localisation support in GOV.UK Frontend

Closing date: Closed - deadline was 12th August 2022
Status: Accepted. You can follow implementation progress here.

Update - 31 August 2022

Data attributes

We will add new data-* attributes to allow customisation of hardcoded English strings, for those users who are not using Nunjucks macros. These will take precedence over any translations passed by JavaScript.

Example of passing translations via data attributes:

<div data-i18n.show-all-sections="Show everything" data-i18n.show-section="Show<span class=&quot;govuk-visually-hidden&quot;> this section</span>">

---

Scope

This proposal relates to:

• enabling the localisation of text within GOV.UK Frontend
• the technical methods by which localisation of text is achieved

It does not cover:

• components that aren’t part of GOV.UK Frontend
• design modifications that would assist specific localisations, such as changing fonts and colours, or changing the layout for right-to-left languages
• how components should be translated

Summary

GOV.UK Frontend currently contains components that include hardcoded English language text in Nunjucks and JavaScript code. Currently, service teams can only change this text by making a copy of the HTML or JavaScript of the component and changing the hardcoded text manually.

We intend to modify components that currently have hardcoded English text to allow this text to be customised, including the ability to change the content order where necessary.

We'd like your feedback on these proposed changes and how they might work for your services. You can:

💬 add comments to this discussion
✉️ send feedback to govuk-design-system-support@digital.cabinet-office.gov.uk
⬆️ upvote this comment if you agree with the proposed changes and have no other feedback to give

Background

Nunjucks

Most components in GOV.UK Frontend have text that can be customised using Nunjucks parameters. However, there are a small number of components where English language text, or a fixed content order that aligns with the English language, is hardcoded into the component’s HTML. One example is the header component’s ‘Menu’ button text.

Components currently containing hardcoded English or a fixed content order include:

• Character count
• Error message
• Footer
• Header
• Summary list

JavaScript

Some components have accompanying JavaScript modules which inject hardcoded English text into the HTML of the component. This includes:

• Accordion
• Character count

For example, it’s not currently possible to translate the “Show”/”Hide” buttons in the accordion component.

Problem

The inability for service teams who support non-English languages to use these GOV.UK Frontend components directly has created forked implementations of these components.

In addition to being inconvenient to create, these forked components can fall out of sync with future updates to GOV.UK Frontend, creating an ongoing maintenance burden for these teams.

Proposal

Nunjucks

We will add new Nunjucks macro options for any hardcoded English strings, to allow them to be customised. This will include, where necessary, the ability to customise the order that text strings are assembled in.

By introducing new macro options, this approach should be backwards compatible and will preserve the current text and content order for existing implementations.

JavaScript

We will allow translation strings to be passed into component JavaScript at the point of initialising, either via the components constructor or the initAll method. Translations will be passed as an object with key value pairs.

Example of passing translations via initAll:

window.GOVUKFrontend.initAll({
  accordion: {
    i18n: {
      locale: "cy",
      translations: {
        show_all_sections: "Dangoswch bob adran",
        hide_all_sections: "Cuddiwch bob adran",
        show_this_section: "Dangoswch yr adran hon",
        hide_this_section: "Cuddio'r adran hon"
      }
    }
  }
})

Example of passing translations to a specific component:

new window.GOVUKFrontend.Accordion(
  document.getElementById("#custom-accordion"), {
    i18n: {
      locale: "cy",
      translations: {
        show_all_sections: "Dangoswch bob adran",
        hide_all_sections: "Cuddiwch bob adran",
        show_this_section: "Dangoswch yr adran hon",
        hide_this_section: "Cuddio'r adran hon"
      }
    }
  }
).init()

We are concerned that this approach may not work for everyone, depending on how you import and initialise the GOV.UK Frontend JavaScript into your project. If you use a bundler in your project, don’t initialise our JavaScript code in your HTML, or your site has a Content Security Policy (CSP) we would especially like to hear about how this approach would work for you.. Likewise, if you have other concerns about how this would work for your service.

Each component will have its own default strings, making this backwards compatible with existing implementations and preserving the existing text if no translation strings have been supplied.

We will also provide a way of supplying different plural forms for translation strings that interpolate numbers. This is needed for components like the character count, for example:

character_count: {
    i18n: {
      locale: "en",
      translations: {
        characters_over_limit_one: "Thou have writen %{count} letter too many",
        characters_over_limit_other: "Thou have writen %{count} letters too many",
        characters_under_limit_one: "Thou have %{count} letter remainen",
        characters_under_limit_other: "Thou have %{count} letters remainen"
      }
    }
  }
})

This is based on the naming specification created by Unicode and used by JavaScript’s Internationalization API.

Dynamic variables

For both Nunjucks and JavaScript, a standardised syntax for interpolation of dynamic variables into the string will be created. We intend to use the %{variableName} format that is already utilised by GOV.UK’s localisation files.

Release plan

We intend to release localisation support in multiple stages.

The first part will be shipped as part of a future release of GOV.UK Frontend v4, and will include:

• changes to Nunjucks components to support localisation
• a basic version of JavaScript localisation, with support for:
  • a limited set of languages (as noted at the start, no support for languages read right-to-left)
  • interpolation of dynamic variables
  • pluralisation support of integers (whole numbers)
• support for Internet Explorer 8 and above

Once our support for Internet Explorer has been reduced (including ending our JavaScript support for IE), we will be able to take advantage of the Internationalization API to add additional features, such as:

• a more advanced version of JavaScript localisation, with support for:
  • a wider set of languages — which languages will be available is dependent upon the user agent
  • pluralisation support of decimal numbers
• replacement of manual pluralisation code with Internationalization API’s PluralRules functionality
• removal of polyfills needed for localisation in Internet Explorer

[oscarduignan]

from hmrc perspective on the javascript side, we provide a bundled version of the govuk-frontend javascript along with the hmrc specific bits from hmrc-frontend that most tax services use so they don't call the init method themselves. But I don't think that would be a problem and I can't think of any issues with CSP for us- guess our code might change to look for service provided translations in the window scope and merge those with default translations provided by our library for welsh

[frankieroberto]

Glad this is being tackled!

A few questions about the javascript implementation...

The page template currently includes the window.GOVUKFrontend.initAll() call within a <script> tag just before the close body tag. If this had to contain all the translations for all the components, that might mean quite a few extra bytes to serve on every page load? Alternatively, would you recommend moving this call to within an external javascript file referenced from a script tag?

Would there be a way to specify the translations for multiple languages within the initAll method, or is it intended that you'd only specify the language being used on the current page?

Would govuk-frontend contain localisations for any languages other than English?

What would the locale key be used for? Would the javascript components set a lang="" attribute on the components, or would we assume that that isn't needed as there would be a correct lang attribute set on the <html> tag?

Our service does have a Content Security Policy set.

[querkmachine]

Hi Frankie,

We want to provide the greatest flexibility for how services can provide localisations—be they hardcoded in HTML, returned from a content management system, a JSON file, a JavaScript file, or some other means. Our examples and documentation use a <script> tag for simplicity's sake, but (hopefully!) you can use this in whatever way works best for your needs.

It's intended that only the currently in use language is specified in the configuration, but we're interested if functionality to switch between them automatically would make life easier.

We do not intend to provide any localisations in govuk-frontend.

The locale key is intended as an override to specify which language's plural form and number formatting rules to use, in cases where only certain areas of a page have been translated. It isn't needed if the lang attribute on <html> has been set appropriately.

Hopefully those answer your questions. If you're interested in testing the pre-release, do let us know, as we're especially interested in how well it works on services with Content Security Policies set.

[penx]

To support ports of the nunjucks templates to other frameworks such as React, I would ask that the localised strings for all supported languages are included as a json file that can be imported from the govuk-frontend npm package

[vanitabarrett]

Hi @penx,

Thanks for your comment. We’re not currently intending to provide any localisations within govuk-frontend - we would expect these to be provided by each service.

[penx]

There would be english-only defaults though? It would be good to have access to these defaults via a json file in a way that could potentially be extended to other languages in future, even if those extensions were provided elsewhere

[domoscargin]

Hi @penx,

We're interested in understanding how you would use something like that if we did provide it.

Is it more of a documentation issue (ie: having access to all the values that can be localised via JS)?

Or is it more to do with being able to use the JSON to simplify passing in translation strings?

[penx]

My thinking is that if govuk-frontend uses these strings internally to provide English-only defaults, then any port of govuk-frontend should use the same set of strings for its defaults too. One result of this is if the govuk-frontend strings change then any downstream ports would be able to auto update their defaults too.

So in the case of govuk-react or any similar port I would see the components that need access to the defaults would have govuk-frontend as a dependency and be able to import and use them as defaults when the user hasn't provided their own localised strings

[domoscargin]

Hi @penx

Just wanted to give an update on this.

Ultimately, we want to encourage port maintainers to use our JavaScript, so we’re not planning to include this JSON file in the initial release. We’ll keep the conversation going with port maintainers to see what we can do to support them, and gather feedback from the release so we can make further calls.

[frankieroberto]

I wonder if it would be worth considering allowing the components to be initialised with the translations for more than one language at the same time, something like this:

window.GOVUKFrontend.initAll({
  accordion: {
    i18n: {
      cy: {
        show_all_sections: "Dangoswch bob adran",
        hide_all_sections: "Cuddiwch bob adran",
        show_this_section: "Dangoswch yr adran hon",
        hide_this_section: "Cuddio'r adran hon"
      },
     en: {
        show_all_sections: "Show all sections",
        hide_all_sections: "Hide all sections",
        show_this_section: "Show this section",
        hide_this_section: "Hide this section"
      }
    }
  }
})

...And then have some way to "set" which locale each component should use. Perhaps the component code could check the current lang value on the <html> element or the container element for the component?

The advantage to this might be that you'd then only need to compile a single javascript file which all pages could reference, rather than one for each language with some logic on which one reference on a given page. It might be simpler to implement too?

A disadvantage might be that the single compiled file would be bigger, with users then having to download the translations for languages they may not see. This would only happen on the first page load though hopefully (and then it'd be cached).

[jezzyp]

Hi Vanita I'm coming at this from a non developer pov - more of a content bod and former UK English localisation person for a transactional service - so my thoughts may or may not be relevant or I may have missed that you've got this covered already. It'd be great if the (english or whatever starting language) " base" strings could be easily extracted and imported into a translation database / service, which does machine translation and enables human intervention / checking. Translated, approved strings can then get squirted back into the front end, with relevant tagging so system knows which language to display. Maintaining a translation memory of translated strings is good, to keep costs down and translation consistency and quality up. If there was some gizmo that enabled localisation people to see strings in context too that'd really helpful. Hope that helps - cheers Jeremy

[kevindew]

Ooh tough problem! Good to see you're digging into it. I was mostly coming to read about your thing but then I wanted to share an idea.

The idea of passing in the translated strings via JS seems like it'd be something that'd be tough going for GOV.UK to do as it'd be hard to compile our JS with it intersecting with locale files and similar.

I did wonder whether you'd ruled out/considered using data attributes in the HTML for it? This feels like quite a natural use-case for them which seems like it could be simpler. That could allow abstracting the JS to need to be aware of locale at all and maintain a separation of concerns between content logic. You could have English as a default hardcoded and just fallback if a data attribute isn't provided.

E.g. for an accordion:

<div class="govuk-accordion"
     data-module="govuk-accordion"
     id="accordion-default"
     data-phrase-show-all-sections="Dangoswch bob adran"
     data-phrase-hide-all-sections="Cuddiwch bob adran"
     data-phrase-show-this-section="Dangoswch yr adran hon"
     data-phrase-hide-this-section="Cuddio'r adran hon">
  <div class="govuk-accordion__section ">
    <div class="govuk-accordion__section-header">
      <h2 class="govuk-accordion__section-heading">
        <span class="govuk-accordion__section-button" id="accordion-default-heading-1">
          Ysgrifennu'n dda ar gyfer y we
        </span>
      </h2>
    </div>
    <div id="accordion-default-content-1" class="govuk-accordion__section-content" aria-labelledby="accordion-default-heading-1">
      <p class='govuk-body'>Dyma gynnwys o google translate, sori</p>
    </div>
  </div>
</div>

[vanitabarrett]

Hey @kevindew , thanks for commenting! We've actually been spiking a data-attributes approach in the last week or so, to see what that might look like, so good to know that might work better for GOV.UK!

[kevindew]

Great stuff, glad to hear it.

[frankieroberto]

This definitely feels like an easier thing to implement, as HTML is usually rendered server-side and so knows which locale the user is currently using, whereas the javascript files are often pre-compiled and entirely static. This is partly why I suggested above that might make sense to be able to include multiple locales in the initAll function, and then have the javascript pick which one to use based on the locale set on the current HTML page (or component?).

Alternatively I think you’d have to pre-compile a separate javascript file per supported locale, and then conditionally reference different javascript files depending on the currently language set for the page. Which isn't too tricky, but might slow down deployments a bit, if you’re supporting lots of languages (and sass compilation can be quite slow anyway).

[domoscargin]

Thanks to everybody for providing us with really useful feedback on this proposal.

We have decided to give users the ability to pass translations to components via data-* attributes, in addition to passing them through JavaScript. Translations provided through data-* attributes will take precedence over any translations passed via JavaScript. Nunjucks macro options will correspond directly to these data-* attributes.

For more details, see @querkmachine’s summary here: #2780 (comment)