# Translation lifecycle

The three statuses of a translation value, which actions move a value between them, and how deploys read statuses without changing them.

Canonical: https://comvi.io/docs/platform/translation-lifecycle

Every translation value has a **status** that tracks review, not delivery. Whether a value is
live on the CDN is decided separately, by the deploy's status filter.

## Statuses

| Status | Meaning |
|---|---|
| **Not Translated** | No value exists for this `(key, language)` pair, or the value was cleared |
| **Needs Review** | A value exists and has not been approved |
| **Translated** | A value exists and has been approved |

Source-language values are not special. A key created in the dashboard stores its source
copy as **Needs Review**, the same as any target value.

## State machine

<Mermaid
code={`flowchart LR
    Start(("new key"))
    NT["Not Translated"]
    NR["Needs Review"]
    T["Translated"]

    Start --> NT
    NT -->|"any save: editor, API, MT, TM"| NR
    NR -->|"any save"| NR
    T -->|"any save"| NR
    NT -->|"import"| T
    NR -->|"import"| T
    NR -->|"status badge (review permission)"| T
    T -->|"status badge"| NR
    T -->|"cleared"| NT
    NR -->|"cleared"| NT
`}
caption="Saving a value always lands it in Needs Review. Only an import or an explicit status change reaches Translated."
/>

| Action | End status |
|---|---|
| Anyone types a value and saves | Needs Review |
| Batch machine translation | Needs Review |
| Translation memory auto-apply on key creation | Needs Review |
| REST API upsert without a `status` | Needs Review |
| File import or `comvi push` | Translated |
| Status badge, or **Status → Mark as Translated** | Translated |
| Status badge, or **Status → Mark as Needs Review** | Needs Review |
| **Clear Translations** | Not Translated |

## Reaching Needs Review

Every write that carries a value and no status lands in **Needs Review**, whoever makes it.
Role does not change this: a Manager's edit lands in Needs Review, the same as a
Translator's.

## Reaching Translated

Two paths reach **Translated**. A status change, by clicking the badge on a value or
selecting keys and using **Status → Mark as Translated**, needs review permission, which
Editor and above have. An import writes every non-empty value as **Translated**, credited to
the importing user, without review.

> **Import skips review**
>
> A file import, including a `comvi push`, marks everything approved on the way in. If your
> process depends on someone approving each string, review before the import, or select the
> imported rows afterwards and use **Status → Mark as Needs Review**.

## Reaching Not Translated

**Clear Translations** in the selection bar empties the value and resets the status in one
step. Removing a language is different: its values are archived with their statuses intact,
and adding the language back restores them as they were.

## Deploys read statuses, never write them

<Mermaid
code={`flowchart LR
    DB[("Translation values<br/>with statuses")]
    Deploy{"Deploy<br/>(status filter)"}
    Bundle["JSON bundles<br/>per (language, namespace)"]
    CDN["CDN edge"]

    DB --> Deploy
    Deploy -- "filter: Translated" --> Bundle
    Bundle --> CDN
`}
caption="A deploy reads the current values, filters by status, bundles them and uploads. It never writes a status back."
/>

Once **Content Deploy** is enabled, every write schedules a deploy about 5 seconds later, a
continuous stream of writes is flushed at least every minute, and **Deploy Now** on
**Settings → Content Deploy** runs one immediately. **Filter by Status** on the same page
decides what the bundle holds. Tick **Translated** to ship only approved copy: a value can
then sit at **Needs Review** in the editor while the previously approved version stays on
the edge. With every box unchecked, all three statuses ship, and a draft reaches the edge
about 5 seconds after you save it. See [CDN settings](/docs/platform/cdn#cdn-settings).

## Next steps

- [Roles & permissions](/docs/platform/roles-permissions): Who can edit, review and deploy.
- [Content Deploy / CDN](/docs/platform/cdn): How a deploy turns statuses into JSON on the edge.
- [Import & export](/docs/platform/import-export): What an import does to statuses.
- [Translator and reviewer workflow](/docs/platform/recipes/translator-review-workflow): A two-stage flow built on these statuses.