feat/df-1065: Welsh translation for plugin

docs/features/code-based/page-controllers.md

@@ -63,11 +63,18 @@ Both are imported from `@defra/forms-engine-plugin/controllers/<ClassName>.js`.
 
 ## Examples
 
-- [Changing the Nunjucks template](#changing-the-nunjucks-template)
-- [Fetching data for the view model](#fetching-data-for-the-view-model)
-- [Intercepting the GET handler](#intercepting-the-get-handler)
-- [Writing to state on POST](#writing-to-state-on-post)
-- [Display-only page (no form components)](#display-only-page-no-form-components)
+- [Custom page controllers](#custom-page-controllers)
+  - [How it works](#how-it-works)
+  - [Choosing a base class](#choosing-a-base-class)
+  - [Examples](#examples)
+    - [Changing the Nunjucks template](#changing-the-nunjucks-template)
+    - [Fetching data for the view model](#fetching-data-for-the-view-model)
+    - [Intercepting the GET handler](#intercepting-the-get-handler)
+    - [Writing to state on POST](#writing-to-state-on-post)
+    - [Display-only page (no form components)](#display-only-page-no-form-components)
+  - [Reference](#reference)
+    - [What QuestionPageController gives you](#what-questionpagecontroller-gives-you)
+    - [Overridable members](#overridable-members)
 
 ### Changing the Nunjucks template
 
@@ -99,11 +106,14 @@ class SelectGrantSchemeController extends QuestionPageController {
     return async (request: FormRequest, context: FormContext, h: FormResponseToolkit) => {
       const farmType = context.state.farmType
 
+      // Support for multiple languages
+      const translator = this.getTranslator(request)
+
       // Fetch grant schemes available for the user's farm type
       const grantSchemes = await getEligibleGrantSchemes(farmType)
 
       // Build the standard view model and add the fetched data
-      const viewModel = this.getViewModel(request, context)
+      const viewModel = this.getViewModel(request, context, translator)
 
       return h.view(this.viewName, { ...viewModel, grantSchemes })
     }
@@ -153,9 +163,12 @@ import type { FormContext, FormRequestPayload, FormResponseToolkit } from '@defr
 class PassportLookupController extends QuestionPageController {
   makePostRouteHandler() {
     return async (request: FormRequestPayload, context: FormContext, h: FormResponseToolkit) => {
+      // Support for multiple languages
+      const translator = this.getTranslator(request)
+
       // Re-render with component validation errors if any
       if (context.errors) {
-        const viewModel = this.getViewModel(request, context)
+        const viewModel = this.getViewModel(request, context, translator)
         return h.view(this.viewName, viewModel)
       }
 
@@ -167,7 +180,7 @@ class PassportLookupController extends QuestionPageController {
       if (!passport) {
         // Re-render with a custom error — the input passed component validation
         // (format/required checks) but was not found in the external system
-        const viewModel = this.getViewModel(request, context)
+        const viewModel = this.getViewModel(request, context, translator)
         viewModel.errors = [{ text: 'Passport number not recognised. Check and try again.' }]
         return h.view(this.viewName, viewModel)
       }
@@ -222,10 +235,10 @@ class IneligiblePageController extends PageController {
 
 ### Overridable members
 
-| Member                           | Description                                                                                                                                                       |
-| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `viewName`                       | The Nunjucks template rendered for this page. Defaults to `'index'`. Set `view` on the page definition to override.                                               |
-| `allowSaveAndExit`               | Whether the "Save and exit" button is shown. `true` on `QuestionPageController`, `false` on `PageController`. Override as a class property to change the default. |
-| `getViewModel(request, context)` | Returns the view model passed to the Nunjucks template. Override to add or modify properties synchronously. Only available on `QuestionPageController`.           |
-| `makeGetRouteHandler()`          | Returns the async GET handler function. Override to control page load behaviour, including async data fetching.                                                   |
-| `makePostRouteHandler()`         | Returns the async POST handler function. Override to control form submission behaviour and write custom data to state.                                            |
+| Member                                       | Description                                                                                                                                                       |
+| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `viewName`                                   | The Nunjucks template rendered for this page. Defaults to `'index'`. Set `view` on the page definition to override.                                               |
+| `allowSaveAndExit`                           | Whether the "Save and exit" button is shown. `true` on `QuestionPageController`, `false` on `PageController`. Override as a class property to change the default. |
+| `getViewModel(request, context, translator)` | Returns the view model passed to the Nunjucks template. Override to add or modify properties synchronously. Only available on `QuestionPageController`.           |
+| `makeGetRouteHandler()`                      | Returns the async GET handler function. Override to control page load behaviour, including async data fetching.                                                   |
+| `makePostRouteHandler()`                     | Returns the async POST handler function. Override to control form submission behaviour and write custom data to state.                                            |

docs/features/index.md

@@ -31,3 +31,7 @@ Drive advanced functionality — such as calling APIs and rendering dynamic cont
 ### [Code-based Features](./features/code-based)
 
 Implement highly tailored behaviour by writing custom TypeScript/JavaScript that integrates with forms-engine-plugin's extension points.
+
+## [Multi-language support](./multi-language.md)
+
+Multiple languages, specifically English and Welsh, can be configured.

docs/features/multi-language.md

@@ -0,0 +1,25 @@
+# Multi-language (specifically English and Welsh)
+
+The `engine-plugin` supports 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 is constructed in the constructor of the `FormModel`.
+
+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.

jest.setup.cjs

@@ -1,3 +1,10 @@
+// Pre-load @defra/forms-model to ensure Joi internals are initialised before any test
+// file runs. This prevents a Symbol identity mismatch between the ESM-wrapped Joi
+// instance (created by babel-jest) and the CJS Joi instance used by Joi's internal
+// Template.isTemplate() check, which occurs when resetModules: true clears the
+// registry between tests.
+require('@defra/forms-model')
+
 process.env.REDIS_HOST = 'dummy'
 process.env.REDIS_KEY_PREFIX = 'forms-designer'
 process.env.REDIS_PASSWORD = 'dummy'

package.json

@@ -83,7 +83,7 @@
   },
   "engines": {
     "node": ">=22.11.0 <25.0.0",
-    "npm": ">=10.9.0 <11.6.4"
+    "npm": ">=10.9.0 <=11.17.0"
   },
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
@@ -126,6 +126,7 @@
     "highlight.js": "^11.11.1",
     "http-status-codes": "^2.3.0",
     "humanize-duration": "^3.33.1",
+    "i18next": "^26.0.5",
     "ioredis": "^5.8.2",
     "joi": "^17.13.3",
     "liquidjs": "^10.24.0",

scripts/generate-component-previews.js

@@ -5,6 +5,7 @@ import { markdownToHtml } from '@defra/forms-model'
 
 // Static imports so Jest can mock them (dynamic computed-path imports cannot be mocked).
 import { createComponent } from '~/src/server/plugins/engine/components/helpers/components.js'
+import { stubTranslator } from '~/src/server/plugins/engine/pageControllers/__stubs__/translator.js'
 import { environment } from '~/src/server/plugins/nunjucks/environment.js'
 
 // Register the markdown filter that the engine plugin normally adds at server init.
@@ -26,7 +27,11 @@ export function renderComponent(fixture) {
     /** @type {unknown} */ (fixture.model)
   )
   const component = createComponent(fixture.def, { model })
-  const viewModel = component.getViewModel(fixture.payload, [])
+  const viewModel = component.getViewModel({
+    payload: fixture.payload,
+    errors: [],
+    translator: stubTranslator
+  })
 
   // Apply large label/legend sizing to match how QuestionPageController styles
   // a single-component page. isPageHeading is intentionally omitted — setting it

scripts/generate-component-previews.test.js

@@ -27,6 +27,7 @@ import {
 } from './generate-component-previews.js'
 
 import { createComponent } from '~/src/server/plugins/engine/components/helpers/components.ts'
+import { stubTranslator } from '~/src/server/plugins/engine/pageControllers/__stubs__/translator.js'
 import { environment } from '~/src/server/plugins/nunjucks/environment.js'
 
 describe('component-preview-fixtures', () => {
@@ -132,6 +133,10 @@ describe('buildPartialMdx', () => {
 describe('renderComponent', () => {
   let mockGetViewModel
 
+  const mockModel = {
+    createTranslator: () => stubTranslator
+  }
+
   beforeEach(() => {
     mockGetViewModel = jest.fn().mockReturnValue({
       type: 'TextField',
@@ -145,22 +150,32 @@ describe('renderComponent', () => {
   })
 
   it('calls createComponent with def and model from fixture', () => {
-    renderComponent(fixtures.TextField)
+    renderComponent({
+      ...fixtures.TextField,
+      model: mockModel
+    })
     expect(createComponent).toHaveBeenCalledWith(fixtures.TextField.def, {
-      model: fixtures.TextField.model
+      model: mockModel
     })
   })
 
   it('calls getViewModel with payload and empty errors array', () => {
-    renderComponent(fixtures.TextField)
-    expect(mockGetViewModel).toHaveBeenCalledWith(
-      fixtures.TextField.payload,
-      []
-    )
+    renderComponent({
+      ...fixtures.TextField,
+      model: mockModel
+    })
+    expect(mockGetViewModel).toHaveBeenCalledWith({
+      payload: {},
+      errors: [],
+      translator: stubTranslator
+    })
   })
 
   it('passes viewModel wrapped as { type, model } to renderString', () => {
-    renderComponent(fixtures.TextField)
+    renderComponent({
+      ...fixtures.TextField,
+      model: mockModel
+    })
     expect(environment.renderString).toHaveBeenCalledWith(
       expect.stringContaining('componentList'),
       expect.objectContaining({

scripts/page-preview-fixtures.js

@@ -65,9 +65,14 @@ function pageViewContext({
       server: { plugins: { 'forms-engine-plugin': {} } }
     })
   )
+  const translator = model.createTranslator()
   return getViewModelOverride
     ? getViewModelOverride(controller, model, mockRequest, mockContext)
-    : controller.getViewModel(/** @type {any} */ (mockRequest), mockContext)
+    : controller.getViewModel(
+        /** @type {any} */ (mockRequest),
+        mockContext,
+        translator
+      )
 }
 
 const fileUploadWithFilesVariant = /** @type {any} */ (
@@ -192,13 +197,18 @@ export const pageFixtures = {
           ]
         }
       ],
-      getViewModelOverride: (ctrl, _model, req, ctx) => {
+      getViewModelOverride: (ctrl, model, req, ctx) => {
         const repeat = /** @type {RepeatPageController} */ (ctrl)
-        const vm = repeat.getListSummaryViewModel(req, ctx, [
-          { itemId: '1', fullname: 'Sarah Phillips' },
-          { itemId: '2', fullname: 'David Jones' },
-          { itemId: '3', fullname: 'Emma Wilson' }
-        ])
+        const vm = repeat.getListSummaryViewModel(
+          req,
+          ctx,
+          [
+            { itemId: '1', fullname: 'Sarah Phillips' },
+            { itemId: '2', fullname: 'David Jones' },
+            { itemId: '3', fullname: 'Emma Wilson' }
+          ],
+          model.createTranslator()
+        )
         return /** @type {PageViewModel} */ (
           /** @type {unknown} */ ({
             ...vm,
@@ -300,10 +310,12 @@ export const pageFixtures = {
       ],
       renderPage: '/summary',
       state: { fullname: 'Sarah Phillips', email: 'sarah@example.gov.uk' },
-      getViewModelOverride: (ctrl, _model, req, ctx) => {
+      getViewModelOverride: (ctrl, model, req, ctx) => {
         const summary = /** @type {SummaryPageController} */ (ctrl)
         return /** @type {PageViewModel} */ (
-          /** @type {unknown} */ (summary.getSummaryViewModel(req, ctx))
+          /** @type {unknown} */ (
+            summary.getSummaryViewModel(req, ctx, model.createTranslator())
+          )
         )
       }
     })

src/server/forms/register-as-a-unicorn-breeder.yaml

@@ -242,20 +242,6 @@ pages:
         content: 'Fill in this field'
         options:
           required: false
-    next:
-      - path: '/pay-for-your-licence'
-  - title: Pay for your licence
-    path: '/pay-for-your-licence'
-    section: section
-    components:
-      - name: licencePayment
-        title: Unicorn breeder licence fee
-        type: PaymentField
-        hint: You'll be redirected to GOV.UK Pay to complete your payment
-        options:
-          required: true
-          amount: 50
-          description: Unicorn breeder annual licence fee
     next:
       - path: '/summary'
 conditions: