DF-1069: feature/i18n-welsh

.env.sample

@@ -28,7 +28,7 @@ UPLOADER_BUCKET_NAME=
 UPLOADER_URL=http://uploader.127.0.0.1.sslip.io:7300
 
 GOOGLE_ANALYTICS_TRACKING_ID=
-GOOGLE_ANALYTICS_CONTAINER_ID=
+GOOGLE_TAG_MANAGER_CONTAINER_ID=
 
 USE_SINGLE_INSTANCE_CACHE=true
 
@@ -42,7 +42,6 @@ LOG_LEVEL=debug
 LOG_FORMAT=pino-pretty
 STAGING_PREFIX=staging
 SERVICE_BANNER_TEXT=
-GOOGLE_TAG_MANAGER_CONTAINER_ID=
 SAVE_AND_EXIT_EXPIRY_IN_DAYS=28
 STORE_COMPLETED_APPLICATIONS_FOR=9 months
 STORE_FEEDBACK_FOR=9 months

.gitignore

@@ -10,3 +10,4 @@ coverage
 .cache
 .env
 tsconfig.tsbuildinfo
+.worktrees/

README.md

@@ -31,6 +31,7 @@ The designer is no longer a plugin and is responsible for running itself on defa
   - [⚠️ See config for default values for each environment](#️-see-config-for-default-values-for-each-environment)
 - [Testing](#testing)
 - [Outputs](#outputs)
+- [Multi-language support](#multi-language-support)
   - [Licence](#licence)
     - [About the licence](#about-the-licence)
 
@@ -233,6 +234,11 @@ Additional steps are required for the different output types.
   - A GOV.UK [notify](https://www.notifications.service.gov.uk) is required
   - For each notification you wish to send, a template must be set up. If there are 'personalisations' they must match the configuration
 
+# Multi-language support
+
+The runner can support multiple languages, specifically English and Welsh.
+See [multi-language](./docs/multi-language.md) for more information.
+
 ## Licence
 
 THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:

docs/multi-language.md

@@ -0,0 +1,49 @@
+# Multi-language (specifically English and Welsh)
+
+The `engine-plugin` and `runner` support multi-languages (if configured).
+Additional languages are configured by adding translations json files and adding a `translations` property under the `metadata` property of the form definition.
+You can use the Designer to edit Welsh translations for your form (to insert the necessary values in the `metadata.translations` property).
+
+Currently only English and Welsh are configured but other languages could be added if desired.
+
+## Forms engine plugin
+
+The `engine-plugin` handles translations at two levels:
+
+1. Boilerplate text - a translation file per language exists in `plugin` (`en-GB.json` and `cy.json`). These provide English and Welsh for each boilerplate text element, such as the feedback link url and text, or the error summary etc.
+2. Dynamic form text - English translations are read from the form definition (such as component title, short description etc), whereas Welsh translations are read from the `metadata.translations.cy` property of the form definition.
+
+The translator provides a series of functions:
+
+- t(key) - a general translation function that takes a key (for example 'validation.numberMax') and returns either the appropriate English text or Welsh text deending on which is the current language
+- tPage(key) - returns the appropriate translations for page elements, such as title, guidance etc.
+- tComponent(key) - returns the appropriate translations for components, such as question text, hint, short description etc.
+- tSection(key) - returns the appropriate translations for sections
+- tListItem(key) - returns the appropriate translations for list items since each list value (e.g from a radio/checkbox etc) must have a translated equivalent
+- tForm(key) - returns the appropriate translations for form-level elements. Currently this only handles the form name.
+
+## Forms runner
+
+The `runner` handles translations at two levels and sits on top of the translations from `engine-plugin`:
+
+1. Boilerplate text - a translation file per language exists in `runner` (`en-GB.json` and `cy.json`). These provide English and Welsh for each boilerplate text element that lives outside of the `engine-plugin`, such as the footer links and 'save and exit' pages.
+2. Dynamic form overview text - English translations are read from the form metadata (such as 'what happens next' or contact information), whereas Welsh translations are read from the `metadata.translations.cy` property of the form definition (specifically entries starting with `form.`).
+
+The translator provides a series of functions:
+
+- t(key) - a general translation function that takes a key and returns either the appropriate English text or Welsh text deending on which is the current language
+- tR(key) - returns the appropriate translations for elements specific to the `runner` (to avoid confusion with the `engine-plugin` translator functions)
+- tForm(key) - returns the appropriate translations for the form-level metadata elements (such as 'what happens next' or contact information), and also the form name.
+
+## Language selector
+
+If additional languages are defined, a language selector is displayed in the top-right of the form.
+Additional languages must be set within the Nunjucks/Vision global `context` in order for the language selector to display.
+The language selector should be shown for all plugin routes as well as all external routes (such as save-and-exit and static pages) when additional languages have been defined for the form.
+
+## Accessing the translator
+
+The translator should be available from the Nunjucks/Vision global `context` (for `engine-plugin` routes) and from the `context` attribute within the model for external routes. Either way, the translator should be accessible in a Nunjucks/Vision page using the attribute `context.translator`. This is particularly important for rendering `layout.html` since it references `context.translator.tForm('title')`. This must be available for both plugin routes and external routes alike.
+
+If you wanted to translate a runner-spcific piece of text, for example the footer links, you would call `context.translator.tR('my-translation-element-name')`.
+If you wanted to translate form-spcific metadtaa values, for example contact information, you would call `context.translator.tForm('contact.oneline.url')` to get the translation of for the key `form.contact.online.url` under `metatdata.translations.cy` - not the extra `form.` in the key name inside the form definition.

jest.setup.cjs

@@ -24,7 +24,6 @@ process.env.SUBMISSION_URL = 'https://test-submission-api.cdp-int.defra.cloud'
 process.env.UPLOADER_URL = 'https://test-uploader.cdp-int.defra.cloud'
 process.env.UPLOADER_BUCKET_NAME = 'dummy-bucket'
 process.env.GOOGLE_TAG_MANAGER_CONTAINER_ID = 'GTM-XXXXXXXX'
-process.env.GOOGLE_ANALYTICS_TRACKING_ID = '12345'
 process.env.GOOGLE_ANALYTICS_CONTAINER_ID = 'YYYYYYYYYY'
 process.env.USE_SINGLE_INSTANCE_CACHE = 'true'
 process.env.BASE_URL = 'http://localhost:3009'