Create documentation for localisation - passing translations via JavaScript

[claireashworth]

What

Documentation is needed for the work which allows users to override hardcoded strings in our component JavaScript (internationalisation) #1708

There are two ways for users of GOV.UK Frontend to pass translations - via data-attributes or via JavaScript. The data-attributes approach will be documented in the Design System website, as the "primary" option for translating component JavaScript.

The second approach (passing translations via JavaScript) is more technical and may be less commonly used - we should document this approach in the Frontend Docs site. This is what this ticket covers.

Why

• To allow users to pass translations via JavaScript, if they wish
• So we document the different methods of passing in translations

Who needs to know about this

Tech Writer; Developers

Done when

Documentation approved by subject matter expert as accurately representing what the user needs to do.

• [x] Plan out rough structure of what needs to be included and where, i.e: rough content structure
• [x] Draft documentation
• [x] Developer review
• [x] 2i review
• [ ] Publish

[vanitabarrett]

A group of us caught up today to talk about where some of this information might live. We talked about how this is the first time we're really having to include technical information of this depth, so wondered if it was better suited for the Frontend Docs. We kind of already have an example (with the Nunjucks macro options) of showing component-level information in the Design System, so we could follow the same pattern (although we know there are issues with this information being hidden away).

Questions:

• How do we support people who go straight to a component page, and help them find docs on setting up i18n?
• The localisation work has some crossover with the Nunjucks macros already - do we need to look at making this stuff less buried?

Several people noted that this is just the first example of many where we might need to document info like this in the Design System (e.g: JS API work).

Proposal:

• Create a new section in the Frontend Docs for 'intro' information to i18n, e.g: how to set it up and get started.
• Make sure any component-specific information lives within the component page in the Design System
• Lots of cross-linking between the two!
• Prototype and test this when we share the pre-release, so we can always iterate/change things up if we find they don't work well for users

Next steps:

• Work on the doc more to refine the content and make sure it's accurate
• Think about the component-specific info and where/how we link to the Frontend Docs - perhaps just using one component, e.g: character count, as an example to start with
• Prototype including this info in the Frontend Docs and Design System, so we can share a more 'realistic' example with teams we're testing with

[vanitabarrett]

Going to move this into Blocked while the pre-release is out for testing

[vanitabarrett]

I've edited the scope of this card to only apply to localisation documentation we want to add to the Frontend Docs site. There will be a separate card for documentation in the Design System site.

[vanitabarrett]

Moving this back into the Sprint Backlog, as we've only really started the Design System part of the documentation.

[domoscargin]

We've decided that config passed via data attributes should always take precedence over config passed via JavaScript initialisation (https://github.com/alphagov/govuk-frontend/issues/2781). We should consider documenting this somewhere.

[claireashworth]

This has gone for 2i review with another tech writer

[claireashworth]

2i done and approved for publishing