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

package/src/server/plugins/engine/components/UkAddressField.ts

@@ -8,7 +8,8 @@ import {
   isFormState
 } from './FormComponent.js'
 import { TextField } from './TextField.js'
-import { type QuestionPageController } from '../pageControllers/QuestionPageController.js'
+import { type RenderContext } from './types.js'
+import { type Translator } from '../i18n/types.js'
 import {
   type FormRequestPayload,
   type FormResponseToolkit
@@ -23,6 +24,7 @@ import {
   type PostcodeLookupExternalArgs
 } from '../types.js'
 import { dispatch } from '../../postcode-lookup/routes/index.js'
+import { resolveLanguage } from '../../../utils/utils.js'
 
 export class UkAddressField extends FormComponent {
   declare options: UkAddressFieldComponent['options']
@@ -41,13 +43,12 @@ export class UkAddressField extends FormComponent {
     const isRequired = options.required !== false
     const hideOptional = !!options.optionalText
     const hideTitle = !!options.hideTitle
-
     this.collection = new ComponentCollection(
       [
         {
           type: ComponentType.TextField,
           name: `${name}__uprn`,
-          title: 'UPRN',
+          title: 'components.addressField.uprn',
           schema: {},
           options: {
             required: false,
@@ -57,7 +58,7 @@ export class UkAddressField extends FormComponent {
         {
           type: ComponentType.TextField,
           name: `${name}__addressLine1`,
-          title: 'Address line 1',
+          title: 'components.addressField.line1',
           schema: { max: 100 },
           options: {
             autocomplete: 'address-line1',
@@ -68,7 +69,7 @@ export class UkAddressField extends FormComponent {
         {
           type: ComponentType.TextField,
           name: `${name}__addressLine2`,
-          title: 'Address line 2',
+          title: 'components.addressField.line2',
           schema: { max: 100 },
           options: {
             autocomplete: 'address-line2',
@@ -79,7 +80,7 @@ export class UkAddressField extends FormComponent {
         {
           type: ComponentType.TextField,
           name: `${name}__town`,
-          title: 'Town or city',
+          title: 'components.addressField.town',
           schema: { max: 100 },
           options: {
             autocomplete: 'address-level2',
@@ -91,7 +92,7 @@ export class UkAddressField extends FormComponent {
         {
           type: ComponentType.TextField,
           name: `${name}__county`,
-          title: 'County',
+          title: 'components.addressField.county',
           schema: { max: 100 },
           options: {
             autocomplete: 'address-level1',
@@ -102,7 +103,7 @@ export class UkAddressField extends FormComponent {
         {
           type: ComponentType.TextField,
           name: `${name}__postcode`,
-          title: 'Postcode',
+          title: 'components.addressField.postcode',
           schema: {
             regex: '^[a-zA-Z]{1,2}\\d[a-zA-Z\\d]?\\s?\\d[a-zA-Z]{2}$'
           },
@@ -143,23 +144,32 @@ export class UkAddressField extends FormComponent {
     return this.getContextValueFromFormValue(value)
   }
 
-  getDisplayStringFromFormValue(value: UkAddressState | undefined): string {
+  getDisplayStringFromFormValue(
+    value: UkAddressState | undefined,
+    _translator: Translator
+  ): string {
     return this.getContextValueFromFormValue(value)?.join(', ') ?? ''
   }
 
-  getDisplayStringFromState(state: FormSubmissionState) {
+  getDisplayStringFromState(
+    state: FormSubmissionState,
+    translator: Translator
+  ) {
     const value = this.getFormValueFromState(state)
 
-    return this.getDisplayStringFromFormValue(value)
+    return this.getDisplayStringFromFormValue(value, translator)
   }
 
   /**
    * Returns one error per child field
    */
   getViewErrors(
+    translator: Translator,
     errors?: FormSubmissionError[]
   ): FormSubmissionError[] | undefined {
-    const uniqueErrors = this.getErrors(errors)?.filter(
+    const { t } = translator
+
+    const uniqueErrors = this.getErrors(translator, errors)?.filter(
       (error, index, self) =>
         index === self.findIndex((err) => err.name === error.name)
     )
@@ -174,7 +184,9 @@ export class UkAddressField extends FormComponent {
           name,
           path: [name],
           href: `#${name}`,
-          text: `Enter ${lowerFirst(label)}`
+          text: t('components.addressField.enterAddress', {
+            shortDescription: lowerFirst(label)
+          })
         }
       ]
     }
@@ -182,10 +194,11 @@ export class UkAddressField extends FormComponent {
     return uniqueErrors
   }
 
-  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
+  getViewModel(context: RenderContext) {
+    const { payload, translator } = context
     const { collection, name, options } = this
 
-    const viewModel = super.getViewModel(payload, errors)
+    const viewModel = super.getViewModel(context)
     let { fieldset, hint, label } = viewModel
 
     fieldset ??= {
@@ -209,7 +222,7 @@ export class UkAddressField extends FormComponent {
       }
     }
 
-    const components = collection.getViewModel(payload, errors)
+    const components = collection.getViewModel(context)
 
     // Hide UPRN
     const uprn = components.at(0)
@@ -224,7 +237,7 @@ export class UkAddressField extends FormComponent {
     const usePostcodeLookup = this.shouldUsePostcodeLookup()
 
     const value = usePostcodeLookup
-      ? this.getDisplayStringFromState(payload)
+      ? this.getDisplayStringFromState(payload, translator)
       : undefined
 
     return {
@@ -284,6 +297,7 @@ export class UkAddressField extends FormComponent {
     args: PostcodeLookupExternalArgs
   ) {
     const { controller, component } = args
+    const language = resolveLanguage(request)
 
     return dispatch(request, h, {
       formName: controller.model.name,
@@ -291,7 +305,8 @@ export class UkAddressField extends FormComponent {
       componentHint: component.hint,
       componentTitle: component.title || controller.title,
       step: args.actionArgs.step,
-      sourceUrl: args.sourceUrl
+      sourceUrl: args.sourceUrl,
+      language
     })
   }
 }

package/src/server/plugins/engine/components/YesNoField.ts

@@ -4,9 +4,12 @@ import {
   yesNoListName,
   type YesNoFieldComponent
 } from '@defra/forms-model'
+import { type LanguageMessages } from 'joi'
 
 import { SelectionControlField } from './SelectionControlField.js'
 import { addClassOptionIfNone } from './helpers/index.js'
+import { buildValidationMessages } from '../i18n/buildValidationMessages.js'
+import { type Translator } from '../i18n/types.js'
 import { messageTemplate } from '../pageControllers/validationOptions.js'
 import { type ErrorMessageTemplateList } from '../types.js'
 import { convertToLanguageMessages } from '../../../utils/type-utils.js'
@@ -52,6 +55,13 @@ export class YesNoField extends SelectionControlField {
     this.options = options
   }
 
+  getValidationMessagesOverride(translator: Translator): LanguageMessages {
+    const { selectYesNoRequired } = buildValidationMessages(translator.t)
+    return convertToLanguageMessages({
+      'any.required': selectYesNoRequired
+    })
+  }
+
   /**
    * For error preview page that shows all possible errors on a component
    */

package/src/server/plugins/engine/components/helpers/components.ts

@@ -6,6 +6,7 @@ import { ListFormComponent } from '../ListFormComponent.js'
 import { escapeMarkdown } from './index.js'
 import * as Components from '../index.js'
 import { markdown } from '../markdownParser.js'
+import { type Translator } from '../../i18n/types.js'
 import { type FormState } from '../../types.js'
 
 // All component instances
@@ -221,6 +222,7 @@ export function createComponent(
 export function getAnswer(
   field: Field,
   state: FormState,
+  translator: Translator,
   options: {
     format:
       | 'data' // Submission data
@@ -230,7 +232,7 @@ export function getAnswer(
 ) {
   // Use escaped display text for GOV.UK Notify emails
   if (options.format === 'email') {
-    return getAnswerMarkdown(field, state, { format: 'email' })
+    return getAnswerMarkdown(field, state, translator, { format: 'email' })
   }
 
   // Use context value for submission data
@@ -248,12 +250,15 @@ export function getAnswer(
     field instanceof Components.LatLongField
   ) {
     return markdown
-      .parse(getAnswerMarkdown(field, state), { async: false })
+      .parse(
+        getAnswerMarkdown(field, state, translator, { format: 'summary' }),
+        { async: false }
+      )
       .trim()
   }
 
   // Use display text for check answers summary (single line)
-  return field.getDisplayStringFromState(state)
+  return field.getDisplayStringFromState(state, translator)
 }
 
 /**
@@ -262,13 +267,14 @@ export function getAnswer(
 export function getAnswerMarkdown(
   field: Field,
   state: FormState,
+  translator: Translator,
   options: {
     format:
       | 'email' // GOV.UK Notify emails
       | 'summary' // Check answers summary
   } = { format: 'summary' }
 ) {
-  const answer = field.getDisplayStringFromState(state)
+  const answer = field.getDisplayStringFromState(state, translator)
 
   // Use escaped display text
   let answerEscaped = `${escapeMarkdown(answer)}\n`
@@ -305,7 +311,8 @@ export function getAnswerMarkdown(
     // Append bullet points
     answerEscaped += items
       .map((item) => {
-        const label = escapeMarkdown(item.text)
+        const resolvedText = translator.tListItem(item, 'text') || item.text
+        const label = escapeMarkdown(resolvedText)
         const value = escapeMarkdown(`(${item.value})`)
 
         let line = label
@@ -344,7 +351,7 @@ export function getAnswerMarkdown(
     answerEscaped = contextValue ? `${contextValue}\n` : ''
   } else if (field instanceof Components.GeospatialField) {
     const features = field.getFormValueFromState(state)
-    const value = field.getDisplayStringFromFormValue(features)
+    const value = field.getDisplayStringFromFormValue(features, translator)
 
     answerEscaped = value ? `${value}\n` : ''
   }

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

@@ -1,11 +1,20 @@
 import { type ComponentType, type Item } from '@defra/forms-model'
 
+import { type Translator } from '../i18n/types.js'
 import {
+  type FormPayload,
   type FormSubmissionError,
   type FormValue,
   type SummaryList
 } from '../types.js'
 
+export interface RenderContext {
+  payload: FormPayload
+  errors: FormSubmissionError[] | undefined
+  translator: Translator
+  isForceAccess?: boolean
+}
+
 export type ComponentText = {
   classes?: string
   attributes?: string | Record<string, string>

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

@@ -1,6 +1,8 @@
 import { join, parse } from 'node:path'
 
 import { type FormDefinition } from '@defra/forms-model'
+import { type RequestQuery } from '@hapi/hapi'
+import { type Yar } from '@hapi/yar'
 
 import { FORM_PREFIX } from '../../constants.js'
 import { FormModel } from './models/FormModel.js'
@@ -67,7 +69,16 @@ export const configureEnginePlugin = async (
       baseUrl: 'http://localhost:3009', // always runs locally
       saveAndExit,
       ordnanceSurveyApiKey,
-      ordnanceSurveyApiSecret
+      ordnanceSurveyApiSecret,
+      getLanguage: (query: RequestQuery = {}, yar?: Yar) => {
+        const defaultLang = 'en-GB'
+
+        if (yar && 'language' in query) {
+          yar.set('language', query.language)
+        }
+
+        return yar?.get('language') ?? defaultLang
+      }
     }
   }
 }

package/src/server/plugins/engine/form-context.ts

@@ -13,6 +13,7 @@ import { type PageController } from './pageControllers/PageController.js'
 import { TerminalPageController } from './pageControllers/index.js'
 import * as defaultServices from './services/index.js'
 import {
+  type AnyFormRequest,
   type AnyRequest,
   type FormContext,
   type FormContextRequest,
@@ -21,6 +22,7 @@ import {
 } from './types.js'
 import { FormStatus } from '../../routes/types.js'
 import { type Services } from '../../types.js'
+import { resolveLanguage } from '../../utils/utils.js'
 
 type JourneyState = FormStatus | 'preview'
 
@@ -36,6 +38,7 @@ export interface FormModelOptions {
 
 export interface FormContextOptions extends FormModelOptions {
   errors?: FormSubmissionError[]
+  language?: string
 }
 
 type SummaryRequest = FormContextRequest & {
@@ -119,10 +122,14 @@ export async function getFormContext(
     $$__referenceNumber: cachedState.$$__referenceNumber
   } as unknown as FormSubmissionState
 
+  const language = resolveLanguage(summaryRequest as unknown as AnyFormRequest)
+  const translator = formModel.createTranslator(language)
+
   return formModel.getFormContext(
     summaryRequest,
     formState,
-    options.errors ?? []
+    options.errors ?? [],
+    translator
   )
 }
 
@@ -148,7 +155,6 @@ export async function resolveFormModel(
   }
 
   // The models cache is created lazily per server instance
-
   server.app.models ??= new Map<string, { model: FormModel; updatedAt: Date }>()
 
   const cache = server.app.models

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

@@ -2,8 +2,6 @@ import {
   ControllerPath,
   Engine,
   getErrorMessage,
-  hasComponents,
-  isFormType,
   type ComponentDef,
   type FormDefinition,
   type Page
@@ -109,7 +107,16 @@ engine.registerFilter('answer', function (name: string) {
     return
   }
 
-  const answer = getAnswer(component as Field, globals.context.relevantState)
+  const field = component as Field
+  const { translator } = globals.context
+  const answer = getAnswer(
+    field,
+    globals.context.relevantState,
+    translator ?? field.model.createTranslator(),
+    {
+      format: 'summary'
+    }
+  )
 
   return answer
 })
@@ -403,18 +410,3 @@ export function getFormVersion(
     | FormVersionMetadata
     | undefined
 }
-
-export function setPageTitles(def: FormDefinition) {
-  def.pages.forEach((page) => {
-    if (!page.title) {
-      if (hasComponents(page)) {
-        // Set the page title from the first form component
-        const firstFormComponent = page.components.find((component) =>
-          isFormType(component.type)
-        )
-
-        page.title = firstFormComponent?.title ?? ''
-      }
-    }
-  })
-}

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

@@ -0,0 +1,69 @@
+import joi, { type JoiExpression, type ReferenceOptions } from 'joi'
+
+import { lowerFirstPreserveProperNouns } from '../components/helpers/index.js'
+
+const opts = {
+  functions: {
+    lowerFirst: lowerFirstPreserveProperNouns
+  }
+} as ReferenceOptions
+
+/**
+ * Builds a set of translated Joi message templates for a given language.
+ * Called once per FormModel at construction time.
+ *
+ * Strings containing {{lowerFirst(#label)}} must be wrapped in joi.expression()
+ * because Joi cannot resolve custom functions from a plain string.
+ * Plain strings with only built-in tokens ({{#label}}, {{#limit}}) work without wrapping.
+ */
+export function buildValidationMessages(t: (key: string) => string) {
+  return {
+    // Expressions — contain lowerFirst custom function
+    required: joi.expression(t('validation.required'), opts) as JoiExpression,
+    selectRequired: joi.expression(
+      t('validation.selectRequired'),
+      opts
+    ) as JoiExpression,
+    pattern: joi.expression(t('validation.pattern'), opts) as JoiExpression,
+    format: joi.expression(t('validation.format'), opts) as JoiExpression,
+    declarationRequired: joi.expression(
+      t('components.declarationField.validation.declarationRequired'),
+      opts
+    ) as JoiExpression,
+    objectRequired: joi.expression(
+      t('validation.objectRequired'),
+      opts
+    ) as JoiExpression,
+    objectMissing: joi.expression(
+      t('validation.objectMissing'),
+      opts
+    ) as JoiExpression,
+
+    // Plain Joi template strings — no lowerFirst
+    selectYesNoRequired: t(
+      'components.yesNoField.validation.selectYesNoRequired'
+    ),
+    max: t('validation.max'),
+    min: t('validation.min'),
+    minMax: t('validation.minMax'),
+    number: t('validation.number'),
+    numberPrecision: t('validation.numberPrecision'),
+    numberInteger: t('validation.numberInteger'),
+    numberMin: t('validation.numberMin'),
+    numberMax: t('validation.numberMax'),
+    maxWords: t('validation.maxWords'),
+    dateFormat: t('components.dateField.validation.dateFormat'),
+    dateMin: t('components.dateField.validation.dateMin'),
+    dateMax: t('components.dateField.validation.dateMax'),
+
+    unicode: 'validation.unicode',
+    arrayMin: 'validation.array.min',
+    arrayMax: 'validation.array.max',
+    arrayLength: 'validation.array.length',
+    featuresMin: 'validation.features.min',
+    featuresMax: 'validation.features.max',
+    featuresLength: 'validation.features.length'
+  }
+}
+
+export type ValidationMessages = ReturnType<typeof buildValidationMessages>

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

@@ -0,0 +1,33 @@
+import { type FormDefinition } from '@defra/forms-model'
+import { type i18n } from 'i18next'
+
+import { createTranslator } from './createTranslator.js'
+import { extractBaseTranslations } from './extractBaseTranslations.js'
+import { createFormI18nInstance } from './index.js'
+import {
+  type FormDefinitionTranslations,
+  type Translator
+} from './types.js'
+
+export function createFormTranslator(
+  def: FormDefinition,
+  language: string
+): Translator {
+  const baseTranslations = extractBaseTranslations(def)
+  const i18nInstance = createFormI18nInstance(baseTranslations)
+  loadFormTranslations(def, i18nInstance)
+
+  return createTranslator(i18nInstance, language)
+}
+
+export function loadFormTranslations(def: FormDefinition, i18nInstance: i18n) {
+  const formTranslations = def.metadata?.translations as
+    | FormDefinitionTranslations
+    | undefined
+
+  if (formTranslations) {
+    for (const [lng, resources] of Object.entries(formTranslations)) {
+      i18nInstance.addResourceBundle(lng, 'form', resources, true, true)
+    }
+  }
+}

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

@@ -0,0 +1,61 @@
+import { type i18n } from 'i18next'
+
+import { type Translator } from './types.js'
+
+/**
+ * Creates a translator for the specified language, decorated with utility functions
+ * for translating specific parts of the form definition.
+ * @param i18nInstance - instance of i18next which gets created on startup (reads the boilerplate files en-GB.json and cy.json)
+ * @param language - requested language
+ */
+export function createTranslator(
+  i18nInstance: i18n,
+  language = 'en-GB'
+): Translator {
+  const t = (key: string, opts?: Record<string, unknown>): string =>
+    i18nInstance.t(key, { lng: language, ns: 'plugin', ...opts })
+
+  const resolveContent = (
+    entity: { id?: string },
+    entityType: string,
+    prop: string
+  ): string => {
+    if (!entity.id) {
+      const raw = (entity as Record<string, unknown>)[prop]
+      if (typeof raw !== 'string') return ''
+      // t() resolves i18next key constants (sub-field labels); returns raw string unchanged if not a key
+      return t(raw)
+    }
+    const key = `${entityType}.${entity.id}.${prop}`
+    const result = i18nInstance.t(key, {
+      lng: language,
+      ns: 'form'
+    })
+    if (result === key) {
+      // No form translation found — fall through to t(raw) so plugin i18n
+      // key constants (e.g. 'components.yesNoField.yes') are still resolved.
+      const raw = (entity as Record<string, unknown>)[prop]
+      if (typeof raw !== 'string') return ''
+      return t(raw)
+    }
+    return result
+  }
+
+  const resolveFormContent = (prop: string) => {
+    const key = `form.${prop}`
+    return i18nInstance.t(key, { lng: language, ns: 'form' })
+  }
+
+  return {
+    t,
+    tForm: (prop) => resolveFormContent(prop),
+    tPage: (entity, prop) => resolveContent(entity, 'pages', prop as string),
+    tComponent: (entity, prop) =>
+      resolveContent(entity, 'components', prop as string),
+    tSection: (entity, prop) =>
+      resolveContent(entity, 'sections', prop as string),
+    tListItem: (entity, prop) =>
+      resolveContent(entity, 'listItems', prop as string),
+    language
+  }
+}

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

@@ -0,0 +1,61 @@
+import {
+  hasComponentsEvenIfNoNext,
+  type FormDefinition
+} from '@defra/forms-model'
+
+import { type FormDefinitionTranslations } from './types.js'
+
+type BaseTranslations = FormDefinitionTranslations[string]
+
+export function extractBaseTranslations(def: FormDefinition): BaseTranslations {
+  const pages: BaseTranslations['pages'] = {}
+  const components: BaseTranslations['components'] = {}
+  const sections: BaseTranslations['sections'] = {}
+  const listItems: BaseTranslations['listItems'] = {}
+  const form: BaseTranslations['form'] = {}
+
+  for (const page of def.pages) {
+    if (page.id && page.title) {
+      pages[page.id] = { title: page.title }
+    }
+
+    if (hasComponentsEvenIfNoNext(page)) {
+      for (const component of page.components) {
+        if (!component.id) continue
+
+        const entry: BaseTranslations['components'][string] = {}
+
+        if (component.title) entry.title = component.title
+        if ('hint' in component && component.hint) entry.hint = component.hint
+        if ('content' in component && component.content) {
+          entry.content = component.content
+        }
+        if ('shortDescription' in component && component.shortDescription) {
+          entry.shortDescription = component.shortDescription
+        }
+
+        if (Object.keys(entry).length) {
+          components[component.id] = entry
+        }
+      }
+    }
+  }
+
+  for (const section of def.sections) {
+    if (section.id && section.title) {
+      sections[section.id] = { title: section.title }
+    }
+  }
+
+  for (const list of def.lists) {
+    for (const item of list.items) {
+      if (item.id && item.text) {
+        listItems[item.id] = { text: item.text }
+      }
+    }
+  }
+
+  form.title = def.name ?? ''
+
+  return { pages, components, sections, listItems, form }
+}