verbaly
This server exposes Verbaly’s i18n workflow as MCP tools, letting an agent set up, diagnose, extract, validate, translate, and prepare drafts for a project while leaving final approval to a human.
Initialize Verbaly: create config and locale catalogs, detect framework/bundler, and list next steps without overwriting existing files.
Diagnose setup end to end: config, catalogs/JSON, bundler plugin, generated types, parser failures, imports, orphan keys, and check failures.
Wrap hardcoded JSX/TSX text in
ttagged templates, with report-only mode and blocked-file guidance.Extract messages into catalogs and refresh generated types, with
dryRunandpruneoptions.Report translation coverage: total, translated, drafts, broken, and outdated per locale.
List missing, unknown, broken, colliding, divergent, outdated, and optional unreviewed translations for the CI-style gate.
Machine-translate missing entries through the configured provider as drafts, with dry-run, locale filters, and retry-safe failure reporting.
Save agent-written translations as drafts after validation, optionally overwriting existing entries.
List machine translations awaiting human review with source and translated text.
Cannot approve translations; a human must run
verbaly review --approve.
Supports Verbaly i18n projects built with Astro, letting the MCP tools detect the framework, manage catalogs, run extraction and checks, and keep translations in sync.
Supports esbuild-based projects through Verbaly's unplugin integration, including bundler detection during init and catalog extraction and validation.
Supports plain HTML projects with Verbaly's DOM runtime, allowing the MCP server to manage the project's translation catalogs and run extraction and checks.
Supports Next.js projects, including JSX/TSX extraction, wrapping hardcoded user-visible text in t tagged templates, framework detection, and catalog checks.
Supports Nuxt projects by detecting the framework, wiring the Verbaly integration, and managing extraction, catalog checks, and translation drafts.
Supports React projects, especially JSX/TSX source files, by finding and wrapping hardcoded text in t tagged templates and extracting messages into catalogs.
Supports Svelte and SvelteKit projects through Verbaly's framework integration, with catalog extraction, validation, and translation management.
Integrates with Vite projects via the @verbaly/vite plugin; the MCP server can detect the bundler, recommend setup wiring, and manage catalogs.
Supports webpack-based projects through Verbaly's unplugin integration, including bundler detection during init and catalog extraction and validation.
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:
// 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).
Related MCP server: Weblate MCP Server
Quick start
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 moduleverbaly/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
Review translations in a panel
npx verbaly-studioStudio 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.
Coding agents
claude mcp add verbaly -- npx -y @verbaly/mcpIn Claude Code, one plugin brings the server and the skill together:
claude plugin marketplace add verbaly-i18n/verbalyclaude plugin install verbaly@verbalyGemini 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 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.
Packages
Package | What it is |
The runtime: | |
Extraction, typed codegen, the gate and the | |
Bundler plugins: Vite, and webpack, Rollup, esbuild and Rspack | |
Framework adapters: hooks or composables plus | |
Server rendering: the language per request, hydration with no flash | |
Astro integration: | |
MCP server: the translation cycle as tools for an agent | |
The local review panel above |
All of them share one version number, and every release is published from CI with npm provenance.
Generated keys are hashes, so t('a1B2c3D4') in a diff tells you nothing. The i18n-ally extension shows the real text inline once you point it at your catalogs. Two files, no Verbaly config changes:
.vscode/settings.json
{
"i18n-ally.localesPaths": ["locales"],
"i18n-ally.keystyle": "flat",
"i18n-ally.sourceLanguage": "en",
"i18n-ally.displayLanguage": "en"
}.vscode/i18n-ally-custom-framework.yml
languageIds:
- javascript
- typescript
- javascriptreact
- typescriptreact
- vue
- svelte
- astro
usageMatchRegex:
- "[^\\w\\d]t\\(\\s*['\"`]({key})['\"`]"
monopoly: truekeystyle 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.
Development
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 i18nextVerbaly is 0.x: the API can still change between minor versions, and every change is in the changelog. Contributions are welcome: see CONTRIBUTING.md.
Feedback
Something broke or surprised you: open a bug. A minimal snippet is enough.
Something felt like friction: tell us what. The roadmap follows real use.
It just works: a star or a mention helps others find it.
Sponsor
Verbaly is MIT-licensed, dependency-free and built independently. If it saves you time, sponsoring it funds the road to 1.0: more integrations, faster releases and long-term maintenance.
License
Available Tools
9 toolsverbaly_doctorDiagnose the setupARead-only
Diagnose a Verbaly project end to end (what verbaly doctor does). It checks the config file, the catalogs and their JSON, the bundler plugin for the detected framework, the generated types, files the parser could not read, a t imported from a package that never exports it, orphan keys, and every failure verbaly check would report, and it reports them all at once instead of stopping at the first. Run it first when something does not work. Read-only. For the missing or broken translations themselves, use verbaly_missing.
Inputs: root. Returns: ok, entries
verbaly_draftsMachine translations awaiting reviewARead-only
Every machine translation still waiting for a human, each with the source text and what the provider wrote, so a person can read both and decide. Read-only. Approving is deliberately not a tool here and never will be: a machine translation is unreviewed by definition, so accepting one is verbaly review --approve, run by a human. For how many drafts each locale has, verbaly_status is enough; verbaly_missing lists them next to the gate.
Inputs: root, locales. Returns: total, entries
verbaly_extractExtract messagesADestructiveIdempotent
Scan the source files, add new messages to the locale catalogs and refresh the generated types (what verbaly extract does). It writes the catalogs unless dryRun is set, and with the same code a second run changes nothing. prune also drops keys the code no longer references, translations included, and waits while any source file fails to parse. In a project without Verbaly, run verbaly_init first; for text still hardcoded in JSX, verbaly_wrap.
Inputs: root, prune, dryRun. Returns: lock, added, dryRun, inCode, +10 more
verbaly_initSet up Verbaly in a projectAIdempotent
Create the config file and the locale catalogs, and detect the bundler or meta-framework so the answer names the package to add and the line to wire (what verbaly init does). A file already there is kept, never overwritten, so running it again is safe. Use it when verbaly_doctor finds no config; once the project is set up, verbaly_doctor is the one to run.
Inputs: dir, root, locales, sourceLocale. Returns: host, next, found, created, +4 more
verbaly_missingMissing and broken translationsARead-only
The gate verbaly check runs in CI, as lists: missing translations, unknown keys, keys written with two texts (collisions: every place shows the first text) and translations that cannot render what the source renders. A dropped {param}, a lost rich tag or a flattened plural block is that last kind. Warnings never fail the gate and are listed too: an incomplete plural set for the locale, keys only a translation has (extra), texts the code and the source catalog disagree on (divergent: the text in the code ships) and translations written for an older source text (outdated). With drafts set, it also lists the machine translations awaiting review. Read-only. For counts use verbaly_status, to review drafts with their source text verbaly_drafts, and for setup problems verbaly_doctor.
Inputs: root, drafts. Returns: ok, extra, broken, missing, +6 more
verbaly_statusTranslation coverageARead-only
Translation coverage of the Verbaly project as numbers per locale: total messages, translated, machine translations awaiting review (drafts), broken, and translations written for an older source text (outdated). It scans the source like verbaly_extract but writes nothing. Read-only. For the entries behind the numbers, use verbaly_missing (what is missing or broken) or verbaly_drafts (each draft with its source text).
Inputs: root. Returns: source, locales, messages, stateProblem
verbaly_translateMachine-translate missing entriesAIdempotent
Fill missing translations with the configured provider (what verbaly translate does). The default provider is Claude, which needs @anthropic-ai/sdk and ANTHROPIC_API_KEY. Every new translation is saved as a draft awaiting human review (verbaly review), which no tool here can approve. Each language is saved as soon as its last batch lands, so a run that is cut keeps the languages it finished. A batch the provider never answers, or a language whose file cannot be saved, is reported in failed and everything else stays written, so a retry only asks for what is left. dryRun lists what would be translated without calling the provider. A locale the project does not have is an error that lists the ones it has, never an empty result. To see what is missing first, use verbaly_missing; to save translations you wrote yourself, verbaly_write_drafts.
Inputs: root, dryRun, locales. Returns: kept, lock, dryRun, failed, +3 more
verbaly_wrapWrap hardcoded JSX textADestructiveIdempotent
Find hardcoded user-visible text in JSX/TSX files and wrap it in a t tagged template so the compiler can extract it (what verbaly wrap does). This is how an existing codebase is onboarded, and verbaly_extract then adds the wrapped texts to the catalogs. It only reports unless write is set, and text already wrapped is skipped, so running it again is safe. Text it cannot wrap safely (a sentence split across markup, an expression rendering JSX) is listed as needing a human. A file that does not bind t is never written, because the rewrite would not compile. It comes back in blocked, with the binding this project needs there, so you can add it and run again.
Inputs: root, write. Returns: files, write, blocked, changed, +2 more
verbaly_write_draftsSave translations an agent wroteADestructiveIdempotent
Save translations you wrote yourself, so neither a catalog nor the state file is ever edited by hand. Each one is checked the way verbaly_translate checks a provider (params, rich tags and plural cases must survive), written only for keys the source catalog has, and marked as a draft awaiting human review. Existing translations are kept unless overwrite is set, which is how an outdated one gets rewritten. Approving is not a tool here: a human reads the drafts (verbaly_drafts lists them) and runs verbaly review --approve.
Inputs: locale (required), entries (required), root, overwrite. Returns: kept, lock, invalid, unknown, +1 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Find missing translations in your app, propose texts and publish and deploy them to your CDN.
AI-native translation management: push translation files, translate, review and audit strings.
Manage app translations: find and create keys, draft translations, commit and ship OTA releases.
Add AI translation to React, Angular, Vue or any website, and review and fix your translations.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceMcp Server For Doc / Cli / Sdk Integration related to Intlayer i18n solution & CMS868Apache 2.0
- AlicenseBqualityCmaintenanceMCP server for managing translation projects in Weblate. With the ability to search, read and write transltaions.2037 npm24MIT
- FlicenseNot gradedqualityDmaintenanceEnables translation of JSON i18n files to multiple languages using various AI providers (Google Gemini, OpenAI, Ollama/DeepSeek) with intelligent caching and deduplication.19 npm5-
- AlicenseAqualityDmaintenanceConnects AI assistants to Lokalise translation management platform with 59 tools across 11 domains, enabling localization teams to manage projects, translations, tasks, and workflows through natural conversation.59871 npm6MIT