Zodは非常に強力なバリデーションツールですが、標準のエラーメッセージは英語で出力されます。
ユーザー向けのUIでは、日本語でわかりやすく表示したい場面が多くあります。

このドキュメントでは、Zodのエラーメッセージを日本語化する具体的な方法とカスタマイズ手法を、実例とともに詳しく解説します。

---

日本語化のアプローチ

Zodの日本語化には以下の3つの方法があります：

方法	概要	おすすめ度
.refine() や .superRefine()	カスタム条件と同時にエラーメッセージ指定	★★★
.describe()＋メッセージ解釈	UI側で .description を使って表示メッセージに利用	★★☆
.errorMap() の活用	グローバルにエラーメッセージを置き換える	★★★

---

方法① .refine() で個別にエラーメッセージを指定

tsCopy codeimport { z } from "zod";

const passwordSchema = z
  .string()
  .min(8, { message: "パスワードは8文字以上で入力してください" })
  .refine((val) => /[A-Z]/.test(val), {
    message: "パスワードには大文字を1文字以上含めてください",
  });

• min() などのメソッドでも message を指定可能
• refine() は自由な条件とカスタムメッセージを同時に扱えるのが便利

---

方法② .superRefine() で複数項目にまたがる日本語バリデーション

tsCopy codeconst signUpSchema = z
  .object({
    password: z.string(),
    confirmPassword: z.string(),
  })
  .superRefine(({ password, confirmPassword }, ctx) => {
    if (password !== confirmPassword) {
      ctx.addIssue({
        code: "custom",
        path: ["confirmPassword"],
        message: "パスワードと確認用パスワードが一致しません",
      });
    }
  });

• フィールド間の整合性に関するバリデーションに最適
• ctx.addIssue() で任意のパスとメッセージを明示的に追加可能

---

方法③ ZodErrorMap を使ってグローバルに日本語化

Zodはエラーコードに応じたグローバルメッセージ変換マップを定義可能です。

tsCopy codeimport { z, ZodIssueCode, setErrorMap } from "zod";

// 日本語化マップを定義
setErrorMap((issue, ctx) => {
  const translations: Record<ZodIssueCode, string> = {
    invalid_type: "型が正しくありません",
    too_small: "値が小さすぎます",
    too_big: "値が大きすぎます",
    invalid_string: "文字列の形式が正しくありません",
    invalid_enum_value: "許可されていない値です",
    invalid_literal: "指定されたリテラル値と一致しません",
    custom: "不正な値です",
    // 他にも必要に応じて追加可能
  };

  const message = translations[issue.code] ?? ctx.defaultError;
  return { message };
});

使用例：

tsCopy codeconst schema = z.object({
  email: z.string().email(),
  age: z.number().min(18),
});

const result = schema.safeParse({ email: "test", age: 10 });
// エラー内容は日本語化されて出力される
console.log(result.error?.format());

---

画面表示に応じて個別翻訳をしたいときは？

フォームのフィールドごとにエラーを表示する場合、以下のように error.format() を活用できます。

tsCopy codeconst result = schema.safeParse(data);
if (!result.success) {
  const formatted = result.error.format();
  console.log(formatted.email?._errors); // ["メールアドレスの形式が正しくありません"]
}

---

React Hook Formで日本語エラーを扱うには？

React Hook Form + Zodで日本語エラーを表示したい場合、Zodスキーマに明示的に message を設定するだけでOKです。

tsCopy codeconst schema = z.object({
  name: z.string().nonempty("名前を入力してください"),
});

これで formState.errors.name.message に日本語エラーが格納され、UIでそのまま利用できます。

---

まとめ

Zodのバリデーションを日本語化することで、ユーザー体験が向上し、エラー内容の理解もスムーズになります。

方法	特徴
.refine() / .superRefine()	特定項目や複数項目間の柔軟な日本語対応が可能
.min(..., { message })など	単項目のエラーを個別に日本語化
setErrorMap()	グローバルで一括日本語化が可能

複雑なアプリケーションでは、これらを併用してスキーマごとの柔軟なエラーメッセージ戦略を設計すると、非常に高品質なUXが実現できます。

プロジェクト全体で統一された日本語バリデーションを整えたい場合は、Zodスキーマを共通モジュールとして分離・共通化する設計がおすすめです。