Allow users to override hardcoded strings in our component JavaScript (internationalisation)

[hannalaakso]

What

Allow strings in our component JavaScript to be customised/changed, to allow for text in other languages, e.g: Welsh.

Why

Some service teams have a requirement to provide their services in Welsh as well as English (and other teams support a wider range of language translations too). At the moment, service teams are stuck with some elements of the page in English unless they manually copy our JavaScript into their application, which isn't ideal.

Related issues:

• Character Count 'count message' cannot be customised or translated #1681
• Summary list links are hard to localise #2094
• Make 'menu' text in header customisable #1904
• Accordion 'open/close all sections' cannot be customised or translated #1325
• Add ability to override or remove OGL logo in Footer #1291
• Add ability to override or remove Crown Copyright in Footer #1290
• Add thousands comma-seperation in character count messages #2568

This work is also closely related to how we allow users to set and configure JavaScript options. We should keep in mind that it may be simpler to develop a solution for internationalisation that also works for setting all configurable JavaScript options.

Who needs to know about this

Developers; Tech Writer

Done when

Prep & Research

• Research internationalisation libraries and how other libraries and design systems do internationalisation #1709
• Spike approaches to internationalisation #1714
• Investigate how our proposed internationalisation approach works for service teams #2566
• Write and share a proposal for internationalisation #1715
• Research a data-attribute approach to passing translations to component JavaScript #2736
• Decide JavaScript and Nunjucks API for passing translation strings #2780
• Decide prioritisation order for methods of passing in translation strings #2781

Missing Nunjucks translations

• Allow localisation of content licence and copyright notices in Footer #2702
• Make 'menu' text in header customisable #1904
• Add ability to customise character count text that announces character/word limit / no-js fallback #2687
• Add examples and tests for translating error message and summary list content #2690
• Add full page example(s) for translated components (via macro options) in the review app #2692

Translating hardcoded strings in JS

• Add internationalisation logic to lookup translation from key #2801
• Add ability to pass translation strings to accordion component via data-attributes #2699
• Allow component JavaScript constructor to take a config object #2698
• Add ability to pass translation strings into accordion component via JS #2802
• Expand internationalisation logic to add string interpolation feature #2700
• Expand internationalisation logic to add pluralisation #2804
• Add ability to pass translation strings into character count component via data-attributes #2701
• Add ability to pass translation strings into character count component via JS #2805
• Respond to Rollup warning for i18n.mjs #2829

Documentation

• Create documentation for localisation - passing translations via data attributes govuk-design-system#2307
• Create documentation for localisation - passing translations via JavaScript govuk-frontend-docs#196
• Summarise approach and decisions for internationalisation in the Design System backlog  #2749

Stretch Goals

• Investigate components being initialised more than once #1127
• Improvements to component initialisation and CSP documentation govuk-frontend-docs#203

[nataliecarey]

At HMRC we only have one component which requires this, we've implemented it with data- attributes. The Nunjucks component takes arguments for the content and passes them through to the JS via the dom element which gets instantiated.

The component which does this is a pure JS component which is activated by a custom meta tag. https://github.com/hmrc/hmrc-frontend/blob/master/src/components/timeout-dialog/template.njk

I'd suggest that the user of a component shouldn't need to know which content is produced by JS and which isn't. Providing them all via the component parameters is my attempt to achieve that.

[jamesalfei]

At DVLA, we require frontend component localisation for supporting the welsh language. This is, in most cases, done within our application but on components such as the text area character count, this is done within the GOVUK frontend via Javascript. This means we cannot localise the text on these components.

This issue was present in 2018 when a PR was opened (and subsequently declined) in favour of a more common approach: #1038

This consistent approach across all components will allow localisation and allow us to offer our customers fully internationalised pages, rather than a mix of Welsh and English which we currently have due to this component.

Note, we are fully aware that we can bring the code in-house and modify it to our needs, but this would mean more overhead to keep up to date with the centralised repo. This is something we want to try and avoid if at all possible.

[domoscargin]

Re: prioritsation of config passed by data attributes and config passed by JavaScript, we've decided that data attributes should always take precedence over config passed by JavaScript.

#2781

[36degrees]

I'm calling this done – the only unticked items are only tangentially unrelated.