#Translation resources

Add languages with ConfigProvider translations. Use locale to choose the active language and fallback order. Runnable example.

#Start with JSON

Copy the complete English template, keeping its keys. It is the same resource used by the components. Read the installed version from the package:

import enUS from '@ifhover/leaf-ui/locales/en-US.json';

Built-in zh-CN.json, zh-TW.json, ja-JP.json and ko-KR.json use the same path. Set locale to use a built-in language without importing these files. Resources contain text grouped by component, with shared actions in common. No registration or helper function is required.

This example uses playful “Martian” text with the private-use tag zh-CN-x-mars. Dates and numbers retain Simplified Chinese regional formatting:

import { ConfigProvider } from '@ifhover/leaf-ui';
import mars from './locales/zh-CN-x-mars.json';

const translations = { 'zh-CN-x-mars': mars };

<ConfigProvider locale={['zh-CN-x-mars', 'en-US']} translations={translations}>
  <App />
</ConfigProvider>;

#Fallback and inheritance

Use valid BCP 47 tags. Empty chains and invalid tags throw an error. Specify fr-CA → fr explicitly when desired. The final fallback always uses built-in English. Include en-US in the chain if your English overrides should participate.

Component props and components text take precedence. Translate application content separately. Resources do not change direction or weekStartsOn; configure those independently.

#Variable sentences

Sentences use ICU MessageFormat so translators can control word order and plurals:

{
  "pagination": {
    "total": "{total, plural, one {# item} other {# items}}"
  }
}

Keep the variable names from the English template, such as {total} and {label}. Plurals use the language supplying the entry. Malformed templates fall back to built-in English and log the entry in development. Output is rendered as plain text.

#Validate translations

The package provides a JSON Schema for editor validation. You may add $schema at the resource root pointing to the installed dist/locales/schema.json; runtime translation ignores it.

Check unknown keys, missing entries and ICU arguments:

pnpm exec leaf-ui-check-translations ./locales/zh-CN-x-mars.json --allow-partial

Use --allow-partial for intentionally incomplete resources. Structure, spelling and variables are still checked; missing entries are listed without failing. Run the check again after upgrading to find new entries.

#Types

import type { LeafTranslation, LeafTranslations } from '@ifhover/leaf-ui';

const mars = {
  select: { placeholder: '挑①個唄' },
} satisfies LeafTranslation;

const translations = { 'zh-CN-x-mars': mars } satisfies LeafTranslations;

#LeafTranslations

#LeafTranslation

Treat resources as immutable and pass a new object when updating them. Resources stay within the Provider rather than a global registry. For SSR, use the same chain, JSON and initial values on server and client. See SSR.