Localization

Localization (i18n) enables Formitiva applications to support multiple languages and regional formats. Formitiva provides built-in translations for UI text and validation messages, while also allowing applications to supply custom per-locale/per-form dictionaries to override or extend default behavior.

localization mechanisms

Formitiva supports two complementary approaches:

1. Built-in translations

   • Default translation keys and messages are bundled with the library.
   • Covers UI text, labels, and validation messages.

2. Custom translations

   • Applications can provide per-locale/per-form JSON dictionaries.
   • Custom keys override or extend built-in translations.

Translation Resolution

The t() helper resolves keys in the following order:

1. Application-provided custom dictionary (if available)
2. Built-in Formitiva translations
3. Fallback behavior (returns the key itself or a configured fallback string)

Supported Languages

This project provides builtin messages localization support for the following languages:

Abbr	Name	Native Name
en	English	English
fr	French	Français
de	German	Deutsch
es	Spanish	Español
zh-cn	Chinese (Simplified)	简体中文
zh-tw	Chinese (Traditional)	繁體中文
it	Italian	Italiano
ja	Japanese	日本語
ko	Korean	한국어
pt	Portuguese	Português
ru	Russian	Русский

The builtin messsages can be found in https://formitiva.com//locales/{lang_abbr}/common.json.

Translation Features

• Label translation

  Field labels (displayName), tooltips, and placeholder text are passed through the t() function automatically. Use message keys in your schema to enable translations and previews in the builder.

  Example:

  { "displayName": "Contact Name" }

• Error message translation

  Validation messages are produced as translatable keys by built-in validators; you may override them per-field (for example patternErrorMessage, requiredMessage) or return keys from custom validators.

  Example:

  { "pattern": "^\\[0-9]{5}$", "patternErrorMessage": "ZIP code must be exactly 5 digits (0–9)" }

• Option label translation

  For choice fields (dropdown, radio, multi-selection) keep value language-independent and translate label. Labels may be message keys resolved at render time.

  Example:

  "options": [ { "label": "United States", "value": "us" }, { "label": "Canada", "value": "ca" } ]

Custom Localization Mechanism

Follow these steps to provide custom, per-form localization dictionaries that the builder and renderer will load automatically:

1. Provide a Translation Dictionary

   • Place files under public/locales/{lang_abbr}/{localizationName}.json.
   • Example: public/locales/fr/my_form_translations.json.

2. Reference It in Your Form Defintion

   • In the form definition JSON, set the localization property to the {localizationName} you created.
   • Example:

{
  "name": "contact",
  "localization": "my_form_translations",
  "properties": [ /* ... */ ]
}

3. Automatic Loading When the app/provider initializes, the renderer:

• Loads public/locales/{lang_abbr}/{localizationName}.json
• Merges it with the global dictionary
• Supports multiple localization files per language
• Allows per-form localization customization

Place locale JSON files under public/locales/{abbr}/ and ensure your app provider loads the appropriate files for the active locale.