Errore-kodeak eta mezu itzuliak

Balio bat baliozkoa ez denean, validate() funtzioak zergatik ez den baliozkoa azaltzen du error objektuaren lau eremuren bidez:

• code: errore mota, zazpi kodeetako bat, zure kodeak kasuaren arabera jardun dezan;
• rule: betetzen ez den SPEC.md arauaren identifikatzailea, adibidez DNI-2;
• message: erabiltzailearentzako esaldi bat, adierazten duzun hizkuntzan;
• expected: kontrol-karakterea okerra denean bakarrik, zuzena, «hau esan nahi zenuen?» iradokitzeko.

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() funtzioak balioa urratsez urrats egiaztatzen du eta lehen hutsegitean gelditzen da; beraz, balio baliogabe batek errore bat du, ez gehiago. type eta normalized formatua ezagut daitekeen unetik daude, kontrol-karakterea okerra izan arren.

Errore-kode guztiak

error.code	Noiz
NOT_A_STRING	Balioa ez da testu-kate bat (null, zenbaki bat, objektu bat). Ez da inoiz kate bihurtzen
EMPTY	Balioa hutsik dago, edo zuriuneak eta bereizleak bakarrik ditu
INVALID_LENGTH	Balioak ez du bere motari dagokion karaktere kopurua
INVALID_FORMAT	Formatuak onartzen ez duen karaktere bat: lehen karaktere okerra, digitu baten lekuan letra bat (edo kontrol-letraren lekuan digitu bat) edo ES aurrizkia allowVatPrefix gabe
INVALID_CONTROL_CHARACTER	Formatua zuzena da, baina kontrol-letra edo kontrol-digitua ez; expected eremuak zuzena du
UNSUPPORTED_TYPE	types aukerak kanpoan uzten duen mota bateko dokumentu baliozko bat
PLACEHOLDER	Ordezko balio bat (00000000T, 00000001R, 99999999R, X0000000T), rejectPlaceholders: true aukerarekin

Azken biak aukera batekin bakarrik gertatzen dira: aukera lehenetsiekin, dokumentu baliozko bat baliozkoa da beti.

Arau guztiak eta haien mezuak

Beheko taulak, kode bakoitzerako, aipa ditzakeen SPEC arau guztiak eta haiekin batera doan mezua biltzen ditu, orri honen hizkuntzan. Mezuak liburutegitik bertatik datoz; beraz, zure erabiltzaileek ikusiko dituztenak dira, hain zuzen.

validate() funtzioaren errore-kode guztiak, bakoitzak aipa dezakeen SPEC arau bakoitza, errore hori ematen duen sarrera bat eta haren mezua euskaraz

Araua	Adibidea	Mezua
Kodea: NOT_A_STRING
INPUT-1	null	Balioak testua izan behar du.
Kodea: EMPTY
INPUT-2	" - "	Sartu IFZ, AIZ edo IFK bat.
Kodea: INVALID_LENGTH
DNI-1	"1234567890"	NAN batek 9 karaktere ditu: 8 digitu eta letra bat.
KLM-1	"K123456"	K/L/M IFZ batek 9 karaktere ditu: K, L edo M, 7 digitu eta letra bat.
NIE-1	"X123456"	AIZ batek 9 karaktere ditu: X, Y edo Z, 7 digitu eta letra bat.
NIE-3	"X11234567L"	AIZ zaharrek bakarrik dituzte 10 karaktere: X, 0 bat, 7 digitu eta letra bat.
CIF-1	"B123456"	Pertsona juridiko edo erakunde baten IFZ (IFK) batek 9 karaktere ditu: letra bat, 7 digitu eta kontrol-karaktere bat.
VAT-1	"ES", { allowVatPrefix: true }	Espainiako IFZ-BEZ batek ES aurrizkia eta, ondoren, 9 karaktereko IFZ bat ditu.
Kodea: INVALID_FORMAT
NIF-1	"T1234567A"	Hau ez da IFZ, AIZ edo IFK bat: digitu batekin edo letra baliodun batekin hasi behar du.
VAT-1	"ES12345678Z"	Sartu IFZa ES aurrizkirik gabe.
DNI-1	"123456789"	NAN baten formatua hau da: 8 digitu eta, ondoren, letra bat.
KLM-1	"K12345678"	K/L/M IFZ baten formatua hau da: K, L edo M hasieran, ondoren 7 digitu eta amaieran letra bat.
KLM-3	"K12345A7L"	K, L edo M letraren ondorengo 7 karaktereek digituak izan behar dute.
NIE-1	"X12345678"	AIZ baten formatua hau da: X, Y edo Z hasieran, ondoren 7 digitu eta amaieran letra bat.
CIF-1	"B12A45674"	Pertsona juridiko edo erakunde baten IFZ (IFK) batek osaera hau du: letra bat, 7 digitu eta kontrol-karaktere bat (digitu bat edo letra bat), hurrenkera horretan.
Kodea: INVALID_CONTROL_CHARACTER
DNI-2	"12345678A"	Kontrol-karakterea ez da zuzena: NAN honetan «Z» izan beharko luke.
DNI-3	"12345678I"	Kontrol-karakterea ez da zuzena: NAN honetan «Z» izan beharko luke.
KLM-2	"K1234567A"	Kontrol-karakterea ez da zuzena: K/L/M IFZ honetan «L» izan beharko luke.
NIE-2	"Y1234567L"	Kontrol-karakterea ez da zuzena: AIZ honetan «X» izan beharko luke.
CIF-3	"G1234567D"	Kontrol-karakterea ez da zuzena: pertsona juridiko edo erakunde baten IFZ (IFK) honetan «4» izan beharko luke.
CIF-4	"B12345675"	Kontrol-karakterea ez da zuzena: pertsona juridiko edo erakunde baten IFZ (IFK) honetan «4» izan beharko luke.
Kodea: UNSUPPORTED_TYPE
POLICY-2	"B12345674", { types: ["DNI", "NIE"] }	Hemen ez da onartzen dokumentu mota hau: pertsona juridiko edo erakunde baten IFZ (IFK).
Kodea: PLACEHOLDER
POLICY-1	"00000000T", { rejectPlaceholders: true }	Zenbaki hau ordezko balio ezagunen zerrendan dago, eta hemen ez da onartzen.

