How can I work with Zod?

[Pkcarreno]

I have a project where I use the zod library for the error messages in the forms. But I don't know how I could integrate this library with the zod message maps.

There is a library that handles this kind of situation, it is called zod-i18n which uses i18next, this library (zod-i18n) generates a message map before mounting the component, I tried to replace i18next with this library (next-intl), but without much success because the flow conflicts with the use of hooks.

Is there any way to integrate this library (next-intl) somehow with zod? has anyone been able to do it?

[amannn]

Interesting question! I haven't worked with zod yet, so I'm not really familiar with the patterns.

My general advice would be that you should receive a structured error object from zod which you can then map to human readable messages within a React component. This looks quite promising: https://github.com/colinhacks/zod/blob/master/ERROR_HANDLING.md#a-demonstrative-example

This is somewhat related: https://next-intl-docs.vercel.app/blog/translations-outside-of-react-components

But again, I'm not really familiar with zod, so any pointers from experienced users might be really helpful.

EDIT: Here's an example I saw in the wild: nextjs-shadcn-admin (SignupForm).

[Dosbodoke]

Hey, I'm facing the same issue, can you share what you did to resolve it?

[Dosbodoke]

Since zod-i18n is under MIT license, you are free to share the code. You can even start a forked repository and start a new open source project that I'm sure it will help a lot of NextJS users

[Pkcarreno]

Hey @Dosbodoke I hope it is not too late, I am a bit busy now, but when I get some time I will share my solution

[Dosbodoke]

It's not, thx mate. I'm currently developing two project, one of them use i18next and I was able to make this integration, but not with next-intl since I'm using it with server components.

I'm using "next-intl": "3.0.0-rc.2"

[Pkcarreno]

@Dosbodoke so, this is my zodIntl.tsx file (name as you want):

import { useFormatter, useTranslations } from 'next-intl'
import type { ZodErrorMap } from 'zod'
import { defaultErrorMap, ZodIssueCode, ZodParsedType } from 'zod'

const jsonStringifyReplacer = (_: string, value: any): any => {
  if (typeof value === 'bigint') {
    return value.toString()
  }

  return value
}

const isRecord = (value: unknown): value is Record<string, unknown> => {
  if (typeof value !== 'object' || value === null) return false

  for (const key in value) {
    if (!Object.prototype.hasOwnProperty.call(value, key)) return false
  }

  return true
}

const getKeyAndValues = (
  param: unknown,
  defaultKey: string
): {
  values: Record<string, unknown>
  key: string
} => {
  if (typeof param === 'string') return { key: param, values: {} }

  if (isRecord(param)) {
    const key = 'key' in param && typeof param.key === 'string' ? param.key : defaultKey
    const values = 'values' in param && isRecord(param.values) ? param.values : {}

    return { key, values }
  }

  return { key: defaultKey, values: {} }
}

export type MakeZodI18nMap = (option?: ZodI18nMapOption) => ZodErrorMap

export type ZodI18nMapOption = {
  t?: any
  ns?: string | readonly string[]
  handlePath?: HandlePathOption | false
}

export type HandlePathOption = {
  context?: string
  ns?: string | readonly string[]
  keyPrefix?: string
}

const defaultNs = 'zod'

