verbaly
<p align="center">
<img src="assets/logo.png" alt="Verbaly" width="320" />
</p>
<h3 align="center">Write your text in the code. Ship it in every language.</h3>
<p align="center">
An i18n compiler and a tiny runtime for React, Vue, Svelte, Next.js, Nuxt, SvelteKit, Astro and plain HTML.<br />
No key files to keep in sync, params typed from the text, and a CI gate that stops broken translations.
</p>
<p align="center">
<a href="https://www.npmjs.com/package/verbaly"><img src="https://img.shields.io/npm/v/verbaly?logo=npm&color=cb3837" alt="npm version" /></a>
<a href="https://github.com/verbaly-i18n/verbaly/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/verbaly-i18n/verbaly/ci.yml?logo=github&label=CI" alt="CI" /></a>
<a href="https://codecov.io/gh/verbaly-i18n/verbaly"><img src="https://codecov.io/gh/verbaly-i18n/verbaly/branch/develop/graph/badge.svg" alt="coverage" /></a>
<a href="https://socket.dev/npm/package/verbaly"><img src="https://badge.socket.dev/npm/package/verbaly" alt="Socket supply chain security" /></a>
<a href="https://scorecard.dev/viewer/?uri=github.com/verbaly-i18n/verbaly"><img src="https://api.scorecard.dev/projects/github.com/verbaly-i18n/verbaly/badge" alt="OpenSSF Scorecard" /></a>
<a href="https://www.npmjs.com/package/verbaly#provenance"><img src="https://img.shields.io/badge/provenance-SLSA%20v1-3fb950?logo=npm" alt="published with npm provenance" /></a>
<img src="https://img.shields.io/badge/gzip-3.35KB-3fb950" alt="3.35KB gzip runtime" />
<img src="https://img.shields.io/badge/dependencies-0-3fb950" alt="zero runtime dependencies" />
<img src="https://img.shields.io/badge/types-included-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
<a href="./LICENSE"><img src="https://img.shields.io/npm/l/verbaly?color=blue" alt="MIT" /></a>
</p>
<p align="center">
<img src="assets/hero.gif" alt="On the left, a component that writes t`Welcome back, ${name}`, t`You have ${count} new messages` and t`Open inbox`. On the right, the same page in a browser switching from English to Spanish to Portuguese. Below, the four steps: write, extract, translate, check." width="860" />
</p>
<p align="center">
<a href="https://verbaly.dev/docs/frameworks/react"><img src="https://img.shields.io/badge/React-20232A?style=flat&logo=react&logoColor=61DAFB" alt="React" title="React" /></a>
<a href="https://verbaly.dev/docs/frameworks/react#next"><img src="https://img.shields.io/badge/Next.js-000000?style=flat&logo=nextdotjs&logoColor=white" alt="Next.js" title="Next.js" /></a>
<a href="https://verbaly.dev/docs/frameworks/vue"><img src="https://img.shields.io/badge/Vue-35495E?style=flat&logo=vuedotjs&logoColor=4FC08D" alt="Vue" title="Vue" /></a>
<a href="https://verbaly.dev/docs/frameworks/vue#nuxt"><img src="https://img.shields.io/badge/Nuxt-0B1E1A?style=flat&logo=nuxt&logoColor=00DC82" alt="Nuxt" title="Nuxt" /></a>
<a href="https://verbaly.dev/docs/frameworks/svelte"><img src="https://img.shields.io/badge/Svelte-2A1A14?style=flat&logo=svelte&logoColor=FF3E00" alt="Svelte and SvelteKit" title="Svelte and SvelteKit" /></a>
<a href="https://verbaly.dev/docs/frameworks/astro"><img src="https://img.shields.io/badge/Astro-17191E?style=flat&logo=astro&logoColor=FF5D01" alt="Astro" title="Astro" /></a>
<a href="https://verbaly.dev/docs/frameworks/vite"><img src="https://img.shields.io/badge/Vite-1B1C2E?style=flat&logo=vite&logoColor=646CFF" alt="Vite" title="Vite" /></a>
<a href="https://verbaly.dev/docs/frameworks/vite#unplugin"><img src="https://img.shields.io/badge/webpack-1C2B34?style=flat&logo=webpack&logoColor=8DD6F9" alt="webpack, Rollup, esbuild and Rspack" title="webpack, Rollup, esbuild and Rspack" /></a>
<a href="https://verbaly.dev/docs/frameworks/dom"><img src="https://img.shields.io/badge/HTML-2B1A16?style=flat&logo=html5&logoColor=E34F26" alt="Plain HTML, no framework" title="Plain HTML, no framework" /></a>
</p>
## The idea
Most i18n tools ask you to invent a key for every sentence, write it in a file per language and keep the files in step with the code by hand. Verbaly turns that around:
```tsx
// 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 });
```
The runtime that ships is **3.35 KB gzip** with zero dependencies, measured on every release by a gate in this repo (`pnpm --filter verbaly size`).
## Quick start
```bash
pnpm add verbaly @verbaly/vite
pnpm add -D @verbaly/compiler # the verbaly command: init, extract, check
npx verbaly init
```
```ts
// vite.config.ts
import verbaly from '@verbaly/vite';
export default { plugins: [verbaly()] };
```
```ts
// 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` is your project's own module: the plugin writes it from your config, with your languages and catalogs already in it. Next.js, Nuxt, SvelteKit and Astro have their own one-line setup: pick yours in the row above, or read the full docs at **https://verbaly.dev/docs**.
## Why Verbaly
<table>
<tr>
<td width="33%" valign="top"><h3>✍️ No key files</h3>You write the sentence. The compiler names it and keeps every language file in step with your code.</td>
<td width="33%" valign="top"><h3>🧷 Typed from the text</h3><code>{name}</code>, plurals, currency and dates come from the message itself, so a wrong or missing param fails to compile.</td>
<td width="33%" valign="top"><h3>🛑 Broken ones never ship</h3><code>verbaly check</code> catches a missing translation, and one that lost a <code>{param}</code>, a tag or a plural case, in plain words.</td>
</tr>
<tr>
<td width="33%" valign="top"><h3>🪶 Small and fast</h3>Zero dependencies, one module per language, and a hot path benchmarked against i18next on every release.</td>
<td width="33%" valign="top"><h3>🔄 Any workflow</h3>Plain JSON, XLIFF, CSV and gettext PO for translators, Android and iOS exports, and AI drafts a person approves.</td>
<td width="33%" valign="top"><h3>🤖 Agent ready</h3>An MCP server, an Agent Skill and <code>llms.txt</code>, with drafts an agent can write but never approve.</td>
</tr>
</table>
## Review translations in a panel
```bash
npx verbaly-studio
```
<p align="center">
<img src="assets/studio.png" alt="Verbaly Studio: an overview that says five things are waiting, one translation that breaks the site, two missing messages and two machine translations nobody has read, with the languages and the last commits to the catalogs" width="860" />
</p>
Studio serves your project over localhost: what is missing, what is broken, what a machine wrote and where each text lives in your code. Your JSON files are the database and git is the history, a save runs the same validations as `verbaly check`, and it never edits your source text.
## How it compares
| | **Verbaly** | i18next | Lingui | Paraglide |
| ------------------------- | -------------------------------------------- | --------------------------------------- | ----------------------------------- | ---------------------------------- |
| Type-safe keys & params | ✅ Inferred from your text | Built in, from a declaration file | Text in code, no keys to mistype | A typed function per message |
| Runtime size (gzip) | ✅ 3.35 KB, zero deps (6.17 with DOM + urls) | 15.5 KB (22.1 with React) | 2.3 KB (4.4 with React) | compiled, no shared runtime |
| Key maintenance | ✅ None, auto-extracted | Written by hand, synced by its CLI | Extract → compile step | By hand |
| Dynamic / CMS content | ✅ Real runtime path | Yes | Yes | Best with keys known at build time |
| Plain HTML (no framework) | ✅ DOM interpreter | With a jQuery plugin | ❌ | ❌ |
| Missing translations | ✅ Fails CI, every build lists it | A CLI command, for CI | CI step | inlang check, in CI |
| Broken translations | ✅ Fails CI, every build lists it | CLI lint, a warning by default | Syntax errors only | inlang check, in CI |
| Catalog format | ✅ Plain JSON | JSON | PO, JSON or CSV | inlang format, others by plugin |
| Coding agents | ✅ MCP server + skill | Skill, hosted MCP (Locize) | Skills + plugin | ❌ |
| Maturity & ecosystem | Pre-1.0: the API can still change | Proven at scale, modules for everything | Stable, standard PO for translators | Stable, with the inlang tools |
Every cell about another tool is the best true thing its own documentation says, read on 2026-11-15 (i18next 27.1.2, Lingui 6.12.0, Paraglide 3.2.2). Sizes are min+gzip of what an app imports, with React external, measured the same day with the same method. The same table is on [verbaly.dev](https://verbaly.dev/#compare).
## Coding agents
```bash
claude mcp add verbaly -- npx -y @verbaly/mcp
```
In Claude Code, one plugin brings the server and the skill together:
```bash
claude plugin marketplace add verbaly-i18n/verbaly
```
```bash
claude plugin install verbaly@verbaly
```
Gemini CLI takes the same pair as an extension: `gemini extensions install https://github.com/verbaly-i18n/verbaly`.
The MCP server gives your agent the whole cycle as tools, with structured output and resources to read your config and catalogs. Machine translations stay drafts until a person approves them (`verbaly review --approve`, or Studio): approving is deliberately not a tool. The [Agent Skill](skills/verbaly/SKILL.md) teaches the write, extract, check and translate cycle (`npx skills add verbaly-i18n/verbaly`, which copies it into the folder of each agent you use), and the docs publish [llms.txt](https://verbaly.dev/llms.txt).
## Packages
| Package | What it is |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [`verbaly`](packages/core) | The runtime: `t`, `Intl` formats, locale helpers and the DOM interpreter |
| [`@verbaly/compiler`](packages/compiler) | Extraction, typed codegen, the gate and the `verbaly` command |
| [`@verbaly/vite`](packages/vite) · [`@verbaly/unplugin`](packages/unplugin) | Bundler plugins: Vite, and webpack, Rollup, esbuild and Rspack |
| [`@verbaly/react`](packages/react) · [`@verbaly/vue`](packages/vue) · [`@verbaly/svelte`](packages/svelte) | Framework adapters: hooks or composables plus `<Trans>` |
| [`@verbaly/next`](packages/next) · [`@verbaly/nuxt`](packages/nuxt) · [`@verbaly/sveltekit`](packages/sveltekit) | Server rendering: the language per request, hydration with no flash |
| [`@verbaly/astro`](packages/astro) | Astro integration: `.astro` extraction and a static build per language |
| [`@verbaly/mcp`](packages/mcp) | MCP server: the translation cycle as tools for an agent |
| [`@verbaly/studio`](packages/studio) | The local review panel above |
All of them share one version number, and every release is published from CI with npm provenance.
<details>
<summary><strong>Editor: see the text behind a key on hover</strong></summary>
Generated keys are hashes, so `t('a1B2c3D4')` in a diff tells you nothing. The [i18n-ally](https://marketplace.visualstudio.com/items?itemName=Lokalise.i18n-ally) extension shows the real text inline once you point it at your catalogs. Two files, no Verbaly config changes:
`.vscode/settings.json`
```json
{
"i18n-ally.localesPaths": ["locales"],
"i18n-ally.keystyle": "flat",
"i18n-ally.sourceLanguage": "en",
"i18n-ally.displayLanguage": "en"
}
```
`.vscode/i18n-ally-custom-framework.yml`
```yaml
languageIds:
- javascript
- typescript
- javascriptreact
- typescriptreact
- vue
- svelte
- astro
usageMatchRegex:
- "[^\\w\\d]t\\(\\s*['\"`]({key})['\"`]"
monopoly: true
```
`keystyle` has to match your catalogs: `flat` for dotted keys, `nested` for groups. Use the extension for reading, not writing: its extract and rename actions assume you own the keys, and here the compiler does.
</details>
## Development
```bash
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 is `0.x`: the API can still change between minor versions, and every change is in the [changelog](changelog/CHANGELOG.md). Contributions are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md).
## Feedback
- **Something broke or surprised you:** [open a bug](https://github.com/verbaly-i18n/verbaly/issues/new?template=bug_report.yml). A minimal snippet is enough.
- **Something felt like friction:** [tell us what](https://github.com/verbaly-i18n/verbaly/issues/new?template=feature_request.yml). The roadmap follows real use.
- **It just works:** a [star](https://github.com/verbaly-i18n/verbaly) or a mention helps others find it.
## Sponsor
Verbaly is MIT-licensed, dependency-free and built independently. If it saves you time, [sponsoring it](https://github.com/sponsors/AronSoto) funds the road to 1.0: more integrations, faster releases and long-term maintenance.
<p align="center">
<a href="https://github.com/sponsors/AronSoto"><img src="https://img.shields.io/badge/♥%20Sponsor%20Verbaly-bef12d?style=for-the-badge&logoColor=1a1f16" alt="Sponsor Verbaly on GitHub" /></a>
</p>
## License
[MIT](./LICENSE) © Aron Soto · [@AronSoto](https://github.com/AronSoto)
TDQS
Scored across 9 tools
Each tool targets a distinct lifecycle step (init, extract, wrap, translate, write_drafts, missing, drafts, status, doctor), but the read-only reporting trio (status/missing/drafts) and the write side (translate vs write_drafts) sit close together. The descriptions do explicitly delimit them ('for counts use verbaly_status', 'to save translations you wrote yourself, verbaly_write_drafts'), so an agent can separate them, but it takes careful reading.
Every tool uses the same verbaly_<verb/verb_noun> snake_case convention (translate, write_drafts, extract, wrap, init, doctor, missing, drafts, status). The prefix and casing are uniform throughout with no deviations.
Nine tools map cleanly onto the CLI's commands and each earns its place: one per lifecycle stage plus three focused read-only diagnostics. The set is well within the ideal 3-15 range and nothing looks redundant at the command level.
The surface covers setup (init), source handling (extract, wrap), translation generation (translate, write_drafts), and full read-only insight (status, missing, drafts, doctor). The one deliberate gap is approval/review: machine drafts can only be accepted via `verbaly review --approve` outside the tools, which is an intentional human-in-the-loop dead end rather than an oversight.