# Translations

The Translations editor: create keys, edit values, change statuses, filter, run bulk actions, and use the side panel with MT, TM, glossary, comments and history.

Canonical: https://comvi.io/docs/platform/translations

The Translations page is the editor: rows are keys in the selected namespaces, and each row
has one line per visible language with the value and a status badge. The source language is
one of those lines, so translators always see what they translate from.

## Create a key

1. Click **Add Translation** at the top of the page. The dialog is titled *Create new key*.

2. Name the key. Keys are unique within a namespace, so `nav.home` can exist independently
   in `common` and in `emails`. `checkout.payment.card_number` tells a translator where the
   string lives; `label_42` does not.

3. Pick the namespace. Stay on `default` until you have a reason to split; see
   [Namespaces](/docs/platform/namespaces).

4. Write the source copy in [ICU MessageFormat](https://unicode-org.github.io/icu/userguide/format_parse/messages/).
   Turn on **Plural key** to get a field per plural form instead of one text box.

5. Add a description: where the string appears, what tone it needs, what it refers to.

The key is created with the source value filled and empty values for every target language.

```text
Hello, {name}!
You have {count, plural, one {# message} other {# messages}}.
{gender, select, male {He} female {She} other {They}} updated the profile.
```

Keep source and target placeholders the same. A translation that drops `{name}` renders with
the placeholder missing at runtime, and nothing checks placeholder parity on save.

## Edit a value

Click a value to edit it in place and save with the **Save** button or `Cmd/Ctrl + Enter`.
Moving to another cell, with `Tab` or a click, saves the pending text first. Saving sets the
value to **Needs Review**, whoever saved it and whatever it was before. Moving it to
**Translated** is a separate click on the status badge. See
[Translation lifecycle](/docs/platform/translation-lifecycle).

If the project has a glossary, a terminology check runs while you type and again on save.
Errors appear in a bar under the field, and you can save anyway. Nothing else is validated,
and broken ICU syntax is not rejected.

| Shortcut | Action |
|---|---|
| `Cmd/Ctrl + Enter` | Save and close the editor without moving the table |
| `Escape` | Cancel and discard changes |
| `Tab` / `Shift+Tab` | Save, then next / previous language of the same key |
| `Cmd/Ctrl + ↓` / `Cmd/Ctrl + ↑` | Next / previous key |

## Statuses

| Status | When it is set |
|---|---|
| **Not Translated** | No value yet, or the value was cleared |
| **Needs Review** | A value exists and has not been approved. Every save lands here, including machine translation and translation-memory auto-apply |
| **Translated** | Approved. Imports land here too. Tick only this status under Content Deploy to keep drafts out of production |

Click a badge to change it. Setting **Translated** needs review permission, which Editor and
above have; Translators can only send a value back to **Needs Review**. Only
**Clear Translations** returns a value to **Not Translated**. See
[Roles & permissions](/docs/platform/roles-permissions).

## Filter and search

The filter bar combines **Search** by key name or value text, **Namespace** (one or several),
**Status** (one or several), **Languages** to hide the ones you do not need, and **Sort** by
key name, creation date or last update. Filters compose, and **Clear all** resets them. A
status plus a language subset narrows the table to "keys that still need review in French".

## Bulk actions

Tick row checkboxes and a selection bar appears at the top of the table:

| Action | Effect |
|---|---|
| **Translate** | Send the selected keys through [machine translation](/docs/platform/machine-translation) for the languages you pick |
| **Status** | Mark the selection **Translated** or **Needs Review**. Needs review permission |
| **Copy Translation** | Copy values from one language to another, optionally overwriting |
| **Change Namespace** | Move keys to another namespace. Names must stay unique there |
| **Clear Translations** | Empty the values for the chosen languages and set them to Not Translated |
| **Export Selected** | Export only the selected keys |
| **Delete Keys** | Remove the selected keys and their values |

> **Delete Keys has no undo**
>
> Recreating a key with the same name gives a new, empty key, not the old values. Export the
> selection first if you might need the data back.

## Side panel

The side panel opens when you edit a value and follows it. For target languages it shows
**Machine translation** suggestions you can apply whole or one plural form at a time,
**Translation memory** matches from memories assigned to the project, **Glossary** terms
for the source text that you can insert at the cursor, a **Comments** thread on this
`(key, language)` pair, and **History**. On the source language it shows comments and
history only, and both appear once the value has been saved at least once.

History records the value, the status, reviews, key metadata edits, and machine-translation
or translation-memory auto-applies, with the user or API key behind each one. Entries are
never edited or deleted.

## Limits

- Keys are unique within a namespace. The same name in another namespace is a different key.
- Key count is capped per organization: 500 on the free plan, 3,000 on early adopter, plus
250 for each keys add-on.
- A bulk translate skips language pairs the provider does not support and stops early when
the organization runs out of MT credits; the job result names both.
- No translation-memory matches usually means no memory assigned to the project or no
content in this language pair. Short source strings rarely match.

## Next steps

- [Translation lifecycle](/docs/platform/translation-lifecycle): The status state machine behind every edit.
- [Machine translation](/docs/platform/machine-translation): Bulk-fill drafts and review them in the editor.
- [Translation memory](/docs/platform/translation-memory): Reuse previous translations from the side panel.
- [Glossaries](/docs/platform/glossaries): Preferred terminology surfaced as you edit.