跳到正文
跳到正文

文档 / 入门 / 快速上手

机器翻译页面

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

Vue 快速上手

用 verbatra 翻译 Vue 应用的 vue-i18n 语言文件,从安装到屏幕上显示第一条德语字符串。

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

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

步骤

安装 CLI

npm install --save-dev @verbatra/cli

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

添加源语言文件

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

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

生成配置

npx @verbatra/cli init --format vue-i18n-json --provider gemini --yes

--format 的值 vue-i18n-json 是 vue-i18n 的文件格式。init 会查找你的语言文件;还没有语言文件时,则写入路径模式 src/locales/{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/locales/de.json。具体措辞取决于模型,例如:

src/locales/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。

在应用中加载语言文件

添加 vue-i18n:

npm install vue-i18n

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

src/main.ts
import { createApp } from "vue";
import { createI18n } from "vue-i18n";
import App from "./App.vue";
import de from "./locales/de.json";
import en from "./locales/en.json";

const i18n = createI18n({
  legacy: false,
  locale: "de",
  fallbackLocale: "en",
  messages: { en, de },
});

createApp(App).use(i18n).mount("#app");
src/App.vue
<template>
  <p>{{ $t("greeting", { name: "Ada" }) }}</p>
</template>

启动你的应用:问候语显示为 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 上编辑

本页内容