@defra/forms-engine-plugin 4.22.0 → 5.0.0-alpha

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

@@ -11,10 +11,12 @@ import { logger } from '../../../common/helpers/logging/logger.js'
 import { COMPONENT_STATE_ERROR } from '../../../constants.js'
 import { FormComponent } from './FormComponent.js'
 import { type PaymentState } from './PaymentField.types.js'
+import { type RenderContext } from './types.js'
 import {
   createError,
   getPluginOptions
 } from '../helpers.js'
+import { type Translator } from '../i18n/types.js'
 import { type FormModel } from '../models/index.js'
 import {
   PaymentErrorTypes,
@@ -28,10 +30,8 @@ import {
 } from '../types/index.js'
 import {
   type ErrorMessageTemplateList,
-  type FormPayload,
   type FormState,
   type FormStateValue,
-  type FormSubmissionError,
   type FormSubmissionState,
   type PaymentExternalArgs
 } from '../types.js'
@@ -39,6 +39,7 @@ import {
   createPaymentService,
   formatCurrency
 } from '../../payment/helper.js'
+import { resolveLanguage } from '../../../utils/utils.js'
 
 export class PaymentField extends FormComponent {
   declare options: PaymentFieldComponent['options']
@@ -93,7 +94,10 @@ export class PaymentField extends FormComponent {
     return this.isPaymentState(value) ? value : undefined
   }
 
-  getDisplayStringFromState(state: FormSubmissionState): string {
+  getDisplayStringFromState(
+    state: FormSubmissionState,
+    _translator: Translator
+  ): string {
     const value = this.getPaymentStateFromState(state)
 
     if (!value) {
@@ -103,8 +107,9 @@ export class PaymentField extends FormComponent {
     return `${formatCurrency(value.amount)} - ${value.description}`
   }
 
-  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
-    const viewModel = super.getViewModel(payload, errors)
+  getViewModel(context: RenderContext) {
+    const { payload } = context
+    const viewModel = super.getViewModel(context)
 
     // Payload is pre-populated from state if a payment has already been made
     const paymentState = this.isPaymentState(payload[this.name] as unknown)
@@ -229,7 +234,8 @@ export class PaymentField extends FormComponent {
   ): Promise<unknown> {
     const { options, name: componentName } = args.component
     const { model } = args.controller
-
+    const language = resolveLanguage(request)
+    const { t } = model.createTranslator(language)
     const state = await args.controller.getState(request)
     const { baseUrl } = getPluginOptions(request.server)
     const summaryUrl = `${baseUrl}/${model.basePath}/summary`
@@ -287,8 +293,8 @@ export class PaymentField extends FormComponent {
 
     if (!payment) {
       const message = isLivePayment
-        ? 'There is a problem and we cannot take a payment. Contact us (details in the footer of this form) or save your progress and return to the form later.'
-        : 'Add a valid test API key before you can preview the payment journey.'
+        ? t('components.paymentField.cannotTakePayment')
+        : t('components.paymentField.testApiKey')
       const govukError = createError(componentName, message)
       request.yar.flash(COMPONENT_STATE_ERROR, govukError, true)
       return h
@@ -323,6 +329,9 @@ export class PaymentField extends FormComponent {
     _metadata: FormMetadata,
     context: FormContext
   ): Promise<void> {
+    const language = resolveLanguage(request)
+    const { t } = this.model.createTranslator(language)
+
     // Zero-amount bypass — no capture needed
     const resolvedAmount = PaymentField.resolveAmount(
       this.options,
@@ -338,7 +347,7 @@ export class PaymentField extends FormComponent {
     if (!paymentState) {
       throw new PaymentPreAuthError(
         this,
-        'Complete the payment to continue',
+        t('components.paymentField.completePayment'),
         true,
         PaymentErrorTypes.PaymentIncomplete
       )
@@ -367,7 +376,8 @@ export class PaymentField extends FormComponent {
     PaymentSubmissionError.checkPaymentAmount(
       status.amount,
       resolvedAmount,
-      this
+      this,
+      t
     )
 
     if (status.state.status === 'success') {
@@ -378,7 +388,7 @@ export class PaymentField extends FormComponent {
     if (status.state.status !== 'capturable') {
       throw new PaymentPreAuthError(
         this,
-        'Your payment authorisation has expired. Please add your payment details again.',
+        t('components.paymentField.paymentExpired'),
         true,
         PaymentErrorTypes.PaymentExpired
       )
@@ -392,7 +402,7 @@ export class PaymentField extends FormComponent {
     if (!captured) {
       throw new PaymentPreAuthError(
         this,
-        'There was a problem and your form was not submitted. Try submitting the form again.',
+        t('components.paymentField.submissionFailed'),
         false
       )
     }

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

@@ -4,10 +4,7 @@ import {
 } from '@defra/forms-model'
 
 import { ListFormComponent } from './ListFormComponent.js'
-import {
-  type FormPayload,
-  type FormSubmissionError
-} from '../types.js'
+import { type RenderContext } from './types.js'
 
 export class SelectField extends ListFormComponent {
   declare options:
@@ -33,8 +30,8 @@ export class SelectField extends ListFormComponent {
     this.options = options
   }
 
-  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
-    const viewModel = super.getViewModel(payload, errors)
+  getViewModel(context: RenderContext) {
+    const viewModel = super.getViewModel(context)
     let { items } = viewModel
 
     items = [{ value: '' }, ...items]

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

@@ -1,20 +1,19 @@
 import { ListFormComponent } from './ListFormComponent.js'
-import { type ListItem } from './types.js'
-import { messageTemplate } from '../pageControllers/validationOptions.js'
 import {
-  type ErrorMessageTemplateList,
-  type FormPayload,
-  type FormSubmissionError
-} from '../types.js'
+  type ListItem,
+  type RenderContext
+} from './types.js'
+import { messageTemplate } from '../pageControllers/validationOptions.js'
+import { type ErrorMessageTemplateList } from '../types.js'
 
 /**
  * "Selection controls" are checkboxes and radios (and switches), as per Material UI nomenclature.
  */
 export class SelectionControlField extends ListFormComponent {
-  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
+  getViewModel(context: RenderContext) {
     const { options } = this
 
-    const viewModel = super.getViewModel(payload, errors)
+    const viewModel = super.getViewModel(context)
     let { fieldset, items, label } = viewModel
 
     fieldset ??= {

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

@@ -7,12 +7,9 @@ import {
   INVALID_ERROR_CODE,
   joi
 } from './helpers/telephone.js'
+import { type RenderContext } from './types.js'
 import { messageTemplate } from '../pageControllers/validationOptions.js'
-import {
-  type ErrorMessageTemplateList,
-  type FormPayload,
-  type FormSubmissionError
-} from '../types.js'
+import { type ErrorMessageTemplateList } from '../types.js'
 
 export class TelephoneNumberField extends FormComponent {
   declare options: TelephoneNumberFieldComponent['options']
@@ -59,8 +56,8 @@ export class TelephoneNumberField extends FormComponent {
     this.options = options
   }
 
-  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
-    const viewModel = super.getViewModel(payload, errors)
+  getViewModel(context: RenderContext) {
+    const viewModel = super.getViewModel(context)
     const { attributes } = viewModel
 
     attributes.autocomplete = 'tel'

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>