lingo extract
从显式翻译调用中生成源 JSONC 文件和 TypeScript 声明。
lingo extract 为显式定义的 React 消息赋予消息目录中的标识。它会扫描 TypeScript/TSX 调用,在本地写入源 JSONC 文件和声明,并保留将各条目关联到源代码的元数据。它不会重写任意 JSX,也不会请求翻译。
在已配置的 React 组件中,受支持的调用形式如下:
const l = useLingo();
const label = l.text("Place order", { context: "Checkout submit button" });在项目根目录运行提取:
lingo extract --src src --source-locale en使用默认路径时,请查看 locales/en.jsonc 和 lingo.d.ts。源消息目录会记录消息值、上下文和源代码位置。React 快速入门提供了该组件所需的导入和提供程序配置。
选项 #
| 选项 | 默认值或作用 |
|---|---|
--src <path> | 扫描目录,默认为 src。 |
--source-locale <locale> | 输出的源语言区域,默认为 en。 |
--out <path> | 覆盖已配置的 i18n.messagesPath;未配置时使用默认值 locales。 |
--types <path> | 覆盖已配置的 i18n.typesPath;未配置时使用默认值 lingo.d.ts。 |
--check | 比较生成内容与磁盘内容的字节,不写入文件。 |
路径以最近的项目根目录为基准解析。源语言区域不会继承本地化配置中的 sourceLocale;如需使用其他语言,请显式指定。正常写入时会创建声明文件目录。
扫描器可识别的内容 #
扫描器可识别由 useLingo 或 createLingo 赋值的变量上的 text、rich、plural 和 select,也可识别常规的 l 和 .l 接收对象。它支持字符串字面量、不含表达式的模板和静态形式的对象。
动态消息没有可稳定提取的源内容。对工厂函数的返回结果进行解构会丢失所跟踪的接收对象结构,并触发警告。声明文件、以点开头的文件和目录,以及 node_modules 均不参与扫描。如果没有 TS/TSX 文件,提取过程会报告这一情况并直接返回,不产生结果;进程成功退出并不代表找到了消息。
审核标识与合并行为 #
键由源内容和上下文生成。措辞或上下文发生变化时,可能产生新的标识;运行时替换的值则不会。键冲突会导致提取失败,需要通过上下文加以区分。
提取结果会与现有源消息目录合并:保留当前值,更新上下文和源代码元数据,添加新条目,并将不再出现的消息标记为孤立条目。排序后的输出具有确定性。在认定某个孤立条目对应的消息已被有意从应用中移除之前,请先检查警告。
检查或翻译消息目录 #
lingo extract --check 会比较消息目录和声明文件的字节内容,不写入文件。lingo check 还会检查上下文、孤立条目和发现的目标。
要进行翻译,请将实际的 .jsonc 路径添加到 files[],完成身份验证和关联,并在首次推送时使用 lingo push --backfill-missing --wait。后续更改使用普通推送即可。更改提取路径不会自动更新文件配置。
请使用兼容 JSONC 的加载器,并遵循消息目录元数据策略加载结果。提供程序需要字符串映射;仅提供原始文件路径或使用普通 JSON 导入,都无法完成这一转换。