export const useMakeZodI18nMap: MakeZodI18nMap = option => {
  const translations = useTranslations(defaultNs)
  const format = useFormatter()

  return (issue, ctx) => {
    const { t, ns, handlePath } = {
      t: translations,
      ns: defaultNs,
      ...option,
      handlePath:
        option?.handlePath !== false
          ? {
              context: 'with_path',
              ns: option?.ns ?? defaultNs,
              keyPrefix: undefined,
              ...option?.handlePath
            }
          : null
    }

    let message: string
    message = defaultErrorMap(issue, ctx).message

    const path =
      issue.path.length > 0 && !!handlePath
        ? {
            context: handlePath.context,
            path: t([handlePath.keyPrefix, issue.path.join('.')].filter(Boolean).join('.'), {
              defaultValue: issue.path.join('.')
            })
          }
        : {}

    switch (issue.code) {
      case ZodIssueCode.invalid_type:
        if (issue.received === ZodParsedType.undefined) {
          message = t('errors.invalid_type_received_undefined', {
            defaultValue: message,
            ...path
          })
        } else {
          message = t('errors.invalid_type', {
            expected: t(`types.${issue.expected}`, {
              defaultValue: issue.expected
            }),
            received: t(`types.${issue.received}`, {
              defaultValue: issue.received
            }),
            defaultValue: message,
            ...path
          })
        }
        break
      case ZodIssueCode.invalid_literal:
        message = t('errors.invalid_literal', {
          expected: JSON.stringify(issue.expected, jsonStringifyReplacer),
          defaultValue: message,
          ...path
        })
        break
      case ZodIssueCode.unrecognized_keys:
        message = t('errors.unrecognized_keys', {
          keys: format.list(issue.keys, { type: 'disjunction' }),
          count: issue.keys.length,
          defaultValue: message,
          ...path
        })
        break
      case ZodIssueCode.invalid_union:
        message = t('errors.invalid_union', {
          defaultValue: message,
          ...path
        })
        break
      case ZodIssueCode.invalid_union_discriminator:
        message = t('errors.invalid_union_discriminator', {
          options: format.list(issue.options as any[], { type: 'disjunction' }),
          defaultValue: message,
          ...path
        })
        break
      case ZodIssueCode.invalid_enum_value:
        message = t('errors.invalid_enum_value', {
          options: format.list(issue.options as any[], { type: 'disjunction' }),
          received: issue.received,
          defaultValue: message,
          ...path
        })
        break
      case ZodIssueCode.invalid_arguments:
        message = t('errors.invalid_arguments', {
          defaultValue: message,
          ...path
        })
        break
      case ZodIssueCode.invalid_return_type:
        message = t('errors.invalid_return_type', {
          defaultValue: message,
          ...path
        })
        break
      case ZodIssueCode.invalid_date:
        message = t('errors.invalid_date', {
          defaultValue: message,
          ...path
        })
        break
      case ZodIssueCode.invalid_string:
        if (typeof issue.validation === 'object') {
          if ('startsWith' in issue.validation) {
            message = t(`errors.invalid_string.startsWith`, {
              startsWith: issue.validation.startsWith,
              defaultValue: message,
              ...path
            })
          } else if ('endsWith' in issue.validation) {
            message = t(`errors.invalid_string.endsWith`, {
              endsWith: issue.validation.endsWith,
              defaultValue: message,
              ...path
            })
          }
        } else {
          message = t(`errors.invalid_string.${issue.validation}`, {
            validation: t(`validations.${issue.validation}`, {
              defaultValue: issue.validation
            }),
            defaultValue: message,
            ...path
          })
        }
        break
      case ZodIssueCode.too_small:
        const minimum = issue.type === 'date' ? new Date(issue.minimum as number) : issue.minimum
        message = t(
          `errors.too_small.${issue.type}.${issue.exact ? 'exact' : issue.inclusive ? 'inclusive' : 'not_inclusive'}`,
          {
            minimum:
              minimum instanceof Date
                ? format.dateTime(minimum, {
                    year: 'numeric',
                    month: 'short',
                    day: 'numeric'
                  })
                : 'err',
            count: typeof minimum === 'number' ? minimum : undefined,
            defaultValue: message,
            ...path
          }
        )
        break
      case ZodIssueCode.too_big:
        const maximum = issue.type === 'date' ? new Date(issue.maximum as number) : issue.maximum
        message = t(
          `errors.too_big.${issue.type}.${issue.exact ? 'exact' : issue.inclusive ? 'inclusive' : 'not_inclusive'}`,
          {
            maximum:
              maximum instanceof Date
                ? format.dateTime(maximum, {
                    year: 'numeric',
                    month: 'short',
                    day: 'numeric'
                  })
                : undefined,
            count: typeof maximum === 'number' ? maximum : undefined,
            defaultValue: message,
            ...path
          }
        )
        break
      case ZodIssueCode.custom:
        const { key, values } = getKeyAndValues(issue.params?.i18n, ns + '.errors.custom')

        message = t(key, {
          ...values,
          defaultValue: message,
          ...path
        })
        break
      case ZodIssueCode.invalid_intersection_types:
        message = t('errors.invalid_intersection_types', {
          defaultValue: message,
          ...path
        })
        break
      case ZodIssueCode.not_multiple_of:
        message = t('errors.not_multiple_of', {
          multipleOf: issue.multipleOf,
          defaultValue: message,
          ...path
        })
        break
      case ZodIssueCode.not_finite:
        message = t('errors.not_finite', {
          defaultValue: message,
          ...path
        })
        break
      default:
    }

    return { message }
  }
}

Is a custom hook that returns a Zod error map in the current language

To use it you need to add this to your form file:

export const ExampleForm = () => {
  const zodErrors = useMakeZodI18nMap()
  z.setErrorMap(zodErrors)

  return {...}
}

That's all, idk if there is a better way to do this but this does the work for me.

[amannn]

I've just added a section on Server Actions to the next-intl docs. There's also an example of how Zod can be used for parsing incoming form data, hope this helps!

A side note for react-hook-form users: zodResolver seems to accept a second argument (schemaOptions) that can be used to provide the errorMap as shown in the Server Actions example in the docs.

