检查消息调用的类型

生成并引入声明,在编辑时检查源字符串、上下文和消息值。

消息调用即使通过了 TypeScript 类型检查,也可能请求错误的消息目录条目。上下文变更或占位符拼写错误,都可能让屏幕上仍然显示源文本或 {name}。提取时生成的声明会将已知的源消息纳入应用的类型系统。

生成并引入声明 #

在安装 CLI 后,运行:

sh
npx lingo extract --src src --source-locale en

默认输出为 locales/en.jsonc 和 lingo.d.ts。如果现有的匹配模式都未包含 lingo.d.ts,请将其添加到应用现有的 tsconfig 包含列表中,并保留其他条目:

json
{
  "include": ["src", "lingo.d.ts"]
}

按应用的常规方式运行类型检查。声明若不在编译器的项目范围内,就无法约束任何调用。如果提取时使用了 --types 或 i18n.typesPath,请改为引入对应的实际输出路径。

理解生成的接口 #

该文件为 LingoMessages 扩展了源字符串及其选项。以下示例展示了生成的结构:

ts
export {};

declare module "@lingo.dev/react" {
  interface LingoMessages {
    "Hello, {name}.": {
      values: { name: string | number };
      context: "Greeting on the account dashboard";
    };
    "Save": {
      context: "Submit settings" | "Bookmark an article";
    };
  }
}

请重新生成此文件,而不是手动维护示例中的内容。问候消息现在必须提供 values.name 及其提取出的上下文。Save 接受已记录的两个上下文中的任意一个。未列出的源字符串无法满足 MessageKey 约束。

没有生成条目时,LingoMessages 为空,MessageKey 允许使用任意字符串。填充条目后,MessageKey 会成为其所有字符串键的联合类型。运行时行为保持不变:这些约束仅在编辑时作用于 l.text 和 l.rich。

让类型与源文本保持同步 #

修改文本、上下文或占位符后,请重新提取。已移除的消息会成为孤立条目,不再参与生成。没有上下文的条目不会生成签名,除非同一源字符串的另一个有效条目提供了上下文。同一源字符串的多个上下文会组成联合类型。

如需检查文件是否与当前源内容一致,但不写入文件,请运行:

sh
npx lingo extract --src src --source-locale en --check

此操作会将 JSONC 和声明分别与当前提取结果进行比较。这是本地检查,不会发起翻译请求。请将其与类型检查一起运行,避免旧声明在不知不觉中仍以过时的消息清单为准。

值类型与覆盖范围 #

生成器可识别顶层 ICU 参数。复数、序数和数字参数使用 number;选择参数使用 string;日期和时间参数使用 Date | number;简单占位符使用 string | number。它无法识别嵌套在复数分支中的所有占位符,因此请单独测试这些分支中的值。

生成的源字符串约束适用于 text 和 rich。plural 和 select 辅助函数保留各自的形式和选项签名。富文本调用会增加一个可选的标签映射,但声明不会验证目标文本中的标签位置。

类型检查可以判断调用是否符合提取出的源消息约定。渲染测试则可以判断已加载的译文能否使用这些值。两者都应保留:即使调用有效,仍可能遇到消息目录条目缺失或目标文本 ICU 格式错误的情况。