Internationalization (i18n)

BlueForm handles i18n at the orchestration level, not inside field components. Labels, descriptions, and validation messages are translated before they reach fields — field components always receive ready-to-render strings and never need to know about locales or translation libraries.

label        // already translated
description  // already translated
errorMessage // already translated

i18n is configured once in setupForm via i18nConfig and is entirely optional — if omitted, all text values are treated as plain strings.

Translating labels and descriptions

The t function receives whatever string is in field config and returns the translated value. BlueForm does not dictate key format — use any convention your app already has.

Preview

Code

import { setupForm, defineMapping } from "react-headless-form";
import InputField from "./fields/InputField";

const [Form] = setupForm({
  renderRoot: ({ children, onSubmit }) => (
    <div className="blueform-example">
      <form onSubmit={onSubmit}>{children}</form>
    </div>
  ),
  fieldMapping: defineMapping({ text: InputField }),
  i18nConfig: {
    t: (message) => {
      switch (message) {
        case "label.username":
          return "Username";
        case "label.email":
          return "Email";
        case "desc.username":
          return "Your public display name";
        case "desc.email":
          return "We'll never share your email";
        default:
          return message;
      }
    },
  },
});

export default function EgI18nMessages() {
  return (
    <Form
      config={{
        username: {
          type: "text",
          label: "label.username",
          description: "desc.username",
        },
        email: {
          type: "text",
          label: "label.email",
          description: "desc.email",
          props: { type: "email" },
        },
      }}
      onSubmit={(data) => alert(JSON.stringify(data, null, 2))}
    >
      <button type="submit">Submit</button>
    </Form>
  );
}

Translating validation messages

validationTranslation maps RHF rule names to translation keys. When a field fails a rule, BlueForm looks up the key and passes it through t along with contextual params — field (the translated label), and rule-specific values like minLength.

This means validation rules stay as plain RHF rules — no translation keys inside rules:

rules: {
  required: true,      // not "validation.required"
  minLength: 3,        // not a message string
}

Preview

Code

import { setupForm, defineMapping } from "react-headless-form";
import InputField from "./fields/InputField";

const [Form] = setupForm({
  renderRoot: ({ children, onSubmit }) => (
    <div className="blueform-example">
      <form onSubmit={onSubmit}>{children}</form>
    </div>
  ),
  fieldMapping: defineMapping({ text: InputField }),
  i18nConfig: {
    validationTranslation: {
      required: "validation.required",
      minLength: "validation.minLength",
      pattern: "validation.pattern",
    },
    t: (message, params) => {
      switch (message) {
        case "label.username":
          return "Username";
        case "label.email":
          return "Email";
        case "label.password":
          return "Password";
        case "desc.username":
          return "Your public display name";

        case "validation.required":
          return `${params?.field} is required`;
        case "validation.minLength":
          return `${params?.field} must be at least ${params?.minLength} characters`;
        case "validation.pattern":
          return `${params?.field} format is invalid`;

        default:
          return message;
      }
    },
  },
});

export default function EgI18nValidation() {
  return (
    <Form
      config={{
        username: {
          type: "text",
          label: "label.username",
          description: "desc.username",
          rules: {
            required: true,
            minLength: 3,
          },
        },
        email: {
          type: "text",
          label: "label.email",
          props: { type: "email" },
          rules: {
            required: true,
            pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
          },
        },
        password: {
          type: "text",
          label: "label.password",
          props: { type: "password" },
          rules: {
            required: true,
            minLength: 6,
          },
        },
      }}
      onSubmit={(data) => alert(JSON.stringify(data, null, 2))}
    >
      <button type="submit">Submit</button>
    </Form>
  );
}

With i18next

Wire i18next.t directly into i18nConfig.t. The example below includes a language toggle to demonstrate that the form re-renders correctly when the locale changes.

Preview

Code

import { setupForm, defineMapping } from "react-headless-form";
import i18next from "i18next";
import { initReactI18next, useTranslation } from "react-i18next";
import InputField from "./fields/InputField";

// Initialize i18next with inline translations for demo purposes.
// In a real app this would live in your i18n bootstrap file.
i18next.use(initReactI18next).init({
  lng: "en",
  resources: {
    en: {
      translation: {
        "form.username.label": "Username",
        "form.username.description": "Your public display name",
        "form.email.label": "Email",
        "form.password.label": "Password",
        "validation.required": "{{field}} is required",
        "validation.minLength":
          "{{field}} must be at least {{minLength}} characters",
        "validation.pattern": "{{field}} format is invalid",
        "switch.language": "Switch to Vietnamese",
      },
    },
    vi: {
      translation: {
        "form.username.label": "Tên người dùng",
        "form.username.description": "Tên hiển thị công khai của bạn",
        "form.email.label": "Email",
        "form.password.label": "Mật khẩu",
        "validation.required": "{{field}} là bắt buộc",
        "validation.minLength": "{{field}} phải có ít nhất {{minLength}} ký tự",
        "validation.pattern": "{{field}} không đúng định dạng",
        "switch.language": "Chuyển sang tiếng Anh",
      },
    },
  },
  interpolation: { escapeValue: false },
});

const [Form] = setupForm({
  renderRoot: ({ children, onSubmit }) => (
    <div className="blueform-example">
      <form onSubmit={onSubmit}>{children}</form>
    </div>
  ),
  fieldMapping: defineMapping({ text: InputField }),
  i18nConfig: {
    // @ts-ignore
    t: (key, params) => i18next.t(key, params as object),
    validationTranslation: {
      required: "validation.required",
      minLength: "validation.minLength",
      pattern: "validation.pattern",
    },
  },
});

export default function EgI18nI18next() {
  const { i18n, t } = useTranslation();

  const toggleLang = () =>
    i18n.changeLanguage(i18n.language === "en" ? "vi" : "en");

  return (
    <div>
      <div style={{ textAlign: "right", marginBottom: "0.5rem" }}>
        <button type="button" onClick={toggleLang}>
          {t("switch.language")}
        </button>
      </div>

      <Form
        key={i18n.language}
        config={{
          username: {
            type: "text",
            label: "form.username.label",
            description: "form.username.description",
            rules: { required: true, minLength: 3 },
          },
          email: {
            type: "text",
            label: "form.email.label",
            props: { type: "email" },
            rules: {
              required: true,
              pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
            },
          },
          password: {
            type: "text",
            label: "form.password.label",
            props: { type: "password" },
            rules: { required: true, minLength: 6 },
          },
        }}
        onSubmit={(data) => alert(JSON.stringify(data, null, 2))}
      >
        <button type="submit">Submit</button>
      </Form>
    </div>
  );
}

Tip

The key={i18n.language} on Form forces a remount when the language changes, ensuring labels and error messages re-resolve through the updated t function. Without it, already-rendered fields would keep their previous translated strings until they re-validate.

Internationalization (i18n)#

#Translating labels and descriptions

#Translating validation messages

#With i18next

Internationalization (i18n)

Translating labels and descriptions

Translating validation messages

With i18next