[Pkcarreno]

Amazing, thank you very much 🙌

[inspiraller]

Try this solution. I've simplified the complexity of use.
https://github.com/inspiraller/react-zod-next-intl

[elie-laloum]

Amazing, thank you!!

I was stuck on transmitting the translation for the refine and superrefine functions without using the hook method (useValidationSchema).

Simply pass the i18n key in the issue params and then use it in the errorMap.

// schema.ts

import { z } from "zod";

let schema = z.object({
  password: z.string().min(8),
  confirm_password: z.string().min(8),
});

schema = schema.superRefine(async ({ password, confirm_password }, check) => {
  if (password !== confirm_password) {
    check.addIssue({
      code: "custom",
      path: ["confirm_password"],
      params: {
        i18n: "customValidation.confirmPassword_match",
      },
    });
  }
})

// custom-error-map.ts

...
export const createCustomErrorMap = (): z.ZodErrorMap => {
  const t = useTranslations("domain-shared-schema-validation");

  return (issue, ctx) => {
    let key = "";
    const { code } = issue;
    switch (code) {
      ...
      case "custom":
        key = issue.params?.i18n ?? (issue.message as string);
        break;
      default:
        key = issue.code;
    }
    return { message: t(key, issue as any) ?? ctx.defaultError };
}

[inspiraller]

I've updated my repo with latest README to tidy up. Don't need custom error map anymore. To solve the above problem I have a similar solution within my useValidationSchema.ts

https://github.com/inspiraller/react-zod-next-intl/blob/main/src/component/Form/Implementation/FormRegister/useValidationSchema.ts

import { PropsFormRegister } from "@/@types";
import { TranslationValues } from "next-intl";
import { z, ZodType } from "zod"; // Add new import
import en from "@/messages/en.json";

type firstKey = keyof typeof en.zod;

type TasProp = (
  key: firstKey | `${firstKey}.confirmPassword_match`, // extend typescript when needed
  val?: TranslationValues | undefined
) => string;

export const useValidationSchema = (
  t?: TasProp
): ZodType<PropsFormRegister> => {
  return z
    .object({
      regUsername: z.string().min(3),
      regEmail: z.string().email(),
      regPassword: z.string().min(8).max(20),
      regConfirmPassword: z.string(),
    })
    .refine((data) => data.regPassword === data.regConfirmPassword, {
      message: t?.("customValidation.confirmPassword_match"), //This is defined in my en.json - zod: {customValidation: {confirmPassword__match: 'my validation message here'}}
      path: ["regConfirmPassword"],
    });
};

[btnalexandre]

Hey,

If you wish, you can use this approach. It allows you to isolate schemas in specific files without complicating the form components :)

Example :

File : auth.schema.ts

import { z } from "zod";
import { useTranslations } from "next-intl";

export const useLoginSchema = () => {
  const t = useTranslations("validation");

  const LOGIN_SCHEMA = z.object({
    email: z
      .string()
      .min(1, { message: t("emailEmpty") })
      .email({ message: t("emailInvalid") }),
    password: z.string().min(1, { message: t("passwordEmpty") }),
  });

  return LOGIN_SCHEMA;
};

export type TLoginSchema = z.infer<ReturnType<typeof useLoginSchema>>;

Component file with react-hook-form

"use client";

import { useLoginSchema, type TLoginSchema } from "~/schemas/auth.schema";
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";

export default function LoginForm() {
  const loginSchema = useLoginSchema();
  const form = useForm<TLoginSchema>({
    resolver: zodResolver(loginSchema),
    defaultValues: {
      email: "",
      password: "",
    },
  });
}

[tretail]

Depending of your usage, you may want translations server-side, but it would not work because of useTranslations being a hook.
A solution would be to do the following:

Using React-hook-form, Zod and Next-Intl

export const createSignInSchema = (
  t: (key: keyof Messages["Schemas"]["SignIn"]) => string,
) => {
  return z.object({
    email: z.string().email({ message: t("invalid_email") }),
    password: z.string().min(1, { message: t("no_input") }),
  });
};

Then use it in a client component:

"use client"
type SignInFormSchema = z.infer<ReturnType<typeof createSignInSchema>>;

const SignInForm = () => {
  const t = useTranslations("Schemas.SignIn"); // <== using useTranslations
  const schema = createSignInSchema(t);
  const reacthookform = useForm<SignInFormSchema>({
    resolver: zodResolver(signInSchema),
  });
...

or server-side:

"use server"

export async function signInAction(
  prev: FormState | null,
  formData: FormData,
): Promise< { message: string } > => {
  const t = await getTranslations("Schemas.SignIn"); // <== using getTranslations 
  const schema = createSignInSchema(t);

 const input = schema.safeParse(Object.fromEntries(formData));

...
}

[jeffpham2906]

@tretail Can i ask how the type Messages would be defined? I found that is not provided by any lib.

[btnalexandre]

@tretail my reply is a bit late, but thank you very much. Your solution is better than mine because it allows you to manage server and client mode without duplicating the schema :)

