跳到正文
跳到正文

文档 / 入门 / 快速上手

机器翻译页面

本页面为自动翻译,可能有错误或表述不够自然。内容以英文版本为准。阅读英文原文。

Angular 快速上手

用 verbatra 翻译 Angular 应用的 ngx-translate 语言文件,从安装到屏幕上出现第一条德语文本。

学完本页,你的 Angular 应用会显示一条由 verbatra 从 src/assets/i18n/en.json 翻译而来的德语字符串,并且锁文件会让之后的每次运行只翻译已更改的内容。你需要 Node.js ^22.22.0 || >=24、一个 Angular 项目,以及大约 10 分钟。前四步不需要账号,也不需要 API 密钥。

已经有语言文件和编码智能体了?那就改为把用 AI 智能体配置 verbatra 中的提示词交给它:它会围绕你的项目已有的文件工作,并在产生任何花费之前停下。

步骤

安装 CLI

npm install --save-dev @verbatra/cli

verbatra 是开发工具,从不随你的应用发布。下面的命令使用 npx;使用 pnpm、yarn 或 bun 时,改为运行 pnpm verbatra、yarn verbatra 或 bun run verbatra。

添加源语言文件

如果 src/assets/i18n/en.json 已存在,跳过这一步。否则,创建它并写入两条字符串,其中一条带占位符:

src/assets/i18n/en.json
{
  "greeting": "Hello, {{name}}!",
  "cart": {
    "empty": "Your cart is empty."
  }
}

生成配置

npx @verbatra/cli init --format ngx-translate-json --provider gemini --yes

--format 的值 ngx-translate-json 是 @ngx-translate/core 的文件格式。init 会查找你的语言文件;还没有语言文件时,则写入路径模式 src/assets/i18n/{locale}.json。--yes 直接采用 init 检测到的结果,不再提示。新的 verbatra.config.ts 把 en 翻译成 de;要添加更多语言,把语言环境代码加入 targetLocales。

不用密钥预览运行

npx @verbatra/cli translate --dry-run
输出
verbatra: dry run over 1 locale, no provider call
verbatra: de done, 2 would translate
verbatra translate (dry run)
  de: 2 would translate, 0 unchanged
1 succeeded, 0 partial, 0 failed (dry run: nothing written)
[ok] dry run done in 0.0s, nothing written
next: verbatra translate (run it for real)

试运行不构造提供商,因此不需要密钥,不产生花费,也不写入任何内容。

翻译

cp .env.example .env

打开 .env,把你的密钥粘贴到 GEMINI_API_KEY= 之后。还没有密钥?Gemini 有免费套餐:在 Google AI Studio 创建一个。其他提供商及其变量见提供商。

npx @verbatra/cli translate

verbatra 把这两条字符串发给 Gemini,检查每个占位符是否保留,并写入 src/assets/i18n/de.json。具体措辞取决于模型,例如:

src/assets/i18n/de.json
{
  "greeting": "Hallo, {{name}}!",
  "cart": {
    "empty": "Dein Warenkorb ist leer."
  }
}

确认每个语言环境都已同步

npx @verbatra/cli check
输出
[ok] checking the locales (0.0s)
verbatra check
  de: 0 missing, 0 stale, 2 up-to-date (in sync)
all locales in sync

check 不调用提供商,语言环境一旦不同步就以退出码 1 退出,因此它可以用门禁拦住 pull request。

在应用中加载语言文件

添加 @ngx-translate/core:

npm install @ngx-translate/core @ngx-translate/http-loader

然后加载两个文件并渲染问候语:

src/app/app.config.ts
import { provideHttpClient } from "@angular/common/http";
import type { ApplicationConfig } from "@angular/core";
import { provideTranslateService } from "@ngx-translate/core";
import { provideTranslateHttpLoader } from "@ngx-translate/http-loader";

export const appConfig: ApplicationConfig = {
  providers: [
    // keep the providers the Angular CLI generated, and add:
    provideHttpClient(),
    provideTranslateService({
      lang: "de",
      fallbackLang: "en",
      loader: provideTranslateHttpLoader({ prefix: "./assets/i18n/", suffix: ".json" }),
    }),
  ],
};
src/app/app.ts
import { Component } from "@angular/core";
import { TranslatePipe } from "@ngx-translate/core";

@Component({
  selector: "app-root",
  imports: [TranslatePipe],
  template: `<p>{{ 'greeting' | translate: { name: 'Ada' } }}</p>`,
})
export class App {}
angular.json
// projects.<name>.architect.build.options
"assets": [
  { "glob": "**/*", "input": "public" },
  { "glob": "**/*", "input": "src/assets", "output": "assets" }
]

启动你的应用:问候语显示为 Hallo, Ada!。

刚才发生了什么

  • verbatra.lock.json 记录每条源字符串的哈希,因此下次运行只发送新增和已更改的字符串。见锁文件与来源记录。
  • 丢失占位符的译文会被搁置,绝不会写入。见翻译安全。

把语言文件、verbatra.lock.json 和 verbatra.provenance.json 一起提交。

可选:连接你的编码智能体

npx @verbatra/cli init --agent

配置已就位时,init --agent 保留它,只添加智能体文件:写入 AGENTS.md 的 verbatra 规则(如果 CLAUDE.md 是你唯一的指令文件,则写入 CLAUDE.md),以及在它检测到的每个编码智能体的项目配置中注册 verbatra MCP 服务器(不允许花费)。它为哪个智能体写入哪些文件,以及用 --client 自己指定智能体,见配置编码智能体。--dry-run 显示这些文件,但不写入。

或者,不用 CLI,只把 MCP 服务器添加到你的 VS Code 用户配置文件;只用其中一种方式,不要两种都用:

添加到 VS Code

接下来

在 GitHub 上编辑

本页内容