概述

gt-i18n 现在支持通过 getTranslations() 实现基于词典的翻译。这使 gt-i18n 与 gt-next、gt-react 以及其他以词典为主要翻译方式的 i18n 库保持一致。

设置

在项目根目录创建一个 dictionary.json 文件，并填入源字符串 (英文) ：

{
  "greeting": {
    "hello": "Hello!"
  },
  "user": {
    "welcome": "Welcome, {name}!"
  },
  "errors": {
    "notFound": "Page not found",
    "unauthorized": "Access denied"
  }
}

当你运行 GT CLI (npx gtx translate) 时，它会自动检测项目根目录中的 dictionary.json，并为你配置的各个区域设置生成翻译。

用法

基于上述源词典，调用 getTranslations() 获取一个 t 函数，用于从你的词典中查找对应条目：

import { getTranslations } from 'gt-i18n';

const t = await getTranslations();

t('greeting.hello'); // "你好！"
t('user.welcome', { name: 'Alice' }); // "欢迎，Alice！"

使用 t.obj() 获取子词典

t() 返回单个字符串。t.obj() 则会以对象形式返回词典中的整个子树：

const t = await getTranslations();

t('errors.notFound'); // "页面未找到"

const errors = t.obj('errors');
// { notFound: "页面未找到", unauthorized: "访问被拒绝" }

当翻译后的词典缺少某些键时，系统会从源词典中补上缺失的条目。这意味着部分翻译不会导致运行时错误——未翻译的键会回退到源文本。

查找行为

查找的解析由两条规则决定：

1. 缺少翻译 → 回退到默认区域设置。 如果某个键存在于源词典中，但当前区域设置没有对应翻译，t() 会返回源文本。
2. 缺少源条目 → 报错。 如果某个键根本不存在于源词典中，t() 就会抛出错误。这是有意为之——如果某个键没有在源词典中定义，那就是一个 bug，而不是缺少翻译。此行为将在即将进行的重构中应用到所有 GT 库。

第二条规则的前提是，翻译后的词典与源词典的结构保持一致，而这正是 GT 自动生成翻译的方式。

链接

• PR #1359
• getTranslations API 参考文档
• 词典指南