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

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

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

@@ -0,0 +1,80 @@
+import { getErrorMessage } from '@defra/forms-model'
+import i18next, { createInstance } from 'i18next'
+
+import { logger } from '../../../common/helpers/logging/logger.js'
+import cy from './translations/cy.json' with { type: 'json' }
+import enGB from './translations/en-GB.json' with { type: 'json' }
+import { type FormDefinitionTranslations } from './types.js'
+
+type BaseTranslations = FormDefinitionTranslations[string]
+
+i18next
+  .init({
+    resources: {
+      'en-GB': { translation: enGB },
+      cy: { translation: cy }
+    },
+    fallbackLng: 'en-GB',
+    interpolation: {
+      prefix: '[[',
+      suffix: ']]',
+      escapeValue: false
+    }
+  })
+  .catch((err: unknown) => {
+    logger.error(`Fatal init for translator i18next: ${getErrorMessage(err)}`)
+  })
+
+/**
+ * Generic translation utility function
+ * @param key - key for lookup
+ * @param language - language requested
+ * @param options
+ * @returns {string}
+ */
+export function t(
+  key: string,
+  language: string,
+  options?: Record<string, unknown>
+): string {
+  return i18next.t(key, { lng: language, ...options })
+}
+
+/**
+ * Creates an instance of i18next with base (boilerplate) translation files loaded (en-GB.json and cy.json),
+ * and appropriate namespaces for loading of form-specific translations later
+ * @param formEnGb
+ * @returns
+ */
+export function createFormI18nInstance(formEnGb: BaseTranslations) {
+  const instance = createInstance()
+
+  instance
+    .init({
+      resources: {
+        'en-GB': {
+          plugin: enGB,
+          form: formEnGb
+        },
+        cy: {
+          plugin: cy
+        }
+      },
+      fallbackLng: 'en-GB',
+      ns: ['plugin', 'form'],
+      defaultNS: 'plugin',
+      interpolation: {
+        prefix: '[[',
+        suffix: ']]',
+        escapeValue: false
+      }
+    })
+    .catch((err: unknown) => {
+      // init with inline resources completes synchronously — unreachable
+      logger.error(
+        `Fatal init for translator instance: ${getErrorMessage(err)}`
+      )
+    })
+
+  return instance
+}

package/src/server/plugins/engine/i18n/translations/cy.json

