> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textsetu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Translation

> Draft translations automatically with Claude, GPT, Gemini, or DeepSeek using a reusable AI engine.

TextSetu can **translate with AI** — draft translations automatically using
Claude, GPT, Gemini, or DeepSeek, tuned to your brand and terminology. Every AI
translation in your organization routes through a reusable, named configuration
called an **AI engine**, so the machine translates *the way your team already
does*.

***

## What an AI engine is

An **AI engine** is an org-scoped, reusable configuration that defines how AI
translates for you: which providers and models to use, how to sound, the rules to
follow, and which terminology to honor. You set it up once and every AI
translation — the per-key button, the bulk page, the API — runs through it, so the
output stays consistent across projects.

An engine composes each prompt from **five layers**, listed here from lowest to
highest precedence. When two layers disagree, the higher one wins.

| # | Layer                             | What it does                                                                                                                                                                                                                                                                           |
| - | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | **Models**                        | A ranked **fallback chain** per language pair. The next model is tried **only after** the previous one actually fails — models run one at a time, never raced against each other.                                                                                                      |
| 2 | **Brand voice**                   | Your tone, formality, and a short product description — the baseline personality of every translation.                                                                                                                                                                                 |
| 3 | **Instructions**                  | Per-language, discrete, testable rules that **override brand voice** (e.g. "use the informal *tú* in Spanish").                                                                                                                                                                        |
| 4 | **Glossary & Translation Memory** | Terminology and prior translations, **inherited from the project** (or overridden per engine). **Highest precedence — overrides the model's own judgment.** Retrieval-augmented: only the glossary terms that actually appear in the source string are injected, so prompts stay lean. |
| 5 | **Reviewers**                     | An optional automated review pass by a **different** model that scores each translation per dimension and flags low scores.                                                                                                                                                            |

Because the glossary and TM layers sit at the top, AI and human translators see
the same terminology — see [Glossary](/docs/guides/glossary) and
[Translation Memory](/docs/guides/translation-memory).

## Providers, BYOK, and credits

An engine can use **Anthropic (Claude)**, **OpenAI**, **Google (Gemini)**, or
**DeepSeek**. There are two ways to pay:

* **BYOK (bring your own key)** — connect your own provider API key. Usage is
  **free and unmetered** by TextSetu; you're billed by the provider directly.
* **TextSetu platform keys** — use TextSetu's provider access, **metered** against
  a prepaid **credit** balance.

You can mix both across engines. See [Cost control](#cost-control) below.

## How AI translations land

AI writes respect the same [approval workflow](/docs/guides/approval-workflow) as human
edits — **review is a per-run choice, not a hard gate**:

* **Approval on** → AI translations land as **proposals** in the review queue,
  exactly like a translator's edit. An approver can instead choose **apply
  directly** to publish them live.
* **Approval off** → AI translations go **live** immediately.

You can also target a **branch** instead of main — the [branch merge](/docs/guides/branches)
then becomes the review gate. **Protected main branches are respected**:
direct-to-main AI writes are refused just as manual ones are. Every AI-written
value is marked **AI-generated** so you can tell machine drafts from human work.

<Tip>
  On approval-required projects, running AI into a branch (or as proposals) gives
  you a clean review step before anything ships — the AI does the first pass, a
  human signs off.
</Tip>

## Running it

### Per key

In the translations grid, use the **Translate with AI** button on a key to draft
one or more languages for that key. How the result lands (live, proposal, or
branch) follows the project's AI-translation settings.

### In bulk

The **bulk AI** page translates many keys at once. Choose your **target
languages** and narrow the work with filters:

* **Only untranslated** — keys with no value yet in the target language.
* **Only outdated** — values flagged outdated because the source changed.
* **By tag** — restrict to keys carrying a tag.
* **By key prefix** — restrict to a scope of the key tree.

Candidates are filtered **in SQL before any model is called**, and requests are
**batched**, so you only pay for the strings that actually need translating. Bulk
runs are **asynchronous** — kick one off and track its progress while it works.

## Cost control

Cost is the binding constraint, so TextSetu is conservative by default:

* **BYOK is free and unmetered.**
* **Platform runs are pre-flighted** against your credit balance — a run you can't
  afford is **refused up front**, never stopped mid-run partway through.
* **Prices are versioned**, so historical usage stays explicable after a price
  change.

Combined with the pre-model candidate filtering above, you only ever spend on
strings that need translating.

## Reports

TextSetu reports both **usage** and **quality** for AI translation — translations,
spend, review scores, and response rate — broken down by **provider**, **model**,
**language**, and **engine**, so you can see what each configuration costs and how
well it performs.

***

## API & MCP

Everything above is automatable. The [REST API](/api/introduction) exposes AI translation under
`/api/v1`:

* `GET /projects/{projectId}/ai/engine` — the resolved engine for a project and
  whether AI translation is available.
* `POST /projects/{projectId}/ai/translations` — start an async run (returns a
  `jobId`); supports the same filters, a `?branch=` target, and the approval
  behavior described above.
* `GET /projects/{projectId}/ai/translations/{jobId}` — poll a run's status plus
  translated / skipped / failed counts.

For AI agents, the [MCP server](/api/mcp) exposes the same capability as tools:
`ai_engine_info`, `ai_translate`, and `ai_translate_status`.

***

Related: [Translating](/docs/guides/translating) · [Approval Workflow](/docs/guides/approval-workflow) · [Branches](/docs/guides/branches) · [Glossary](/docs/guides/glossary) · [Translation Memory](/docs/guides/translation-memory)