@defra/forms-engine-plugin 5.0.0-alpha.7 → 5.0.0-alpha.9

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

@@ -63,6 +63,7 @@ export class PaymentField extends FormComponent {
         reference: joi.string().required(),
         amount: joi.number().required(),
         description: joi.string().required(),
+        descriptionInEng: joi.string().optional(),
         uuid: joi.string().uuid().required(),
         formId: joi.string().required(),
         isLivePayment: joi.boolean().required(),
@@ -239,8 +240,9 @@ 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 { language, t, tComponent } = model.createTranslator(
+      resolveLanguage(request)
+    )
     const state = await args.controller.getState(request)
     const { baseUrl } = getPluginOptions(request.server)
     const summaryUrl = `${baseUrl}/${model.basePath}/summary`
@@ -272,7 +274,8 @@ export class PaymentField extends FormComponent {
       return h.redirect(summaryUrl).code(StatusCodes.SEE_OTHER)
     }
 
-    const description = options.description
+    const description =
+      tComponent(args.component, 'paymentDescription') || options.description
 
     const slug = `/${model.basePath}`
 
@@ -292,7 +295,7 @@ export class PaymentField extends FormComponent {
       payCallbackUrl,
       reference,
       isLivePayment,
-      { formId, slug },
+      { formId, slug, language },
       prefilledEmail
     )
 
@@ -313,6 +316,7 @@ export class PaymentField extends FormComponent {
       reference,
       amount: resolvedAmount,
       description,
+      descriptionInEng: options.description,
       paymentId: payment.paymentId,
       componentName,
       returnUrl: summaryUrl,
@@ -449,6 +453,7 @@ export interface PaymentSessionData {
   reference: string
   amount: number
   description: string
+  descriptionInEng?: string
   paymentId: string
   componentName: string
   returnUrl: string

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

@@ -1,4 +1,9 @@
-import { ComponentType, type UkAddressFieldComponent } from '@defra/forms-model'
+import {
+  ComponentType,
+  FormStatus,
+  type FormMetadata,
+  type UkAddressFieldComponent
+} from '@defra/forms-model'
 import { type ObjectSchema } from 'joi'
 import lowerFirst from 'lodash/lowerFirst.js'
 
@@ -9,6 +14,8 @@ import {
 } from './FormComponent.js'
 import { TextField } from './TextField.js'
 import { type RenderContext } from './types.js'
+import { getCachedPluginTranslator } from '../i18n/form.js'
+import { getAvailableLanguages } from '../i18n/languages.js'
 import { type Translator } from '../i18n/types.js'
 import {
   type FormRequestPayload,
@@ -290,7 +297,6 @@ export class UkAddressField extends FormComponent {
     )
   }
 
-  // eslint-disable-next-line @typescript-eslint/require-await
   static async dispatcher(
     request: FormRequestPayload,
     h: FormResponseToolkit,
@@ -299,14 +305,31 @@ export class UkAddressField extends FormComponent {
     const { controller, component } = args
     const language = resolveLanguage(request)
 
+    const availableLanguages = getAvailableLanguages(controller.model.def)
+    const languages = availableLanguages.length
+      ? { languages: availableLanguages }
+      : {}
+
+    const translator = await getCachedPluginTranslator(
+      request,
+      { id: controller.model.formId } as unknown as FormMetadata,
+      args.isLive ? FormStatus.Live : FormStatus.Draft,
+      language
+    )
+    const { tComponent, tForm } = translator
+
     return dispatch(request, h, {
-      formName: controller.model.name,
+      formName: tForm('title'),
+      formId: controller.model.formId,
+      formStatus: args.isLive ? FormStatus.Live : FormStatus.Draft,
+      componentId: component.id ?? 'unknown',
       componentName: component.name,
-      componentHint: component.hint,
-      componentTitle: component.title || controller.title,
+      componentHint: tComponent(component, 'hint'),
+      componentTitle: tComponent(component, 'title') || controller.title,
       step: args.actionArgs.step,
       sourceUrl: args.sourceUrl,
-      language
+      language,
+      ...languages
     })
   }
 }

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

@@ -4,7 +4,6 @@ import {
   yesNoListName,
   type YesNoFieldComponent
 } from '@defra/forms-model'
-import { type LanguageMessages } from 'joi'
 
 import { SelectionControlField } from './SelectionControlField.js'
 import { addClassOptionIfNone } from './helpers/index.js'
@@ -55,11 +54,13 @@ export class YesNoField extends SelectionControlField {
     this.options = options
   }
 
-  getValidationMessagesOverride(translator: Translator): LanguageMessages {
+  getValidationMessagesOverride(translator: Translator) {
     const { selectYesNoRequired } = buildValidationMessages(translator.t)
-    return convertToLanguageMessages({
-      'any.required': selectYesNoRequired
-    })
+    return {
+      [this.name]: convertToLanguageMessages({
+        'any.required': selectYesNoRequired
+      })
+    }
   }
 
   /**

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

@@ -347,8 +347,7 @@ export function getAnswerMarkdown(
     field instanceof Components.EastingNorthingField ||
     field instanceof Components.LatLongField
   ) {
-    const contextValue = field.getContextValueFromState(state)
-    answerEscaped = contextValue ? `${contextValue}\n` : ''
+    answerEscaped = answer ? `${answer}\n` : ''
   } else if (field instanceof Components.GeospatialField) {
     const features = field.getFormValueFromState(state)
     const value = field.getDisplayStringFromFormValue(features, translator)

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

@@ -2,6 +2,8 @@ import { type ComponentDef } from '@defra/forms-model'
 import joi, { type JoiExpression, type ReferenceOptions } from 'joi'
 import lowerFirst from 'lodash/lowerFirst.js'
 
+import { type Translator } from '../../i18n/types.js'
+
 /**
  * Prevent Markdown formatting
  * @see {@link https://pandoc.org/chunkedhtml-demo/8.11-backslash-escapes.html}
@@ -66,3 +68,20 @@ export const lowerFirstExpressionOptions = {
  */
 export const createLowerFirstExpression = (template: string): JoiExpression =>
   joi.expression(template, lowerFirstExpressionOptions) as JoiExpression
+
+/**
+ * Translate a component label, in precedence order of errorDescription, then shortDesciption, then title
+ * @param {ComponentDef} component
+ * @param {Translator} translator
+ */
+export function getTranslatedLabel(
+  component: ComponentDef,
+  translator: Translator
+) {
+  const { tComponent } = translator
+  const translatedLabel =
+    tComponent(component, 'errorDescription') ||
+    tComponent(component, 'shortDescription') ||
+    tComponent(component, 'title')
+  return translatedLabel
+}

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

@@ -8,13 +8,14 @@ import {
 } from '@defra/forms-model'
 import Boom from '@hapi/boom'
 import { type ResponseToolkit, type Server } from '@hapi/hapi'
-import { format, parseISO } from 'date-fns'
+import { format, parseISO, type Locale } from 'date-fns'
+import { cy, enGB } from 'date-fns/locale'
 import { StatusCodes } from 'http-status-codes'
 import { type Schema, type ValidationErrorItem } from 'joi'
 import { Liquid } from 'liquidjs'
 
 import { logger } from '../../common/helpers/logging/logger.js'
-import { FORM_VERSION_METADATA_KEY } from '../../constants.js'
+import { CY, EN_GB, FORM_VERSION_METADATA_KEY } from '../../constants.js'
 import {
   getAnswer,
   type Field
@@ -303,16 +304,20 @@ export function checkEmailAddressForLiveFormSubmission(
  * @param [details] - provided by {@link Schema.validate}
  */
 export function getErrors(
+  language: string | undefined,
   details?: ValidationErrorItem[]
 ): FormSubmissionError[] | undefined {
   if (!details?.length) {
     return
   }
 
-  return details.map(getError)
+  return details.map((detail) => getError(language, detail))
 }
 
-export function getError(detail: ValidationErrorItem): FormSubmissionError {
+export function getError(
+  language: string | undefined,
+  detail: ValidationErrorItem
+): FormSubmissionError {
   const { context, message, path } = detail
 
   const name = context?.key ?? ''
@@ -320,7 +325,10 @@ export function getError(detail: ValidationErrorItem): FormSubmissionError {
 
   const text = message.replace(
     /\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d\.\d+([+-][0-2]\d:[0-5]\d|Z)/,
-    (text) => format(parseISO(text), 'd MMMM yyyy')
+    (text) =>
+      format(parseISO(text), 'd MMMM yyyy', {
+        locale: toLanguageLocale(language)
+      })
   )
 
   return {
@@ -410,3 +418,41 @@ export function getFormVersion(
     | FormVersionMetadata
     | undefined
 }
+
+const payLanguageCodes = {
+  [EN_GB]: 'en',
+  [CY]: 'cy'
+} as Record<string, string>
+
+const languageLocales = {
+  [EN_GB]: enGB,
+  [CY]: cy
+} as Record<string, Locale>
+
+const defaultLanguageCode = 'en'
+const defaultLanguageLocale = enGB
+
+/**
+ * Converts a BCP 47 language tag to the ISO 639-1 code GOV.UK Pay accepts.
+ * Defaults to English if the language is not supported.
+ * @param { string | undefined } language - BCP 47 language code
+ * @returns {string} language code required by GOV.UK Pay
+ */
+export function toPayLanguageCode(language: string | undefined): string {
+  return payLanguageCodes[language ?? 'unknown'] ?? defaultLanguageCode
+}
+
+/**
+ * Converts a BCP 47 language tag to the date-fns Locale (for date formatting).
+ * Defaults to English if the language is not supported.
+ * @param { string | undefined } language - BCP 47 language code
+ * @returns {Locale} language locale
+ */
+export function toLanguageLocale(language: string | undefined): Locale {
+  return languageLocales[language ?? 'unknown'] ?? defaultLanguageLocale
+}
+
+/**
+ * @import { FormsService } from '../../types.js'
+ * @import { Locale } from 'date-fns/locale'
+ */

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

@@ -1,30 +1,40 @@
 import {
   yesNoListNoItemId,
   yesNoListYesItemId,
-  type FormDefinition
+  type FormDefinition,
+  type FormMetadata
 } from '@defra/forms-model'
 import { type i18n } from 'i18next'
 
+import { CY } from '../../../constants.js'
 import { createTranslator } from './createTranslator.js'
 import { extractBaseTranslations } from './extractBaseTranslations.js'
 import { createFormI18nInstance } from './index.js'
-import {
-  type FormDefinitionTranslations,
-  type Translator
-} from './types.js'
+import { type FormDefinitionTranslations } from './types.js'
 
 export function createFormTranslator(
-  def: FormDefinition,
+  metadata: FormMetadata,
+  definition: FormDefinition | undefined,
   language: string
-): Translator {
-  const baseTranslations = extractBaseTranslations(def)
+) {
+  const baseTranslations = extractBaseTranslations(definition)
   const i18nInstance = createFormI18nInstance(baseTranslations)
-  loadFormTranslations(def, i18nInstance)
+  loadFormTranslations(definition, i18nInstance)
+  extractMetadataBaseTranslations(metadata, i18nInstance)
+
+  const translator = createTranslator(i18nInstance, language)
 
-  return createTranslator(i18nInstance, language)
+  return translator
 }
 
-export function loadFormTranslations(def: FormDefinition, i18nInstance: i18n) {
+export function loadFormTranslations(
+  def: FormDefinition | undefined,
+  i18nInstance: i18n
+) {
+  if (!def) {
+    return
+  }
+
   const formTranslations = def.metadata?.translations as
     | FormDefinitionTranslations
     | undefined
@@ -34,7 +44,7 @@ export function loadFormTranslations(def: FormDefinition, i18nInstance: i18n) {
       i18nInstance.addResourceBundle(lng, 'form', resources, true, true)
 
       // Temporary workaround - until we develop a better solution
-      if (lng === 'cy') {
+      if (lng === CY) {
         i18nInstance.addResource(
           lng,
           'form',
@@ -51,3 +61,24 @@ export function loadFormTranslations(def: FormDefinition, i18nInstance: i18n) {
     }
   }
 }
+
+export function extractMetadataBaseTranslations(
+  metadata: FormMetadata | undefined,
+  i18nInstance: i18n
+) {
+  if (metadata) {
+    const translations = {
+      'form.title': metadata.title,
+      'form.contact.email.address': metadata.contact?.email?.address ?? '',
+      'form.contact.email.responseTime':
+        metadata.contact?.email?.responseTime ?? '',
+      'form.contact.online.url': metadata.contact?.online?.url ?? '',
+      'form.contact.online.text': metadata.contact?.online?.text ?? '',
+      'form.contact.phone': metadata.contact?.phone ?? '',
+      'form.submissionGuidance': metadata.submissionGuidance ?? '',
+      'form.privacyNoticeText': metadata.privacyNoticeText ?? '',
+      'form.privacyNoticeUrl': metadata.privacyNoticeUrl ?? ''
+    }
+    i18nInstance.addResourceBundle('en-GB', 'form', translations, true, true)
+  }
+}

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

@@ -7,13 +7,19 @@ import { type FormDefinitionTranslations } from './types.js'
 
 type BaseTranslations = FormDefinitionTranslations[string]
 
-export function extractBaseTranslations(def: FormDefinition): BaseTranslations {
+export function extractBaseTranslations(
+  def: FormDefinition | undefined
+): BaseTranslations {
   const pages: BaseTranslations['pages'] = {}
   const components: BaseTranslations['components'] = {}
   const sections: BaseTranslations['sections'] = {}
   const listItems: BaseTranslations['listItems'] = {}
   const form: BaseTranslations['form'] = {}
 
+  if (!def) {
+    return { pages, components, sections, listItems, form }
+  }
+
   for (const page of def.pages) {
     if (page.id && page.title) {
       pages[page.id] = { title: page.title }

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

@@ -0,0 +1,54 @@
+import { type FormMetadata, type FormStatus } from '@defra/forms-model'
+import Boom from '@hapi/boom'
+import { LRUCache } from 'lru-cache'
+
+import { getPluginOptions } from '../helpers.js'
+import { createFormTranslator } from './createFormTranslator.js'
+import { type Translator } from './types.js'
+import { type AnyFormRequest } from '../types.js'
+
+const cache = new LRUCache({
+  max: 100,
+  ttl: 1000 * 60 * 15 // 15 minutes
+})
+
+/**
+ * Get translator for plugin, for the current form's metadata (as well as the plugin-specific boilerplate).
+ * This is an async call so we can read the form definition inside this call.
+ * See docs/features/multi-language.md for the language and translation flow overview.
+ * @param {AnyFormRequest} request
+ * @param {FormMetadata} metadata - the metadata of the form
+ * @param {FormStatus} status - the form status to use when retrieving the definition
+ * @param {string} language - the language to use for the translator
+ */
+export async function getCachedPluginTranslator(
+  request: AnyFormRequest,
+  metadata: FormMetadata,
+  status: FormStatus,
+  language: string
+) {
+  const key = `${metadata.id}-${status}-${language}-plugin-meta`
+
+  if (cache.has(key)) {
+    return cache.get(key) as unknown as Translator
+  }
+
+  const { services } = getPluginOptions(request.server)
+
+  const definition = await services?.formsService.getFormDefinition(
+    metadata.id,
+    status
+  )
+
+  if (!definition) {
+    throw Boom.notFound(
+      `FormDefinition not found for form ${metadata.id} and status ${status}`
+    )
+  }
+
+  const translator = createFormTranslator(metadata, definition, language)
+
+  cache.set(key, translator)
+
+  return translator
+}

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

@@ -0,0 +1,19 @@
+import { type FormDefinition } from '@defra/forms-model'
+
+/**
+ * Return a list of available languages.
+ * Empty array if only English, or an array of English and Welsh if translations have been defined.
+ * @param {FormDefinition} def
+ */
+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/i18n/translations/cy.json

@@ -29,7 +29,9 @@
     "continue": "Parhau",
     "saveAndExit": "Cadw a gadael",
     "draft": "ddrafft",
-    "live": "fyw"
+    "live": "fyw",
+    "or": "neu",
+    "and": "a"
   },
 
   "pages": {

package/src/server/plugins/engine/i18n/translations/en-GB.json

@@ -29,7 +29,9 @@
     "continue": "Continue",
     "saveAndExit": "Save and exit",
     "draft": "draft",
-    "live": "live"
+    "live": "live",
+    "or": "or",
+    "and": "and"
   },
 
   "pages": {

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

@@ -22,6 +22,12 @@ export {
   resolveFormModel
 } from './form-context.js'
 export * from './form-availability.js'
+export { getAvailableLanguages } from './i18n/languages.js'
+export {
+  extractMetadataBaseTranslations,
+  loadFormTranslations
+} from './i18n/createFormTranslator.js'
+export { extractBaseTranslations } from './i18n/extractBaseTranslations.js'
 
 const globals = {
   checkComponentTemplates,

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

@@ -31,6 +31,7 @@ import { type i18n } from 'i18next'
 import joi from 'joi'
 
 import { logger } from '../../../common/helpers/logging/logger.js'
+import { EN_GB } from '../../../constants.js'
 import { type ListFormComponent } from '../components/ListFormComponent.js'
 import {} from '../components/YesNoField.js'
 import {
@@ -47,6 +48,7 @@ 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 { getAvailableLanguages } from '../i18n/languages.js'
 import { type Translator } from '../i18n/types.js'
 import { type ExecutableCondition } from './types.js'
 import { type PageController } from '../pageControllers/PageController.js'
@@ -240,7 +242,12 @@ export class FormModel {
   }
 
   /** Returns a scoped translator pair for the given language. */
-  createTranslator(language = 'en-GB'): Translator {
+  createTranslator(language = EN_GB): Translator {
+    // @ts-expect-error - dynamic language lookup
+    if (!this.def.metadata?.translations?.[language]) {
+      // If not translations defined in the FormDefinition, always default to English
+      language = EN_GB
+    }
     return createTranslator(this.i18nInstance, language)
   }
 
@@ -662,7 +669,7 @@ function validateFormState(
 
   // Add relevant state errors
   if (error) {
-    const errorsState = error.details.map(getError)
+    const errorsState = error.details.map((item) => getError(EN_GB, item))
     return { ...context, errors: errors.concat(errorsState) }
   }
 
@@ -679,16 +686,3 @@ 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

@@ -4,6 +4,7 @@ import {
   type Section
 } from '@defra/forms-model'
 
+import { EN_GB } from '../../../constants.js'
 import { PaymentField } from '../components/PaymentField.js'
 import { type PaymentState } from '../components/PaymentField.types.js'
 import {
@@ -96,7 +97,7 @@ export class SummaryViewModel {
       .validate(this.context.relevantState, { ...opts, stripUnknown: true })
 
     // Format errors
-    this.errors = result.error?.details.map(getError)
+    this.errors = result.error?.details.map((item) => getError(EN_GB, item))
     this.details = this.summaryDetails(request, sections, translator)
 
     // Format check answers

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

@@ -5,6 +5,7 @@ import {
 import { addDays, format as dateFormat } from 'date-fns'
 
 import { config } from '../../../../../config/index.js'
+import { EN_GB } from '../../../../constants.js'
 import { getAnswer } from '../../components/helpers/components.js'
 import { escapeMarkdown } from '../../components/helpers/index.js'
 import { PaymentField } from '../../components/index.js'
@@ -116,7 +117,7 @@ function appendPaymentSection(paymentItems: DetailItem[], lines: string[]) {
 
   const formattedAmount = formatCurrency(paymentState.amount)
   const dateOfPayment = paymentState.preAuth?.createdAt
-    ? formatPaymentDate(paymentState.preAuth.createdAt)
+    ? formatPaymentDate(paymentState.preAuth.createdAt, EN_GB)
     : ''
 
   lines.push(

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

@@ -28,6 +28,7 @@ interface PaymentOutput {
   reference: string
   amount: number
   description: string
+  descriptionInEng?: string
   createdAt: string
 }
 
@@ -93,6 +94,7 @@ export function format(
  *        reference: 'REF-123',
  *        amount: 10.00,
  *        description: 'Application fee',
+ *        descriptionInEng: 'Applicaiton fee',
  *        createdAt: '2025-01-23T10:30:00.000Z'
  *      }
  *    }
@@ -204,6 +206,7 @@ function extractPayment(
     reference: paymentState.reference,
     amount: paymentState.amount,
     description: paymentState.description,
+    descriptionInEng: item.field.def.options.description,
     createdAt: paymentState.preAuth?.createdAt ?? ''
   }
 }

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

@@ -226,7 +226,7 @@ export class FileUploadPageController extends QuestionPageController {
     }
   }
 
-  getErrors(details?: ValidationErrorItem[]) {
+  getErrors(details?: ValidationErrorItem[], language?: string) {
     const { fileUpload } = this
 
     if (details) {
@@ -239,7 +239,7 @@ export class FileUploadPageController extends QuestionPageController {
         if (!isUploadError || isUploadRootError) {
           // The error is for the root of the upload or another
           // field on the page so defer to the getError helper
-          errors.push(getError(error))
+          errors.push(getError(language, error))
         } else {
           const { context, path, type } = error
 

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

@@ -364,8 +364,8 @@ export class QuestionPageController extends PageController {
     return this.collection.getStateFromValidForm(payload)
   }
 
-  getErrors(details?: ValidationErrorItem[]) {
-    return getErrors(details)
+  getErrors(details?: ValidationErrorItem[], language?: string) {
+    return getErrors(language, details)
   }
 
   async getState(request: AnyFormRequest) {