[btnalexandre]

@tretail Can i ask how the type Messages would be defined? I found that is not provided by any lib.

you can find it in next/intl :

import { type Messages } from "next-intl";

[CCinCapital]

Thanks for the snippets.

If anyone needs the nested keys, try:

import { Messages, NestedKeyOf } from "next-intl";

...
t: (key: NestedKeyOf<Messages["schemas"]["SignIn"]>) => string,
...

[YHADJRABIA]

@amannn

The t.has feature introduced in 3.21.0 might be messing up the type of API translated zod messages.

Before the update, I was able to do this without any typescript errors from zod validators:

export async function POST(req: NextRequest) {
  try {
    const locale = getLocaleFromNextRequest(req)
    const t_zod = await getTranslations({ locale, namespace: 'Zod' })

    const rawBody = await req.json()
    const body = EmailVerificationByCodeValidator(t_zod).safeParse(rawBody) <----- Error here now
 ...

export const EmailVerificationByCodeValidator = (
  t: ReturnType<typeof useTranslations<'Zod'>>
) => z.object({ code: codeSchema(t) })

export type EmailVerificationByCodeSchema = z.infer<
  ReturnType<typeof EmailVerificationByCodeValidator>
>

Now, I get this typescript error when hovering over t_zod, which points at the new has attribute

Workarounds:

• Override useTranslations.d.ts and remove has -> No more typescript errors;
• Cast t_zod as ReturnType<typeof useTranslations> (which hinders auto-complete)

P.S. using const t_zod = await getTranslations('Zod') isn't an option (It only shows zod errors in default locale regardless of which locale the user uses)
Replacing t: ReturnType<typeof useTranslations<'Zod'>> with t: ReturnType<typeof getTranslations<'Zod'>> isn't an option either

Any suggestions?

[amannn]

Ah yep, there seems to be a bug—thanks for the hint! This should be fixed with #1616

[YHADJRABIA]

Hi amann, thank you for confirming that it was indeed a bug and for the fix 🙂

P.S. I confirm that the typescript errors are gone

[nthadrien]

I had the same issues with a custom i18n I made with solid-js. So I came up with 2 solutions, I hope this will help.

1- Vanilla approach by calling a js/ts file that listens to pathname changes:

import { z } from 'zod';
 
 // Define your locale-specific error maps
 const errorMapFr = (issue, ctx) => {
   // French translations...
   return { message: 'Champ invalide' };
 };
 
 const errorMapEn = (issue, ctx) => {
   // English translations...
   return { message: 'Invalid field' };
 };
 
 const localeMaps = {
   fr: errorMapFr,
   en: errorMapEn,
 };
 
 // This function listens for URL changes and sets the Zod locale.
 function setZodLocaleFromPathname() {
   const path = window.location.pathname;
   // A simple way to extract the locale from the URL (e.g., /fr/about)
   const localeCode = path.split('/')[1]; 
   const errorMap = localeMaps[localeCode] || localeMaps.en; // Default to English
   
   z.setErrorMap(errorMap);
 }
 
 // Initial call when the page loads
 setZodLocaleFromPathname();
 
 // Listen for subsequent URL changes triggered by browser navigation (e.g., back/forward buttons)
 window.addEventListener('popstate', setZodLocaleFromPathname);

2-Using CreateEffect and useParams() to listen on Params change at the locale component changer :

export const LangSwitch = () => {
 
     const params = useParams();
     const location = useLocation();
 
     createEffect(() => {
         params.locale == "en" ? z.config(en()) : z.config(fr());
         console.log("lang changed to:", params.locale);
     });
 
     const changePath = (a: string) => {
         if (a == params.locale) return location.pathname;
         const pp = location.pathname.split("/");
         pp[1] = a;
         return pp.join("/");
     }
 
     return (
         <div class="dropdown">
             <button class="btn btn-sm fw-bold" type="button" data-bs-toggle="dropdown" aria-expanded="false">
                 <i class="las la-language me-1" />{params.locale}
             </button>
             <ul class="dropdown-menu dropdown-menu-end">
                 <For each={Object.keys(languages)}>
                     {item => <li>
                         <A activeClass="active" href={changePath(item)} class="dropdown-item text-capitalize" >
                             {item} - {languages[item]}
                         </A>
                     </li>}
                 </For>
             </ul>
         </div>
     );
 }

with this approach all I need was the component to be used on my layout and zodv4 lib. Nothing more