Localization (i18n)

Ctrovalidate provides a centralized, isomorphic Translator system in the ctrovalidate-core package. It allows you to manage error messages for multiple languages and dynamically switch locales across your entire application.

🏗️ The Global Translator

The translator instance is shared across all packages (core, react, vue, svelte, browser). When you change the locale in the core, the adapters react to it.

[!IMPORTANT] Reactivity Note: Changing the locale does NOT automatically re-render existing error messages. You must trigger a re-validation (e.g., validateForm()) to update the UI with new translations.

import { translator } from 'ctrovalidate-core';
 
// Switch to French
translator.setLocale('fr');

🛠️ Registering Custom Locales

You can add support for new languages by providing a dictionary object that maps rule names to translated messages.

// Register Spanish
translator.addMessages('es', {
  required: '¡Este campo es obligatorio!',
  email: 'Por favor, introduce un correo electrónico válido.',
  minLength: 'Debe tener al menos {0} caracteres.'
});
 
// Activate it
translator.setLocale('es');

🧩 Message Interpolation

Messages support dynamic placeholders using the {n} syntax, where n corresponds to the index of the rule parameter.

• Rule: minLength:8
• Message: Must be at least {0} characters.
• Result: Must be at least 8 characters.

For rules with multiple parameters (like between:18,65):

• Message: Value must be between {0} and {1}.
• Result: Value must be between 18 and 65.

🔄 Two Ways to Use Locales

Ctrovalidate supports two complementary approaches for managing locales:

1. Global Locale (App-Wide)

Use translator.setLocale() to change the language for all validation across your entire application.

import { translator } from 'ctrovalidate-core';
 
// Switch globally
translator.setLocale('es');
 
// All hooks will now use Spanish messages (if registered)

[!IMPORTANT] Reactivity Note: Changing the global locale does NOT automatically re-render existing error messages. You must trigger a re-validation (e.g., validate()) to update the UI with new translations.

2. Hook-Level Locale (Per-Form Override)

Pass a locale option directly to the hook to override the global locale for that specific form instance.

import { useCtrovalidate } from 'ctrovalidate-react';
 
const { errors, validate } = useCtrovalidate({
  schema: { email: 'required|email' },
  locale: 'fr', // This form always uses French, regardless of global locale
});

Use Cases:

• Global: User preference switcher, app-wide language settings
• Hook-Level: Multi-language forms on the same page, admin panels with fixed locales

🔄 Dynamic Switching Example (React)

Here is a verified pattern for switching languages dynamically in a React application using the global approach.

import { useCtrovalidate } from 'ctrovalidate-react';
import { translator } from 'ctrovalidate-core';
 
// 1. Setup dictionaries once (e.g., in App.tsx)
translator.addMessages('es', {
  required: 'Requerido',
  email: 'Email inválido'
});
 
function MyForm() {
  const { validateForm, errors } = useCtrovalidate({ /* ... */ });
 
  const switchLanguage = async (lang) => {
    // 2. Set the global locale
    translator.setLocale(lang);
    
    // 3. IMPORTANT: Re-validate to update current errors
    await validate();
  };
 
  return (
    <button onClick={() => switchLanguage('es')}>Español</button>
  );
}

🚀 Contextual Overrides

While global i18n is powerful, you often need to override messages for a specific field without touching the global dictionary.

In HTML (Browser)

<input 
  name="username" 
  data-ctrovalidate-rules="required" 
  data-ctrovalidate-message="Your username is required to login." 
/>

In Schemas (Direct Override)

You can pass a messages object to the hook options to override specific rules for that form instance.

useCtrovalidate({
  schema: { ... },
  messages: {
    'required': 'Custom required message for this form',
    'email': 'Please enter a valid email address'
  }
});

Message Resolution (highest priority first):

1. messages[ruleName] — from setCustomMessages(), hook messages option, or data-ctrovalidate-{ruleName}-message attribute
2. messages['*'] — catch-all from setCustomMessages(), hook messages, or data-ctrovalidate-message attribute
3. translator.translate(ruleName, params, locale) — resolves via locale dictionary:
   • Uses locale override or translator.currentLocale
   • Looks up the rule key in that locale's dictionary
   • Falls back to the 'default' key, then 'Invalid input.'

Note: The locale option does not add a separate priority level — it controls which locale dictionary is used during translation.

✅ Best Practices

• Shared Dictionaries: Keep your translation objects in a separate i18n/ directory to facilitate contribution and maintenance.
• Fallback: Ctrovalidate includes a built-in English fallback. If a rule is missing in your custom locale, it will gracefully revert to English.
• Dynamic Switching: In SPAs, listen for your app's language change event and call translator.setLocale() accordingly.
• Hook-Level Locale: Use the locale option when you need a specific form to always use a certain language, regardless of global settings.