提取并加载消息目录
提取源消息,获取翻译后的 JSONC 文件,再结合对应的源元数据构建运行时映射。
组件包含源消息及其上下文。提取操作会将这些调用汇集到一个可供翻译的文件中,加载操作则将翻译后的值重新关联到组件的键。本指南将带你完成第一条问候语的文件处理流程,生成提供器所需的 Messages 映射。
提取源文件 #
在应用中安装 CLI 和加载器所需的依赖:
npm install --save-dev @lingo.dev/cli@latest
npm install @lingo.dev/spec@1.17.1 jsonc-parser
npx lingo extract --src src --source-locale en提取操作在本地运行,无需 API 密钥。默认会写入 locales/en.jsonc 和 lingo.d.ts。显式指定的 --out 和 --types 标志优先于配置中的 i18n.messagesPath 和 i18n.typesPath,而配置值又优先于默认值。如果 Pages 应用中的调用位于 src 之外,请使用调用所在的实际目录,例如 --src pages。
检查问候语对应的条目。条目的值是完整的英文模板,键则由源消息和上下文生成。条目前的注释用 @context 记录含义,用 @src 记录源位置,并用 @orphan 标记此前已提取、如今不再有效的条目。请求翻译前,请先审核这些更改。
翻译选定的目录 #
如果应用尚未配置 Lingo.dev,请初始化这一指定文件,并将西班牙语设为目标语言,然后完成身份验证并关联本地化引擎:
npx lingo init --source en --targets es --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link你需要具备已启用的本地化引擎的访问权限,且账户须有足够的用量额度。CLI 身份验证介绍了无人值守运行所需的凭据。
如果 .lingo/config.json 已存在,请保留其绑定关系和其他文件条目。添加或更新选择 locales/en.jsonc 的条目,并确认项目的源语言区域为 en。如果已有基线,请先使用 npx lingo push --wait 完成现有目标语言区域的常规更新,处理所有待审核或失败状态,并检查获取到的更改,再将 es 添加到 targetLocales。在后续补填过程中,保持源版本不变。添加语言介绍了这一操作顺序。不要使用 init --force 修改配置,因为它会重建文件条目,并可能丢弃高级选项。完整的配置结构请参阅配置。
对于新项目,或已完成上述准备工作的现有项目,请请求缺失的目标文件并等待获取完成。命令等待期间,请勿修改目标文件,因为下载过程可能覆盖本地编辑:
npx lingo push --backfill-missing --wait运行结束后,请检查 locales/es.jsonc。先处理所有报告的待审核或失败状态,再将输出视为完整结果。后续源内容发生更改时,请重新提取并使用 npx lingo push --wait;补填仅用于补齐缺失文件,不用于现有目标文件的常规更新。
保留与目标版本对应的源元数据 #
通用 JSONC 翻译流程会在目标文件中保留源文件的 @orphan 标记,但会移除其 @context 和 @src 注释。仅凭目标文件,加载器无法判断消息属于哪个页面。
请保留与目标文件对应同一版本的提取源文件。从源文件中选出有效条目,再将这些条目的键与目标文件中的翻译值关联。这样既能排除已移除的消息,也能保留按源路由筛选的能力。目标文件中缺失的键不予补入,以便运行时回退到源内容。
解析原始目录 #
创建 src/catalog.ts,并使用以下由应用自行维护的加载器:
import { parse, type ParseError } from "jsonc-parser";
import { getActiveEntries, readLocaleFile, type LocaleEntry } from "@lingo.dev/spec";
import type { Messages } from "@lingo.dev/react";
function readStringCatalog(raw: string) {
const errors: ParseError[] = [];
const value: unknown = parse(raw, errors, { allowTrailingComma: true });
if (
errors.length > 0 ||
value === null ||
typeof value !== "object" ||
Array.isArray(value) ||
Object.values(value).some((entry) => typeof entry !== "string")
) {
throw new Error("Expected a flat JSONC object with string values");
}
return readLocaleFile(raw);
}
export function loadMatchedMessages(
sourceJsonc: string,
targetJsonc: string,
include: (entry: LocaleEntry) => boolean = () => true,
): Messages {
const active = getActiveEntries(readStringCatalog(sourceJsonc).entries);
const target = new Map(readStringCatalog(targetJsonc).entries.map((entry) => [entry.key, entry.value]));
return Object.fromEntries(
active.filter(include).flatMap((entry) => {
const value = target.get(entry.key);
return value === undefined ? [] : [[entry.key, value]];
}),
);
}readLocaleFile 会解析 JSONC 语法和元数据,但不会验证运行时数据结构。尽管声明了条目类型,它仍会接受数组和非字符串值;如果根值为基本类型或 null,则不返回任何条目。上面的第一个函数会在这些值传入渲染器之前拒绝此类结构。两个函数都在本地执行,不进行任何 I/O 操作。
在 Vite 应用中,请在向提供器供应数据的模块内,以原始文本形式加载文件:
import source from "../locales/en.jsonc?raw";
import target from "../locales/es.jsonc?raw";
import { loadMatchedMessages } from "./catalog";
export const spanishMessages = loadMatchedMessages(source, target);这里假定该模块直接位于 src 下,且已引入 Vite 的客户端类型。通过 locale="es" 将 spanishMessages 作为 messages 传入。此时,问候语应使用获取到的西班牙语模板,同时仍将 {name} 替换为 Ana。请检查实际措辞,并测试条目缺失时的表现;加载文件与判断其语言质量是两回事。
仅选择路由所需的源条目 #
可选的 include 判断函数会在关联前对有效的源条目执行。页面加载器可以使用 entry.metadata.src 纳入页面自身的调用和共享组件。请在源文件上进行筛选,因为元数据仍保留在其中。部署时,请一并保留源文件和目标文件,避免路由筛选使用其他版本的键。
Next Pages 指南提供了完整的路由判断函数。TanStack 指南使用此加载器加载请求目录。两者的内置加载器都能筛选带有元数据的文件,但都不会自动将不含注释的目标文件与源元数据关联。
规范辅助工具参考 #
| 导出项 | 行为约定 |
|---|---|
readLocaleFile(content): LocaleFile | 解析 JSONC,支持尾随逗号和条目前的元数据块注释;遇到语法错误时抛出异常。 |
getActiveEntries(entries): LocaleEntry[] | 保留 metadata.orphan 不为真值的条目。 |
LocaleFile | { entries: LocaleEntry[] }。 |
LocaleEntry | { key: string; value: string; metadata: EntryMetadata }。 |
EntryMetadata | 可选的 context、src 和 orphan。 |
computeKey(source, context?) | 共享的规范化源消息/上下文标识,React 也导出此项。 |
buildIcuPlural(forms) | 按规范顺序输出已知的基数类别。 |
buildIcuSelect(forms) | 按排序后的键输出备选项。 |
ICU 构建器接受字符串记录;React 的复数和选择类型则添加了其必需的 other 形式。生成的运行时目录是普通的 Messages 映射,而不是 LocaleFile。
现有的带键资源、文档和静态 TypeScript 语言区域模块使用各自的格式处理器,而不采用本指南中的提取流程。示例项目同时展示了这些布局和 React 应用。