Códigos de erro e mensaxes traducidas

Cando un valor non é válido, validate() explica por que con catro campos de error:

code: que clase de erro é, un de sete códigos, para que o seu código poida actuar segundo o caso;
rule: o identificador da regra de SPEC.md que non se cumpre, como DNI-2;
message: unha frase para a persoa usuaria, no idioma que indique;
expected: só se o carácter de control é incorrecto, o correcto, para suxerir «quixo dicir…?».

import { validate } from "nif-dni-nie-cif-validation";

validate("12345678A").error;
// { code: "INVALID_CONTROL_CHARACTER", rule: "DNI-2", expected: "Z",
//   message: 'The control character is not correct: for this DNI it should be "Z".' }

validate() comproba o valor paso a paso e detense no primeiro fallo, así que un valor non válido ten exactamente un erro. type e normalized están presentes en canto o formato é recoñecible, aínda que o carácter de control sexa incorrecto.

Todos os códigos de erro

`error.code`	Cando
`NOT_A_STRING`	O valor non é unha cadea de texto (`null`, un número, un obxecto). Nunca se converte nunha cadea
`EMPTY`	O valor está baleiro, ou só ten espazos e separadores
`INVALID_LENGTH`	O valor non ten o número de caracteres do seu tipo
`INVALID_FORMAT`	Un carácter que o formato non admite: un primeiro carácter incorrecto, unha letra onde vai un díxito (ou un díxito onde vai a letra de control) ou un prefixo `ES` sen `allowVatPrefix`
`INVALID_CONTROL_CHARACTER`	O formato é correcto, pero a letra ou o díxito de control non; `expected` contén o correcto
`UNSUPPORTED_TYPE`	Un documento válido dun tipo que `types` exclúe
`PLACEHOLDER`	Un número de exemplo (`00000000T`, `00000001R`, `99999999R`, `X0000000T`) con `rejectPlaceholders: true`

Os dous últimos só se producen cunha opción: coas opcións predeterminadas, un documento válido sempre é válido.

Todas as regras e as súas mensaxes

A táboa seguinte recolle, para cada código, todas as regras de SPEC que pode citar e a mensaxe que o acompaña, no idioma desta páxina. As mensaxes saen da propia biblioteca, así que son exactamente as que verán as súas persoas usuarias.

Todos os códigos de erro de validate(), cada regra de SPEC que poden citar, unha entrada que os produce e a súa mensaxe en galego
Regra	Exemplo	Mensaxe
Código: `NOT_A_STRING`
INPUT-1	`null`	O valor debe ser un texto.
Código: `EMPTY`
INPUT-2	`" - "`	Introduza un NIF, NIE ou CIF.
Código: `INVALID_LENGTH`
DNI-1	`"1234567890"`	Un DNI ten 9 caracteres: 8 díxitos e unha letra.
KLM-1	`"K123456"`	Un NIF K/L/M ten 9 caracteres: K, L ou M, 7 díxitos e unha letra.
NIE-1	`"X123456"`	Un NIE ten 9 caracteres: X, Y ou Z, 7 díxitos e unha letra.
NIE-3	`"X11234567L"`	Só os NIE antigos teñen 10 caracteres: X, un 0, 7 díxitos e unha letra.
CIF-1	`"B123456"`	Un NIF de entidade (CIF) ten 9 caracteres: unha letra, 7 díxitos e un carácter de control.
VAT-1	`"ES", { allowVatPrefix: true }`	Un NIF-IVE español é ES seguido dun NIF de 9 caracteres.
Código: `INVALID_FORMAT`
NIF-1	`"T1234567A"`	Non é un NIF, NIE nin CIF: debe comezar por un díxito ou por unha letra válida.
VAT-1	`"ES12345678Z"`	Introduza o NIF sen o prefixo ES.
DNI-1	`"123456789"`	Un DNI son 8 díxitos seguidos dunha letra.
KLM-1	`"K12345678"`	Un NIF K/L/M comeza por K, L ou M, seguido de 7 díxitos e unha letra.
KLM-3	`"K12345A7L"`	Os 7 caracteres que seguen a K, L ou M deben ser díxitos.
NIE-1	`"X12345678"`	Un NIE comeza por X, Y ou Z, seguido de 7 díxitos e unha letra.
CIF-1	`"B12A45674"`	Un NIF de entidade (CIF) consta dunha letra, 7 díxitos e un carácter de control (un díxito ou unha letra).
Código: `INVALID_CONTROL_CHARACTER`
DNI-2	`"12345678A"`	O carácter de control non é correcto: para este DNI debería ser «Z».
DNI-3	`"12345678I"`	O carácter de control non é correcto: para este DNI debería ser «Z».
KLM-2	`"K1234567A"`	O carácter de control non é correcto: para este NIF K/L/M debería ser «L».
NIE-2	`"Y1234567L"`	O carácter de control non é correcto: para este NIE debería ser «X».
CIF-3	`"G1234567D"`	O carácter de control non é correcto: para este NIF de entidade (CIF) debería ser «4».
CIF-4	`"B12345675"`	O carácter de control non é correcto: para este NIF de entidade (CIF) debería ser «4».
Código: `UNSUPPORTED_TYPE`
POLICY-2	`"B12345674", { types: ["DNI", "NIE"] }`	Aquí non se admite ningún NIF de entidade (CIF).
Código: `PLACEHOLDER`
POLICY-1	`"00000000T", { rejectPlaceholders: true }`	Este número figura na lista de valores de exemplo que non se admiten aquí.

