What are localised error messages intended for? (and how to get them user-friendly)

[thany]

These localised error messages from zod/locales/* are not user-friendly. They are very developer friendly, but the vast majority of forms on the internet are probably intended for everyday users with very little knowledge of what an array or an undefined means. Yet, error messages like...

Invalid input: expected string, received undefined
Too small: expected array to have >=1 items

...are the official localised ones. So who are they for? What is the purpose of translating such technical looking error messages as-is?

And as for the documentation on this, what is the recommended way to have a JSON file somewhere to load in place of these very technical looking messages? So,

1. How can I load error messages from some JSON file, e.g. what API is avilable to do this?
2. What is the excepted/recommended format of said JSON?

Ultimately, I can't present this to the customer with a straight face. I have to mention "these are not final, they will be customised to be something more readable". And the above two questions will hopefully have the answer to achieve that.

[jthrilly]

To add onto this: it isn't clear from the docs how to add new localised messages. Is the intent that we copy the logic from the locale files? That feels like it might cause fragility. Could something like ICU messages be used to simplify?: https://next-intl.dev/docs/usage/translations#icu-messages

Also, if I want to provide a localised message that uses additional variables/context, I am forced to use the custom issue code to get access to a params record where I can dump arbitrary data:

if (
  greaterThan(
    value,
    formValues[attribute],
    comparisonVariable.type,
  )
) {

  ctx.addIssue({
    code: 'too_big',
    maximum: formValues[attribute],
    inclusive: false,
    origin: comparisonVariable.type === 'datetime' ? 'date' : 'number',
    message: `Your answer must be less than you used for the field '${comparisonVariable.name}'`, // <-- no way to do this in a localised way without using code: 'custom'
  });
}

Two suggestions:

1. params on all issue codes
2. message is typed as string | (locale: string) => string or similar, to allow for integration with internationalisation frameworks.

[thany]

Your remark about custom error messages (which in your mind probably aren't considered "custom" - they are just what you need) I have solved it by going

ctx.addIssue({
  code: 'custom',
  format: 'unsupported_phone',
});

And then in the localised files (which are also "custom" in my case, because they pretty much have to have), I can grab the format parameter and put it through our implementation of i18next. The params parameter is also available there, with any arbitrary stuff I'm passing along with the error.

Still not ideal, still forced to play in the "custom corner" of things, but at least it works.

It does unfortunately make it seem like i18n is but an afterthought for Zod, just as it is for most other schema validation packages.