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

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

@@ -0,0 +1,271 @@
+{
+  "validation": {
+    "required": "Enter {{lowerFirst(#label)}}",
+    "selectRequired": "Select {{lowerFirst(#label)}}",
+    "pattern": "Enter a valid {{lowerFirst(#label)}}",
+    "format": "Enter {{lowerFirst(#label)}} in the correct format",
+    "objectRequired": "Enter {{#label}}",
+    "objectMissing": "{{#title}} must include a {{lowerFirst(#label)}}",
+    "max": "{{#label}} must be {{#limit}} characters or less",
+    "min": "{{#label}} must be {{#limit}} characters or more",
+    "minMax": "{{#label}} must be between {{#min}} and {{#max}} characters",
+    "number": "{{#label}} must be a number",
+    "numberPrecision": "{{#label}} must have {{#limit}} or fewer decimal places",
+    "numberInteger": "{{#label}} must be a whole number",
+    "numberMin": "{{#label}} must be {{#limit}} or higher",
+    "numberMax": "{{#label}} must be {{#limit}} or lower",
+    "maxWords": "{{#label}} must be {{#limit}} words or fewer"
+  },
+
+  "errors": {
+    "title": "There is a problem",
+    "optionsMismatch": "Options are different because you changed a previous answer"
+  },
+
+  "common": {
+    "optional": "(optional)",
+    "warningIconFallback": "Warning",
+    "back": "Back",
+    "continue": "Continue",
+    "saveAndExit": "Save and exit",
+    "draft": "draft",
+    "live": "live"
+  },
+
+  "pages": {
+    "question": {
+      "paymentCancelledBannerTitle": "Important",
+      "paymentCancelledTitle": "Your payment has been cancelled",
+      "paymentCancelledBody": "Your payment details were deleted because the form was inactive for 5 days.",
+      "paymentCancelledAction": "Add your payment details again.",
+      "backToAddAnother": "Go back to add another",
+      "backToCheckAnswers": "Go back to check answers",
+      "startNow": "Start now"
+    },
+
+    "summary": {
+      "title": "Check your answers before sending your form",
+      "change": "Change",
+      "notProvided": "Not provided",
+      "declaration": "Declaration",
+      "acceptAndSubmit": "Accept and submit",
+      "payAndSubmit": "Pay and submit",
+      "submit": "Submit",
+      "saveAndExit": "Save and exit",
+      "paymentSuccessBannerTitle": "Success",
+      "paymentSuccessTitle": "We have your payment details",
+      "paymentSuccessBody": "Your payment is on hold. We will charge you when you submit the form.",
+      "paymentDetailsTitle": "Payment details",
+      "paymentFor": "Payment for",
+      "totalAmount": "Total amount",
+      "reference": "Reference",
+      "dateOfPayment": "Date of payment",
+      "submissionFailed": "There was a problem and your form was not submitted. Try submitting the form again",
+      "submissionFailedContactSuffix": " or you can [[contactUsLink]] and quote your reference number to arrange a refund",
+      "contactUsLinkText": "contact us (opens in new tab)",
+      "confirmationEmail": "Confirmation email (optional)",
+      "confirmationEmailHint": "Enter your email address to receive a confirmation email and a copy of your answers"
+    },
+
+    "repeater": {
+      "removeAnswer": "Are you sure you want to remove this answer?",
+      "remove": "Remove",
+      "cancel": "Cancel",
+      "lastItemCannotBeRemoved": "Last list item cannot be removed",
+      "itemToRemoveNotFound": "List item to remove not found",
+      "continue": "Continue",
+      "addAnother": "Add another",
+      "saveAndExit": "Save and exit",
+      "change": "Change",
+      "notProvided": "Not provided",
+      "visuallyHiddenItem": "item [[index]]",
+      "pageTitle_one": "You have added [[count]] answer",
+      "pageTitle_other": "You have added [[count]] answers",
+      "tooMany_one": "You can only add up to [[count]] answer",
+      "tooMany_other": "You can only add up to [[count]] answers",
+      "tooFew_one": "You must add at least [[count]] answer",
+      "tooFew_other": "You must add at least [[count]] answers"
+    },
+
+    "fileUpload": {
+      "upload": "Upload file",
+      "maxFilesReached": "You have reached the maximum number of files. Please remove a file to upload more."
+    },
+
+    "exit": {
+      "defaultTitle": "Your progress has been saved",
+      "whatHappensNext": "What happens next",
+      "body": "Your form progress has been saved. You can return to complete your application at any time using the link provided.",
+      "returnToApplication": "Return to application"
+    },
+
+    "confirmation": {
+      "formSubmitted": "Form submitted",
+      "whatHappensNext": "What happens next",
+      "referenceNumber": "Your reference number",
+      "feedbackLink": "What do you think of this service? (takes 30 seconds)"
+    },
+
+    "preview": {
+      "warnMissingNotificationEmail": {
+        "body": "If you want to receive a test email, [[link]] you want form submissions to go to.",
+        "linkText": "enter the email address (opens in new tab)"
+      },
+      "bannerForce": "This is a preview of a [[previewMode]] form. Do not enter personal information.",
+      "bannerText": "This is a preview of a [[previewMode]] form page you are editing.",
+      "previousPages": "It depends on answers from earlier pages in the form. In the live version, users will need to complete those questions first."
+    }
+  },
+
+  "postcodeLookup": {
+    "postcodeLabel": "Postcode",
+    "postcodeHint": "For example, AA3 1AB",
+    "buildingNameLabel": "Building name or number (optional)",
+    "buildingNameHint": "For example, 15 or Prospect Cottage",
+    "selectAddress": "Select an address",
+    "addressLine1Label": "Address line 1",
+    "addressLine2Label": "Address line 2 (optional)",
+    "townLabel": "Town or city",
+    "countyLabel": "County (optional)",
+    "findAddress": "Find address",
+    "enterManually": "enter address manually",
+    "searchAgain": "Search again",
+    "useThisAddress": "Use this address",
+    "findAnAddressInstead": "find an address instead",
+    "noAddressFoundTitle": "No address found",
+    "noAddressFoundBody": "We could not find an address that matches",
+    "addressFound_one": "[[count]] address found for",
+    "addressFound_other": "[[count]] addresses found for",
+    "validation": {
+      "invalidPostcode": "Enter a valid postcode or enter an address manually",
+      "requiredPostcode": "Enter a postcode",
+      "selectAddress": "Select an address",
+      "requiredAddressLine1": "Enter address line 1",
+      "requiredTown": "Enter town or city",
+      "invalidManualPostcode": "Enter a valid postcode",
+      "requiredManualPostcode": "Enter postcode"
+    }
+  },
+
+  "components": {
+    "dateField": {
+      "day": "Day",
+      "month": "Month",
+      "year": "Year",
+      "validation": {
+        "dateFormat": "{{#title}} must be a real date",
+        "dateMin": "{{#title}} must be the same as or after {{#limit}}",
+        "dateMax": "{{#title}} must be the same as or before {{#limit}}"
+      }
+    },
+
+    "monthYearField": {
+      "month": "Month",
+      "year": "Year"
+    },
+
+    "addressField": {
+      "uprn": "UPRN",
+      "line1": "Address line 1",
+      "line2": "Address line 2",
+      "town": "Town or city",
+      "county": "County",
+      "postcode": "Postcode",
+      "enterAddress": "Enter [[shortDescription]]",
+      "findAddress": "Find an address",
+      "selectedAddress": "Selected address:",
+      "useDifferentAddress": "Use a different address",
+      "enterManually": "enter address manually"
+    },
+
+    "latLongField": {
+      "latitude": "Latitude",
+      "longitude": "Longitude",
+      "latitudeRequired": "Enter latitude",
+      "longitudeRequired": "Enter longitude",
+      "precision": "{{#label}} must have no more than 7 decimal places",
+      "notANumber": "{{#label}} must be a valid number",
+      "latitudeBase": "Enter a valid latitude for [[fieldLabel]] like 51.519450",
+      "longitudeBase": "Enter a valid longitude for [[fieldLabel]] like -0.127758",
+      "latitudeRange": "Latitude for [[fieldLabel]] must be between [[min]] and [[max]]",
+      "longitudeRange": "Longitude for [[fieldLabel]] must be between [[min]] and [[max]]"
+    },
+
+    "eastingNorthingField": {
+      "easting": "Easting",
+      "northing": "Northing",
+      "eastingRequired": "Enter easting",
+      "northingRequired": "Enter northing",
+      "eastingDigits": "{{#label}} for [[fieldLabel]] must be between 1 and 6 digits",
+      "northingDigits": "{{#label}} for [[fieldLabel]] must be between 1 and 7 digits",
+      "eastingRange": "{{#label}} for [[fieldLabel]] must be between [[min]] and [[max]]",
+      "northingRange": "{{#label}} for [[fieldLabel]] must be between [[min]] and [[max]]"
+    },
+
+    "nationalGridField": {
+      "required": "Enter {{lowerFirst(#title)}}",
+      "pattern": "Enter a valid National Grid field number for {{lowerFirst(#title)}} like NG 1234 5678",
+      "howToFind": "How to find location details"
+    },
+
+    "osGridRefField": {
+      "required": "Enter {{lowerFirst(#title)}}",
+      "pattern": "Enter a valid OS grid reference for {{lowerFirst(#title)}} like TQ123456",
+      "howToFind": "How to find location details"
+    },
+
+    "locationFieldBase": {
+      "howToFind": "How to find location details"
+    },
+
+    "yesNoField": {
+      "yes": "Yes",
+      "no": "No",
+      "validation": {
+        "selectYesNoRequired": "{{#label}} - select yes or no"
+      }
+    },
+
+    "declarationField": {
+      "defaultLabel": "I understand and agree",
+      "defaultConfirmationLabel": "I confirm that I understand and accept this declaration",
+      "notProvided": "Not provided",
+      "validation": {
+        "declarationRequired": "You must confirm you understand and agree with the {{lowerFirst(#label)}} to continue"
+      }
+    },
+
+    "geospatialField": {
+      "added_one": "Added [[count]] location",
+      "added_other": "Added [[count]] locations",
+      "validation": {
+        "descriptionRequired": "Enter description for location [[count]]",
+        "wrongCountry": "Location [[count]] must be within [[country]]"
+      }
+    },
+
+    "paymentField": {
+      "detailsRequired": "Payment details required",
+      "pendingTransaction": "You may see a pending transaction in your bank account but you will only be charged when you submit the form.",
+      "addPaymentDetails": "Add payment details",
+      "cannotTakePayment": "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.",
+      "testApiKey": "Add a valid test API key before you can preview the payment journey.",
+      "completePayment": "Complete the payment to continue",
+      "paymentExpired": "Your payment authorisation has expired. Please add your payment details again.",
+      "submissionFailed": "There was a problem and your form was not submitted. Try submitting the form again.",
+      "canSubmitAfterPayment": "You can submit the form after you have added your payment details.",
+      "preAuthorisedTitle": "You have already authorised a payment for this form",
+      "preAuthorisedBody": "Continue to submit the form. You will not be charged twice.",
+      "totalAmountLabel": "Total amount:",
+      "paymentAmountMismatch": "The pre-authorised payment amount is somehow different from that requested. Try adding payment details again."
+    },
+
+    "fileUploadField": {
+      "uploaded": "Uploaded",
+      "uploadFailed": "There was a problem with your uploaded files. Re-upload them before submitting the form again.",
+      "uploadedFilesHeading": "Uploaded files",
+      "filesCount_one": "[[count]] file uploaded",
+      "filesCount_other": "[[count]] files uploaded"
+    }
+  }
+}

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 []
+}