#翻译资源

通过 ConfigProvider 的 translations 补充语言，locale 决定当前语言与回退顺序。查看可运行示例。

#从 JSON 开始

复制完整英文模板，按原有键翻译内容。模板与组件实际使用的资源一致，也可从安装的包中读取：

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

内置的 zh-CN.json、zh-TW.json、ja-JP.json、ko-KR.json 使用同一路径。使用内置语言只需设置 locale，无需导入这些文件。JSON 只保存文本；对象按组件分组，通用动作在 common 中。不需要注册或调用辅助函数。

以下用火星文演示自定义资源，zh-CN-x-mars 是私用语言标记，日期和数字按简体中文格式显示：

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>;

#回退与继承

语言代码使用有效的 BCP 47 标签；空数组或无效标签会抛出错误。需要 fr-CA → fr 时显式写出这两项。最终英文兜底始终使用库内置资源，若需自定义英文也参与查找，请把 en-US 放进链中。

组件实例参数与 components 提供的文字优先于翻译资源。业务内容由应用翻译。翻译不会自动改变 direction 或 weekStartsOn，需要时单独设置。

#动态文本

句子使用 ICU MessageFormat 占位符，译者可以调整完整语序，也可以定义复数：

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

保留英文模板中的变量名，例如 {total}、{label}。复数规则使用实际提供该词条的语言。模板无效时该句回退内置英文，开发环境会输出对应词条的警告；内容作为普通文本渲染。

#检查翻译

安装包提供 JSON Schema，编辑器可将它关联到翻译文件。也可在 JSON 顶层添加 $schema 指向本地安装包的 dist/locales/schema.json，运行时会忽略此字段。

检查未知键、遗漏和 ICU 变量：

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

有意只翻译部分词条时使用 --allow-partial。此时仍检查结构、拼写和变量，缺失项只输出清单。组件升级后重新检查，可找到需要补充的词条。

#类型

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

翻译资源是只读配置；更新时传入新对象。资源保留在当前 Provider 内，不写入全局注册表。SSR 时服务端与客户端传入相同的语言链、JSON 和初始值，详见 服务端渲染。