Add support for i18n

package.json

@@ -41,6 +41,7 @@
     "ajv": "^8.17.1",
     "ajv-draft-04": "^1.0.0",
     "ajv-formats": "^3.0.1",
+    "ajv-i18n": "^4.2.0",
     "content-type": "^1.0.5",
     "json-schema-traverse": "^1.0.0",
     "lodash.clonedeep": "^4.5.0",
@@ -78,4 +79,4 @@
   "peerDependencies": {
     "express": "*"
   }
-}
+}

src/framework/ajv/index.ts

@@ -31,7 +31,7 @@ function createAjv(
   options: Options = {},
   request = true,
 ): AjvInstance {
-  const { ajvFormats, ...ajvOptions } = options;
+  const { ajvFormats, ajvLocale, ...ajvOptions } = options;
 
   const ajv = factoryAjv(openApiSpec.openapi, {
     ...ajvOptions,

src/framework/ajv/options.ts

@@ -2,6 +2,7 @@ import {
   NormalizedOpenApiValidatorOpts,
   Options,
   RequestValidatorOptions,
+  ResponseValidatorOptions,
   ValidateRequestOpts,
   ValidateResponseOpts,
 } from '../types';
@@ -16,7 +17,7 @@ export class AjvOptions {
     return this.baseOptions();
   }
 
-  get response(): Options {
+  get response(): ResponseValidatorOptions {
     const { allErrors, coerceTypes, removeAdditional } = <ValidateResponseOpts>(
       this.options.validateResponses
     );
@@ -54,6 +55,7 @@ export class AjvOptions {
       validateFormats,
       serDes,
       ajvFormats,
+      ajvLocale,
     } = this.options;
     const serDesMap = {};
     for (const serDesObject of serDes) {
@@ -82,6 +84,7 @@ export class AjvOptions {
       formats,
       serDesMap,
       ajvFormats,
+      ajvLocale,
     };
 
     return options;

src/framework/types.ts

@@ -46,8 +46,16 @@ export interface Options extends ajv.Options {
   // Specific options
   serDesMap?: SerDesMap;
   ajvFormats?: FormatsPluginOptions;
+  /**
+   * Locale for ajv-i18n (e.g. 'ru', 'de', 'zh'). Localizes AJV validation error messages.
+   * Can be a static string or a function that returns the locale per-request (e.g. reading
+   * from AsyncLocalStorage or a request-scoped context).
+   */
+  ajvLocale?: string | (() => string | undefined);
 }
 
+export interface ResponseValidatorOptions extends Options, ValidateResponseOpts { }
+
 export interface RequestValidatorOptions extends Options, ValidateRequestOpts { }
 
 export type ValidateRequestOpts = {
@@ -169,6 +177,12 @@ export interface OpenApiValidatorOpts {
   serDes?: SerDes[];
   formats?: Format[] | Record<string, ajv.Format>;
   ajvFormats?: FormatsPluginOptions;
+  /**
+   * Locale for ajv-i18n (e.g. 'ru', 'de', 'zh'). Localizes AJV validation error messages.
+   * Can be a static string or a function that returns the locale per-request (e.g. reading
+   * from AsyncLocalStorage or a request-scoped context).
+   */
+  ajvLocale?: string | (() => string | undefined);
   fileUploader?: boolean | multer.Options;
   multerOpts?: multer.Options;
   $refParser?: {

src/middlewares/openapi.request.validator.ts

@@ -1,4 +1,5 @@
 import Ajv, { ValidateFunction } from 'ajv';
+import * as localize from 'ajv-i18n';
 import { NextFunction, RequestHandler, Response } from 'express';
 import { createRequestAjv } from '../framework/ajv';
 import {
@@ -35,6 +36,7 @@ export class RequestValidator {
   private ajv: Ajv;
   private ajvBody: Ajv;
   private requestOpts: ValidateRequestOpts = {};
+  private ajvLocale: string | (() => string | undefined) | undefined;
 
   constructor(
     apiDoc: OpenAPIV3.DocumentV3 | OpenAPIV3.DocumentV3_1,
@@ -46,6 +48,7 @@ export class RequestValidator {
     delete this.apiDoc.components?.examples;
     this.requestOpts.allowUnknownQueryParameters =
       options.allowUnknownQueryParameters;
+    this.ajvLocale = options.ajvLocale;
 
     this.ajv = createRequestAjv(
       apiDoc,
@@ -206,11 +209,14 @@ export class RequestValidator {
       if (valid && validBody) {
         next();
       } else {
-        const errors = augmentAjvErrors(
-          []
-            .concat(validator.validatorGeneral.errors ?? [])
-            .concat(validatorBody.errors ?? []),
-        );
+        const rawErrors = []
+          .concat(validator.validatorGeneral.errors ?? [])
+          .concat(validatorBody.errors ?? []);
+        const locale = typeof this.ajvLocale === 'function' ? this.ajvLocale() : this.ajvLocale;
+        if (locale && localize[locale]) {
+          localize[locale](rawErrors);
+        }
+        const errors = augmentAjvErrors(rawErrors);
         const err = ajvErrorsToValidatorError(400, errors);
         const message = this.ajv.errorsText(errors, { dataVar: 'request' });
         const error: BadRequest = new BadRequest({

src/middlewares/openapi.response.validator.ts

@@ -1,5 +1,6 @@
 import { RequestHandler } from 'express';
 import Ajv, { ValidateFunction, Options } from 'ajv';
+import * as localize from 'ajv-i18n';
 import mung from '../framework/modded.express.mung';
 import { createResponseAjv } from '../framework/ajv';
 import {
@@ -14,6 +15,7 @@ import {
   OpenApiRequestMetadata,
   InternalServerError,
   ValidateResponseOpts,
+  ResponseValidatorOptions,
 } from '../framework/types';
 import * as mediaTypeParser from 'media-typer';
 import * as contentTypeParser from 'content-type';
@@ -33,17 +35,19 @@ export class ResponseValidator {
   } = {};
   private eovOptions: ValidateResponseOpts;
   private serial: number;
+  private ajvLocale: string | (() => string | undefined) | undefined;
 
   constructor(
     openApiSpec: OpenAPIV3.DocumentV3 | OpenAPIV3.DocumentV3_1,
-    options: Options = {},
+    options: ResponseValidatorOptions = {},
     eovOptions: ValidateResponseOpts = {},
     serial: number = -1,
   ) {
     this.spec = openApiSpec;
     this.ajvBody = createResponseAjv(openApiSpec, options);
     this.eovOptions = eovOptions;
     this.serial = serial;
+    this.ajvLocale = options.ajvLocale;
 
     // This is a pseudo-middleware function. It doesn't get registered with
     // express via `use`
@@ -194,7 +198,12 @@ export class ResponseValidator {
     });
 
     if (!valid) {
-      const errors = augmentAjvErrors(validator.errors);
+      const rawErrors = validator.errors;
+      const locale = typeof this.ajvLocale === 'function' ? this.ajvLocale() : this.ajvLocale;
+      if (locale && localize[locale]) {
+        localize[locale](rawErrors);
+      }
+      const errors = augmentAjvErrors(rawErrors);
       const message = this.ajvBody.errorsText(errors, {
         dataVar: '', // responses
       });