@defra/forms-engine-plugin 4.23.0 → 5.0.0-alpha.1

package/src/server/plugins/engine/i18n/types.ts

@@ -0,0 +1,62 @@
+import {
+  type ComponentDef,
+  type Item,
+  type Page,
+  type Section
+} from '@defra/forms-model'
+
+/**
+ * Structure of the `translations` block in a form definition.
+ * Also used to derive the valid property keys for the typed tX functions.
+ */
+export type FormDefinitionTranslations = Record<
+  string,
+  {
+    pages: Record<string, Partial<{ title: string; repeatTitle: string }>>
+    // ComponentDef is a discriminated union; Pick across the full union is not feasible.
+    // The four keys below are the complete set of translatable component properties.
+    components: Record<
+      string,
+      Partial<{
+        title: string
+        hint: string
+        content: string
+        shortDescription: string
+      }>
+    >
+    sections: Record<string, Partial<Pick<Section, 'title'>>>
+    listItems: Record<string, Partial<Pick<Item, 'text' | 'hint'>>>
+    form: Record<string, string>
+  }
+>
+
+type EntityTranslations = FormDefinitionTranslations[string]
+
+/**
+ * Scoped translator returned by model.createTranslator(language).
+ * t          — plugin namespace (UI strings, buttons, errors, sub-field labels)
+ * tForm      — form namespace: form attributes, currently only form name
+ * tPage      — form namespace: page titles
+ * tComponent — form namespace: component titles, hints, shortDescriptions
+ * tSection   — form namespace: section titles
+ * tListItem  — form namespace: list item text
+ * language   - current language
+ */
+export interface Translator {
+  t: (key: string, opts?: Record<string, unknown>) => string
+  tForm: (prop: string) => string
+  tPage: (page: Page, prop: keyof EntityTranslations['pages'][string]) => string
+  tComponent: (
+    component: ComponentDef,
+    prop: keyof EntityTranslations['components'][string]
+  ) => string
+  tSection: (
+    section: Section,
+    prop: keyof EntityTranslations['sections'][string]
+  ) => string
+  tListItem: (
+    item: Item,
+    prop: keyof EntityTranslations['listItems'][string]
+  ) => string
+  language: string
+}

package/src/server/plugins/engine/index.ts

@@ -8,7 +8,8 @@ import {
   checkComponentTemplates,
   checkErrorTemplates,
   evaluate,
-  govukRebrand
+  govukRebrand,
+  tGlobal
 } from '../nunjucks/environment.js'
 import * as filters from '../nunjucks/filters/index.js'
 
@@ -26,7 +27,8 @@ const globals = {
   checkComponentTemplates,
   checkErrorTemplates,
   evaluate,
-  govukRebrand
+  govukRebrand,
+  t: tGlobal
 }
 
 export const VIEW_PATH = 'src/server/plugins/engine/views'

package/src/server/plugins/engine/models/FormModel.ts

@@ -27,6 +27,7 @@ import {
 } from '@defra/forms-model'
 import { add, format } from 'date-fns'
 import { Parser, type Value } from 'expr-eval-fork'
+import { type i18n } from 'i18next'
 import joi from 'joi'
 
 import { logger } from '../../../common/helpers/logging/logger.js'
@@ -40,9 +41,13 @@ import { todayAsDateOnly } from '../date-helper.js'
 import {
   findPage,
   getError,
-  getPage,
-  setPageTitles
+  getPage
 } from '../helpers.js'
