Docs / Help
FAQ
Short answers to the questions that come up most when running verbatra, from what a run costs to what you should commit.
Short answers with a link to the page that has the details. For error messages, see Troubleshooting and Error codes.
How do I control cost?
Runs are incremental, so only missing or changed keys reach the provider, and an unchanged project
costs nothing to re-run. verbatra translate --estimate sizes a run without calling a provider, and
--max-tokens or maxTokens in the config caps it. See Estimating cost.
What does a run actually cost?
Little: 400 keys into 3 locales on gemini-2.5-flash come to about 72,000 tokens, which you price
at your provider's current rate, and later runs pay only for the strings you changed. How to size a
run, where each provider publishes its rates, and how to calibrate against your own project are in
Estimating cost.
Which provider should I start with?
Gemini, because its free API tier lets you translate a whole project at no cost, and switching later
means editing one id. Keep confidential strings off the free tier: see
Data handling and privacy. Every
provider is compared on Providers.
Can I run a local model?
Yes: the openai-compatible provider points verbatra at any server that speaks the OpenAI chat API,
such as LM Studio, Ollama or vLLM, usually with no key. Without a language model at all,
libretranslate uses a self-hosted LibreTranslate server. See Providers.
Which languages does verbatra support?
Any language your provider supports, written as a valid BCP 47 code such as pt-BR or zh-Hant.
DeepL and Google Cloud Translation have fixed lists; the LLM providers have none. See
Language support.
How do keys keep their order?
Existing keys keep their positions and new keys are appended in source order, so a translated file diffs cleanly. See Formats.
Why did a translation get flagged for review?
A review heuristic found something worth a second look, such as a translation equal to its source, and flagged it without withholding it. Every reason code is listed under Review reasons.
Does verbatra work in a monorepo?
Yes. The config search walks up from the working directory and stops at the nearest .git, so a
package finds its own config and the root finds the root config; --cwd and --config point
anywhere else. See The config file.
What should I commit?
Commit your locale files, verbatra.lock.json and verbatra.provenance.json; never .env,
.env.local, .verbatra-local/ or verbatra.cache.json, which verbatra init adds to
.gitignore. See The lock file.
How do I re-translate everything?
Delete the locale file and run verbatra translate: every key is then missing and translated
fresh. Deleting the lock file does not do it, because without a baseline existing translations count
as current. For one key, use Studio's retranslate action or retranslateEntry.
Does using the CLI mean installing the SDK?
No extra step: @verbatra/cli depends on @verbatra/sdk, so it comes along. Only
@verbatra/studio and @verbatra/mcp are separate, optional installs.
Where do API keys live?
Only in environment variables, which the CLI also reads from
.env.local and .env. The config rejects unknown keys so a secret
cannot end up in a committed file. See Providers.
Does verbatra send my strings anywhere?
Only to the provider you configure, and only when a command translates; there is no telemetry.
With provider: { id: "none" } nothing leaves the machine. See
Data handling and privacy.
What does verbatra doctor actually check?
The setup, in one pass, without a translation call and without reading a key value unless you
pass --live, which sends it to fetch the provider's language list: the config, the format, the
provider, the API key variable, the network policy, the source file and locale support, plus
informational reports on plurals, locale codes and leftover locale state. verbatra doctor has the
full check table.
Can an AI agent set up or operate verbatra for me?
Yes, through four surfaces: a setup prompt for coding agents
(Set up with an AI agent), the --json output for your own loops
(Recipes for agents and scripts), WebMCP tools in an open Studio tab
(Drive Studio with a browser agent), and a stdio MCP server
(verbatra mcp). Studio and the MCP server spend on a provider only behind an
--allow-spend flag; in the --json loop a real translate spends at once, so your script or
agent must get a human go-ahead first.
Does this site publish anything for AI agents and crawlers?
Yes, three static files, generated at build time and always in English regardless of which locale you are browsing:
/llms.txt: a curated index of every doc page's title and description, grouped the way the sidebar is, as Markdown links./llms-full.txt: the entire documentation in one file, each page's rendered content concatenated in order, for an agent that ingests content directly instead of following links./.well-known/ai.txt: a usage policy telling AI crawlers this project is MIT licensed and that crawling, indexing, and citing this content is welcome.
All three are linked from the footer's "For AI agents" column.
Is this site's content translated by AI?
Mostly, through two different mechanisms. The UI chrome (navigation labels, buttons, the footer, the
landing page copy, the landing FAQ) lives in messages/en.json and its de, es, and fr
siblings; those are machine-translated with verbatra itself, against the next-intl-json format,
through the Gemini provider, by running pnpm i18n after the English source changes. It is this
project dogfooding its own tool, and the docs-i18n-check workflow fails a pull request whose
locale files have drifted from the English source. The documentation prose you are reading right
now, every guide and reference page including this one, is locale-suffixed MDX (page.mdx,
page.de.mdx, page.es.mdx, page.fr.mdx) that is also AI-translated, but outside that automated
pipeline: pnpm i18n only translates the structured locale file formats, never Markdown,
so it never touches these pages. Instead, an AI agent translates a doc page in the same change that
edits its English source, so all four languages land together; that is why every non-English page
carries the machine-translated notice.
Not everything comes out of those two steps unchanged: some texts, including parts of the legal pages, were written or corrected directly in the locale files instead. Translations are checked on a best-effort basis, and not every translated text is reviewed by a person before it is published, so a translation may contain errors. The privacy policy describes the same process.
If something in German, Spanish, or French reads oddly, open an issue either way: for UI copy the fix goes into the English source and is retranslated, or straight into the affected locale file; for doc prose, edit the MDX file directly and send a pull request.
Edit on GitHub