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

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

@@ -2,12 +2,14 @@ import {
   ComponentType,
   hasFormComponents,
   isFormType,
+  type ComponentDef,
   type DeclarationFieldComponent,
   type Item
 } from '@defra/forms-model'
 import joi, {
   type ArraySchema,
   type BooleanSchema,
+  type LanguageMessages,
   type StringSchema
 } from 'joi'
 
@@ -15,23 +17,23 @@ import {
   FormComponent,
   isFormValue
 } from './FormComponent.js'
+import { type RenderContext } from './types.js'
+import { buildValidationMessages } from '../i18n/buildValidationMessages.js'
+import { type Translator } from '../i18n/types.js'
 import { messageTemplate } from '../pageControllers/validationOptions.js'
 import {
   type ErrorMessageTemplateList,
   type FormPayload,
   type FormState,
   type FormStateValue,
-  type FormSubmissionError,
   type FormSubmissionState,
   type FormValue
 } from '../types.js'
 
 export class DeclarationField extends FormComponent {
-  private readonly DEFAULT_DECLARATION_LABEL = 'I understand and agree'
-
   declare options: DeclarationFieldComponent['options']
 
-  declare declarationConfirmationLabel: string
+  declare declarationConfirmationLabel: string | undefined
 
   declare formSchema: ArraySchema<StringSchema[]>
   declare stateSchema: BooleanSchema
@@ -69,8 +71,9 @@ export class DeclarationField extends FormComponent {
 
     this.options = options
     this.content = content
-    this.declarationConfirmationLabel =
-      options.declarationConfirmationLabel ?? this.DEFAULT_DECLARATION_LABEL
+    // Store only the form-authored label (if provided). If absent, getViewModel
+    // resolves the default via t() at render time so the correct language is used.
+    this.declarationConfirmationLabel = options.declarationConfirmationLabel
     const formComponents = hasFormComponents(props.page?.pageDef)
       ? props.page.pageDef.components
       : []
@@ -114,20 +117,40 @@ export class DeclarationField extends FormComponent {
     return this.isValue(value) ? value : undefined
   }
 
-  getDisplayStringFromFormValue(value: FormValue | FormPayload): string {
-    return value === 'true' ? this.declarationConfirmationLabel : 'Not provided'
+  getValidationMessagesOverride(translator: Translator) {
+    const { declarationRequired } = buildValidationMessages(translator.t)
+    const msg = declarationRequired as unknown as string
+    return {
+      'any.required': msg,
+      'any.unknown': msg,
+      'array.includesRequiredUnknowns': msg
+    } as unknown as LanguageMessages
   }
 
-  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
-    const defaultDeclarationConfirmationLabel =
-      'I confirm that I understand and accept this declaration'
+  getDisplayStringFromFormValue(
+    value: FormValue | FormPayload,
+    translator: Translator
+  ): string {
+    const { t } = translator
+    return value === 'true'
+      ? (this.declarationConfirmationLabel ??
+          t('components.declarationField.defaultLabel'))
+      : t('components.declarationField.notProvided')
+  }
+
+  getViewModel(context: RenderContext) {
+    const { payload } = context
+    const { t, tComponent } = context.translator
+
     const {
       hint,
-      content,
-      declarationConfirmationLabel = defaultDeclarationConfirmationLabel
+      declarationConfirmationLabel = t(
+        'components.declarationField.defaultLabel'
+      )
     } = this
+    const content = tComponent(this as unknown as ComponentDef, 'content')
 
-    const viewModel = super.getViewModel(payload, errors)
+    const viewModel = super.getViewModel(context)
     let { fieldset, label } = viewModel
 
     fieldset ??= {

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

@@ -16,7 +16,12 @@ import {
 } from './LocationFieldHelpers.js'
 import { NumberField } from './NumberField.js'
 import { createLowerFirstExpression } from './helpers/index.js'
-import { type EastingNorthingState } from './types.js'
+import {
+  type EastingNorthingState,
+  type RenderContext
+} from './types.js'
+import { t as tPlugin } from '../i18n/index.js'
+import { type Translator } from '../i18n/types.js'
 import { messageTemplate } from '../pageControllers/validationOptions.js'
 import {
   type ErrorMessageTemplateList,
@@ -55,18 +60,47 @@ export class EastingNorthingField extends FormComponent {
     const northingMin = schema?.northing?.min ?? DEFAULT_NORTHING_MIN
     const northingMax = schema?.northing?.max ?? DEFAULT_NORTHING_MAX
 
-    const eastingRequired = 'Enter easting'
-    const northingRequired = 'Enter northing'
+    const fieldLabel = lowerFirst(this.label)
 
-    const eastingDigitsMessage = `{{#label}} for ${lowerFirst(this.label)} must be between 1 and 6 digits`
-    const northingDigitsMessage = `{{#label}} for ${lowerFirst(this.label)} must be between 1 and 7 digits`
+    const eastingDigitsMessage = tPlugin(
+      'components.eastingNorthingField.eastingDigits',
+      'en-GB',
+      { fieldLabel }
+    )
+    const northingDigitsMessage = tPlugin(
+      'components.eastingNorthingField.northingDigits',
+      'en-GB',
+      { fieldLabel }
+    )
 
     const customValidationMessages: LanguageMessages =
       convertToLanguageMessages({
-        'any.required': eastingRequired,
-        'number.base': eastingRequired,
-        'number.min': `{{#label}} for ${lowerFirst(this.label)} must be between {{#limit}} and ${eastingMax}`,
-        'number.max': `{{#label}} for ${lowerFirst(this.label)} must be between ${eastingMin} and {{#limit}}`,
+        'any.required': tPlugin(
+          'components.eastingNorthingField.eastingRequired',
+          'en-GB'
+        ),
+        'number.base': tPlugin(
+          'components.eastingNorthingField.eastingRequired',
+          'en-GB'
+        ),
+        'number.min': tPlugin(
+          'components.eastingNorthingField.eastingRange',
+          'en-GB',
+          {
+            fieldLabel,
+            min: eastingMin,
+            max: eastingMax
+          }
+        ),
+        'number.max': tPlugin(
+          'components.eastingNorthingField.eastingRange',
+          'en-GB',
+          {
+            fieldLabel,
+            min: eastingMin,
+            max: eastingMax
+          }
+        ),
         'number.precision': eastingDigitsMessage,
         'number.integer': eastingDigitsMessage,
         'number.unsafe': eastingDigitsMessage
@@ -74,10 +108,32 @@ export class EastingNorthingField extends FormComponent {
 
     const northingValidationMessages: LanguageMessages =
       convertToLanguageMessages({
-        'any.required': northingRequired,
-        'number.base': northingRequired,
-        'number.min': `{{#label}} for ${lowerFirst(this.label)} must be between {{#limit}} and ${northingMax}`,
-        'number.max': `{{#label}} for ${lowerFirst(this.label)} must be between ${northingMin} and {{#limit}}`,
+        'any.required': tPlugin(
+          'components.eastingNorthingField.northingRequired',
+          'en-GB'
+        ),
+        'number.base': tPlugin(
+          'components.eastingNorthingField.northingRequired',
+          'en-GB'
+        ),
+        'number.min': tPlugin(
+          'components.eastingNorthingField.northingRange',
+          'en-GB',
+          {
+            fieldLabel,
+            min: northingMin,
+            max: northingMax
+          }
+        ),
+        'number.max': tPlugin(
+          'components.eastingNorthingField.northingRange',
+          'en-GB',
+          {
+            fieldLabel,
+            min: northingMin,
+            max: northingMax
+          }
+        ),
         'number.precision': northingDigitsMessage,
         'number.integer': northingDigitsMessage,
         'number.unsafe': northingDigitsMessage
@@ -88,7 +144,7 @@ export class EastingNorthingField extends FormComponent {
         {
           type: ComponentType.NumberField,
           name: `${name}__easting`,
-          title: 'Easting',
+          title: 'components.eastingNorthingField.easting',
           schema: {
             min: eastingMin,
             max: eastingMax,
@@ -104,7 +160,7 @@ export class EastingNorthingField extends FormComponent {
         {
           type: ComponentType.NumberField,
           name: `${name}__northing`,
-          title: 'Northing',
+          title: 'components.eastingNorthingField.northing',
           schema: {
             min: northingMin,
             max: northingMax,
@@ -135,7 +191,8 @@ export class EastingNorthingField extends FormComponent {
   }
 
   getDisplayStringFromFormValue(
-    value: EastingNorthingState | undefined
+    value: EastingNorthingState | undefined,
+    _translator: Translator
   ): string {
     if (!value) {
       return ''
@@ -145,10 +202,13 @@ export class EastingNorthingField extends FormComponent {
     return `${value.easting}, ${value.northing}`
   }
 
-  getDisplayStringFromState(state: FormSubmissionState) {
+  getDisplayStringFromState(
+    state: FormSubmissionState,
+    translator: Translator
+  ) {
     const value = this.getFormValueFromState(state)
 
-    return this.getDisplayStringFromFormValue(value)
+    return this.getDisplayStringFromFormValue(value, translator)
   }
 
   getContextValueFromFormValue(
@@ -167,15 +227,16 @@ export class EastingNorthingField extends FormComponent {
     return this.getContextValueFromFormValue(value)
   }
 
-  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
-    const viewModel = super.getViewModel(payload, errors)
-    return getLocationFieldViewModel(this, viewModel, payload, errors)
+  getViewModel(context: RenderContext) {
+    const viewModel = super.getViewModel(context)
+    return getLocationFieldViewModel(this, viewModel, context)
   }
 
   getViewErrors(
+    translator: Translator,
     errors?: FormSubmissionError[]
   ): FormSubmissionError[] | undefined {
-    const allErrors = this.getErrors(errors)
+    const allErrors = this.getErrors(translator, errors)
     return deduplicateErrorsByHref(allErrors)
   }
 

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

@@ -5,12 +5,9 @@ import {
 import joi, { type CustomHelpers } from 'joi'
 
 import { FormComponent } from './FormComponent.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 EmailAddressField extends FormComponent {
   declare options: EmailAddressFieldComponent['options']
@@ -54,8 +51,8 @@ export class EmailAddressField 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 = 'email'

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

@@ -9,6 +9,8 @@ import {
   FormComponent,
   isUploadState
 } from './FormComponent.js'
+import { type RenderContext } from './types.js'
+import { type Translator } from '../i18n/types.js'
 import { InvalidComponentStateError } from '../pageControllers/errors.js'
 import { messageTemplate } from '../pageControllers/validationOptions.js'
 import {
@@ -19,10 +21,8 @@ import {
   type FileUpload,
   type FileUploadMetadata,
   type FormContext,
-  type FormPayload,
   type FormState,
   type FormStateValue,
-  type FormSubmissionError,
   type FormSubmissionState,
   type SummaryList,
   type SummaryListAction,
@@ -32,10 +32,8 @@ import {
   type UploadStatusResponse
 } from '../types.js'
 import { render } from '../../nunjucks/index.js'
-import {
-  type FormQuery,
-  type FormRequestPayload
-} from '../../../routes/types.js'
+import { type FormRequestPayload } from '../../../routes/types.js'
+import { resolveLanguage } from '../../../utils/utils.js'
 
 export const uploadIdSchema = joi.string().uuid().required()
 
@@ -163,19 +161,26 @@ export class FileUploadField extends FormComponent {
     return this.isValue(value) ? value : undefined
   }
 
-  getDisplayStringFromFormValue(files: FileState[] | undefined): string {
+  getDisplayStringFromFormValue(
+    files: FileState[] | undefined,
+    translator: Translator
+  ): string {
     if (!files?.length) {
       return ''
     }
 
-    const unit = files.length === 1 ? 'file' : 'files'
-    return `Uploaded ${files.length} ${unit}`
+    return translator.t('components.fileUploadField.filesCount', {
+      count: files.length
+    })
   }
 
-  getDisplayStringFromState(state: FormSubmissionState) {
+  getDisplayStringFromState(
+    state: FormSubmissionState,
+    translator: Translator
+  ) {
     const files = this.getFormValueFromState(state)
 
-    return this.getDisplayStringFromFormValue(files)
+    return this.getDisplayStringFromFormValue(files, translator)
   }
 
   getContextValueFromFormValue(
@@ -189,17 +194,12 @@ export class FileUploadField extends FormComponent {
     return this.getContextValueFromFormValue(files)
   }
 
-  getViewModel(
-    payload: FormPayload,
-    errors?: FormSubmissionError[],
-    query: FormQuery = {}
-  ) {
+  getViewModel(context: RenderContext) {
+    const { errors, isForceAccess = false } = context
+    const { t } = context.translator
     const { options, page, schema } = this
 
-    // Allow preview URL direct access
-    const isForceAccess = 'force' in query
-
-    const viewModel = super.getViewModel(payload, errors)
+    const viewModel = super.getViewModel(context)
     const { attributes, id, value } = viewModel
 
     const files = this.getFormValue(value) ?? []
@@ -213,7 +213,10 @@ export class FileUploadField extends FormComponent {
       const { form } = status
       const { file } = form
 
-      const tag = { classes: 'govuk-tag--green', text: 'Uploaded' }
+      const tag = {
+        classes: 'govuk-tag--green',
+        text: t('components.fileUploadField.uploaded')
+      }
 
       const valueHtml = render
         .view('components/fileuploadfield-value.html', {
@@ -309,6 +312,9 @@ export class FileUploadField extends FormComponent {
     metadata: FormMetadata,
     context: FormContext
   ) {
+    const language = resolveLanguage(request)
+    const { t } = this.model.createTranslator(language)
+
     const notificationEmail = metadata.notificationEmail
 
     if (!notificationEmail) {
@@ -347,7 +353,7 @@ export class FileUploadField extends FormComponent {
         // Scenarios: file missing from S3, invalid retrieval key (timing problem), etc.
         throw new InvalidComponentStateError(
           this,
-          'There was a problem with your uploaded files. Re-upload them before submitting the form again.'
+          t('components.fileUploadField.uploadFailed')
         )
       }
 

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

@@ -1,11 +1,14 @@
 import {
+  type ComponentDef,
   type FormComponentsDef,
   type FormMetadata,
   type Item
 } from '@defra/forms-model'
+import { type LanguageMessages } from 'joi'
 
 import { ComponentBase } from './ComponentBase.js'
-import { optionalText } from './constants.js'
+import { type RenderContext } from './types.js'
+import { type Translator } from '../i18n/types.js'
 import {
   type FormContext,
   type FormRequestPayload
@@ -115,7 +118,10 @@ export class FormComponent extends ComponentBase {
     }
   }
 
-  getErrors(errors?: FormSubmissionError[]): FormSubmissionError[] | undefined {
+  getErrors(
+    _translator: Translator,
+    errors?: FormSubmissionError[]
+  ): FormSubmissionError[] | undefined {
     const { name } = this
 
     // Filter component and child errors only
@@ -134,34 +140,59 @@ export class FormComponent extends ComponentBase {
   }
 
   getFirstError(
+    translator: Translator,
     errors?: FormSubmissionError[]
   ): FormSubmissionError | undefined {
-    return this.getErrors(errors)?.[0]
+    return this.getErrors(translator, errors)?.[0]
   }
 
   getViewErrors(
+    translator: Translator,
     errors?: FormSubmissionError[]
   ): FormSubmissionError[] | undefined {
-    const firstError = this.getFirstError(errors)
+    const firstError = this.getFirstError(translator, errors)
     return firstError && [firstError]
   }
 
-  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
+  /**
+   * Override in composite fields to return translated Joi message overrides for
+   * their sub-fields, applied at validation time so schema-level English messages
+   * are replaced with the correct language. Return null to skip message patching.
+   */
+  getValidationMessagesOverride(
+    _translator: Translator
+  ): LanguageMessages | null {
+    return null
+  }
+
+  getViewModel({
+    payload,
+    errors,
+    translator,
+    isForceAccess: _isForceAccess = false
+  }: RenderContext) {
     const { hint, name, options = {}, title, viewModel } = this
 
+    const { t, tComponent } = translator
+
     const isRequired = !('required' in options) || options.required !== false
     const hideOptional = 'optionalText' in options && options.optionalText
-    const label = `${title}${!isRequired && !hideOptional ? optionalText : ''}`
+
+    const resolvedTitle =
+      tComponent(this as unknown as ComponentDef, 'title') || title
+    const optionalTag =
+      !isRequired && !hideOptional ? ` ${t('common.optional')}` : ''
+    const label = `${resolvedTitle}${optionalTag}`
 
     if (hint) {
       viewModel.hint = {
-        text: hint
+        text: tComponent(this as unknown as ComponentDef, 'hint') || hint
       }
     }
 
     // Filter component errors only
-    const componentErrors = this.getErrors(errors)
-    const componentError = this.getFirstError(componentErrors)
+    const componentErrors = this.getErrors(translator, errors)
+    const componentError = this.getFirstError(translator, componentErrors)
 
     if (componentErrors) {
       viewModel.errors = componentErrors
@@ -184,15 +215,21 @@ export class FormComponent extends ComponentBase {
     }
   }
 
-  getDisplayStringFromFormValue(value: FormValue | FormPayload): string {
+  getDisplayStringFromFormValue(
+    value: FormValue | FormPayload,
+    _translator: Translator
+  ): string {
     // Map selected values to text
     // eslint-disable-next-line @typescript-eslint/no-base-to-string
     return this.isValue(value) ? value.toString() : ''
   }
 
-  getDisplayStringFromState(state: FormSubmissionState): string {
+  getDisplayStringFromState(
+    state: FormSubmissionState,
+    translator: Translator
+  ): string {
     const value = this.getFormValueFromState(state)
-    return this.getDisplayStringFromFormValue(value)
+    return this.getDisplayStringFromFormValue(value, translator)
   }
 
   getContextValueFromFormValue(

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

@@ -7,10 +7,11 @@ import {
   isGeospatialState
 } from './FormComponent.js'
 import { getGeospatialSchema } from './helpers/geospatial.js'
+import { type RenderContext } from './types.js'
+import { type Translator } from '../i18n/types.js'
 import { messageTemplate } from '../pageControllers/validationOptions.js'
 import {
   type ErrorMessageTemplateList,
-  type FormPayload,
   type FormState,
   type FormStateValue,
   type FormSubmissionError,
@@ -31,13 +32,11 @@ export class GeospatialField extends FormComponent {
 
     const { options } = def
 
-    const formSchema = getGeospatialSchema(def)
-      .label(this.label)
-      .messages({
-        'array.min': messageTemplate.featuresMin as string,
-        'array.max': messageTemplate.featuresMax as string,
-        'array.length': messageTemplate.featuresLength as string
-      })
+    const formSchema = getGeospatialSchema(def).label(this.label).messages({
+      'array.min': messageTemplate.featuresMin,
+      'array.max': messageTemplate.featuresMax,
+      'array.length': messageTemplate.featuresLength
+    })
 
     this.formSchema = formSchema
     this.stateSchema = formSchema.default(null)
@@ -58,20 +57,26 @@ export class GeospatialField extends FormComponent {
     return this.isValue(value) ? value : undefined
   }
 
-  getDisplayStringFromFormValue(features: GeospatialState | undefined): string {
+  getDisplayStringFromFormValue(
+    features: GeospatialState | undefined,
+    translator: Translator
+  ): string {
     if (!features?.length) {
       return ''
     }
 
-    const unit = features.length === 1 ? 'location' : 'locations'
-
-    return `Added ${features.length} ${unit}`
+    return translator.t('components.geospatialField.added', {
+      count: features.length
+    })
   }
 
-  getDisplayStringFromState(state: FormSubmissionState) {
+  getDisplayStringFromState(
+    state: FormSubmissionState,
+    translator: Translator
+  ) {
     const features = this.getFormValueFromState(state)
 
-    return this.getDisplayStringFromFormValue(features)
+    return this.getDisplayStringFromFormValue(features, translator)
   }
 
   getContextValueFromFormValue(
@@ -86,8 +91,8 @@ export class GeospatialField extends FormComponent {
     return this.getContextValueFromFormValue(features)
   }
 
-  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
-    const viewModel = super.getViewModel(payload, errors)
+  getViewModel(context: RenderContext) {
+    const viewModel = super.getViewModel(context)
     const value =
       typeof viewModel.value === 'string'
         ? viewModel.value
@@ -101,16 +106,25 @@ export class GeospatialField extends FormComponent {
     }
   }
 
-  getErrors(errors?: FormSubmissionError[]): FormSubmissionError[] | undefined {
-    const fieldErrors = super.getErrors(errors)
+  getErrors(
+    translator: Translator,
+    errors?: FormSubmissionError[]
+  ): FormSubmissionError[] | undefined {
+    const fieldErrors = super.getErrors(translator, errors)
 
     fieldErrors?.forEach((err) => {
       if (err.name === 'description') {
         err.href = `#description_${err.path[1]}`
-        err.text = `Enter description for location ${Number(err.path[1]) + 1}`
+        err.text = translator.t(
+          'components.geospatialField.validation.descriptionRequired',
+          { count: Number(err.path[1]) + 1 }
+        )
       } else if (typeof err.name === 'number' && err.context?.country) {
         err.href = `#description_${err.path[1]}`
-        err.text = `Location ${Number(err.path[1]) + 1} must be in ${err.context.country}`
+        err.text = translator.t(
+          'components.geospatialField.validation.wrongCountry',
+          { count: Number(err.path[1]) + 1, country: err.context.country }
+        )
       }
     })
 
@@ -118,9 +132,10 @@ export class GeospatialField extends FormComponent {
   }
 
   getViewErrors(
+    translator: Translator,
     errors?: FormSubmissionError[]
   ): FormSubmissionError[] | undefined {
-    return this.getErrors(errors)
+    return this.getErrors(translator, errors)
   }
 
   isValue(value?: FormStateValue | FormState): value is GeospatialState {