+import { loadFormTranslations } from '../i18n/createFormTranslator.js'
+import { createTranslator } from '../i18n/createTranslator.js'
+import { extractBaseTranslations } from '../i18n/extractBaseTranslations.js'
+import { createFormI18nInstance } from '../i18n/index.js'
+import { type Translator } from '../i18n/types.js'
 import { type ExecutableCondition } from './types.js'
 import { type PageController } from '../pageControllers/PageController.js'
 import {
@@ -81,6 +86,7 @@ export class FormModel {
   conditions: Partial<Record<string, ExecutableCondition>>
   pages: PageControllerClass[]
   services: Services
+  private readonly i18nInstance: i18n
 
   controllers?: Record<string, typeof PageController>
   pageDefMap: Map<string, Page>
@@ -123,7 +129,12 @@ export class FormModel {
     // by joi so as not to change the source data.
     def = structuredClone(result.value)
 
-    // Add default lists
+    const baseTranslations = extractBaseTranslations(def)
+    this.i18nInstance = createFormI18nInstance(baseTranslations)
+    loadFormTranslations(def, this.i18nInstance)
+
+    // Add default lists. Yes/No text stored as i18n key constants so they
+    // resolve to the user's language at render time via the translator.
     def.lists.push({
       id: def.schema === SchemaVersion.V1 ? yesNoListName : yesNoListId,
       name: '__yesNo',
@@ -132,20 +143,17 @@ export class FormModel {
       items: [
         {
           id: '02900d42-83d1-4c72-a719-c4e8228952fa',
-          text: 'Yes',
+          text: 'components.yesNoField.yes',
           value: true
         },
         {
           id: 'f39000eb-c51b-4019-8f82-bbda0423f04d',
-          text: 'No',
+          text: 'components.yesNoField.no',
           value: false
         }
       ]
     })
 
-    // Fix up page titles
-    setPageTitles(def)
-
     this.engine = def.engine
     this.schemaVersion = def.schema ?? SchemaVersion.V1
     this.def = def
@@ -213,7 +221,7 @@ export class FormModel {
     ) {
       this.pages.push(
         createPage(this, {
-          title: 'Form submitted',
+          title: 'pages.confirmation.formSubmitted',
           path: ControllerPath.Status,
           controller: ControllerType.Status
         })
@@ -231,6 +239,11 @@ export class FormModel {
     )
   }
 
+  /** Returns a scoped translator pair for the given language. */
+  createTranslator(language = 'en-GB'): Translator {
+    return createTranslator(this.i18nInstance, language)
+  }
+
   /**
    * build the entire model schema from individual pages/sections and filter out answers
    * for pages which are no longer accessible due to an answer that has been changed
@@ -337,7 +350,8 @@ export class FormModel {
   getFormContext(
     request: FormContextRequest,
     state: FormSubmissionState,
-    errors?: FormSubmissionError[]
+    errors?: FormSubmissionError[],
+    translator?: Translator
   ): FormContext {
     const { query } = request
 
@@ -365,11 +379,13 @@ export class FormModel {
       componentDefMap: this.componentDefMap,
       pageMap: this.pageMap,
       componentMap: this.componentMap,
-      referenceNumber: getReferenceNumber(state)
+      referenceNumber: getReferenceNumber(state),
+      languages: getAvailableLanguages(this.def),
+      translator
     }
 
     // Validate current page
-    context = validateFormPayload(request, page, context)
+    context = validateFormPayload(request, page, context, translator)
 
     // Find start page
     let nextPage = findPage(this, startPath)
@@ -387,7 +403,7 @@ export class FormModel {
 
       // Stop at current page
       if (
-        this.pageStateIsInvalid(context, nextPage) ||
+        this.pageStateIsInvalid(context, nextPage, translator) ||
         nextPage.path === currentPath
       ) {
         break
@@ -448,7 +464,11 @@ export class FormModel {
     }
   }
 
-  private pageStateIsInvalid(context: FormContext, page: PageControllerClass) {
+  private pageStateIsInvalid(
+    context: FormContext,
+    page: PageControllerClass,
+    translator?: Translator
+  ) {
     // Get any list-bound fields on the page
     const listFields = page.collection.fields.filter(hasListFormField)
 
@@ -464,7 +484,7 @@ export class FormModel {
           list.items.filter((item) => item.condition).length > 0
 
         if (hasOptionalItems) {
-          return this.fieldStateIsInvalid(context, field, list)
+          return this.fieldStateIsInvalid(context, field, list, translator)
         }
       }
     }
@@ -473,7 +493,8 @@ export class FormModel {
   private fieldStateIsInvalid(
     context: FormContext,
     field: ListFormComponent,
-    list: List
+    list: List,
+    translator?: Translator
   ) {
     const { evaluationState, state } = context
 
@@ -503,8 +524,9 @@ export class FormModel {
       if (isInvalid) {
         context.errors ??= []
 
-        const text =
-          'Options are different because you changed a previous answer'
+        const text = (translator ?? this.createTranslator('en-GB')).t(
+          'errors.optionsMismatch'
+        )
 
         context.errors.push({
           text,
@@ -571,7 +593,8 @@ export class FormModel {
 function validateFormPayload(
   request: FormContextRequest,
   page: PageControllerClass,
-  context: FormContext
+  context: FormContext,
+  translator?: Translator
 ): FormContext {
   const { collection } = page
   const { payload, state } = context
@@ -601,10 +624,10 @@ function validateFormPayload(
     }
   })
 
-  const { value, errors } = collection.validate({
-    ...payload,
-    ...update
-  })
+  const { value, errors } = collection.validate(
+    { ...payload, ...update },
+    translator
+  )
 
   // Add sanitised payload (ready to save)
   const formState = page.getStateFromValidForm(request, state, value)
@@ -656,3 +679,16 @@ function getReferenceNumber(state: FormSubmissionState): string {
 
   return state.$$__referenceNumber
 }
+
+export function getAvailableLanguages(
+  def: FormDefinition
+): { name: string; code: string }[] {
+  // @ts-expect-error - dynamic property
+  if (def.metadata?.translations?.cy) {
+    return [
+      { name: 'English', code: 'en-GB' },
+      { name: 'Cymraeg', code: 'cy' }
+    ]
+  }
+  return []
+}

package/src/server/plugins/engine/models/SummaryViewModel.ts

@@ -1,4 +1,8 @@
-import { SchemaVersion, type Section } from '@defra/forms-model'
+import {
+  SchemaVersion,
+  type ComponentDef,
+  type Section
+} from '@defra/forms-model'
 
 import { PaymentField } from '../components/PaymentField.js'
 import { type PaymentState } from '../components/PaymentField.types.js'
@@ -15,6 +19,7 @@ import {
   getError,
   getPageHref
 } from '../helpers.js'
+import { type Translator } from '../i18n/types.js'
 import {
   type Detail,
   type DetailItem,
@@ -56,22 +61,29 @@ export class SummaryViewModel {
   allowSaveAndExit = false
   paymentState?: PaymentState
   paymentDetails?: CheckAnswers
+  t: (key: string, opts?: Record<string, unknown>) => string
+  private readonly _translator!: Translator
   paymentRequired?: boolean
   paymentPreAuthorized?: boolean
 
   constructor(
     request: FormContextRequest,
     page: PageControllerClass,
-    context: FormContext
+    context: FormContext,
+    translator: Translator
   ) {
     const { model } = page
     const { basePath, def, sections } = model
     const { isForceAccess } = context
 
+    const { t } = translator
+    this.t = t
+    this._translator = translator
+
     this.page = page
     this.pageTitle = page.title
     if (def.schema === SchemaVersion.V2 && !page.title) {
-      this.pageTitle = 'Check your answers before sending your form'
+      this.pageTitle = t('pages.summary.title')
     }
 
     this.serviceUrl = `/${basePath}`
@@ -85,7 +97,7 @@ export class SummaryViewModel {
 
     // Format errors
     this.errors = result.error?.details.map(getError)
-    this.details = this.summaryDetails(request, sections)
+    this.details = this.summaryDetails(request, sections, translator)
 
     // Format check answers
     this.checkAnswers = this.details.map((detail): CheckAnswers => {
@@ -98,7 +110,7 @@ export class SummaryViewModel {
         if (!isForceAccess) {
           items.push({
             href: item.href,
-            text: 'Change',
+            text: t('pages.summary.change'),
             classes: 'govuk-link--no-visited-state',
             visuallyHiddenText: item.label
           })
@@ -110,7 +122,7 @@ export class SummaryViewModel {
           },
           value: {
             classes: 'app-prose-scope',
-            html: item.value || 'Not provided'
+            html: item.value || t('pages.summary.notProvided')
           },
           actions: {
             items
@@ -125,7 +137,11 @@ export class SummaryViewModel {
     })
   }
 
-  private summaryDetails(request: FormContextRequest, sections: Section[]) {
+  private summaryDetails(
+    request: FormContextRequest,
+    sections: Section[],
+    translator: Translator
+  ) {
     const { context, errors } = this
     const { relevantPages, state } = context
 
@@ -143,10 +159,15 @@ export class SummaryViewModel {
 
         if (page instanceof RepeatPageController) {
           items.push(
-            ItemRepeat(page, state, {
-              path: page.getSummaryPath(request),
-              errors
-            })
+            ItemRepeat(
+              page,
+              state,
+              {
+                path: page.getSummaryPath(request),
+                errors
+              },
+              translator
+            )
           )
         } else {
           for (const field of collection.fields) {
@@ -154,15 +175,20 @@ export class SummaryViewModel {
             if (field instanceof PaymentField) {
               continue
             }
-            items.push(ItemField(page, state, field, { path, errors }))
+            items.push(
+              ItemField(page, state, field, { path, errors }, translator)
+            )
           }
         }
       })
 
       if (items.length) {
+        const sectionTitle = section
+          ? translator.tSection(section, 'title') || section.title
+          : undefined
         details.push({
           name: section?.name,
-          title: section?.title,
+          title: sectionTitle,
           items
         })
       }
@@ -182,19 +208,22 @@ function ItemRepeat(
   options: {
     path: string
     errors?: FormSubmissionError[]
-  }
+  },
+  translator: Translator
 ): DetailItemRepeat {
   const { collection, repeat } = page
   const { name, title } = repeat.options
 
   const values = page.getListFromState(state)
-  const unit = values.length === 1 ? 'answer' : 'answers'
+  const count = values.length
+  const value =
+    count === 0 ? '' : translator.t('pages.repeater.pageTitle', { count })
 
   return {
     name,
     label: title,
     title,
-    value: values.length ? `You have added ${values.length} ${unit}` : '',
+    value,
     href: getPageHref(page, options.path, {
       returnUrl: getPageHref(page, page.getSummaryPath())
     }),
@@ -204,7 +233,7 @@ function ItemRepeat(
     // Repeater field detail items
     subItems: values.map((repeatState) =>
       collection.fields.map((field) =>
-        ItemField(page, repeatState, field, options)
+        ItemField(page, repeatState, field, options, translator)
       )
     )
   }
@@ -221,17 +250,31 @@ export function ItemField(
   options: {
     path: string
     errors?: FormSubmissionError[]
-  }
+  },
+  translator: Translator
 ): DetailItemField {
+  // FormComponent doesn't expose shortDescription/title as raw def properties,
+  // so build a lookup object with English values to let tComponent's GUID lookup fire.
+  const fieldDef = {
+    id: field.id,
+    type: field.type,
+    shortDescription: field.label,
+    title: field.title
+  } as unknown as ComponentDef
+  const rawLabel = translator.tComponent(fieldDef, 'shortDescription')
+  const translatedLabel = rawLabel !== '' ? rawLabel : field.label
+  const rawTitle = translator.tComponent(fieldDef, 'title')
+  const translatedTitle = rawTitle !== '' ? rawTitle : field.title
+  const optional =
+    field.options.required === false
+      ? ` ${translator.t('common.optional')}`
+      : ''
   return {
     name: field.name,
-    label: field.title,
-    title:
-      field.options.required === false
-        ? `${field.summaryLabel} (optional)`
-        : field.summaryLabel,
-    error: field.getFirstError(options.errors),
-    value: getAnswer(field, state),
+    label: translatedTitle,
+    title: `${translatedLabel}${optional}`,
+    error: field.getFirstError(translator, options.errors),
+    value: getAnswer(field, state, translator, { format: 'summary' }),
     href: getPageHref(page, options.path, {
       returnUrl: getPageHref(page, page.getSummaryPath())
     }),

package/src/server/plugins/engine/options.js

@@ -25,7 +25,8 @@ const pluginRegistrationOptionsSchema = Joi.object({
   baseUrl: Joi.string().uri().required(),
   saveAndExit: Joi.function().optional(),
   ordnanceSurveyApiKey: Joi.string().optional(),
-  ordnanceSurveyApiSecret: Joi.string().optional()
+  ordnanceSurveyApiSecret: Joi.string().optional(),
+  getLanguage: Joi.function().optional()
 })
 
 /**

package/src/server/plugins/engine/outputFormatters/adapter/v1.ts

@@ -49,6 +49,11 @@ export function format(
     meta.versionMetadata = versionMetadata
   }
 
+  const definitionLanguage = model.def.metadata?.language
+  if (typeof definitionLanguage === 'string') {
+    meta.language = definitionLanguage
+  }
+
   const main = Object.fromEntries(
     Object.entries(v2Main).map(([key, value]) => {
       if (value === undefined) {

package/src/server/plugins/engine/outputFormatters/human/v1.ts

@@ -30,6 +30,7 @@ export function format(
   formStatus: ReturnType<typeof checkFormStatus>,
   _formMetadata?: FormMetadata
 ) {
+  const translator = model.createTranslator()
   const { files } = submitResponse.result
 
   const formName = escapeMarkdown(model.name)
@@ -72,9 +73,7 @@ export function format(
       lines.push(`[${filename}](${designerUrl}/file-download/${fileId})\n`)
     } else {
       lines.push(
-        getAnswer(item.field, item.state, {
-          format: 'email'
-        })
+        getAnswer(item.field, item.state, translator, { format: 'email' })
       )
     }
 

package/src/server/plugins/engine/outputFormatters/machine/v1.ts

@@ -7,6 +7,7 @@ import { config } from '../../../../../config/index.js'
 import { getAnswer } from '../../components/helpers/components.js'
 import { FileUploadField } from '../../components/index.js'
 import { type checkFormStatus } from '../../helpers.js'
+import { type Translator } from '../../i18n/types.js'
 import { type FormModel } from '../../models/index.js'
 import {
   type DetailItem,
@@ -25,9 +26,10 @@ export function format(
   _formStatus: ReturnType<typeof checkFormStatus>,
   _formMetadata?: FormMetadata
 ) {
+  const translator = model.createTranslator()
   const now = new Date()
 
-  const categorisedData = categoriseData(items)
+  const categorisedData = categoriseData(items, translator)
 
   const data = {
     meta: {
@@ -68,7 +70,7 @@ export function format(
  *    }
  * }
  */
-function categoriseData(items: DetailItem[]) {
+function categoriseData(items: DetailItem[], translator: Translator) {
   const output: {
     main: Record<string, string>
     repeaters: Record<string, Record<string, string>[]>
@@ -77,11 +79,11 @@ function categoriseData(items: DetailItem[]) {
 
   items.forEach((item) => {
     if ('subItems' in item) {
-      output.repeaters[item.name] = extractRepeaters(item)
+      output.repeaters[item.name] = extractRepeaters(item, translator)
     } else if (isFileUploadFieldItem(item)) {
       output.files[item.name] = extractFileUploads(item)
     } else {
-      output.main[item.name] = getAnswer(item.field, item.state, {
+      output.main[item.name] = getAnswer(item.field, item.state, translator, {
         format: 'data'
       })
     }
@@ -95,7 +97,7 @@ function categoriseData(items: DetailItem[]) {
  * @param item - the repeater item
  * @returns the repeater item
  */
-function extractRepeaters(item: DetailItemRepeat) {
+function extractRepeaters(item: DetailItemRepeat, translator: Translator) {
   const repeaters: Record<string, string>[] = []
 
   item.subItems.forEach((inputRepeaterItem) => {
@@ -105,9 +107,8 @@ function extractRepeaters(item: DetailItemRepeat) {
       outputRepeaterItem[repeaterComponent.name] = getAnswer(
         repeaterComponent.field,
         repeaterComponent.state,
-        {
-          format: 'data'
-        }
+        translator,
+        { format: 'data' }
       )
     })
 

package/src/server/plugins/engine/pageControllers/FileUploadPageController.ts

@@ -14,6 +14,7 @@ import {
   getError,
   getExponentialBackoffDelay
 } from '../helpers.js'
+import { type Translator } from '../i18n/types.js'
 import { type FormModel } from '../models/index.js'
 import { QuestionPageController } from './QuestionPageController.js'
 import { getProxyUrlForLocalDevelopment } from './helpers/index.js'
@@ -187,10 +188,12 @@ export class FileUploadPageController extends QuestionPageController {
 
       const { filename } = fileToRemove.status.form.file
 
+      const { t } = this.getTranslator(request)
+
       return h.view(this.fileDeleteViewName, {
         ...viewModel,
         context,
-        backLink: this.getBackLink(request, context),
+        backLink: this.getBackLink(request, context, t),
         pageTitle: `Are you sure you want to remove this file?`,
         itemTitle: filename,
         confirmation: { text: 'You cannot recover removed files.' },
@@ -258,14 +261,15 @@ export class FileUploadPageController extends QuestionPageController {
 
   getViewModel(
     request: FormContextRequest,
-    context: FormContext
+    context: FormContext,
+    translator: Translator
   ): FeaturedFormPageViewModel {
     const { fileUpload } = this
     const { state } = context
 
     const upload = this.getUploadFromState(state)
 
-    const viewModel = super.getViewModel(request, context)
+    const viewModel = super.getViewModel(request, context, translator)
     const { components } = viewModel
 
     // Featured form component

package/src/server/plugins/engine/pageControllers/PageController.ts

@@ -15,9 +15,11 @@ import {
   getStartPath,
   normalisePath
 } from '../helpers.js'
+import { type Translator } from '../i18n/types.js'
 import { type FormModel } from '../models/index.js'
 import { type ExecutableCondition } from '../models/types.js'
 import {
+  type AnyFormRequest,
   type FormContext,
   type PageViewModelBase
 } from '../types.js'
@@ -28,6 +30,7 @@ import {
   type FormRequestRefs,
   type FormResponseToolkit
 } from '../../../routes/types.js'
+import { resolveLanguage } from '../../../utils/utils.js'
 
 export class PageController {
   /**
@@ -161,6 +164,10 @@ export class PageController {
     return ControllerPath.Status.valueOf()
   }
 
+  protected getTranslator(request: AnyFormRequest): Translator {
+    return this.model.createTranslator(resolveLanguage(request))
+  }
+
   makeGetRouteHandler(): (
     request: FormRequest,
     context: FormContext,
@@ -168,7 +175,11 @@ export class PageController {
   ) => ReturnType<Lifecycle.Method<FormRequestRefs>> {
     return (request, context, h) => {
       const { viewModel, viewName } = this
-      return h.view(viewName, viewModel)
+      const { t } = this.getTranslator(request)
+      return h.view(viewName, {
+        ...viewModel,
+        t
+      })
     }
   }