zod-vue-i18n

zod-vue-i18n

zod vue3 i18n vue-i18n

maintained with ❤️ by

Install

# pnpm
pnpm add zod-vue-i18n

# yarn
yarn add zod-vue-i18n

# npm
npm install zod-vue-i18n --save

Usage

This library is used to translate Zod's default error messages with vue-i18n.

import { createI18n } from 'vue-i18n'
import { z } from 'zod'
import { makeZodI18nMap } from 'zod-vue-i18n'

const i18n = createI18n({
    locale: 'en',
    messages: {
        en: {
            errors: {
                // ...
            }
        },
        it: {
            errors: {
                // ...
            }
        }
    }
})

z.setErrorMap(makeZodI18nMap(i18n))

Zod 4

If you are using Zod 4, you can import the makeZodI18nMap from the v4 subpath:

import { createI18n } from 'vue-i18n'
import { makeZodI18nMap } from 'zod-vue-i18n/v4'
import { z } from 'zod/v4' // zod@3.25.x || zod@4.0.x

const i18n = createI18n({
    locale: 'en',
    messages: {
        en: {
            errors: {
                // ...
            }
        },
        it: {
            errors: {
                // ...
            }
        }
    }
})
z.config({
    localeError: makeZodI18nMap(i18n)
})

Locales

We provide a set of json files with the translation of the errors of zod. You can use them in your project.

import { createI18n } from 'vue-i18n'
import { z } from 'zod'
import { makeZodI18nMap } from 'zod-vue-i18n'
import en from 'zod-vue-i18n/locales/en.json'
import it from 'zod-vue-i18n/locales/it.json'

const i18n = createI18n({
    locale: 'en',
    messages: {
        en,
        it
    }
})

z.setErrorMap(makeZodI18nMap(i18n))

if you want to add a set of error labels in your vue-i18n instance, you can use two different ways:

1. Merge the messages when you create the instance

import { createI18n } from 'vue-i18n'
import { z } from 'zod'
import { makeZodI18nMap } from 'zod-vue-i18n'
import en from 'zod-vue-i18n/locales/en.json'
import it from 'zod-vue-i18n/locales/it.json'
import myProjectMessages from './i18n'

const i18n = createI18n({
    locale: 'en',
    messages: {
        en: {
            ...en,
            ...myProjectMessages.en
        },
        it: {
            ...it,
            ...myProjectMessages.it
        }
    }
})

z.setErrorMap(makeZodI18nMap(i18n))

2. Add the messages when you need

import en from 'zod-vue-i18n/locales/en.json'

// Assuming you have a `vue-i18n` instance already created
i18n.global.mergeLocaleMessage(
    'en', // the locale you want to add
    en // the error messages you want to add
)

Zod 4

If you are using Zod 4, you can import the locales from the v4 subpath:

import en from 'zod-vue-i18n/locales/v4/en.json'

Plurals

Messages using count, maximum, minimum, keys or value can be converted to the plural form using vue-i18n pluralization feature

{
    "exact": "String must contain exactly {{minimum}} character | String must contain exactly {{minimum}} characters"
}

import { createI18n } from 'vue-i18n'
import { z } from 'zod'
import { makeZodI18nMap } from 'zod-vue-i18n'
import en from 'zod-vue-i18n/locales/en.json'
import it from 'zod-vue-i18n/locales/it.json'

const i18n = createI18n({
    locale: 'en',
    messages: {
        en,
        it
    }
})

z.setErrorMap(makeZodI18nMap(i18n))

z.string().length(1).safeParse('123') // String must contain exactly 1 character
z.string().length(3).safeParse('1234') // String must contain exactly 3 characters

Custom error messages

You can use custom error messages with the params property of the refine function.

import { createI18n } from 'vue-i18n'
import { z } from 'zod'
import { makeZodI18nMap } from 'zod-vue-i18n'

const i18n = createI18n({
    locale: 'en',
    messages: {
        en: {
            my_custom_key: 'This is not a string'
        }
    }
})

z.setErrorMap(makeZodI18nMap(i18n))

z.string()
    .refine(() => false, { params: { i18n: 'my_custom_key' } })
    .safeParse(123) // This is not a string

Note To use this functionality you need to add the i18n key to the params object.

Custom labels on any validation (Zod 4)

The params.i18n channel only works on refine/superRefine/custom. To attach a translated message to any validation — including built-ins like .min() or .email() — Zod 4 users can use makeZodI18nLabel, which wires the translation into Zod's native error option.

import { createI18n } from 'vue-i18n'
import { makeZodI18nLabel } from 'zod-vue-i18n/v4'
import { z } from 'zod/v4'

const i18n = createI18n({
    locale: 'en',
    messages: {
        en: {
            errors: {
                nameTooShort: 'Name too short: at least {min} characters',
                invalidEmail: 'This email is not valid'
            }
        }
    }
})

const label = makeZodI18nLabel(i18n)

z.string().min(5, label('nameTooShort', { min: 5 }))
z.email(label('invalidEmail'))
z.string().refine(() => false, label('nameTooShort'))

The message is resolved lazily on every parse, so statically-defined schemas keep producing the right text when the active locale changes — no need to recreate the schema. The lookup goes through the same key resolution as the error map (so the errors. namespace, fallbacks and plurals all apply), and accepts an optional count for pluralization: label('key', { count: n }, n).

Use WithPath to validate zod schema

When you use z.object to create a schema, you can handle the object key to customize the error message.

import { createI18n } from 'vue-i18n'
import { z } from 'zod'
import { makeZodI18nMap } from 'zod-vue-i18n'

const i18n = createI18n({
    locale: 'en',
    messages: {
        en: {
            errors: {
                invalidType: 'Expected {expected}, received {received}',
                invalidTypeWithPath:
          'The {path} property expected {expected}, received {received}'
            }
        }
    }
})

z.setErrorMap(makeZodI18nMap(i18n))

z.string().parse(1) // => Expected string, received number

z.object({
    name: z.string()
}).parse({ name: 1 }) // => The name property expected string, received number

If WithPath is suffixed to the key of the message, that message will be adopted in the case of an object type schema. If there is no message key with \WithPath, fall back to the normal error message.

zDate helper

The package also exports zDate, a ready-made schema that validates ISO calendar dates in YYYY-MM-DD format. This is handy for <input type="date"> values, which the browser exposes as strings rather than Date objects.

import { zDate } from 'zod-vue-i18n'
// import { zDate } from 'zod-vue-i18n/v4' // when using Zod 4

zDate.parse('2026-06-16') // ok
zDate.parse('16/06/2026') // throws

Development

The published package targets Node.js 16 and up, as declared in engines. Working on this repository needs a newer runtime: vitest requires ^22.12.0 || ^24.0.0 || >=26.0.0 and tsdown requires ^22.18.0 || ^24.11.0 || >=26.0.0, so use Node.js ^22.18, ^24.11 or >=26. CI runs the latest 24.x.

pnpm install
pnpm test        # vitest
pnpm type-check  # tsc --noEmit
pnpm lint        # eslint
pnpm build       # tsdown

Claude Code skill

This repo ships an installable Claude Code skill that teaches AI agents how to integrate @volverjs/zod-vue-i18n. Install it from your terminal:

npx skills add volverjs/zod-vue-i18n

See skills/volverjs-zod-vue-i18n/README.md for details.

Acknoledgements

zod-vue-i18n is inspired by zod-i18n-map.

License

MIT