# AI context

Steer AI machine translation with free-form guidance at the project, language and key level: what each level is for, limits, precedence and the draft generator.

Canonical: https://comvi.io/docs/platform/ai-context

AI context is guidance you write for AI machine translation, injected into the prompt. Only
the AI providers (OpenAI, Anthropic Claude) read it; traditional MT providers do not accept
instructions. See the [provider matrix](/docs/platform/machine-translation#provider-matrix).

## Levels

| Level | Where to edit | Limit | Use it for |
|---|---|---|---|
| **Project** | **Settings → General**, **AI translation context (sent to MT)** | 8,000 chars | Brand voice, audience, tone, product terminology: everything true for every string |
| **Language** | **Languages**, the target language's dialog | 2,000 chars | Formality register (du/Sie, tu/vous), regional conventions, script preferences |
| **Key** | The key editor, next to the description and character limit | 2,000 chars | Where the string appears, what a placeholder refers to, gender and number constraints |

Every level is optional. Changes apply to the next machine-translation request; existing
translations are not re-translated.

## Precedence

```text
key context  >  language context  >  project context
```

More specific wins. The system prompt tells the model that project and language guidelines
are defaults and per-key context takes priority.

## What to write

`Project context`

```text
Product: Comvi, a translation management system for developers.
Audience: professional software developers; technically fluent.
Tone: concise, direct, friendly but not playful. No exclamation marks.
Never translate: product names (Comvi, Comvi i18n), code identifiers,
CLI command names.
```

`Language context (de)`

```text
German: use informal "du" throughout. Compound nouns are fine, but
prefer shorter synonyms in buttons and labels.
```

`Key context`

```text
Button label on the checkout page. "Order" is a verb here, not a noun.
```

Write the project context as the briefing you would give a new human translator, the
language context as only what differs for that language, and the key context as only what
the model cannot know from the string. Do not repeat yourself across levels or duplicate
what other features handle: [glossary terms](/docs/platform/glossaries) are injected
automatically and translation memory supplies prior human translations.

## Description and key context

A key has both **Internal notes (not sent to MT)** (the **Description** field in the *Create
new key* dialog) and **AI translation context (sent to MT)**. Notes are for your team and
never reach the model; the AI context is sent with every AI translation of that key. Put
translation hints in the AI context field.

## Collected UI context

The [in-context editor plugin](/docs/i18n/plugins/in-context-editor) reports where each key
is rendered in your running app, and Comvi keeps a sanitized profile: the key's UI role, a
length hint, and the text of nearby elements. Rendered values are never stored, only
references to other keys in the catalog. The profile is sent with each AI translation of the
key in a `## UI context (collected)` block, and the key's context panel in the editor shows
the same thing the model sees. Comvi keeps the five most recent observations per key per
screen group; nothing needs configuring.

## Cost of a long project context

Project and language context sit in the prompt's system message, which is identical for
every key in one run, and key context is sent per key. Both AI providers cache that stable
prefix, but only Anthropic's usage reporting excludes cache reads, so only there does a long
project context stop costing full price on every key. On OpenAI the reported prompt tokens
include the cached ones, and Comvi meters what the provider reports.

> **Budget before writing 8,000 characters on an OpenAI project**
>
> Every key in a bulk run pays for the whole project context there. Keep it tight, or pick
> Anthropic for the project.

## Generate a draft project context

Click **Generate description** next to the project AI context box on **Settings → General**.
Comvi samples the project's key names and source texts and asks an AI model for a draft
covering domain, audience, tone and terminology.

- The project needs at least 30 keys; below that the button is disabled.
- The draft is not saved for you. Review it, edit it, and save the field.
- Limited to 5 generations per hour per project.
- Needs project edit permission and is a dashboard action only; API keys cannot call it.