参考 / SDK
机器翻译页面
配置与术语表
加载并校验 verbatra 配置、编辑术语表的 SDK 入口函数,以及检测目录是否为项目的入口函数。
加载配置
loadConfig
查找、加载并校验项目配置,返回 VerbatraConfig。优先级为:configOverride(校验内存中的对象)高于 configPath(加载一个明确指定的文件),后者高于按查找顺序从 cwd 开始的查找。以文件路径给出的 glossary 会在这里读取并校验,因此下游代码拿到的始终是内存中的术语表:版本 1 的“源术语到译文”映射,或版本 2 的定义。
function loadConfig(
options?: LoadConfigOptions,
): Promise<VerbatraConfig>;属性
类型
返回:VerbatraConfig
抛出:CONFIG_、CONFIG_
示例:不用文件的配置
配置的 schema 见配置文件。fs 是读取术语表文件所用的文件系统端口,详见依赖接缝。
loadConfigWithMeta
同样的加载,外加来源信息:返回 { config, source, glossary }。source 说明配置来自查找命中、明确指定的路径还是内存中的覆盖(有绝对路径 filepath 时一并给出),glossary 记录术语表是缺失、内联,还是从文件解析而来。需要显示配置来源时使用它。
function loadConfigWithMeta(
options?: LoadConfigOptions,
): Promise<LoadedConfig>;属性
类型
返回:LoadedConfig
抛出:CONFIG_、CONFIG_
两者都接受 fresh: true,让 JavaScript 或 TypeScript 配置文件重新求值,而不是复用同一进程中更早一次加载的求值结果;长时间运行的进程若会在编辑后重新加载配置,应设置它。JSON、YAML 和 package.json 配置总是重新读取。
configCandidatePaths
列出 loadConfigWithMeta 在相同的 { cwd?, configPath? } 下可能读取配置的每个文件:设置了 configPath 时只有该文件,否则是查找链中每个目录里的每个查找位置,由近到远,无论文件是否存在。监视这些文件(例如按修改时间),就能在不必对每个请求都加载配置的情况下,发现配置被创建、编辑或删除。术语表文件不包括在内;loadConfigWithMeta 在 glossary 中给出它的名称。
function configCandidatePaths(
options?: ConfigCandidateOptions,
): readonly string[];属性
类型
返回:readonly string[]
resolveProjectRoot
返回各流程解析相对路径所依据的项目根目录:找到的配置文件所在的目录,这样在子目录中启动的进程,也会处理项目自己的语言文件、锁文件和 .verbatra-local/;对来自 configPath 的配置,则返回 cwd。流程拿到的若是 loadConfig 或 loadConfigWithMeta 返回的配置,其 cwd 已默认为该根目录。复制或重建配置时,以及对不接受配置的 loadLockFile、loadProvenance 和 runStatus,把 resolveProjectRoot(loaded.source, cwd) 作为 cwd 传入。
function resolveProjectRoot(
source: ConfigSource,
cwd: string,
): string;返回:string
术语表
readGlossaryFile
从磁盘重新读取文件形式的术语表,返回规范化的 Glossary:{ version, terms, doNotTranslate }。version 对扁平术语映射为 1,对按语言环境区分的术语表为 2;每个术语带有 source、可选的 target、targets、forbidden、caseSensitive,以及可选的 note 和 partOfSpeech。它的 glossary 输入是 loadConfigWithMeta 给出的 GlossaryProvenance,因此读取的始终是配置所指定的那个文件。在长时间运行、需要显示术语表当前状态而不是加载时状态的工具中使用它。
function readGlossaryFile(
input: GlossaryFileInput,
deps?: GlossaryFileDeps,
): Promise<Glossary>;属性
类型
返回:Glossary
抛出:GLOSSARY_、CONFIG_
术语表是内联的或不存在时,抛出 GLOSSARY_;文件违反术语表文件规则或声明了其他版本时,抛出 CONFIG_。
直到 0.11,它返回的是扁平术语映射本身。
updateGlossaryTerm
在文件形式的术语表中添加、更改或删除恰好一个术语,并返回此刻规范化后的术语表。translation 是新文本,或用 null 删除该术语。文件其余部分保持键的顺序和缩进,写入是原子的,整个读取、修改、写入的过程都持有项目范围的术语表锁,因此两个并发的编辑会被串行化,而不是交错进行。
function updateGlossaryTerm(
input: UpdateGlossaryTermInput,
deps?: GlossaryFileDeps,
): Promise<Glossary>;属性
类型
返回:Glossary
抛出:GLOSSARY_、CONFIG_、LOCK_、LOCK_、RUN_、GLOSSARY_
它还接受 locale(此时 translation 是该语言环境自己的译文,null 只删除它)、forbidden(locale 绝不能使用的译法;null 或 [] 表示删除)、note、partOfSpeech(各自用 null 删除)、caseSensitive 和 doNotTranslate(true 把该术语加入保持不翻译的术语,false 将其移除;不能与术语字段组合使用)。只要编辑只是为所有语言环境设置或删除译文,版本 1 的文件就保持版本 1;任何其他编辑都会把它重写为版本 2,每个已有术语的译文保留为 target。不带 locale 的 translation: null 只删除共享译文;术语本身在不再有译文和禁用译法时才被删除,对版本 1 的术语来说这是立即发生的。
给出 sourceLocale 时,仅大小写与已存术语不同的术语(两者都不是 caseSensitive)会更新该术语,并保留其已存的拼写;不给出时,只有完全匹配才会更新。 内联的术语表会以 GLOSSARY_ 拒绝,而不是被转换。缺少 term、字段为空白、编辑没有设置任何字段或把 doNotTranslate 与术语字段混用、没有语言环境却给出禁用译法、语言环境无效、编辑会让术语表无效,以及编辑结果会超过 1 MiB 的术语表上限,都以 CONFIG_ 拒绝;写入失败(包括术语表写锁)则是 GLOSSARY_,文件系统错误作为它的 cause。编辑后术语表与原来相同的,则成功且不写入任何内容。
它还接受 lockAcquireTimeoutMs,用来限定等待术语表锁的时间,超时后调用以 LOCK_ 失败(默认 10 分钟);无效的上限会在读取任何内容之前以 LOCK_ 失败。
glossaryForLocale
解析术语表中适用于某个目标语言环境的部分:glossaryForLocale(config.glossary, "de") 返回 { terms, doNotTranslate },每个术语带有该语言环境的 target(先取它自己的条目,再取其基础语言的,最后取共享的)、它的 forbidden 译法、caseSensitive,以及 note 和 partOfSpeech;术语表中没有任何内容适用于该处时返回 undefined。这正是翻译请求发往该语言环境时所携带的 TranslateRequest.glossary,也是该语言环境的审校检查和缓存指纹所看到的内容。
function glossaryForLocale(
glossary: GlossaryInput | Glossary | undefined,
locale: string,
): LocaleGlossary | undefined;返回:LocaleGlossary | undefined
glossaryHits
glossaryHits({ glossary, locale, sourceLocale, source }) 返回适用于某个目标语言环境中一段源文本的术语表条目,形式为 { terms, doNotTranslate },与 glossaryForLocale 返回的结构相同:每个其源术语作为完整术语出现在 source 中的术语,连同该语言环境须遵守的译文和禁用译法,以及每个出现在其中、须保持不翻译的术语。术语是否区分大小写,按它自己声明的为准;忽略大小写时,按 sourceLocale 的规则折叠大小写。它使用的匹配规则与翻译运行在标记遗漏的术语表术语时相同,并且不读取任何内容。
function glossaryHits(
input: GlossaryHitsInput,
): LocaleGlossary;属性
类型
返回:LocaleGlossary
glossaryDraftCheck
glossaryDraftCheck({ glossary, locale, sourceLocale, source, draft }) 在你写入之前,对照 glossaryHits 在源文本中找到的术语表条目,检查一份译文草稿。每个术语都带回 targetUsed(草稿是否包含所要求的译文;对只禁用某些译法的术语则不出现)和 forbiddenUsed(草稿使用了、而源中没有的禁用译法),每个须保持不翻译的术语带回 kept。翻译运行用这些规则标记 GLOSSARY_ 和 GLOSSARY_。它不读取任何内容。
function glossaryDraftCheck(
input: GlossaryDraftCheckInput,
): GlossaryDraftCheck;属性
类型
返回:GlossaryDraftCheck
normalizeGlossary
把任一形式的术语表(版本 1 的扁平映射或版本 2 的定义)转换为 readGlossaryFile 返回的规范化 Glossary,并填充所有默认值。用它可以把内联术语表与文件形式的术语表以同样的方式显示。它不会再次校验;loadConfig 已经校验过。
function normalizeGlossary(
glossary: GlossaryInput | Glossary,
): Glossary;返回:Glossary
sharedGlossaryTranslations
把规范化的 Glossary 投影为一个扁平映射:把每个带共享 target 的术语映射到该译文,顺序与术语表一致。各语言环境自己的译文、禁用译法和不翻译术语都会省略,因此只在使用方只能显示扁平术语映射的场合使用它。名为 _ 的术语仍是自有键。
function sharedGlossaryTranslations(
glossary: Glossary,
): Readonly<Record<string, string>>;属性
类型
返回:Readonly<Record<string, string>>
redactGlossary
让规范化 Glossary 中的每个源术语、译文、禁用译法、备注、词性和不翻译术语都经过 redact,并返回 { glossary, redactedTerms }。redactedTerms 列出每个有值被替换的术语,被脱敏的源术语本身记为 [REDACTED],因此这份列表绝不会再次暴露密钥。MCP 服务器和 Studio 在术语表离开进程之前使用它。
function redactGlossary(glossary: Glossary): RedactedGlossary;属性
类型
返回:RedactedGlossary
readCurrentGlossary
读取已加载配置所指定的术语表的当前状态:readCurrentGlossary({ loaded }),其中 loaded 是 loadConfigWithMeta 的返回值。文件形式的术语表从磁盘重新读取,内联的取自配置,无论哪种,结果都是规范化的 Glossary;配置没有声明术语表时返回 undefined。要查看某个目标语言环境须遵守什么,把结果传给 glossaryForLocale。
function readCurrentGlossary(
input: ReadCurrentGlossaryInput,
deps?: GlossaryFileDeps,
): Promise<Glossary | undefined>;属性
类型
返回:Glossary | undefined
editConfiguredGlossaryTerm
面向持有已加载配置的工具的 updateGlossaryTerm:用 loaded 代替 glossary,编辑字段相同,把值为 undefined 的字段视为未提供,并先对照已配置的目标语言环境检查 locale,不在其中时以 UNKNOWN_ 失败,且不写入任何内容。MCP 服务器和 Studio 通过它写入术语表。
function editConfiguredGlossaryTerm(
input: EditConfiguredGlossaryTermInput,
deps?: GlossaryFileDeps,
): Promise<Glossary>;属性
类型
返回:Glossary
抛出:UNKNOWN_、GLOSSARY_、CONFIG_、LOCK_、LOCK_、RUN_、GLOSSARY_
长度限制
setKeyLengthLimit
在 verbatra.limits.json 中设置、更改或删除某个键的长度限制。这个文件已提交,与锁文件放在一起,保存配置的 maxLength 未涵盖的限制。该键必须存在于源中;为配置的 maxLength 已设置的键设限制会被拒绝;null 删除文件中的条目,已离开源的键或由配置设置的键的条目也可以删除。读取、修改、写入在项目范围的限制锁下运行,文件以原子方式替换,因此来自一个或多个进程的并发调用都不会丢失更新。没有任何更改的调用不写入任何内容,无法作为限制文件读取的文件绝不会被覆盖。
function setKeyLengthLimit(
input: SetKeyLengthLimitInput,
deps?: SetKeyLengthLimitDeps,
): Promise<SetKeyLengthLimitResult>;属性
类型
返回:SetKeyLengthLimitResult
抛出:LENGTH_、LOCK_、UNKNOWN_、LOCALE_、LOCALE_、SOURCE_、SOURCE_、UNKNOWN_、LOCK_、RUN_、LIMITS_、LIMITS_
编写、检测与纯人工模式
defineConfig
为带类型的 verbatra.config.ts 提供的恒等辅助函数:原样返回它的参数,用于类型推断和编辑器自动补全,包括所选提供商已知的模型 ID(仅用于编写阶段;运行时任何非空字符串都能通过)。除 opencode、openai-compatible、libretranslate 和 none 外,每个提供商还有一个接受 AuthoringConfigFor<"<id>"> 的重载,例如 AuthoringConfigFor<"anthropic">,它把 provider 块收窄到该提供商的选项;这四个提供商使用下面的 AuthoringConfig 兜底重载。
function defineConfig(config: AuthoringConfigFor<"anthropic">): VerbatraConfigInput;
function defineConfig(config: AuthoringConfigFor<"openai">): VerbatraConfigInput;
function defineConfig(config: AuthoringConfigFor<"gemini">): VerbatraConfigInput;
function defineConfig(config: AuthoringConfigFor<"deepl">): VerbatraConfigInput;
function defineConfig(config: AuthoringConfigFor<"google-translate">): VerbatraConfigInput;
function defineConfig(config: AuthoringConfig): VerbatraConfigInput;返回:VerbatraConfigInput
示例:添加源文件和配置
verbatraConfigSchema
loadConfig 用来校验的 zod schema,导出后,你自己的工具就能以 SDK 相同的方式校验配置对象。未知的顶层键会被拒绝,因此密钥不会藏在配置里,$schema 除外:它是可选的字符串,运行时忽略,让 JSON 或 YAML 配置可以把编辑器指向该包的 @verbatra/sdk/config-schema.json。
const verbatraConfigSchema: z.ZodObject<{ ... }, z.core.$strict>;它的 rates 块是 RateCard,即把估算(见运行前估算费用)换算成金额的价目表:
属性
类型
scaffoldingMetadata
CLI 的 init 命令据以生成提示的只读元数据:providerEnv(提供商 id 到读取其密钥的环境变量)、scaffoldModels(init 为每个 LLM 提供商写入配置的默认模型)、providerTokenLimitKeys(每个 LLM 提供商用来设置输出 token 上限的选项键)和 supportedFormats(格式 id 的封闭集合)。从 providerTokenLimitKeys 读取 token 上限的键,不要假定某一个,因为各提供商的键不同(提供商);DeepL 和 Google Cloud Translation 没有对应条目,因为它们不设 token 上限。ScaffoldableProviderId 类型是 Exclude<ProviderId, "openai-compatible" | "libretranslate" | "none">:只需要 id 就够的每个提供商。openai-compatible 和 libretranslate 各自需要只有你能提供的 baseUrl,且没有必需的环境变量;none 则完全不调用提供商。
const scaffoldingMetadata: {
readonly providerEnv: { ... };
readonly scaffoldModels: { ... };
readonly providerTokenLimitKeys: { ... };
readonly supportedFormats: readonly [...];
readonly humanOnlyProviderId: "none";
readonly openAiCompatibleKeyEnv: "OPENAI_COMPATIBLE_API_KEY";
readonly libreTranslateKeyEnv: "LIBRETRANSLATE_API_KEY";
readonly configSearchPlaces: readonly string[];
};scaffoldingMetadata.humanOnlyProviderId 是 "none",即禁用机器翻译的 id。它没有 providerEnv 条目,因为它不读取密钥。
scaffoldingMetadata.libreTranslateKeyEnv 是 "LIBRETRANSLATE_,即 libretranslate 提供商读取其密钥的变量。它是可选的:没有带 --api-keys 启动的服务器不需要密钥,因此生成器应让它保持未设置。
scaffoldingMetadata.openAiCompatibleKeyEnv 是 "OPENAI_,即 openai-compatible 提供商的选项没有指定 apiKeyEnvVar 时读取的变量。scaffoldingMetadata.configSearchPlaces 按检查顺序列出 loadConfig 查找配置时检查的每个文件名;写入 verbatra.config.ts 的生成器,应在其中另一个已存在时拒绝写入,因为先找到的那个生效。
detectProject
根据项目的文件检测其语言文件的格式和布局,方式与 verbatra init 在写入配置之前相同。它不写入任何内容,也不调用提供商。它扫描目录(跳过隐藏目录、node_ 和构建输出,深度和条目数有上限),找出已注册的适配器认领的文件,找到每个文件中拼写出语言环境的路径段,并保留覆盖语言环境最多的文件路径模式。格式取其适配器的 canHandle 在给定内容时认领每个匹配文件的那一个;对 JSON,所有 JSON 适配器都会认领,此时由 package.json 中唯一匹配的 i18n 库决定。
function detectProject(
input?: DetectProjectInput,
deps?: DetectProjectDeps,
): Promise<ProjectDetection>;属性
类型
返回:ProjectDetection
import { detectProject } from "@verbatra/sdk";
const detection = await detectProject({ cwd: "/path/to/project" });
if (detection.ambiguities.length > 0) {
// several formats or file patterns fit: choose one of detection.ambiguities[0].candidates
}
const format = detection.format?.id; // for example "yaml"
const pattern = detection.layout?.pattern; // for example "config/locales/{locale}.yml"结果包含 format(带 from:input、files 或 dependencies)、layout(pattern、localeStyle、locales、sourceLocale、files、unqualifiedSourceFile)、ambiguities(每项带 subject,取 format 或 layout,以及它的 candidates)、取值为 high、medium、low 或 none 的 confidence,以及 reasons,每个决定一句话。势均力敌的情况报告为歧义,绝不猜测。可选的 format、pattern 和 sourceLocale 输入会缩小搜索范围,deps.fs 和 deps.adapterRegistry 替换文件系统和适配器,因此第三方适配器的文件也能被检测到。缺失、不可读或格式错误的文件绝不会抛出错误,只会让报告变得单薄。layout.unqualifiedSourceFile 指出布局旁边一个文件,其中的字符串不属于任何语言环境名称,例如 messages.properties 或 gettext 的 .pot 模板;此时不确定源语言环境,因为源是从模式为它指定的文件中读取的。
isMachineTranslationEnabled
恰好在配置设置了 provider: { id: "none" } 时返回 false,这是纯人工模式(见不用机器翻译运行):从不构造提供商,也不读取 API 密钥。提供会产生花费的操作的界面用它把这些操作整个省去,Studio 和 MCP 服务器就是这样做到即使加了 --allow-spend 也不提供花费的。
function isMachineTranslationEnabled(
config: Pick<VerbatraConfig, "provider">,
): boolean;返回:boolean
assertMachineTranslationEnabled
接受配置和一个指明操作的短语,在 provider: { id: "none" } 下抛出 SdkError MACHINE_。在把 translate 包装成显式的“翻译所有待处理项”操作之前调用它,这样该操作的失败方式与 retranslateEntry 相同,而不是悄悄地只从翻译记忆库填充。
function assertMachineTranslationEnabled(
config: Pick<VerbatraConfig, "provider">,
action: string,
): void;返回:void
抛出:MACHINE_
assertTargetLocale
接受配置和一个语言环境,当该语言环境不是已配置的 targetLocales 之一时,抛出 SdkError UNKNOWN_,错误信息与每个接受 locales 过滤条件的 SDK 函数相同。在自己只接受单个语言环境的界面中调用它,例如 MCP 服务器的 glossary.get,这样错误的语言环境的失败方式与在 SDK 中完全一致。
function assertTargetLocale(
config: Pick<VerbatraConfig, "targetLocales">,
locale: string,
): void;返回:void