AI translation

How Translation Works

AI translation is the only feature that needs network access or credentials — everything else in Glotfile works offline. You can trigger it from the Editor or with glotfile translate; both use the same engine.

What gets sent

For each string that needs translating, Glotfile sends the provider:

  • the source string (or plural forms),
  • the key’s context,
  • the relevant Glossary terms (only those that appear in the string),
  • the target locale,
  • any max length, and
  • for vision-capable models, the key’s screenshot.

Strings are sent in batches (the ai.batchSize setting, default 25).

Project context and per-language rules

Two committed config fields shape the system prompt that frames the whole batch:

  • projectContext — a project-wide description (what the product is, how its key terms should be read, the tone to use), added for every language. This is the most effective way to keep terminology consistent across a product — e.g. telling the model that “sign in” means physically checking in at a building, not logging into an account.
  • localeInstructions — extra rules for one language (register, preferred terminology, grammar conventions), appended on top of the project context for that language’s batch.

Set both in Settings → Translation guidance, or directly in config — see the Configuration Reference. Each field has a Suggest button (also glotfile suggest-guidance) that drafts a starting point from your catalog using the configured AI model — review and edit it before saving. Because they ride in the system prompt rather than per item, they apply uniformly to every string in the run.

Validation on the way back

A translation is only written if it passes validation:

  • Placeholders must match the source — a translation that drops or renames {name}, %s, :id, etc. is rejected. See Placeholders and ICU.
  • ICU plural/select structure must be preserved.
  • Max length, if set, must not be exceeded.

Rejected translations are reported and skipped, not written:

skip checkout.total @ de: placeholder {amount} is missing

What it writes

  • Accepted translations are written as machine state.
  • A reviewed value is never overwritten — your human edits are safe.
  • The source string each translation was made from is recorded, so later source edits can flag the translation as stale.

Vision and model fit

Screenshots are sent only to models that can see them. For models that can’t (e.g. Bedrock Meta Llama text models), the run proceeds text-only and prints how many screenshots were skipped — so any model still works. See AI Providers for the support matrix.

Privacy

⚠ What leaves your machine — AI translation is the only path by which your source strings leave your boundary. No credentials are ever written to glotfile.json or the AI Log. To keep strings in-region, pin a Bedrock region or point an Anthropic/OpenAI endpoint at an in-region gateway — see AI Providers.

Batch mode

Batch mode submits translation jobs through the Anthropic Message Batches API at 50% of normal token cost. Results are asynchronous — typically ready well under an hour, with a 24-hour upper bound. Batch mode is only available when ai.provider is anthropic.

CLI

glotfile translate --batch          # submit and exit immediately
glotfile translate --batch --wait   # submit, then stay attached and apply when done
glotfile batch                      # check status; auto-applies results if finished
glotfile batch apply                # apply finished results now
glotfile batch cancel               # cancel a pending batch

Web UI

When the Anthropic provider is active, the Translate dialog shows a Batch (50% cost) button alongside the normal Translate button. After submission, a banner in the editor tracks progress; when the batch finishes, click Apply results to write the translations.

Pending handle

The in-flight batch state is stored in .glotfile/batch.json — project-local and machine-specific. Only one pending batch per project is tracked at a time. The .glotfile/ directory is self-ignoring (it writes its own .gitignore entry), so batch.json is never committed.

Staleness and error recovery

When results arrive, Glotfile checks each entry against the current state:

  • Translations for keys whose source text changed (or that were deleted) since submission are skipped.
  • Entries that the API marks as failed, or whose content is malformed, are automatically re-run through the normal synchronous translate path during apply.
  • AI Providers · Glossary · Placeholders and ICU · AI Log