A regra distingue casos que comparten código. Por exemplo, INVALID_CONTROL_CHARACTER cita DNI-3 cando a letra é unha das que nunca aparecen (I, Ñ, O, U), CIF-3 cando o control dun CIF é unha letra e a clave leva un díxito (ou ao revés) e CIF-4 cando é da clase correcta pero ten un valor incorrecto:

import { validate } from "nif-dni-nie-cif-validation";

validate("12345678I").error?.rule; // "DNI-3"
validate("B1234567A").error?.rule; // "CIF-3": a B leva díxito
validate("B12345675").error?.rule; // "CIF-4": un díxito, pero non o correcto
validate("T1234567A").error?.rule; // "NIF-1": ningún NIF comeza por T
validate("X11234567L").error?.rule; // "NIE-3": 10 caracteres, pero non é a forma antiga do NIE

Escoller o idioma

O inglés vén incluído. Cada un dos demais idiomas é un punto de entrada á parte, así que un bundle só contén os idiomas que importa. Importe o obxecto do idioma e páseo como locale:

Idioma	Importación
Inglés (predeterminado)	`import { en } from "nif-dni-nie-cif-validation/locales/en"`
Castelán (español)	`import { es } from "nif-dni-nie-cif-validation/locales/es"`
Catalán (català), tamén para o valenciano	`import { ca } from "nif-dni-nie-cif-validation/locales/ca"`
Éuscaro (euskara)	`import { eu } from "nif-dni-nie-cif-validation/locales/eu"`
Galego	`import { gl } from "nif-dni-nie-cif-validation/locales/gl"`

import { describeCifOrganisation, validate } from "nif-dni-nie-cif-validation";
import { eu } from "nif-dni-nie-cif-validation/locales/eu";

validate("12345678A", { locale: eu }).error?.message;
// "Kontrol-karakterea ez da zuzena: NAN honetan «Z» izan beharko luke."
describeCifOrganisation("B", eu); // "Erantzukizun mugatuko sozietatea"

O mesmo obxecto de idioma serve en todas partes: como opción locale de validate() e de todos os esquemas (zNif({ locale }), vNif({ locale }), yNif({ locale })), e como segundo argumento de describeCifOrganisation(). Tamén traduce meta.orgDescription, o tipo de entidade dun CIF.

Para seguir o idioma da persoa usuaria, asigne un obxecto de idioma a cada etiqueta de idioma, cun predeterminado:

import { type NifLocale, validate } from "nif-dni-nie-cif-validation";
import { ca } from "nif-dni-nie-cif-validation/locales/ca";
import { en } from "nif-dni-nie-cif-validation/locales/en";
import { es } from "nif-dni-nie-cif-validation/locales/es";

const LOCALES: Record<string, NifLocale> = { ca, en, es };
const localeFor = (language: string) => LOCALES[language.slice(0, 2)] ?? en;
const locale = localeFor("ca-ES"); // por exemplo, navigator.language

validate("12345678A", { locale }).error?.message;
// "El caràcter de control no és correcte: per a aquest DNI hauria de ser «Z»."
validate("B12345674", { locale }).meta?.orgDescription; // "Societat de responsabilitat limitada"

O catalán serve tamén para o valenciano: a AEAT dá os mesmos nomes de entidade en ambos, e as mensaxes non usan ningunha forma que difira entre os dous estándares.

As súas propias mensaxes

code e rule son estables, así que pode asocialos aos seus propios textos e usar a mensaxe da biblioteca como alternativa:

import { type NifErrorCode, validate } from "nif-dni-nie-cif-validation";

const MESSAGES: Partial<Record<NifErrorCode, string>> = {
  EMPTY: "Please enter your tax ID.",
  UNSUPPORTED_TYPE: "Please enter a personal tax ID, not a company's.",
};

const error = validate("B12345674", { types: ["DNI", "NIE"] }).error;
error && (MESSAGES[error.code] ?? error.message); // "Please enter a personal tax ID, not a company's."

Un idioma é un obxecto normal (NifLocale), así que tamén pode escribir un para outro idioma. Se a un obxecto de idioma lle falta un texto, úsase o inglés para ese texto. A terminoloxía e as fontes de cada nome de entidade traducido están en docs/translations.md (en inglés).

Nos esquemas

Os esquemas de Zod, Valibot e Yup dan a mesma mensaxe, e poñen o código e a regra onde cada biblioteca o permite:

Biblioteca	Mensaxe	Código e regra
Zod	a `message` do issue	os `params` do issue: `{ code, rule, expected? }`
Valibot	a `message` do issue	o propio issue: `issue.code`, `issue.rule`, `issue.expected`
Yup	a `message` do `ValidationError`	os `params` do erro: `{ code, rule, expected? }`

Consulte Validar formularios para ver exemplos.