Zod 中的本地化设置：使用 setErrorMap 和 zod-i18n-js教程-PHP中文网

Zod 中的本地化设置：使用 setErrorMap 和 zod-i18n

心靈之曲

发布： 2025-08-12 21:04:29

原创

223人浏览过

zod 中的本地化设置：使用 seterrormap 和 zod-i18n

本文将介绍如何在 Zod 中实现类似于 Yup 的 setLocale 功能，用于自定义验证错误信息，特别是针对国际化 (i18n) 的场景。

使用 z.setErrorMap 自定义错误信息

Zod 提供了 z.setErrorMap(errorMap) 方法，允许你全局定义错误映射，从而定制验证失败时的错误信息。errorMap 是一个函数，它接收两个参数：issue 和 ctx。issue 包含了关于验证错误的详细信息，例如错误代码和预期类型。ctx 提供了默认的错误信息。

以下是一个示例，展示了如何使用 z.setErrorMap 来定制 invalid_type 和 custom 错误代码的错误信息：

import { z } from "zod";

const customErrorMap: z.ZodErrorMap = (issue, ctx) => {
  if (issue.code === z.ZodIssueCode.invalid_type) {
    if (issue.expected === "string") {
      return { message: "类型错误！应为字符串。" };
    }
  }
  if (issue.code === z.ZodIssueCode.custom) {
    return { message: `值小于最小值 ${(issue.params || {}).minimum}` };
  }
  return { message: ctx.defaultError };
};

z.setErrorMap(customErrorMap);

const schema = z.string().min(5);

try {
  schema.parse(123);
} catch (error) {
  console.log(error.errors); // 输出: [ { code: 'invalid_type', message: '类型错误！应为字符串。', ... } ]
}

try {
  schema.parse("abc");
} catch (error) {
  console.log(error.errors); // 输出: [ { code: 'too_small', message: '字符串必须至少包含 5 个字符', ... } ]
}

登录后复制

在这个例子中，当验证的类型不是字符串时，错误信息会被替换为 "类型错误！应为字符串。"。当字符串小于5个字符时，会使用默认的提示信息。

使用 zod-i18n 实现国际化

对于需要支持多语言的应用程序，可以使用 zod-i18n 库。它与 i18next 集成，允许你使用翻译文件来管理错误信息。

比格设计

比格设计是135编辑器旗下一款一站式、多场景、智能化的在线图片编辑器

124

查看详情

首先，你需要安装 zod-i18n 和 i18next：

npm install zod-i18n i18next

登录后复制

然后，你需要配置 i18next，并将其与 zod-i18n 关联。以下是一个示例：

import i18next from "i18next";
import { z } from "zod";
import { zodI18nMap } from "zod-i18n-map";
import translation from "zod-i18n-map/locales/zh-CN/zod.json"; // 导入中文翻译文件

i18next.init({
  lng: "zh-CN", // 设置语言
  resources: {
    "zh-CN": { zod: translation }, // 添加翻译资源
  },
});

z.setErrorMap(zodI18nMap);

const schema = z.string().email();

try {
  schema.parse("foo");
} catch (error) {
  console.log(error.errors); // 输出: [ { code: 'invalid_string', message: '无效的邮箱', ... } ]
}

登录后复制

在这个例子中，我们首先初始化了 i18next，指定语言为中文 ("zh-CN")，并加载了中文的 Zod 翻译文件。然后，我们将 zodI18nMap 设置为 Zod 的错误映射。当验证 email 失败时，错误信息将会被翻译成中文。

注意事项

在使用 z.setErrorMap 时，确保你处理了所有可能的 issue.code，以提供全面的错误信息。
zod-i18n 需要与 i18next 配合使用，因此你需要熟悉 i18next 的配置和使用方法。
定期更新你的翻译文件，以确保错误信息是最新的。
在大型项目中，建议将错误映射和翻译文件放在单独的模块中，以便于维护和管理。

总结

通过 z.setErrorMap 和 zod-i18n，你可以轻松地自定义 Zod 的错误信息，并实现国际化。这使得你能够为用户提供更友好和更具信息量的验证反馈，从而提高用户体验。选择哪种方法取决于你的项目需求和复杂度。对于简单的自定义，z.setErrorMap 可能就足够了。对于需要支持多语言的应用程序，zod-i18n 是一个更好的选择。

以上就是Zod 中的本地化设置：使用 setErrorMap 和 zod-i18n的详细内容，更多请关注php中文网其它相关文章！