---
title: "Angular 快速上手"
description: "用 verbatra 翻译 Angular 应用的 ngx-translate 语言文件，从安装到屏幕上出现第一条德语文本。"
type: "tutorial"
---
# Angular 快速上手

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

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

已经有语言文件和编码智能体了？那就改为把[用 AI 智能体配置 verbatra](https://verbatra.kreitz-webdev.de/zh-CN/docs/start-with-ai.md) 中的提示词交给它：它会围绕你的项目已有的文件工作，并在产生任何花费之前停下。

## 步骤 [#步骤]

<Steps>
<Step>

### 安装 CLI [#安装-cli]

```bash
npm install --save-dev @verbatra/cli
```

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

</Step>
<Step>

### 添加源语言文件 [#添加源语言文件]

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

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

</Step>
<Step>

### 生成配置 [#生成配置]

```bash
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`。

</Step>
<Step>

### 不用密钥预览运行 [#不用密钥预览运行]

```bash
npx @verbatra/cli translate --dry-run
```

```text output
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)
```

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

</Step>
<Step>

### 翻译 [#翻译]

```bash
cp .env.example .env
```

打开 `.env`，把你的密钥粘贴到 `GEMINI_API_KEY=` 之后。还没有密钥？Gemini 有免费套餐：在 [Google AI Studio](https://aistudio.google.com/apikey) 创建一个。其他提供商及其变量见[提供商](https://verbatra.kreitz-webdev.de/zh-CN/docs/providers.md)。

```bash
npx @verbatra/cli translate
```

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

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

</Step>
<Step>

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

```bash
npx @verbatra/cli check
```

```text output
[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。

</Step>
<Step>

### 在应用中加载语言文件 [#在应用中加载语言文件]

添加 `@ngx-translate/core`：

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

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

```ts title="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" }),
    }),
  ],
};
```

```ts title="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 {}
```

```jsonc title="angular.json"
// projects.<name>.architect.build.options
"assets": [
  { "glob": "**/*", "input": "public" },
  { "glob": "**/*", "input": "src/assets", "output": "assets" }
]
```

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

</Step>
</Steps>

## 刚才发生了什么 [#刚才发生了什么]

- `verbatra.lock.json` 记录每条源字符串的哈希，因此下次运行只发送新增和已更改的字符串。见[锁文件与来源记录](https://verbatra.kreitz-webdev.de/zh-CN/docs/the-lock-file.md)。
- 丢失占位符的译文会被搁置，绝不会写入。见[翻译安全](https://verbatra.kreitz-webdev.de/zh-CN/docs/translation-safety.md)。

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

## 可选：连接你的编码智能体 [#可选连接你的编码智能体]

<AvailableFrom version="0.12.0" />

```bash
npx @verbatra/cli init --agent
```

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

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

[添加到 VS Code](vscode:mcp/install?%7B%22name%22%3A%22verbatra%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40verbatra%2Fmcp%22%5D%7D)

## 接下来 [#接下来]

<Cards>
  <Card title="添加语言" href="https://verbatra.kreitz-webdev.de/zh-CN/docs/add-a-language.md" description="添加一个目标语言环境，让一次运行把它填好。" />
  <Card title="在 CI 中运行 verbatra" href="https://verbatra.kreitz-webdev.de/zh-CN/docs/ci-and-exit-codes.md" description="语言环境发生漂移时让 pull request 失败。" />
  <Card title="选择技术栈" href="https://verbatra.kreitz-webdev.de/zh-CN/docs/pick-your-stack.md" description="其他每个框架的格式 id 和文件布局。" />
</Cards>