Arauak kode bera duten kasuak bereizten ditu. Adibidez, INVALID_CONTROL_CHARACTER kodeak DNI-3 aipatzen du letra inoiz agertzen ez den horietako bat denean (I, Ñ, O, U), CIF-3 IFK baten kontrola letra bat denean eta gakoak digitua daramanean (edo alderantziz), eta CIF-4 mota zuzenekoa izan arren balio okerra duenean:

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

validate("12345678I").error?.rule; // "DNI-3"
validate("B1234567A").error?.rule; // "CIF-3": B gakoak digitua darama
validate("B12345675").error?.rule; // "CIF-4": digitu bat, baina ez zuzena
validate("T1234567A").error?.rule; // "NIF-1": IFZ bat ere ez da T letraz hasten
validate("X11234567L").error?.rule; // "NIE-3": 10 karaktere, baina ez da AIZaren forma zaharra

Hizkuntza aukeratzea

Ingelesa barne dago. Gainerako hizkuntza bakoitza sarrera-puntu bereizi bat da; beraz, bundle batek inportatzen dituen hizkuntzak bakarrik ditu. Inportatu hizkuntzaren objektua eta pasa ezazu locale gisa:

Hizkuntza	Inportazioa
Ingelesa (lehenetsia)	import { en } from "nif-dni-nie-cif-validation/locales/en"
Gaztelania (español)	import { es } from "nif-dni-nie-cif-validation/locales/es"
Katalana (català), valentzierarako ere bai	import { ca } from "nif-dni-nie-cif-validation/locales/ca"
Euskara	import { eu } from "nif-dni-nie-cif-validation/locales/eu"
Galegoa (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"

Hizkuntza-objektu berak balio du leku guztietan: validate() funtzioaren eta eskema guztien locale aukera gisa (zNif({ locale }), vNif({ locale }), yNif({ locale })), eta describeCifOrganisation() funtzioaren bigarren argumentu gisa. meta.orgDescription ere itzultzen du, IFK baten erakunde mota.

Erabiltzailearen hizkuntzari jarraitzeko, esleitu hizkuntza-objektu bat hizkuntza-etiketa bakoitzari, lehenetsi batekin:

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"); // adibidez, 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"

Katalanak valentzierarako ere balio du: AEATk erakunde-izen berak ematen ditu bietan, eta mezuek ez dute bi estandarren artean desberdina den formarik erabiltzen.

Pasa objektua, ez haren kodea

{ locale: "es" } TypeScript errore bat da, eta, exekuzio-garaian, kate bat ez da kontuan hartzen: mezuak ingelesez geratzen dira. Ez da salbuespenik jaurtitzen; beraz, inprimakiak funtzionatzen jarraitzen du, baina hizkuntza okerrean. Inportatu objektua.

Zure mezuak

code eta rule egonkorrak dira; beraz, zure testuekin lot ditzakezu, eta liburutegiaren mezua ordezko gisa erabili:

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."

Hizkuntza bat objektu arrunt bat da (NifLocale); beraz, beste hizkuntza baterako ere idatz dezakezu bat. Hizkuntza-objektu bati testu bat falta bazaio, ingelesa erabiltzen da testu horretarako. Itzulitako erakunde-izen bakoitzaren terminologia eta iturriak docs/translations.md fitxategian daude (ingelesez).

Eskemetan

Zod, Valibot eta Yup eskemek mezu bera ematen dute, eta kodea eta araua liburutegi bakoitzak uzten duen lekuan jartzen dituzte:

Liburutegia	Mezua	Kodea eta araua
Zod	issue-aren message	issue-aren params: { code, rule, expected? }
Valibot	issue-aren message	issue-a bera: issue.code, issue.rule, issue.expected
Yup	ValidationError objektuaren message	errorearen params: { code, rule, expected? }

Ikusi Inprimakiak egiaztatzea adibideak ikusteko.