类型生成与检查

从基准语言 JSON 通过 Templater 编译元数据生成翻译键和参数契约。

定义基准资源

类型生成器读取 JSON，不执行应用代码。例如 locales/en.json：

json

{
  "welcome": "Welcome",
  "cart": {
    "items": "{{#plural count}}{{:one}}{{#}} item{{:other}}{{#}} items{{/plural}}"
  },
  "updated": "Updated {{at | date:short}}"
}

locales/zh-CN.json 可以包含部分翻译：

json

{
  "cart": { "items": "{{#plural count}}{{:other}}{{#}} 件商品{{/plural}}" }
}

生成声明

直接安装独立包 @shareyou/i18n 后运行：

pnpm exec shareyou-i18n generate --source locales/en.json --locale zh-CN=locales/zh-CN.json --out i18n.generated.d.ts

参数	说明
`--source <file>`	基准语言 JSON，定义键名和参数契约
`--out <file>`	输出声明文件路径
`--locale <tag=file>`	额外校验一种翻译，可重复传入
`--check`	只校验声明，不写入文件
`--help`, `-h`	显示用法

CLI 会拒绝未知参数、重复的单值选项、重复语言标签，以及输出路径覆盖输入文件。输出固定使用双引号、按键名排序、以分号结尾：

// Generated by shareyou-i18n. Do not edit.
export interface MessageArguments {
  readonly "cart.items": { readonly "count": number; };
  readonly "updated": { readonly "at": number | Date; };
  readonly "welcome": Readonly<Record<string, never>>;
}

接入应用

import { createI18n } from '@shareyou/i18n';
import type { MessageArguments } from './i18n.generated.js';
import en from './locales/en.json' with { type: 'json' };
import zhCN from './locales/zh-CN.json' with { type: 'json' };

const i18n = createI18n<MessageArguments>({
  locale: 'zh-CN', fallbackLocale: 'en', messages: { en, 'zh-CN': zhCN },
});

i18n.t('cart.items', { count: 3 });
i18n.t('welcome');
i18n.t('updated', { at: new Date() });

// @ts-expect-error 必须提供 count。
i18n.t('cart.items');
// @ts-expect-error count 必须为数字。
i18n.t('cart.items', { count: '3' });
// @ts-expect-error 没有这个翻译键。
i18n.t('cart.missing');

JSON 导入需配置 TypeScript 的 resolveJsonModule 或使用相应打包器。 NodeNext 项目使用 .js 导入路径，TypeScript 会将类型导入解析到生成的 .d.ts。

Templater 参数用法	生成类型
未声明类型的普通占位符	`unknown`
`:type` 约束	原有 `typeof` 类型映射
`number` 格式化、`plural`、`ordinal` 控制参数	`number`
`date`、`time` 格式化	`Date \| number`
`select` 控制参数	`string`

生成器直接复用 Templater 编译产物的参数元数据，不自行维护解析器或类型映射。所有分支都参与契约，同名参数约束取交集。无法同时满足的约束会报告消息键和错误原因。无参数消息可以不传第二个参数，或传空对象；带参数消息必须传入完整参数。

其他语言与 CI

--locale 可以重复传入。翻译文件允许缺少键，由运行时回退；已有键必须与基准语言保持相同的参数名称和类型。复数类别允许随语言改变。额外键、语法错误或参数契约不一致会以非零状态退出，诊断包括文件和消息键。

CLI 不需要执行模板，也不检查应用配置中的命名格式是否存在。语言、时区和命名格式由 i18n 在渲染时传入 Templater。

提交生成声明，并在 CI 运行同一条命令加上 --check：

pnpm exec shareyou-i18n generate --source locales/en.json --locale zh-CN=locales/zh-CN.json --out i18n.generated.d.ts --check

--check 不写入文件。声明缺失或过期时退出状态为 1；正常生成的输出顺序固定，不包含时间戳。校验失败不覆盖已有声明，成功生成时使用临时文件原子替换。每次修改基准资源或翻译后都应重新生成或检查。

没有生成类型时，createI18n 仍会从资源推导键名，参数使用通用字典并在运行时检查。生成的声明是静态契约，不会自动追踪运行时替换的文件；因此需要把生成检查加入项目构建或 CI。