verbaly

在代码中编写文本，以各种语言发布。

一款 i18n 编译器和轻量级运行时，支持 React、Vue、Svelte、Next.js、Nuxt、SvelteKit、Astro 和纯 HTML。
无需同步维护键文件，参数类型从文本中推导，并通过 CI 门禁阻止有问题的翻译。

设计理念

大多数 i18n 工具都要求你为每个句子创建一个键，按语言分别写入文件，再手动让这些文件与代码保持同步。Verbaly 则反其道而行：

// with key files: name it, write it in en.json, es.json, pt.json, keep them in sync
t('dashboard.welcome_back', { name });

// with Verbaly: write the sentence where it is used
t`Welcome back, ${name}`;

// and the compiler writes a stable key and a typed call for you
t('ESsQIvlA', { name });

发布的运行时经 gzip 压缩后仅 3.35 KB，且零依赖。每次发布时，都会通过此仓库中的检查进行测量（pnpm --filter verbaly size）。

快速开始

pnpm add verbaly @verbaly/vite
pnpm add -D @verbaly/compiler   # the verbaly command: init, extract, check
npx verbaly init

// vite.config.ts
import verbaly from '@verbaly/vite';

export default { plugins: [verbaly()] };

// anywhere in your app: extracted and typed on save
import { t, setLocale } from 'verbaly/app';

t`Hello ${name}`;
await setLocale('es'); // loads only the Spanish module

verbaly/app 是项目自己的模块：插件会根据你的配置生成它，其中已包含你的语言和目录。Next.js、Nuxt、SvelteKit 和 Astro 都有各自的一行设置：在上方选择对应框架，或阅读完整文档：**https://verbaly-web.vercel.app/docs**。

Verbaly 的优势

npx verbaly-studio

Studio 通过 localhost 提供项目服务：显示缺少什么、什么出了问题、机器写了什么，以及每段文本在代码中的位置。JSON 文件是数据库，git 则记录历史；每次保存都会运行与 verbaly check 相同的验证，而且绝不会修改源文本。

对比

大小为各库主入口在 React 外置时的 min+gzip 大小，使用相同方法于 2026-10-15 测得。

编码 Agent

claude mcp add verbaly -- npx -y @verbaly/mcp

MCP 服务通过工具向你的 Agent 提供完整流程，并提供结构化输出以及用于读取配置和目录的资源。机器翻译会一直保留为草稿，直到有人批准（使用 verbaly review --approve 或 Studio）；批准操作特意不作为工具提供。Agent Skill 会指导写入、提取、检查和翻译流程（npx degit AronSoto/verbaly/skills/verbaly .claude/skills/verbaly），文档还发布了 llms.txt。

软件包

所有软件包共用一个版本号，每次发布都通过 CI 发布，并附带 npm 来源证明。

{
  "i18n-ally.localesPaths": ["locales"],
  "i18n-ally.keystyle": "flat",
  "i18n-ally.sourceLanguage": "en",
  "i18n-ally.displayLanguage": "en"
}

languageIds:
  - javascript
  - typescript
  - javascriptreact
  - typescriptreact
  - vue
  - svelte
  - astro
usageMatchRegex:
  - "[^\\w\\d]t\\(\\s*['\"`]({key})['\"`]"
monopoly: true

开发

pnpm install
pnpm build      # tsdown: ESM + CJS + .d.ts
pnpm test       # each package's suite
pnpm typecheck
pnpm --filter verbaly bench   # the hot path against i18next

Verbaly 处于 0.x 阶段：API 在次要版本之间仍可能发生变化，每项变更都会记录在变更日志中。欢迎贡献：请参阅 CONTRIBUTING.md。

反馈

• 遇到故障或意外情况：提交 Bug。提供一段最小代码片段即可。
• 觉得哪里不够顺手：告诉我们。路线图会根据实际使用情况制定。
• **一切运行顺利：**点个星或提及我们，都能帮助其他人发现它。

赞助

Verbaly 采用 MIT 许可、没有依赖项，由独立开发者构建。如果它为你节省了时间，赞助项目将为迈向 1.0 提供资金支持：更多集成、更快发布和长期维护。

许可证

MIT © Aron Soto · @AronSoto