---
title: "FAQ"
description: "Short answers to the questions that come up most when running verbatra, from what a run costs to what you should commit."
type: "reference"
---
# 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](https://verbatra.kreitz-webdev.de/docs/troubleshooting.md) and [Error codes](https://verbatra.kreitz-webdev.de/docs/error-codes.md).

## How do I control cost? [#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](https://verbatra.kreitz-webdev.de/docs/estimating-cost.md).

## What does a run actually 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](https://verbatra.kreitz-webdev.de/docs/estimating-cost.md).

## Which provider should I start with? [#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](https://verbatra.kreitz-webdev.de/docs/data-handling.md#vendor-retention-and-data-processing-terms). Every
provider is compared on [Providers](https://verbatra.kreitz-webdev.de/docs/providers.md).

## Can I run a local model? [#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](https://verbatra.kreitz-webdev.de/docs/providers.md#libretranslate).

## Which languages does verbatra support? [#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](https://verbatra.kreitz-webdev.de/docs/language-support.md).

## How do keys keep their order? [#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](https://verbatra.kreitz-webdev.de/docs/formats.md).

## Why did a translation get flagged for review? [#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](https://verbatra.kreitz-webdev.de/docs/error-codes.md#review-reason-codes).

## Does verbatra work in a monorepo? [#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](https://verbatra.kreitz-webdev.de/docs/config-file.md).

## What should I commit? [#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](https://verbatra.kreitz-webdev.de/docs/the-lock-file.md).

## How do I re-translate everything? [#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? [#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? [#where-do-api-keys-live]

Only in environment variables, which the CLI also reads from
[`.env.local` and `.env`](https://verbatra.kreitz-webdev.de/docs/cli.md#environment-files). The config rejects unknown keys so a secret
cannot end up in a committed file. See [Providers](https://verbatra.kreitz-webdev.de/docs/providers.md).

## Does verbatra send my strings anywhere? [#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](https://verbatra.kreitz-webdev.de/docs/data-handling.md).

## What does verbatra doctor actually check? [#what-does-verbatra-doctor-actually-check]

<AvailableFrom version="0.9.0" />

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`](https://verbatra.kreitz-webdev.de/docs/cli/doctor.md) has the
full check table.

## Can an AI agent set up or operate verbatra for me? [#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](https://verbatra.kreitz-webdev.de/docs/start-with-ai.md)), the `--json` output for your own loops
([Recipes for agents and scripts](https://verbatra.kreitz-webdev.de/docs/agent-recipes.md)), WebMCP tools in an open Studio tab
([Drive Studio with a browser agent](https://verbatra.kreitz-webdev.de/docs/agent-tools-in-studio.md)), and a stdio MCP server
([`verbatra mcp`](https://verbatra.kreitz-webdev.de/docs/cli/mcp.md)). 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? [#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`](https://verbatra.kreitz-webdev.de/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`](https://verbatra.kreitz-webdev.de/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`](https://verbatra.kreitz-webdev.de/.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? [#is-this-sites-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](https://verbatra.kreitz-webdev.de/docs/formats.md), 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](https://verbatra.kreitz-webdev.de/privacy) 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.