@@ -0,0 +1,271 @@
+{
+  "validation": {
+    "required": "Nodwch {{lowerFirst(#label)}}",
+    "selectRequired": "Dewiswch {{lowerFirst(#label)}}",
+    "pattern": "Nodwch {{lowerFirst(#label)}} dilys",
+    "format": "Nodwch {{lowerFirst(#label)}} yn y fformat cywir",
+    "objectRequired": "Nodwch {{#label}}",
+    "objectMissing": "Rhaid i {{#title}} gynnwys {{lowerFirst(#label)}}",
+    "max": "Rhaid i {{#label}} fod yn {{#limit}} o nodau neu lai",
+    "min": "Rhaid i {{#label}} fod yn {{#limit}} o nodau neu fwy",
+    "minMax": "Rhaid i {{#label}} fod rhwng {{#min}} a {{#max}} o nodau",
+    "number": "Rhaid i {{#label}} fod yn rhif",
+    "numberPrecision": "Rhaid i {{#label}} beidio â chael mwy na {{#limit}} lle degol",
+    "numberInteger": "Rhaid i {{#label}} fod yn rhif cyfan",
+    "numberMin": "Rhaid i {{#label}} fod yn {{#limit}} neu uwch",
+    "numberMax": "Rhaid i {{#label}} fod yn {{#limit}} neu is",
+    "maxWords": "Rhaid i {{#label}} fod yn {{#limit}} o eiriau neu lai"
+  },
+
+  "errors": {
+    "title": "Mae problem",
+    "optionsMismatch": "Mae'r opsiynau'n wahanol oherwydd i chi newid ateb blaenorol"
+  },
+
+  "common": {
+    "optional": "(dewisol)",
+    "warningIconFallback": "Rhybudd",
+    "back": "Yn ôl",
+    "continue": "Parhau",
+    "saveAndExit": "Cadw a gadael",
+    "draft": "ddrafft",
+    "live": "fyw"
+  },
+
+  "pages": {
+    "question": {
+      "paymentCancelledBannerTitle": "Pwysig",
+      "paymentCancelledTitle": "Mae eich taliad wedi'i ganslo",
+      "paymentCancelledBody": "Cafodd eich manylion talu eu dileu oherwydd bod y ffurflen yn anweithredol am 5 diwrnod.",
+      "paymentCancelledAction": "Ychwanegwch eich manylion talu eto.",
+      "backToAddAnother": "Ewch yn ôl i ychwanegu un arall",
+      "backToCheckAnswers": "Ewch yn ôl i wirio'ch atebion",
+      "startNow": "Dechrau nawr"
+    },
+
+    "summary": {
+      "title": "Gwiriwch eich atebion cyn anfon eich ffurflen",
+      "change": "Newid",
+      "notProvided": "Heb ei ddarparu",
+      "declaration": "Datganiad",
+      "acceptAndSubmit": "Derbyn a chyflwyno",
+      "payAndSubmit": "Talu a chyflwyno",
+      "submit": "Cyflwyno",
+      "saveAndExit": "Cadw a gadael",
+      "paymentSuccessBannerTitle": "Llwyddiant",
+      "paymentSuccessTitle": "Mae gennym eich manylion talu",
+      "paymentSuccessBody": "Mae eich taliad ar ddal. Byddwn yn codi tâl arnoch pan fyddwch yn cyflwyno'r ffurflen.",
+      "paymentDetailsTitle": "Manylion talu",
+      "paymentFor": "Taliad am",
+      "totalAmount": "Cyfanswm",
+      "reference": "Cyfeirnod",
+      "dateOfPayment": "Dyddiad talu",
+      "submissionFailed": "Roedd problem ac ni chyflwynwyd eich ffurflen. Ceisiwch gyflwyno'r ffurflen eto",
+      "submissionFailedContactSuffix": " neu gallwch [[contactUsLink]] a dyfynnu'ch cyfeirnod i drefnu ad-daliad",
+      "contactUsLinkText": "cysylltu â ni (yn agor mewn tab newydd)",
+      "confirmationEmail": "E-bost cadarnhad (dewisol)",
+      "confirmationEmailHint": "Rhowch eich cyfeiriad e-bost i dderbyn e-bost cadarnhau a chopi o'ch atebion"
+    },
+
+    "repeater": {
+      "removeAnswer": "Ydych chi'n siŵr eich bod am dynnu'r ateb hwn?",
+      "remove": "Tynnu",
+      "cancel": "Canslo",
+      "lastItemCannotBeRemoved": "Ni ellir tynnu eitem olaf y rhestr",
+      "itemToRemoveNotFound": "Ni chanfuwyd eitem y rhestr i'w thynnu",
+      "continue": "Parhau",
+      "addAnother": "Ychwanegu un arall",
+      "saveAndExit": "Cadw a gadael",
+      "change": "Newid",
+      "notProvided": "Heb ei ddarparu",
+      "visuallyHiddenItem": "eitem [[index]]",
+      "pageTitle_one": "Rydych wedi ychwanegu [[count]] ateb",
+      "pageTitle_other": "Rydych wedi ychwanegu [[count]] ateb",
+      "tooMany_one": "Dim ond hyd at [[count]] ateb y gallwch ei ychwanegu",
+      "tooMany_other": "Dim ond hyd at [[count]] ateb y gallwch eu hychwanegu",
+      "tooFew_one": "Rhaid i chi ychwanegu o leiaf [[count]] ateb",
+      "tooFew_other": "Rhaid i chi ychwanegu o leiaf [[count]] ateb"
+    },
+
+    "fileUpload": {
+      "upload": "Uwchlwytho ffeil",
+      "maxFilesReached": "Rydych wedi cyrraedd nifer uchaf y ffeiliau. Tynnwch ffeil i uwchlwytho rhagor."
+    },
+
+    "exit": {
+      "defaultTitle": "Mae eich cynnydd wedi'i gadw",
+      "whatHappensNext": "Beth sy'n digwydd nesaf",
+      "body": "Mae cynnydd eich ffurflen wedi'i gadw. Gallwch ddychwelyd i gwblhau eich cais ar unrhyw adeg gan ddefnyddio'r ddolen a ddarperir.",
+      "returnToApplication": "Dychwelyd i'r cais"
+    },
+
+    "confirmation": {
+      "formSubmitted": "Ffurflen wedi'i chyflwyno",
+      "whatHappensNext": "Beth sy'n digwydd nesaf",
+      "referenceNumber": "Eich cyfeirnod",
+      "feedbackLink": "Beth yw eich barn am y gwasanaeth hwn? (yn cymryd 30 eiliad)"
+    },
+
+    "preview": {
+      "warnMissingNotificationEmail": {
+        "body": "Os hoffech dderbyn e-bost prawf, [[link]] yr hoffech i gyflwyniadau ffurflen fynd iddo.",
+        "linkText": "nodwch y cyfeiriad e-bost (yn agor mewn tab newydd)"
+      },
+      "bannerForce": "Rhagolwg o ffurflen [[previewMode]] yw hon. Peidiwch â rhoi gwybodaeth bersonol.",
+      "bannerText": "Dyma ragolwg o dudalen ffurflen [[previewMode]] rydych chi'n ei golygu.",
+      "previousPages": "Mae'n dibynnu ar atebion o dudalennau cynharach yn y ffurflen. Yn y fersiwn fyw, bydd angen i ddefnyddwyr gwblhau'r cwestiynau hynny yn gyntaf."
+    }
+  },
+
+  "postcodeLookup": {
+    "postcodeLabel": "Cod post",
+    "postcodeHint": "Er enghraifft, AA3 1AB",
+    "buildingNameLabel": "Enw neu rif yr adeilad (dewisol)",
+    "buildingNameHint": "Er enghraifft, 15 neu Bryn Melyn",
+    "selectAddress": "Dewiswch gyfeiriad",
+    "addressLine1Label": "Llinell cyfeiriad 1",
+    "addressLine2Label": "Llinell cyfeiriad 2 (dewisol)",
+    "townLabel": "Tref neu ddinas",
+    "countyLabel": "Sir (dewisol)",
+    "findAddress": "Dod o hyd i gyfeiriad",
+    "enterManually": "nodwch gyfeiriad â llaw",
+    "searchAgain": "Chwilio eto",
+    "useThisAddress": "Defnyddio'r cyfeiriad hwn",
+    "findAnAddressInstead": "dod o hyd i gyfeiriad yn lle hynny",
+    "noAddressFoundTitle": "Ni chanfuwyd cyfeiriad",
+    "noAddressFoundBody": "Ni allem ddod o hyd i gyfeiriad cyfatebol",
+    "addressFound_one": "Canfuwyd [[count]] cyfeiriad ar gyfer",
+    "addressFound_other": "Canfuwyd [[count]] cyfeiriad ar gyfer",
+    "validation": {
+      "invalidPostcode": "Nodwch god post dilys neu nodwch gyfeiriad â llaw",
+      "requiredPostcode": "Nodwch god post",
+      "selectAddress": "Dewiswch gyfeiriad",
+      "requiredAddressLine1": "Nodwch linell cyfeiriad 1",
+      "requiredTown": "Nodwch dref neu ddinas",
+      "invalidManualPostcode": "Nodwch god post dilys",
+      "requiredManualPostcode": "Nodwch god post"
+    }
+  },
+
+  "components": {
+    "dateField": {
+      "day": "Diwrnod",
+      "month": "Mis",
+      "year": "Blwyddyn",
+      "validation": {
+        "dateFormat": "Rhaid i {{#title}} fod yn ddyddiad go iawn",
+        "dateMin": "Rhaid i {{#title}} fod yr un fath â neu ar ôl {{#limit}}",
+        "dateMax": "Rhaid i {{#title}} fod yr un fath â neu cyn {{#limit}}"
+      }
+    },
+
+    "monthYearField": {
+      "month": "Mis",
+      "year": "Blwyddyn"
+    },
+
+    "addressField": {
+      "uprn": "UPRN",
+      "line1": "Llinell cyfeiriad 1",
+      "line2": "Llinell cyfeiriad 2",
+      "town": "Tref neu ddinas",
+      "county": "Sir",
+      "postcode": "Cod post",
+      "enterAddress": "Nodwch [[shortDescription]]",
+      "findAddress": "Dod o hyd i gyfeiriad",
+      "selectedAddress": "Cyfeiriad a ddewiswyd:",
+      "useDifferentAddress": "Defnyddio cyfeiriad gwahanol",
+      "enterManually": "nodwch gyfeiriad â llaw"
+    },
+
+    "latLongField": {
+      "latitude": "Lledred",
+      "longitude": "Hydred",
+      "latitudeRequired": "Nodwch ledred",
+      "longitudeRequired": "Nodwch hydred",
+      "precision": "Rhaid i {{#label}} beidio â chael mwy na 7 lle degol",
+      "notANumber": "Rhaid i {{#label}} fod yn rif dilys",
+      "latitudeBase": "Nodwch ledred dilys ar gyfer [[fieldLabel]] fel 51.519450",
+      "longitudeBase": "Nodwch hydred dilys ar gyfer [[fieldLabel]] fel -0.127758",
+      "latitudeRange": "Rhaid i ledred [[fieldLabel]] fod rhwng [[min]] a [[max]]",
+      "longitudeRange": "Rhaid i hydred [[fieldLabel]] fod rhwng [[min]] a [[max]]"
+    },
+
+    "eastingNorthingField": {
+      "easting": "Dwyreiniannau",
+      "northing": "Gogleddiannau",
+      "eastingRequired": "Nodwch ddwyreiniannau",
+      "northingRequired": "Nodwch ogleddiannau",
+      "eastingDigits": "Rhaid i {{#label}} ar gyfer [[fieldLabel]] fod rhwng 1 a 6 digid",
+      "northingDigits": "Rhaid i {{#label}} ar gyfer [[fieldLabel]] fod rhwng 1 a 7 digid",
+      "eastingRange": "Rhaid i {{#label}} ar gyfer [[fieldLabel]] fod rhwng [[min]] a [[max]]",
+      "northingRange": "Rhaid i {{#label}} ar gyfer [[fieldLabel]] fod rhwng [[min]] a [[max]]"
+    },
+
+    "nationalGridField": {
+      "required": "Nodwch {{lowerFirst(#title)}}",
+      "pattern": "Nodwch rif maes Grid Cenedlaethol dilys ar gyfer {{lowerFirst(#title)}} fel NG 1234 5678",
+      "howToFind": "Sut i ddod o hyd i fanylion lleoliad"
+    },
+
+    "osGridRefField": {
+      "required": "Nodwch {{lowerFirst(#title)}}",
+      "pattern": "Nodwch gyfeirnod grid AO dilys ar gyfer {{lowerFirst(#title)}} fel TQ123456",
+      "howToFind": "Sut i ddod o hyd i fanylion lleoliad"
+    },
+
+    "locationFieldBase": {
+      "howToFind": "Sut i ddod o hyd i fanylion lleoliad"
+    },
+
+    "yesNoField": {
+      "yes": "Ie",
+      "no": "Na",
+      "validation": {
+        "selectYesNoRequired": "{{#label}} - dewiswch ie neu na"
+      }
+    },
+
+    "declarationField": {
+      "defaultLabel": "Rwy'n deall ac yn cytuno",
+      "defaultConfirmationLabel": "Rwy'n cadarnhau fy mod yn deall ac yn derbyn y datganiad hwn",
+      "notProvided": "Heb ei ddarparu",
+      "validation": {
+        "declarationRequired": "Rhaid i chi gadarnhau eich bod yn deall ac yn cytuno â'r {{lowerFirst(#label)}} i barhau"
+      }
+    },
+
+    "geospatialField": {
+      "added_one": "Ychwanegwyd [[count]] lleoliad",
+      "added_other": "Ychwanegwyd [[count]] lleoliad",
+      "validation": {
+        "descriptionRequired": "Rhowch ddisgrifiad ar gyfer lleoliad [[count]]",
+        "wrongCountry": "Rhaid i leoliad [[count]] fod y tu mewn i [[country]]"
+      }
+    },
+
+    "paymentField": {
+      "detailsRequired": "Angen manylion talu",
+      "pendingTransaction": "Mae'n bosibl y gwelwch drafodiad ar y gweill yn eich cyfrif banc ond dim ond pan fyddwch yn cyflwyno'r ffurflen y codir tâl arnoch.",
+      "addPaymentDetails": "Ychwanegu manylion talu",
+      "cannotTakePayment": "Mae problem ac ni allwn dderbyn taliad. Cysylltwch â ni (manylion yn nhroedyn y ffurflen hon) neu cadwch eich cynnydd a dychwelyd at y ffurflen yn ddiweddarach.",
+      "testApiKey": "Ychwanegwch allwedd API prawf ddilys cyn i chi allu rhagolwg y daith talu.",
+      "completePayment": "Cwblhewch y taliad i barhau",
+      "paymentExpired": "Mae awdurdodiad eich taliad wedi dod i ben. Ychwanegwch eich manylion talu eto.",
+      "submissionFailed": "Roedd problem ac ni chyflwynwyd eich ffurflen. Ceisiwch gyflwyno'r ffurflen eto.",
+      "canSubmitAfterPayment": "Gallwch gyflwyno'r ffurflen ar ôl i chi ychwanegu eich manylion talu.",
+      "preAuthorisedTitle": "Rydych eisoes wedi awdurdodi taliad ar gyfer y ffurflen hon",
+      "preAuthorisedBody": "Parhewch i gyflwyno'r ffurflen. Ni chodir tâl arnoch ddwywaith.",
+      "totalAmountLabel": "Cyfanswm:",
+      "paymentAmountMismatch": "Mae swm y taliad a rhaganrhuddhawyd rywsut yn wahanol i'r hyn a ofynnwyd amdano. Ceisiwch ychwanegu manylion talu eto."
+    },
+
+    "fileUploadField": {
+      "uploaded": "Wedi'i uwchlwytho",
+      "uploadFailed": "Roedd problem gyda'ch ffeiliau a uwchlwythwyd. Uwchlwythwch nhw eto cyn cyflwyno'r ffurflen.",
+      "uploadedFilesHeading": "Ffeiliau a uwchlwythwyd",
+      "filesCount_one": "Uwchlwythwyd [[count]] ffeil",
+      "filesCount_other": "Uwchlwythwyd [[count]] ffeil"
+    }
+  }
+}