# AI translation (https://transglot.ai/docs/concepts/ai-translation/)
**Glossa** is the transglot translation engine. It drafts the translations your team then reviews. Every draft is recorded in a translation's history with the model that wrote it, for example **Glossa Flux draft**.
## Two models [#two-models]
| Model | Used for |
| --- | --- |
| **Glossa Flux** | The default. Fast drafts for every target language. |
| **Glossa Deep** | The higher-quality model. A project uses it for every target language when you turn on **Quality mode** under the project's **AI translation** settings. Available on Team and above. |
## When translation runs [#when-translation-runs]
- **Automatically.** While the project's **Auto-translate** setting is on (it is by default), new and changed source strings are translated as they arrive from a push, an upload or a connector, and existing strings are translated into a language you add.
- **On demand.** **Translate missing** in the editor fills a language's gaps, or only the rows you selected. See [Translate with AI](https://transglot.ai/docs/guides/translating/translate-with-ai).
- **From the CLI.** `transglot init` asks before the first run, and `transglot push --wait` waits for the translation of what you pushed. See the [Quickstart](https://transglot.ai/docs/quickstart).
Each run is a **batch**: you can follow its progress, and cancel it, while it runs.
## What Glossa reads [#what-glossa-reads]
The context you give a project is what makes its translations specific rather than generic:
- **The project description**, the line you wrote under **What is it?** when you created the project.
- **Each key's description**, and its maximum length. See [Keys and strings](https://transglot.ai/docs/concepts/keys-and-strings).
- **Your glossary** (Starter and above), so required and forbidden terms are respected. See [Glossary and brand voice](https://transglot.ai/docs/concepts/glossary-and-brand-voice).
- **Your brand voice**, the tone, formality and rules you set on the project's **Voice** page.
- **Similar approved translations**, when semantic translation memory is turned on (Team and above), so new text is phrased consistently with what you already approved. See [Translation memory](https://transglot.ai/docs/concepts/translation-memory).
- **Screenshots**, when **Screenshot context** is turned on (Team and above), so Glossa can see where a string appears. Screenshots add image cost to the runs that use them.
When the exact same source text has been translated before, transglot reuses that translation at no cost instead of translating it again.
## What Glossa keeps intact [#what-glossa-keeps-intact]
Placeholders such as `{name}`, `{{count}}`, `%s` or `:name` and HTML tags are carried into every translation unchanged. A plural key gets one form for each plural category the target language uses, not only the forms the source has. A draft that still breaks either after a retry is not written, so the string stays untranslated rather than broken. See [Quality checks](https://transglot.ai/docs/concepts/quality-checks).
## What Glossa never does [#what-glossa-never-does]
A translation you have edited or reviewed is never overwritten by AI. Glossa only writes into strings that are empty or still a Glossa draft.
## When a person takes over [#when-a-person-takes-over]
Each AI translation carries a confidence signal. Translations that pass the automatic checks and come back confident can be marked as not needing review, so your reviewers only see the ones worth their time. Everything else is flagged for review. Automatic checks always win: a translation with a broken placeholder, the wrong plural forms, or a glossary conflict is always sent to review no matter how confident it was.
That routing is off by default; see [Translation states](https://transglot.ai/docs/concepts/translation-states) for the setting and the states a translation moves through.
## Related [#related]
- [AI translation settings](https://transglot.ai/docs/guides/translating/ai-translation-settings)
- [The assistant](https://transglot.ai/docs/guides/translating/the-assistant)
- [Words and usage](https://transglot.ai/docs/concepts/words-and-usage)
# Glossary and brand voice (https://transglot.ai/docs/concepts/glossary-and-brand-voice/)
A glossary fixes **what words** a translation uses. Brand voice sets **how it sounds**. Both are set per project, and Glossa reads both on every translation.
## The glossary [#the-glossary]
Each project has a **Glossary**, available on Starter and above. A term is a word or phrase from your source text, with the wording each target language must use. A term can also be marked:
| Option | Meaning |
| --- | --- |
| **Do not translate** | Keep the term exactly as it is in the source, such as a product name. |
| **Forbidden** | A word that must never appear in the translation. |
| **Case-sensitive** | Match the term only with the same capitalisation. |
A term can also carry a **Notes** field for translators and the kind of word it is, such as a noun.
Glossary terms are matched against source text and enforced during translation and during quality checks; a translation that departs from a glossary term is flagged. In the editor, the context panel lists the glossary terms a string contains, and the **Has glossary issue** filter finds translations that break one.
How strictly a departure is treated is the **Glossary enforcement** setting on the project's **Checks** page: **Off**, **Warn** or **Enforce**.
You can add terms one at a time with **Add term**, import them from a CSV or TBX file with **Import CSV or TBX**, and **Export** them. On Team and above, **Extract terms** proposes candidate terms from your source strings; candidates are not enforced until you approve them. Developers, admins and account Owners can manage the glossary.
## Brand voice [#brand-voice]
The project's **Voice** settings page describes how your product sounds in every language:
- **How you sound**: formality, warmth, a description of your brand voice, and regional notes.
- **Lines you never cross**: rules a translation must always or never follow.
- **Per-language adjustments**, so German can be formal while Spanish is not.
On Team and above you can also give Glossa example pairs of a source string and the translation you want, let it propose a voice from the translations your team has already approved (a draft you edit and save; nothing applies until you save), and choose whether the glossary, the style guide and semantic translation memory are used for the project.
Admins of the workspace and Owners of its account can change the Voice page.
## Related [#related]
- [The glossary](https://transglot.ai/docs/guides/quality/the-glossary)
- [Add a glossary term](https://transglot.ai/docs/guides/quality/add-a-glossary-term)
- [Review extracted glossary terms](https://transglot.ai/docs/guides/quality/review-extracted-glossary-terms)
- [Brand voice](https://transglot.ai/docs/guides/quality/brand-voice)
# Core concepts (https://transglot.ai/docs/concepts/)
Read these once and the rest of the docs will make sense. Each page explains one idea and links to the guides that put it to work.
## How your work is organised [#how-your-work-is-organised]
## How translation works [#how-translation-works]
## How quality is kept [#how-quality-is-kept]
## How usage is measured [#how-usage-is-measured]
For the vocabulary in one place, see the [Glossary of terms](https://transglot.ai/docs/resources/glossary).
# Keys and strings (https://transglot.ai/docs/concepts/keys-and-strings/)
## Keys [#keys]
A **key** is the name your code asks for, such as `checkout.title`. Each key holds one **source string** in the project's source language and one translation per target language. Keys and their source strings arrive from a push, an upload, or a connected repository or content platform. Source text is read-only in the console: to change it, change your source file and push or upload it again. **New key** in the editor adds a key and its details.
| Field | What it is for |
| --- | --- |
| **Key name** | The identifier your code uses. Nested keys from JSON or YAML files are stored with dotted names, such as `cart.items`. |
| **Description (context for translators & AI)** | What the string is and where it appears. Glossa and your translators both read it, so "Headline shown on the checkout page" gets a better translation than nothing. |
| **Plural key** | Marks the key as plural, so it holds one form per plural category instead of a single string. |
| **Max length (optional)** | The longest a translation may be, in characters. Glossa aims to stay within it, and the [quality checks](https://transglot.ai/docs/concepts/quality-checks) report a translation that goes over. |
| **Tags** | Labels for grouping keys, such as the release or feature they belong to. The editor can filter by tag. |
A key can also carry screenshots, which show reviewers where the string appears, and comments, where your team discusses it. See [The screenshot library](https://transglot.ai/docs/guides/quality/the-screenshot-library) and [Comment on a string](https://transglot.ai/docs/guides/translating/comment-on-a-string).
From the CLI, a key metadata file can set descriptions and maximum lengths for formats that have nowhere to keep them. See [Configuration](https://transglot.ai/docs/developers/cli/configuration).
## Plural forms [#plural-forms]
Languages differ in how many plural forms they have. English has `one` and `other`; Polish has `one`, `few`, `many` and `other`; Arabic has six. A plural key stores one form per CLDR plural category of each language, so a translation into Polish has four forms even when the English source has two. Glossa writes every form the target language needs, and a translation missing a form is flagged. See [Plural forms](https://transglot.ai/docs/guides/projects/plural-forms).
## Placeholders [#placeholders]
A **placeholder** is a part of a string your code fills in at runtime. transglot recognises these syntaxes and keeps them intact in every translation:
| Syntax | Example |
| --- | --- |
| Double braces (i18next, Vue, Handlebars) | `{{count}}` |
| Single braces (ICU, .NET, Python) | `{name}` |
| printf | `%s`, `%d`, `%1$s` |
| Laravel | `:name` |
| HTML tags | ``, `` |
The editor highlights placeholders in the source and the translation. A translation that loses, adds or changes a placeholder is flagged, because shipping it would break the string at runtime.
The project's **Message syntax** setting, under **Checks**, decides how strictly strings are read as ICU MessageFormat: **Auto** reads a string as ICU only when it holds a plural, select, ordinal, number, date or time; **ICU** reads every string as ICU; **Legacy** never does.
## When source strings change or disappear [#when-source-strings-change-or-disappear]
When a source string changes, its existing translations are marked **stale** until someone reads them again. While the project's **Auto-translate** setting is on, Glossa drafts new translations for the changed string. A translation you have edited or reviewed is never overwritten by AI: it stays as it is, marked stale, for a person to update.
A push adds and updates keys but does not delete keys that are missing from the pushed file, unless you ask it to with `transglot push --sync-removals`. You can also delete keys in the editor.
## Related [#related]
- [Add or edit a key](https://transglot.ai/docs/guides/projects/add-or-edit-a-key)
- [Translation states](https://transglot.ai/docs/concepts/translation-states)
- [File formats](https://transglot.ai/docs/developers/formats)
# Languages and locales (https://transglot.ai/docs/concepts/languages-and-locales/)
## Source and target languages [#source-and-target-languages]
**The source language** is the language your strings are written in. You pick it when you create the project. Everything in the project is translated from it, it is the one language you never translate into, and it cannot be removed.
**Target languages** are the languages you ship. Each one is tracked on its own: its own coverage, its own review work and its own published output. You can add and remove target languages at any time from the project's **Languages** settings, under **Add a language**. Adding and removing languages needs a developer, an admin or an Owner of the account.
When you add a language to a project that already has strings, transglot fills it straight away: strings already in translation memory are reused, and the rest are translated by Glossa while the project's **Auto-translate** setting is on. Removing a language deletes every translation in it; your keys and source strings are untouched.
## Language tags [#language-tags]
Languages are named with BCP-47 tags, the standard your framework already uses:
| Tag | Language |
| --- | --- |
| `de` | German |
| `pt-BR` | Portuguese (Brazil) |
| `fr-CA` | French (Canada) |
| `zh-Hans` | Chinese (Simplified) |
| `sr-Latn` | Serbian (Latin script) |
transglot normalises what you type, so differences of case or separator (`pt-br`, `pt_BR`) do not create duplicates. It refuses a tag it does not recognise rather than creating a language that would never match your files: **"Unknown locale: use a BCP-47 tag like de, pt-BR, or zh-Hans."**
Plural rules come from the language too. Each language has its own set of plural categories, such as `one` and `other` for English or `one`, `few`, `many` and `other` for Polish, and a plural key holds one form per category. See [Keys and strings](https://transglot.ai/docs/concepts/keys-and-strings).
## How many languages you can use [#how-many-languages-you-can-use]
Free accounts can use a limited number of distinct languages across all their projects, counting source languages; paid plans have no language limit. When an account is at its limit you can still add a language it already uses in another project. See [pricing](https://transglot.ai/pricing).
## Translated is not the same as shipped [#translated-is-not-the-same-as-shipped]
Whether a language reaches your app is a separate question from whether it exists in the project. A language reaches your app when you pull it into your build, merge the pull request a connected repository opens, or publish it to the CDN. See [Publish a locale](https://transglot.ai/docs/guides/delivery/publish-a-locale).
## Related [#related]
- [Add a target language](https://transglot.ai/docs/guides/projects/add-a-target-language)
- [Remove a language](https://transglot.ai/docs/guides/projects/remove-a-language)
- [Plural forms](https://transglot.ai/docs/guides/projects/plural-forms)
# Quality checks (https://transglot.ai/docs/concepts/quality-checks/)
transglot checks translations in two layers: automatic checks for problems that would break your product, which run on every plan, and an AI review that scores each translation and lists specific findings, on Team and above.
## Automatic checks [#automatic-checks]
These look for problems that can be detected with certainty, and they run without spending any of your usage:
| Check | What it catches |
| --- | --- |
| **Placeholders** | A placeholder such as `{name}`, `%s` or an HTML tag that is missing, added or changed. |
| **Plural forms** | A plural key missing one of the forms the target language needs. |
| **Length** | A translation longer than the key's maximum length. With screenshots, a translation likely to overflow the space it renders in. |
| **Glossary** | A translation that departs from a glossary term, uses a forbidden word, or translates a term marked **Do not translate**. |
Glossa's drafts go through these checks as they are written. A draft that still breaks a placeholder, a plural form or a forbidden glossary term after a retry is not written: the string stays untranslated and the run reports it, rather than shipping a broken string. A draft that only breaks a softer rule, such as the maximum length, is written as a draft; with **Route AI translations by confidence** turned on, it is flagged for review. See [Translation states](https://transglot.ai/docs/concepts/translation-states).
How placeholders and plurals are read depends on the project's **Message syntax** setting, and how strictly glossary departures are treated depends on **Glossary enforcement**. Both are on the project's **Checks** page.
## AI review and the quality score [#ai-review-and-the-quality-score]
On Team and above, **Run QA** in the editor, or **Re-run checks** on the project's **Quality** page, has Glossa review the translations against their source.
The quality score is a 0-100 rating that transglot produces for a translation, alongside a list of specific findings, each with a severity. The scorecard groups those findings using the industry-standard MQM categories so they can be compared with other tools' reports.
Findings are either **blocking** or **warning**. A translation with a blocking finding, or a low score, is marked **needs checking**. A run is incremental: it scores what has changed since the last run, so running it again over an unchanged project does no new work. Reviewing translations counts towards your usage; see [Words and usage](https://transglot.ai/docs/concepts/words-and-usage).
The **Quality** page shows every language's score and its findings, and the **Scorecard** shows the per-language MQM scores you can print or export. See [The per-language scorecard](https://transglot.ai/docs/guides/quality/the-per-language-scorecard).
## Self-heal [#self-heal]
On Team and above, **Self-heal** retranslates machine translations that fail review. The project's **Auto-heal mode** decides whether a fix is offered as a suggestion for a reviewer to accept (**Suggest**) or written in directly (**Apply**). **Source drift repair** does the same when a source string changes, re-checking its translations and repairing the ones the edit broke. Neither ever overwrites a translation a person has edited or reviewed. See [Self-heal a translation](https://transglot.ai/docs/guides/quality/self-heal-a-translation).
## Related [#related]
- [Run a quality check](https://transglot.ai/docs/guides/quality/run-a-quality-check)
- [What does the quality score mean?](https://transglot.ai/docs/guides/quality/what-does-the-quality-score-mean)
- [Why was my translation flagged for review?](https://transglot.ai/docs/guides/translating/why-was-my-translation-flagged-for-review)
# Translation memory (https://transglot.ai/docs/concepts/translation-memory/)
Translation memory works in two ways, and the difference matters.
## Exact matches [#exact-matches]
When the exact same source text has been translated before, transglot reuses that translation at no cost instead of translating it again. This happens automatically during every translation run, and adding a language can fill strings from memory straight away.
Exact-match reuse draws on an anonymised, shared pool as well as your own workspace's history. You can turn that off per project with the **Translation memory** setting under the project's **AI translation** settings. With it off, the project neither reads from nor adds to the pool, and every string is translated fresh.
Reused words show up as **Words reused at $0** on [your dashboard](https://transglot.ai/docs/first-steps/your-dashboard), and the project's **AI translation** settings show how many words the project reused this month.
## Similar matches [#similar-matches]
transglot also finds previously reviewed translations of similar text and offers them as suggestions. A similar match is only ever a suggestion; it is never written to your project automatically.
In the editor, similar matches appear in the context panel under **Similar approved translations**, where a translator can insert one with a keyboard shortcut. The same matches also guide Glossa, so a new translation comes out phrased consistently with the ones you already approved.
Similar matches come from **Semantic translation memory**, a project setting that is off by default and available on Team and above. Two further settings tune it:
| Setting | What it does |
| --- | --- |
| **Minimum match** | How close a match must be before it is shown, or **Exact only**. A legal project may want nothing under 95%; a marketing one may be glad of 75%. |
| **Match sources** | Where matches may come from: **All projects here** (every project in the workspace) or **This project only**, when one project's reviewed work should not surface in another client's. |
Similar matches only ever come from your own workspace's reviewed translations.
## Searching past translations [#searching-past-translations]
The editor's context panel also lets you search past translations by phrase, to check how a term was translated before.
## Who can change these settings [#who-can-change-these-settings]
Admins of the workspace and Owners of its account, on the project's **AI translation** settings page. See [AI translation settings](https://transglot.ai/docs/guides/translating/ai-translation-settings).
## Related [#related]
- [The editor](https://transglot.ai/docs/guides/translating/the-editor)
- [AI translation](https://transglot.ai/docs/concepts/ai-translation)
- [What counts towards my usage?](https://transglot.ai/docs/administration/billing/what-counts-towards-my-usage)
# Translation states (https://transglot.ai/docs/concepts/translation-states/)
Every translation in the editor shows its state as a chip. The state tells you who last stood behind the text: Glossa, a person, or a reviewer.
## The states [#the-states]
| State | Meaning |
| --- | --- |
| **not translated** | The key has no translation in this language yet. |
| **draft** | Glossa wrote it and nobody has read it yet. The editor describes it as "A GLOSSA draft. Nobody has read it." |
| **edited** | A person wrote or changed the text, by hand, by importing it, or by pushing it from a file. |
| **approved** | A reviewer signed it off. |
| **needs checking** | Someone flagged it, or an automatic check found a problem. The editor describes it as "Flagged for someone to check." |
A separate **stale** chip can appear next to any state. It means the source string changed after the translation was written, so it should be read again before anyone approves it.
## What moves a translation [#what-moves-a-translation]
- **AI translation** writes a **draft**. It only ever fills strings that are empty or still a Glossa draft: a translation you have edited or reviewed is never overwritten by AI.
- **Saving a change** in the editor makes the translation **edited**.
- **Approve** makes it **approved** and clears any flag. You cannot approve a translation with no text, or one you wrote yourself: "You wrote this one, so someone else has to approve it. Flag it to send it back."
- **Flag for a check** marks it **needs checking**. Flagging an approved translation also withdraws the approval, so it drops back to **edited**. Flagging a draft leaves it a draft.
- **A quality check** that finds a blocking problem or gives a low score marks it **needs checking**. Quality checks run on Team and above. See [Quality checks](https://transglot.ai/docs/concepts/quality-checks).
- **A source change** marks it **stale**. A draft is translated again while **Auto-translate** is on; an edited or approved translation keeps its text and waits for a person.
Approving is a reviewer's job: the Reviewer and Admin roles and the account's Owners can approve. Translators can write and edit translations but not approve them. See [Roles and what each one can do](https://transglot.ai/docs/administration/team/roles-and-what-each-one-can-do).
## Flagging AI translations for review [#flagging-ai-translations-for-review]
Each AI translation carries a confidence signal. Translations that pass the automatic checks and come back confident can be marked as not needing review, so your reviewers only see the ones worth their time. Everything else is flagged for review. Automatic checks always win: a translation with a broken placeholder, the wrong plural forms, or a glossary conflict is always sent to review no matter how confident it was.
This is the **Route AI translations by confidence** setting on the project's **Checks** page. It is available on Team and above and off by default; with it off, Glossa's translations land as **draft** and are not flagged.
## Using states downstream [#using-states-downstream]
- In the editor, filter by **State** (**GLOSSA drafts**, **Edited**, **Approved**), or by **Waiting for approval** and **Needs checking**. See [Filter the editor](https://transglot.ai/docs/guides/translating/filter-the-editor).
- When you pull files with the CLI, `min_state` in `transglot.json` can limit a file to `human_edited` (edited or approved) or `reviewed` (approved only) translations. See [Configuration](https://transglot.ai/docs/developers/cli/configuration).
## Related [#related]
- [Approve or flag a translation](https://transglot.ai/docs/guides/translating/approve-or-flag-a-translation)
- [Why was my translation flagged for review?](https://transglot.ai/docs/guides/translating/why-was-my-translation-flagged-for-review)
- [Version history](https://transglot.ai/docs/guides/translating/version-history)
# Words and usage (https://transglot.ai/docs/concepts/words-and-usage/)
Your plan includes an allowance of AI translation each month. Usage is measured against that allowance, and what happens when you exceed it depends on whether usage-based billing is turned on for your account.
## How words are counted [#how-words-are-counted]
Usage is counted in source words, once for each target language a string is translated into. One hundred source words translated into five languages is five hundred words of usage.
Counting is script-aware: a language written without spaces, such as Japanese or Chinese, is measured on a basis that fits its script rather than by counting spaces.
## What counts [#what-counts]
Every word handed to Glossa counts, whatever it was sent for:
- **Translation**, whether automatic, from the editor or from the CLI.
- **AI review** of translations in a quality check.
- **Repairs**, when self-heal or source drift repair translates a failing string again.
- **Brand voice drafts**, when Glossa proposes a voice from your approved translations.
## What does not count [#what-does-not-count]
- **Reused translations.** When the exact same source text has been translated before, transglot reuses that translation at no cost instead of translating it again. Your dashboard shows these as **Words reused at $0**.
- **Anything your team writes by hand**, imports or pushes from a file.
- **Reading, filtering and approving**, and the automatic checks.
- **The scorecard**, which is built from findings a quality check already produced.
Three settings move usage the most: **Auto-translate** translates new strings as they arrive, adding a language translates every key into it, and turning **Translation memory** off stops free reuse.
## Allowances belong to the account [#allowances-belong-to-the-account]
The words are the account's, shared by every workspace in it. The account's **Usage** page shows the words used this cycle against what the plan includes, and which workspaces used them. Only people with access to a whole workspace see its usage on the dashboard.
On the Free plan, the allowance is a hard limit: when it runs out, translation stops until the next cycle or until you upgrade. New Free accounts also receive a one-time grant of welcome words; see [Create your account](https://transglot.ai/docs/first-steps/create-your-account).
On paid plans, the account's Owners and billing members can turn on **Usage-based overage** on the **Usage** page. With it off, translation stops in every workspace of the account when the allowance runs out. With it on, translation continues and words above the allowance are charged at the overage rate, up to the **Spend cap a cycle, in USD** you set; at the cap, translation pauses.
For current allowances and rates, see [pricing](https://transglot.ai/pricing).
## Related [#related]
- [What counts towards my usage?](https://transglot.ai/docs/administration/billing/what-counts-towards-my-usage)
- [Usage-based billing](https://transglot.ai/docs/administration/billing/usage-based-billing)
- [Your plan and seats](https://transglot.ai/docs/administration/billing/your-plan-and-seats)
# Workspaces and projects (https://transglot.ai/docs/concepts/workspaces-and-projects/)
transglot organises everything in three levels.
| Level | What it is | What it holds |
| --- | --- | --- |
| **Account** | Who pays. | The plan, billing and invoices, the usage allowance, and one or more workspaces. |
| **Workspace** | One company or one product estate. | Your team and their roles, projects, integrations, security settings and the audit log. |
| **Project** | One product or codebase to translate. | Keys and source strings, the source language and target languages, translations, the glossary and brand voice, and the project's tokens and keys for delivery. |
Your **login** is separate from all three: one login can belong to several workspaces, with a different role in each.
## Accounts [#accounts]
Every workspace belongs to an account, and the account's plan applies to every workspace in it. An account has two kinds of people:
- **Owners** manage the account and hold every permission in every workspace of it. Some things only an Owner can do, such as setting up single sign-on, requiring two-factor authentication, custom branding and deleting a workspace.
- **Billing members** manage the plan, payment and invoices.
The account's settings show its **Usage**, its **Owners & billing members**, its **Workspaces** and an **Account log** of what changed. See [Your plan and seats](https://transglot.ai/docs/administration/billing/your-plan-and-seats).
## Workspaces [#workspaces]
A workspace is where your team works. Each member has one of four built-in roles:
| Role | What it is for |
| --- | --- |
| **Admin** | Runs the workspace: members, projects, access and approvals. |
| **Developer** | Ships the integration: keys, languages, glossary and AI translation. |
| **Reviewer** | Writes and approves translations, and reviews assigned work. Cannot add keys or run AI translation. |
| **Translator** | Writes translations. Cannot approve their own work. |
A member can be given access to one project instead of the whole workspace, and reviewers and translators can be limited to some languages. Workspaces can also define custom roles. See [Roles and what each one can do](https://transglot.ai/docs/administration/team/roles-and-what-each-one-can-do) and [Grant access to one project](https://transglot.ai/docs/administration/team/grant-access-to-one-project).
## Projects [#projects]
A project is one set of keys translated into a set of languages: typically one app, one website or one codebase. Each project has its own source language, its own target languages, its own settings for AI translation, checks and voice, and its own deploy tokens, publishable keys and CDN delivery. See [Your project](https://transglot.ai/docs/guides/projects/your-project).
Use separate projects when the strings ship separately or need different languages, voice or reviewers. Keep strings that ship together in one project, so they share a glossary and are released together.
## Limits by plan [#limits-by-plan]
How many workspaces, projects, languages and seats an account has depends on its plan. Free includes one workspace and one project; paid plans have no workspace or project limit. See [pricing](https://transglot.ai/pricing) for the current figures.
## Related [#related]
- [Create a workspace](https://transglot.ai/docs/first-steps/create-a-workspace)
- [Create your first project](https://transglot.ai/docs/first-steps/create-your-first-project)
- [Members and roles](https://transglot.ai/docs/administration/team/members-and-roles)
# Accept an invitation (https://transglot.ai/docs/first-steps/accept-an-invitation/)
The link in the invitation email is the only way in: there is nowhere to look an invitation up. The invitation names one email address, and only a login with that address can accept it.
### Open the link in the invitation email [#open-the-link-in-the-invitation-email]
The page shows **Join** followed by the workspace name, and the role you were invited as.
### Sign in or sign up with the invited address [#sign-in-or-sign-up-with-the-invited-address]
If you are not signed in, the page offers **Sign in** or **sign up** with the invited address, and brings you straight back to the invitation afterwards. A new login confirms its email address first; open the confirmation link and you land back on the invitation, ready to accept.
### Select Accept invitation [#select-accept-invitation]
You join the workspace with the role the invitation named, and it appears on your dashboard. The people who manage the workspace are notified that you joined.
If the invitation was limited to one project, or to some languages, that is all you see in the workspace. See [Roles and what each one can do](https://transglot.ai/docs/administration/team/roles-and-what-each-one-can-do).
## If it doesn't work [#if-it-doesnt-work]
- **"This invitation has expired. Ask for a new one."**: invitations last seven days. Ask whoever invited you to send another.
- **"You are signed in as ... Only that address can accept it."**: you are signed in with a different address. Select **Sign out and use** the invited address.
- **The page asks you to confirm your email address.** Open the confirmation link transglot sent when you signed up, or select **Send the confirmation email again**.
- **The link does not open at all.** The invitation may have been withdrawn. Ask whoever invited you.
## Related [#related]
- [Create your account](https://transglot.ai/docs/first-steps/create-your-account)
- [Your dashboard](https://transglot.ai/docs/first-steps/your-dashboard)
- [Invite a teammate](https://transglot.ai/docs/administration/team/invite-a-teammate)
# Create a workspace (https://transglot.ai/docs/first-steps/create-a-workspace/)
A workspace holds your projects, your glossary and your team. Every workspace belongs to an account, which holds the plan and pays for it; every workspace in an account shares that plan. You can create a workspace in any account you are an Owner of, or in a new account, which makes you its Owner. See [Workspaces and projects](https://transglot.ai/docs/concepts/workspaces-and-projects).
Do not create your own. Open the private link in the invitation email instead; a workspace you create yourself has nobody else in it. See [Accept an invitation](https://transglot.ai/docs/first-steps/accept-an-invitation).
## Create the workspace [#create-the-workspace]
### Start the wizard [#start-the-wizard]
On your dashboard, select **New workspace**.
### Workspace [#workspace]
Under **Which account it belongs to**, check the account. If you can choose between several, each row names the account and its plan. Enter the **Workspace name**; the workspace address shown below it is a preview. Select **Continue**.
### Project [#project]
Every workspace starts with one project. Enter the **Project name** and, under **What is it?**, a line about the product, such as "Checkout flow for an e-commerce app". Glossa reads that line as context for every translation in the project.
### Markets [#markets]
Pick the **Source language** your strings are written in and the **Target languages** you want to ship. You can add more languages later.
### Team [#team]
Optionally invite people under **Invitations**, each with an **Email**, an **Invite role** and, for reviewers, the **Languages** they work on. Invitations go out when you finish. You can also skip this step and invite people later.
### Strings [#strings]
Choose how your strings will arrive: a file, a migration from another tool, or a repository. Then select **Create workspace**.
The workspace and its first project are created together and the invitations go out. You land on the new project's **Get started** page, which asks for your strings in the way you chose. See [Setup steps](https://transglot.ai/docs/first-steps/the-activation-checklist).
## How many workspaces an account holds [#how-many-workspaces-an-account-holds]
The plan decides it. Free includes one workspace; paid plans have no workspace limit. A workspace that is scheduled for deletion still counts until it is gone. See [pricing](https://transglot.ai/pricing).
## If it doesn't work [#if-it-doesnt-work]
- **The name is taken.** An account cannot hold two workspaces with the same name. The wizard says so beside the name and offers **Open that one**.
- **The account is full.** The wizard explains, for example "Acme is on Free, which includes 1 workspace, and already has Acme Web." If you can change the account's plan, it offers **Upgrade the account**.
- **"You are not an Owner of that account, so it cannot hold a new workspace. Pick another account."** The account you picked is not one you own, for example because you were removed as an Owner in another tab.
- **Languages or invitations were removed.** If the account's plan has room for fewer languages or seats than you picked, the wizard removes the extra ones and says how many.
## Related [#related]
- [Create your first project](https://transglot.ai/docs/first-steps/create-your-first-project)
- [Invite a teammate](https://transglot.ai/docs/administration/team/invite-a-teammate)
- [Roles and what each one can do](https://transglot.ai/docs/administration/team/roles-and-what-each-one-can-do)
# Create your account (https://transglot.ai/docs/first-steps/create-your-account/)
Your login is yours. One login can belong to several workspaces, with a different role in each.
Sign up with **the same email address the invitation was sent to**, then open the invitation link again. An invitation can only be accepted by the address it was sent to. See [Accept an invitation](https://transglot.ai/docs/first-steps/accept-an-invitation).
## Sign up [#sign-up]
### Open the sign-up page [#open-the-sign-up-page]
Go to [app.transglot.ai/register](https://app.transglot.ai/register).
### Choose how to sign up [#choose-how-to-sign-up]
Select **Google** or **GitHub** to sign up with that account, or fill in the form under **Or sign up with email**: your **Name**, **Email address**, a **Password**, and the same password again in **Confirm password**. Then select **Create account**.
### Confirm your email address [#confirm-your-email-address]
transglot emails you a confirmation link. Open it to finish setting up your account. Until you do, the console shows **Email verification**, with **Resend verification email** if the message did not arrive and **Wrong address? Change it** if you mistyped the address.
Once your address is confirmed, [create a workspace](https://transglot.ai/docs/first-steps/create-a-workspace), or [connect a repository from the CLI](https://transglot.ai/docs/quickstart), which creates one for you.
## Welcome words on the Free plan [#welcome-words-on-the-free-plan]
A new account on the Free plan receives a one-time grant of welcome words on top of the plan's monthly allowance, in two parts:
- The first part arrives when you confirm your email address.
- The rest arrives after you confirm a mobile number once. Open the account's **Welcome words** settings page, or select **Confirm a mobile number** on the billing page. transglot sends a 6-digit code by text message; enter it and the words are added.
If you sign up with an address at an email alias or forwarding service, all of the welcome words arrive after the phone check instead.
Welcome words come once per person. An email address or sign-in that has already received them does not receive them again; a new account then starts with the Free plan's monthly allowance only. For current amounts, see [pricing](https://transglot.ai/pricing).
## If it doesn't work [#if-it-doesnt-work]
- **The email address is already registered.** [Sign in](https://transglot.ai/docs/first-steps/sign-in) instead, or use **Forgot your password?** on the sign-in page.
- **Your company uses single sign-on.** Do not create a password account. Sign in through your company's identity provider instead; see [Sign in to transglot](https://transglot.ai/docs/first-steps/sign-in).
- **"We could not finish this sign-up"**: the sign-up needs a manual review. Email the review code the page shows to hello@transglot.ai and a person reviews it.
- **Your country is not in the list when you confirm a mobile number.** Phone checks are not available there yet. Write to hello@transglot.ai and say where you are.
- **"That is not a mobile number. The code can only go to a mobile phone."**: landline and internet phone numbers cannot receive the code.
- **"This number has already unlocked welcome words. Each number works once."**: use another mobile number of your own.
## Related [#related]
- [Sign in to transglot](https://transglot.ai/docs/first-steps/sign-in)
- [Create a workspace](https://transglot.ai/docs/first-steps/create-a-workspace)
- [Secure your account](https://transglot.ai/docs/administration/security/secure-your-account)
# Create your first project (https://transglot.ai/docs/first-steps/create-your-first-project/)
A project holds one set of keys, the source language they are written in, and the target languages you ship. Creating a workspace creates its first project too, so you only need this page for the projects after that, or if you skipped ahead. To create a project from your repository instead, run `npx transglot@latest init`; see the [Quickstart](https://transglot.ai/docs/quickstart).
Admins of the workspace and Owners of its account. Other roles can open projects but cannot create them.
### Start the wizard [#start-the-wizard]
Open the workspace and select **New project**.
### Project [#project]
Enter the **Project name** and, under **What is it?**, a line about the product, such as "Checkout flow for an e-commerce app". This is not decoration: Glossa reads it as context for every translation in the project, so a specific line gets you better translations.
### Markets [#markets]
Pick the **Source language**, the language your strings are written in today, and the **Target languages** you want to ship. Languages are named with BCP-47 tags such as `en`, `pt-BR` or `zh-Hans`. See [Languages and locales](https://transglot.ai/docs/concepts/languages-and-locales).
### Strings [#strings]
Choose how your strings will arrive: a file, a migration from another tool, or a repository. Then select **Create project**.
The project is created and you land on its **Get started** page, which walks you through the rest: bringing your source strings in and running your first AI translation. See [Setup steps](https://transglot.ai/docs/first-steps/the-activation-checklist).
## If it doesn't work [#if-it-doesnt-work]
- **"Unknown locale: use a BCP-47 tag like de, pt-BR, or zh-Hans."**: the language is not a tag transglot recognises. Use the language code, optionally with a region or script.
- **"The account this workspace belongs to has no room for another project on its plan."**: the account has as many projects as its plan includes. Free includes one project; paid plans have no project limit. Delete a project or ask an account Owner to upgrade.
- **New project is not offered.** You are not an admin of this workspace or an Owner of its account.
## Related [#related]
- [Add a target language](https://transglot.ai/docs/guides/projects/add-a-target-language)
- [Import content](https://transglot.ai/docs/guides/projects/import-content)
- [Import from another tool](https://transglot.ai/docs/integrations/migrate/import-from-another-tool)
# Do I need a developer to set transglot up? (https://transglot.ai/docs/first-steps/do-i-need-a-developer-to-set-transglot-up/)
There are three ways to get strings into transglot, and they need very different amounts of engineering.
| Route | Who sets it up | Plan |
| --- | --- | --- |
| **Upload or migrate.** Upload language files, a zipped locale folder, or bring a project across from Lokalise, Phrase, Crowdin, Transifex, Weblate or POEditor. | Uploading: a developer, admin or account Owner. Migrating: an admin or account Owner, with a read token from the tool you are leaving. No code either way. | Every plan |
| **Connect a system you already run.** A code repository, a content platform or a file-storage service, set up once from the integrations screens. | An admin, plus someone with access to the other system to authorise the connection. This is configuration, not programming. | Starter and up |
| **Push from your codebase.** The CLI, the GitHub Action or the API, fitted into your existing build. | A developer. | Starter and up |
Getting translations back out has the same split. Exporting files and publishing back to a connected content platform need no code. The CDN needs a few lines in your app. A connected repository opens a pull request against your own files with no change to your app at all.
## Where to start [#where-to-start]
- No code: [Import content](https://transglot.ai/docs/guides/projects/import-content) or [Import from another tool](https://transglot.ai/docs/integrations/migrate/import-from-another-tool).
- Connect a system: [Connect GitHub](https://transglot.ai/docs/integrations/git/connect-github), [Connect a content platform](https://transglot.ai/docs/integrations/content-platforms) or [Connect file storage](https://transglot.ai/docs/integrations/storage/connect-file-storage).
- From your codebase: the [Quickstart](https://transglot.ai/docs/quickstart).
See [Plan requirements](https://transglot.ai/docs/integrations/plan-requirements) for what each integration needs.
# Sign in to transglot (https://transglot.ai/docs/first-steps/sign-in/)
### Open the sign-in page [#open-the-sign-in-page]
Go to [app.transglot.ai/login](https://app.transglot.ai/login).
### Choose how to sign in [#choose-how-to-sign-in]
- **Passkey**: use a passkey you registered on this device or with your password manager.
- **Google** or **GitHub**: sign in with the account you connected.
- **Email and password**: enter your **Email address** and **Password**, tick **Remember me** to stay signed in on this device, and select **Log in**.
### Enter your second factor, if asked [#enter-your-second-factor-if-asked]
If you turned on two-factor authentication, transglot asks for the **Authentication code** from your authenticator app. If you do not have the app to hand, choose **log in using a recovery code** and enter one of the recovery codes you saved. Each recovery code works once.
You land on [your dashboard](https://transglot.ai/docs/first-steps/your-dashboard).
## Single sign-on [#single-sign-on]
If your company requires single sign-on, everyone with an email address on its verified domain is sent to the company's identity provider when they sign in with a password or a passkey, and signing in with Google or GitHub stops working for them. Sign in through the identity provider instead.
The Owners of the account that holds the workspace can always sign in with their password, so a broken identity provider cannot lock everyone out. See [Set up single sign-on](https://transglot.ai/docs/administration/security/set-up-single-sign-on).
## If it doesn't work [#if-it-doesnt-work]
- Use **Forgot your password?** on the sign-in form to get a reset link by email.
- If you lost your authenticator, use a recovery code.
- For anything else, see [I can't sign in](https://transglot.ai/docs/resources/troubleshooting/i-cant-sign-in).
## Related [#related]
- [Turn on two-factor authentication](https://transglot.ai/docs/administration/security/turn-on-two-factor-authentication)
- [Add a passkey](https://transglot.ai/docs/administration/security/add-a-passkey)
- [Create your account](https://transglot.ai/docs/first-steps/create-your-account)
# Setup steps (https://transglot.ai/docs/first-steps/the-activation-checklist/)
**Setup steps** is one list that you see at two scopes. On [your dashboard](https://transglot.ai/docs/first-steps/your-dashboard), the card labelled **Across your workspaces** covers every project you can reach. On a project's **Get started** page, the card labelled **This project** covers that project only.
## The five steps [#the-five-steps]
| Step | Done when |
| --- | --- |
| **Create your first project** | A project exists. On a project's **Get started** page this is done from the start. |
| **Add a target language** | The project has a language to translate into besides its source language. |
| **Add your source strings** | The project has source strings, from an upload, a push or a connector. |
| **Run your first translation** | A translation run has produced translations, either drafted by Glossa or reused from translation memory. A run counts as soon as it has written something, even if it later failed or was cancelled. A run that wrote nothing leaves the step open. |
| **Invite a teammate** | The workspace has a second member, or an invitation you sent has not expired yet. An invitation that expires unaccepted stops counting. |
Steps the project already satisfies count from the start, such as target languages you picked while creating it, or a teammate already in the workspace. Progress is worked out from your real state each time a page loads, so finishing a step anywhere updates every place the list appears, and doing steps out of order works as well as doing them in order.
## Reading the card [#reading-the-card]
- The card counts **N of M complete** beside its title, with a bar of the same figures.
- The next step in order is highlighted. An unfinished step carries a link named for what it does: **Create a project**, **Add a language**, **Add strings**, **Open the editor** or **Invite someone**.
- A step you are already on reads **"You are on the page for this step."**
- A step your role cannot do names who does it instead of linking you to a screen that would refuse you. A translator, for example, reads **"Someone who can manage the project’s languages does this step."** under **Add a target language**.
- On the dashboard, finished steps are folded behind **N already done** so what is left comes first.
- When every step is done, the card says so and stays finished, even while strings are waiting to be translated.
## Bringing strings in from the Get started page [#bringing-strings-in-from-the-get-started-page]
Below the setup steps, a project's **Get started** page offers two ways to add your source strings:
- **Upload your language files** takes JSON, YAML, XLIFF, .strings, .arb, .po and more, straight from your machine. Nothing is written until you confirm what was detected.
- **Push from your codebase** gives ready-made snippets for `transglot.json`, the command line and `curl`. Pick a framework preset and the snippets rewrite themselves for it, with your project's details filled in. If you can manage tokens, select **Generate deploy token** to fill the snippets with a real token. It is shown once: **"Deploy token minted. Copy it now, it is shown once."**
The CLI, the GitHub Action and the API need a deploy token, which starts on the Starter plan. On Free, the page says so, and uploading works instead. See [Deploy tokens](https://transglot.ai/docs/developers/deploy-tokens).
## Try a sample first [#try-a-sample-first]
**Seed a sample project** on the **Get started** page, or **Explore a sample** on the dashboard, creates a finished project with real strings so you can look around before wiring up your own. It is a real project, so you need to be allowed to create projects, and your plan needs room for one more. When it is not available, the dashboard shows why: **Needs a spare project** when the account has no room for another project, or **Admins and owners** when your role cannot create projects.
## If it doesn't work [#if-it-doesnt-work]
- **A step you finished still reads as not done.** It is usually **Run your first translation**: a run that has not written any translation yet does not count. Open the editor, translate the missing strings again, and the step ticks once something lands.
- **There is no token strip.** Either your plan does not include API access, in which case the page says so and you upload files instead, or your role cannot create deploy tokens in this project. Ask an admin.
- **You see no setup card on the dashboard.** If you were given access to specific projects rather than a whole workspace and none of them has strings yet, the dashboard does not show the account-wide card, because its steps are work for whoever runs the workspace.
## Related [#related]
- [Your dashboard](https://transglot.ai/docs/first-steps/your-dashboard)
- [Translate with AI](https://transglot.ai/docs/guides/translating/translate-with-ai)
- [The command line tool](https://transglot.ai/docs/developers/cli)
# Your dashboard (https://transglot.ai/docs/first-steps/your-dashboard/)
The dashboard is titled **Portfolio** and covers **Every workspace you can reach**. What it shows depends on whether anything has been translated yet.
## Before your first strings arrive [#before-your-first-strings-arrive]
Every figure would be a zero, so the page guides you instead. It shows [Setup steps](https://transglot.ai/docs/first-steps/the-activation-checklist) labelled **Across your workspaces**, then the ways to bring your strings in. Only the ways your plan and your role can use are offered as cards; anything closed to you is named with what would open it.
| Card | What it does |
| --- | --- |
| **Upload files** | Drop a JSON, YAML or XLIFF file; the format is detected for you. Included on every plan. |
| **Locale folder** | Zip your locales directory, and the files map to languages. |
| **Migrate** | Bring your keys and translations across from six other tools. See [Import from another tool](https://transglot.ai/docs/integrations/migrate/import-from-another-tool). |
| **Connect your repo** | The CLI or the GitHub Action, with a config for your framework. See [Quickstart](https://transglot.ai/docs/quickstart). |
| **Connect a tool** | The card reads "Contentful, Figma, Shopify and more from the marketplace." See [Integrations](https://transglot.ai/docs/integrations) for what you can connect. |
| **Explore a sample** | A finished project with real strings, to look around first. It needs room for one more project on your plan. |
## Once your strings have arrived [#once-your-strings-have-arrived]
The page reports on your work.
- **Your accounts and workspaces.** Workspaces are grouped by the account they belong to, with the account's plan and its words used this cycle. Each workspace lists its projects, with one bar per target language showing its coverage. Select **Open workspace** to go to it.
- **Filters.** **Everything**, **Blocked** and **Waiting on review** narrow the list to the work that needs you.
- **Markets.** Every target language across your projects, with its coverage, translated and score figures, its state, and whether it is published.
- **Figures.** **Words reused at $0** counts words served from translation memory instead of being translated again. **AI words this cycle** shows AI translation used against your plan's allowance. **Active batches** counts translation runs in progress. **Projects** counts the projects you can see.
- **Translation memory** shows the words reused this month, **Overall progress** the share of target strings translated across all projects, and **Recent activity** what has happened lately, with **View all** for the full feed.
Words used this cycle are shown only to people with access to the whole workspace.
## If it doesn't work [#if-it-doesnt-work]
- **You see Start your workspace.** You do not belong to a workspace yet. If you are expecting an invitation, do not create a workspace: open the private link in the invitation email. See [Accept an invitation](https://transglot.ai/docs/first-steps/accept-an-invitation).
- **A project you expected is missing.** You may not have access to it. Ask an admin of the workspace.
- **Explore a sample reads Needs a spare project.** The account has as many projects as its plan includes. Free up a project or upgrade.
- **You see zeros instead of setup steps.** If you were given access to specific projects rather than a whole workspace, the dashboard reports on them rather than showing setup steps, because those steps are work for whoever runs the workspace.
## Related [#related]
- [Create a workspace](https://transglot.ai/docs/first-steps/create-a-workspace)
- [Setup steps](https://transglot.ai/docs/first-steps/the-activation-checklist)
- [How transglot works](https://transglot.ai/docs/how-transglot-works)
# How transglot works (https://transglot.ai/docs/how-transglot-works/)
Every screen in transglot belongs to one of four stages: content in, translation, quality and delivery. They run in that order for each string, and they keep running as your source text changes.
## Where your work lives [#where-your-work-lives]
A **workspace** holds your team and your projects, and belongs to an **account** that holds the plan and billing. A **project** holds one set of keys (your source strings), the source language they are written in, and the target languages you ship. See [Workspaces and projects](https://transglot.ai/docs/concepts/workspaces-and-projects) and [Keys and strings](https://transglot.ai/docs/concepts/keys-and-strings).
## 1. Content in [#1-content-in]
Strings reach a project in one of these ways:
- **From your codebase**, with the [CLI](https://transglot.ai/docs/developers/cli), the [GitHub Action](https://transglot.ai/docs/developers/github-action) or the [API](https://transglot.ai/docs/developers/api).
- **From a connected repository**, which extracts strings when you push. See [Connect GitHub](https://transglot.ai/docs/integrations/git/connect-github).
- **From a content platform** such as a CMS, a store or a help centre. See [Connect a content platform](https://transglot.ai/docs/integrations/content-platforms).
- **From a file** you upload, or a project you migrate from another tool. See [Import content](https://transglot.ai/docs/guides/projects/import-content).
The project records which language the strings are written in and which languages you translate into. See [Languages and locales](https://transglot.ai/docs/concepts/languages-and-locales).
## 2. Translation [#2-translation]
Glossa, the transglot translation engine, drafts the missing translations. It reads the context you give it: the project description, each key's description, your [glossary](https://transglot.ai/docs/concepts/glossary-and-brand-voice), your brand voice and, when you turn it on, similar translations your team has already approved. When the exact same source text has been translated before, transglot reuses that translation at no cost instead of translating it again. See [AI translation](https://transglot.ai/docs/concepts/ai-translation) and [Translation memory](https://transglot.ai/docs/concepts/translation-memory).
New and changed strings are translated as they arrive while the project's **Auto-translate** setting is on, or you start a run yourself from the editor. Everything lands in [the editor](https://transglot.ai/docs/guides/translating/the-editor), where your team can change any translation. A translation you have edited or reviewed is never overwritten by AI.
## 3. Quality [#3-quality]
Automatic checks look for broken placeholders, missing plural forms, translations longer than a key allows, and glossary conflicts, so a broken translation is never written. On Team and above, an AI review also gives each translation a 0-100 quality score with specific findings, and flags the ones a person should check. Reviewers approve or flag translations, and can see a string in context through screenshots and the in-context editor. See [Quality checks](https://transglot.ai/docs/concepts/quality-checks) and [Translation states](https://transglot.ai/docs/concepts/translation-states).
## 4. Delivery [#4-delivery]
Finished languages go back out in the way that suits your product:
- **Pulled into your build** with the CLI or the GitHub Action.
- **Proposed as a pull request** by a connected repository.
- **Published to the CDN**, which your app reads at runtime. See [The CDN](https://transglot.ai/docs/guides/delivery/the-cdn).
- **Published back** to the content platform the strings came from.
- **Exported** as files from the project.
## Next steps [#next-steps]
# Overview (https://transglot.ai/docs/)
transglot keeps the text of your product translated. You bring your source strings from a repository, a file or a content platform. Glossa, the transglot translation engine, drafts every missing translation using your glossary, your brand voice and the translations your team already approved. Automatic checks flag what needs a human, your team reviews it in the editor, and the finished languages go back out through git, the CDN or the platform the content came from.
## Start from your AI agent [#start-from-your-ai-agent]
Working in Claude Code, Cursor or VS Code? Add transglot to your agent and ask it to translate, review and sync your strings for you. [More about the MCP server](https://transglot.ai/docs/mcp).
## Explore the docs [#explore-the-docs]
## What you can do [#what-you-can-do]
- **Translate with AI.** Fill every missing translation in one run, or translate only the rows you pick. Translations someone has already edited or reviewed are never overwritten. See [AI translation](https://transglot.ai/docs/concepts/ai-translation) and [Translate with AI](https://transglot.ai/docs/guides/translating/translate-with-ai).
- **Review.** Work through translations in [the editor](https://transglot.ai/docs/guides/translating/the-editor), [approve or flag them](https://transglot.ai/docs/guides/translating/approve-or-flag-a-translation), [assign a language to a translator](https://transglot.ai/docs/guides/translating/assign-a-language-to-a-translator) and discuss a string in [comments](https://transglot.ai/docs/guides/translating/comment-on-a-string).
- **Check quality.** Every translation is checked for broken placeholders, wrong plural forms, glossary conflicts and more, and gets a quality score with specific findings. See [Quality checks](https://transglot.ai/docs/concepts/quality-checks), [the glossary](https://transglot.ai/docs/guides/quality/the-glossary) and [brand voice](https://transglot.ai/docs/guides/quality/brand-voice).
- **Deliver.** Pull files into your build with [the CLI](https://transglot.ai/docs/developers/cli), get a pull request from [a connected repository](https://transglot.ai/docs/integrations/git/connect-github), serve published languages at runtime from [the CDN](https://transglot.ai/docs/guides/delivery/the-cdn), or publish back to [a content platform](https://transglot.ai/docs/integrations/content-platforms).
## Build with transglot [#build-with-transglot]
New to transglot and not sure where to start? Read [How transglot works](https://transglot.ai/docs/how-transglot-works), or [Do I need a developer to set transglot up?](https://transglot.ai/docs/first-steps/do-i-need-a-developer-to-set-transglot-up) if you are choosing a route.
# Use transglot from your AI agent (https://transglot.ai/docs/mcp/)
Your coding agent can work on your translations directly. The transglot MCP server (`@transglot/mcp`, built on the [Model Context Protocol](https://modelcontextprotocol.io)) gives an agent tools for one project, so you can ask in plain language: "translate what is missing in French", "what does `checkout.title` say in German", "add our product name to the glossary as do-not-translate".
The server runs on your machine with `npx`, so you need Node.js 20 or later. One server serves one project: the deploy token decides which, and the token's [abilities](#choose-the-tokens-abilities) decide which tools work.
## Get a deploy token [#get-a-deploy-token]
### Open the project's Developer settings [#open-the-projects-developer-settings]
In the console, open the project, then **Settings** → **Developer**. Under **API tokens**, select **New token**.
### Pick the abilities [#pick-the-abilities]
For an agent that reads and edits translations, choose `read`, `write` and `pull`. Add `manage` if it should also start translation runs, run quality checks and edit the glossary. [Choose the token's abilities](#choose-the-tokens-abilities) has the full list.
### Copy the token [#copy-the-token]
The token is shown once. Paste it into the box above, or into your client's configuration below. More on tokens in [Deploy tokens](https://transglot.ai/docs/developers/deploy-tokens).
Tokens need a plan with API access, Starter and above. See [pricing](https://transglot.ai/pricing).
## Point your agent at these docs [#point-your-agent-at-these-docs]
Agents read documentation better as plain text. Give yours [llms.txt](https://transglot.ai/docs/llms.txt) (an index of every page) or [llms-full.txt](https://transglot.ai/docs/llms-full.txt) (every page in one file), or the markdown of a single page: each page has a **Copy Markdown** button.
## Set up any client by hand [#set-up-any-client-by-hand]
The server speaks MCP over stdio. Every client runs the same command, `npx -y @transglot/mcp`, with the token in the `TRANSGLOT_TOKEN` environment variable. Replace `tgl_xxx` with your token. If the console showed the token with a number and a `|` in front, leave that part out: the shell reads `|` as a pipe.
```bash
claude mcp add transglot --env TRANSGLOT_TOKEN=tgl_xxx -- npx -y @transglot/mcp
```
```json title="claude_desktop_config.json"
{
"mcpServers": {
"transglot": {
"command": "npx",
"args": ["-y", "@transglot/mcp"],
"env": { "TRANSGLOT_TOKEN": "tgl_xxx" }
}
}
}
```
```json title=".cursor/mcp.json"
{
"mcpServers": {
"transglot": {
"command": "npx",
"args": ["-y", "@transglot/mcp"],
"env": { "TRANSGLOT_TOKEN": "tgl_xxx" }
}
}
}
```
VS Code can prompt for the token instead of storing it in the file:
```json title=".vscode/mcp.json"
{
"inputs": [
{
"type": "promptString",
"id": "transglot-token",
"description": "transglot deploy token",
"password": true
}
],
"servers": {
"transglot": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@transglot/mcp"],
"env": { "TRANSGLOT_TOKEN": "${input:transglot-token}" }
}
}
}
```
```json title="~/.codeium/windsurf/mcp_config.json"
{
"mcpServers": {
"transglot": {
"command": "npx",
"args": ["-y", "@transglot/mcp"],
"env": { "TRANSGLOT_TOKEN": "tgl_xxx" }
}
}
}
```
The **Integrations** settings page in the app also has the Claude Code, Claude Desktop and Cursor snippets, under **MCP server**.
A configuration file that holds a token is a secret. Keep it out of version control, or use your client's way of reading the token from the environment.
## Environment variables [#environment-variables]
| Variable | Required | Description |
| --- | --- | --- |
| `TRANSGLOT_TOKEN` | Yes | The deploy token. It is sent only in the `Authorization` header and is removed from any error text. |
| `TRANSGLOT_BASE_URL` | No | The API address. Default: `https://api.transglot.ai`. `TRANSGLOT_URL`, the CLI's variable, is used when this one is not set. |
Without a token the server exits at once with `transglot-mcp: TRANSGLOT_TOKEN is required.` on stderr, which your client shows in its MCP log.
## Tools [#tools]
Read tools have no side effects. Tools that start a translation run or a quality check use the workspace's word allowance; their descriptions say so, so the agent and your client's approval prompt can tell.
| Tool | What it does | Ability |
| --- | --- | --- |
| `get_project` | Reads the project: name, source locale, every locale and the key count. | any of `push`, `pull`, `manage` |
| `list_languages` | Lists the project's locales and the source locale. Locales cannot be added through the API. | any of `push`, `pull`, `manage` |
| `get_translation` | Reads one key in one locale: value, state, staleness and quality verdict. | `read` |
| `upsert_translation` | Writes one value, or its plural forms, for an existing key as a human edit. Editing the source locale can queue a translation run. | `write` |
| `translate_missing` | Starts a translation run that fills missing values. Never overwrites edited or reviewed translations. | `manage` |
| `get_batch_status` | Reads one translation run, optionally with its failed items. | any of `push`, `pull`, `manage` |
| `list_batches` | Lists recent translation runs, or only the active ones. | any of `push`, `pull`, `manage` |
| `retry_failed_batch` | Queues the failed items of a finished run as a new run. | `manage` |
| `cancel_batch` | Stops a running translation run. Unspent words return to the allowance. | `manage` |
| `run_qa` | Runs the AI quality check over target translations. Needs a plan with Quality mode (Team and above). | `manage` |
| `glossary_list_terms` | Lists glossary terms, 100 per page. | `read` |
| `glossary_add_term` | Adds an active glossary term: do-not-translate, forbidden, or with required translations. | `manage` |
| `glossary_update_term` | Replaces a glossary term by id. | `manage` |
| `glossary_delete_term` | Deletes a glossary term. | `manage` |
| `pull_file` | Exports one locale as a file, optionally only translations at a minimum state. | `pull` |
| `push_file` | Imports a file into one locale. Can delete keys missing from a source file. | `push` |
`pull_file` and `push_file` in version 0.1.0 of the package handle `json_flat`, `json_nested`, `android_xml`, `ios_strings`, `ios_stringsdict`, `flutter_arb`, `laravel_php` and `laravel_json`. For other formats, use the [CLI](https://transglot.ai/docs/developers/cli).
The glossary tools need a plan that includes the glossary (Starter and above). See [pricing](https://transglot.ai/pricing).
### Choose the token's abilities [#choose-the-tokens-abilities]
| You want the agent to | Give the token |
| --- | --- |
| Read translations and the glossary only | `read` and `pull` |
| Also edit single translations | `read`, `write` and `pull` |
| Also sync whole files | add `push` |
| Also start, retry and stop translation runs, run quality checks, and edit the glossary | add `manage` |
A tool the token's abilities do not cover returns an error with the hint `The token lacks the "manage" ability. Issue a token that has it.`, naming the ability that is missing.
## What the API does not offer [#what-the-api-does-not-offer]
There are no tools to list or search keys, create or delete single keys, add languages, or manage webhooks, because the public API has no endpoints for them. Keys are created and removed by pushing source files.
## Behaviour [#behaviour]
- **Transport:** stdio only. Diagnostics go to stderr.
- **Errors:** API errors come back as tool errors in the form `slug (HTTP status): detail`, with a hint on what to do next.
- **Rate limits:** the API allows 60 requests per minute per token. The server retries a rate-limited request up to twice, waiting as the API asks, before it returns an error.
Check the installed version with `npx -y @transglot/mcp --version`.
# Quickstart (https://transglot.ai/docs/quickstart/)
This quickstart connects a repository that already has a locale file, such as `messages/en.json`, to transglot with the command line tool. When you finish, the repository has a `transglot.json` file and a translated file for each target language, and the project is ready to review in the console.
- Node.js 22 or later on the machine with the repository.
- A browser on any machine, to sign in and approve the connection.
- The CLI, the GitHub Action and the API start on the Starter plan. If your account is on Free, the browser offers a free trial while you connect. See [pricing](https://transglot.ai/pricing).
### Run `init` in your repository [#run-init-in-your-repository]
From the root of the repository, run:
```bash
npx transglot@latest init
```
`init` finds your locale files and works out the source language before anything leaves your machine. It prints what it found, for example `Found messages/en.json JSON (nested), 412 strings, source language en`, then prints a link and a code and opens the link in your browser.
Always run it as `npx transglot@latest`: in a repository that lists an older version of `transglot` as a dependency, plain `npx transglot` runs that older version.
If `init` reports **No locale files were found in this folder.**, tell it where they are with `--path` and `--format`, for example `--path messages/{locale}.json --format json_nested`. If the repository only has the source file, name the languages to translate into with `--targets fr,de`.
### Sign up or sign in, then approve [#sign-up-or-sign-in-then-approve]
The browser opens **Connect the CLI**. If you are not signed in, choose **Sign in**, or **Sign up** to create your account, and you come straight back to this page. A new account confirms its email address first; the page moves on by itself once you open the confirmation link.
Under **Connect this terminal?**, check that the code matches the one in your terminal, then select **Approve**. Approve only a code you started yourself. When the browser and the terminal are on different networks (an SSH session or a container, for example), the page then shows **Type this number in your terminal**: type the two digits into the terminal.
### Create or choose a workspace [#create-or-choose-a-workspace]
A workspace holds your projects and your team.
- If you have no workspace yet, the page shows **Create your workspace**. Enter a **Workspace name** and select **Create workspace**.
- If you have more than one, choose it under **Choose a workspace**.
If the workspace's account is on Free, the page offers a trial of the Starter plan with **Start the free trial**. Stripe asks for a card and nothing is charged that day. An account that cannot start a trial is offered the paid plan instead. Only the account's owners and billing members can start it; anyone else is told who to ask, and the terminal waits.
### Create or choose the project [#create-or-choose-the-project]
Under **Choose the project for this repository**, either connect an existing project, or check the name, **Source language** and **Target languages** that `init` proposed from your files and create the project.
Connecting creates a project token for this machine, so you need to be an admin of the workspace or an owner of its account. If you are not, the page names the admins who can connect it.
The page then says **Your terminal is connected**.
### Run the first translation [#run-the-first-translation]
Back in the terminal, `init` writes `transglot.json`, uploads your source strings and any translations you already have, and shows what Glossa will translate, per language, with the number of words the run needs. Answer **Start translating?** to start it.
A progress bar runs for each language. When the run finishes, `init` writes the translated files next to your source file and prints the files to commit:
```bash
git add transglot.json .gitignore messages/
git commit -m "Set up transglot"
```
`transglot.json` is safe to commit: it holds no secret. The project token stays on this machine, outside the repository.
```json title="transglot.json"
{
"url": "https://api.transglot.ai",
"sources": [{ "path": "messages/{locale}.json", "format": "json_nested" }],
"pull": [{ "path": "messages/{locale}.json", "format": "json_nested", "locales": ["fr", "de"] }]
}
```
### Review the translations [#review-the-translations]
`init` ends with a **Review translations** link to the project. Open it to read and edit the translations in [the editor](https://transglot.ai/docs/guides/translating/the-editor). Translations that need a human are flagged for review; see [Translation states](https://transglot.ai/docs/concepts/translation-states).
### Push and pull as you work [#push-and-pull-as-you-work]
When you add or change source strings, push them and wait for the translation, then pull the results:
```bash
npx transglot@latest push --wait
npx transglot@latest pull
```
`push` uploads the files named under `sources`. New and changed strings are translated automatically while the project's **Auto-translate** setting is on, which it is by default. `--wait` waits for that translation to finish. `pull` writes the files named under `pull`.
In the folder `init` set up, these commands use the token stored on this machine. In CI, create a [deploy token](https://transglot.ai/docs/developers/deploy-tokens) and store it as the `TRANSGLOT_TOKEN` secret instead; see [Continuous integration](https://transglot.ai/docs/developers/cli/continuous-integration) or use the [GitHub Action](https://transglot.ai/docs/developers/github-action).
## Prefer not to use the command line? [#prefer-not-to-use-the-command-line]
You can bring strings in without any code:
- **Upload files.** [Create a project](https://transglot.ai/docs/first-steps/create-your-first-project), then use **Upload your language files** on its **Get started** page. It accepts JSON, YAML, XLIFF, .strings, .arb, .po and more, and nothing is written until you confirm what was detected. Uploading works on every plan. See [Import content](https://transglot.ai/docs/guides/projects/import-content).
- **Migrate from another tool.** Bring your keys and translations across from Lokalise, Phrase, Crowdin, Transifex, Weblate or POEditor. See [Import from another tool](https://transglot.ai/docs/integrations/migrate/import-from-another-tool).
- **Connect a repository or a content platform.** See [Connect GitHub](https://transglot.ai/docs/integrations/git/connect-github) and [Connect a content platform](https://transglot.ai/docs/integrations/content-platforms).
Then [translate with AI](https://transglot.ai/docs/guides/translating/translate-with-ai) from the editor, and get the results out by [publishing to the CDN](https://transglot.ai/docs/guides/delivery/publish-a-locale) or exporting files.
## Next steps [#next-steps]
# Appearance and language (https://transglot.ai/docs/administration/account/appearance/)
**Who can do this:** everyone, for themselves.
Open **Settings**, choose the **You** tab, then **Appearance & language**.
## Theme [#theme]
Under **Theme** ("Follow your system setting, or pin the console to light or dark."), pick **Light**, **Dark** or **System**. The change applies straight away.
The theme is remembered in this browser only. It is not shared with your teammates, and another browser or device keeps its own choice.
## Console language [#console-language]
Pick a **Console language**: "The language every screen in this console is shown in. Your projects, their source strings and their translations are not affected." The list shows the languages the console is available in, each written in its own language.
The console language is saved to your login, so it follows you to any browser you sign in from. It changes the console only, not the languages of the projects you translate.
## Related [#related]
- [Your profile](https://transglot.ai/docs/administration/account/your-profile)
- [Notification preferences](https://transglot.ai/docs/administration/account/notification-preferences)
# Notification preferences (https://transglot.ai/docs/administration/account/notification-preferences/)
**Who can do this:** everyone, for themselves. These settings are yours alone and apply in every workspace you belong to. "Nothing changes for your teammates."
### Open Notifications settings [#open-notifications-settings]
Open **Settings**, choose the **You** tab, then **Notifications**. You can also select **Preferences** in your notification inbox.
### Set the digest [#set-the-digest]
Under **Email digest**, choose a **Frequency**: **Daily**, **Weekly** or **Off**.
### Choose the kinds of email [#choose-the-kinds-of-email]
Under **Kinds of email**, turn each kind on or off.
### Choose the channels for each event [#choose-the-channels-for-each-event]
Under **Per-event channels**, tick **In-app**, **Email** or both for each event.
### Save [#save]
Select **Save preferences**, or **Discard** to undo your changes.
## The email digest [#the-email-digest]
The digest is "a rollup of what you have not read", sent daily or weekly, or not at all. Events marked "(emailed immediately)" do not wait for the digest: they are emailed when they happen, as long as their kind of email and their own **Email** switch are on.
## Kinds of email [#kinds-of-email]
| Kind | What it covers |
| --- | --- |
| **Security** | Sign-ins, password and credential changes, and access to your workspaces. **Always on.** |
| **Billing** | Payments, invoices, renewals and plan changes. **Always on.** |
| **Project activity** | Batches, QA runs, imports and integrations in your projects. |
| **Reports** | Weekly and monthly summaries of your workspace. |
| **Reminders** | Work waiting on you: reviews, assignments and expiring invitations. |
| **Getting started & team** | Getting started, invitations, and changes to your team. |
| **Product & offers** | Product tips, new features and offers. |
Security and billing email cannot be turned off.
## Per-event channels [#per-event-channels]
Every event appears in your in-app inbox by default. Directed events, such as a mention or a review request, are also emailed by default; routine events, such as a batch finishing, are not.
| Event | Emailed immediately |
| --- | :-: |
| Translation batch completed | |
| Translation batch failed | |
| Translation batch finished with errors | |
| New comment on a string | |
| You were @mentioned | Yes |
| QA run completed | |
| Keys were deleted in bulk | Yes |
| A teammate joined | |
| Review requested of you | Yes |
| Self-heal completed | |
| Source drift repaired | |
| Usage reached 50/75/100% of the plan allowance | Yes |
| A fallback engine translated part of a batch | Yes |
| A translation was assigned to you | Yes |
| An assignment was submitted for your review | Yes |
| Your assignment was approved | |
| Changes were requested on your assignment | Yes |
| An assignment was withdrawn from your review | Yes |
| Your export is ready | Yes |
Workspace notifications to a team chat channel are set up per workspace, not here. See [Connect Slack](https://transglot.ai/docs/integrations/notifications/connect-slack).
## Related [#related]
- [Your notifications](https://transglot.ai/docs/administration/account/your-notifications)
- [Your profile](https://transglot.ai/docs/administration/account/your-profile)
- [Connect Slack](https://transglot.ai/docs/integrations/notifications/connect-slack)
# Your notifications (https://transglot.ai/docs/administration/account/your-notifications/)
**Who can use it:** everyone. Your inbox collects notifications from every workspace you belong to.
New activity that involves you lands in your inbox: "a batch finishing, somebody answering a comment, a review request landing in your queue." Which events reach you, and which are also emailed, is set in your [notification preferences](https://transglot.ai/docs/administration/account/notification-preferences).
## The bell [#the-bell]
The **Notifications** bell sits at the foot of the console's left rail and shows how many notifications you have not read. Select it to open your latest notifications in a panel:
- Select a notification to mark it read and open what it is about.
- Select **Mark all read** to clear the count.
- Select **View all notifications** to open the full inbox.
While you work, a new notification also appears briefly at the edge of the screen, with **Open** when there is something to go to.
## The inbox page [#the-inbox-page]
The **Notifications** page lists **Everything that involves you**, newest first, and says how many are unread.
### Open a notification [#open-a-notification]
Select a notification. It is marked read, and transglot opens the string, batch, review or page it is about.
### Clear the rest [#clear-the-rest]
Select **Mark all read** to mark everything read at once.
### See older notifications [#see-older-notifications]
Select **Load more** at the end of the list.
**Preferences** at the top of the page opens your notification preferences.
When there is nothing new, the page reads "You are all caught up".
Notifications are kept for 90 days, whether you have read them or not.
## Related [#related]
- [Notification preferences](https://transglot.ai/docs/administration/account/notification-preferences)
- [Your assignments](https://transglot.ai/docs/guides/translating/your-assignments)
- [Comment on a string](https://transglot.ai/docs/guides/translating/comment-on-a-string)
# Your profile (https://transglot.ai/docs/administration/account/your-profile/)
**Who can do this:** everyone, for their own login.
Your profile belongs to you, not to a workspace. If you belong to several workspaces, they all show the same name and address.
## Change your name or email address [#change-your-name-or-email-address]
### Open Profile [#open-profile]
Open **Settings**, choose the **You** tab, then **Profile**.
### Edit your details [#edit-your-details]
Edit **Name** ("Shown on your comments, assignments and activity.") or **Email address**.
### Save [#save]
Select **Save changes**. Saving does not sign you out anywhere.
### Confirm it is you (email changes only) [#confirm-it-is-you-email-changes-only]
If you changed your email address, confirm your password or use a passkey when asked. Changing your name alone never asks for this.
### Verify the new address [#verify-the-new-address]
transglot emails the new address a verification link. Until you open it, the page shows **address unverified**. **Re-send the verification email** sends the link again.
A warning also goes to your old address, so the person who holds it always finds out. The confirmation step exists because password resets are sent to the address on your login: anyone who could move it without your password could take over the login.
## Delete your profile and sign-in [#delete-your-profile-and-sign-in]
Under **Delete your profile and sign-in**, enter your **Password** and select **Delete your profile**. "Your login goes, with its sign-in methods, notifications and saved views. Invitations you sent that are still waiting are withdrawn, and any seat you held is given back." Work you did inside workspaces keeps your name.
Deleting your profile is immediate, every session ends, and it cannot be undone.
Deleting is refused while you are the only Owner of an account that still has workspaces, members, invitations or a billing record. Add another Owner or discard the account first. See [Account Owners and Billing members](https://transglot.ai/docs/administration/team/account-owners-and-billing-members). An account you are the only Owner of, with none of those, is closed along with your login. It is also refused while an account you own is closing or has an unpaid invoice.
## If it doesn't work [#if-it-doesnt-work]
- **The form refuses the new address**: another transglot login already uses it, or it belongs to a temporary inbox service. Use a permanent address. If it is permanent and still refused, contact support.
- **You signed in with Google, GitHub or your company directory and never set a password**: on the confirmation screen, choose **Sign out and reset your password**. You receive a link to set one, then sign back in and try again.
## Related [#related]
- [Secure your account](https://transglot.ai/docs/administration/security/secure-your-account)
- [Appearance and language](https://transglot.ai/docs/administration/account/appearance)
- [Notification preferences](https://transglot.ai/docs/administration/account/notification-preferences)
# Apply a promo code (https://transglot.ai/docs/administration/billing/apply-a-promo-code/)
**Who can do this:** the Owners and Billing members of the account.
The **Promo code** card "checks the price before you buy". The code is applied when you subscribe from **Plan & billing**.
### Open Plan & billing [#open-plan--billing]
Open **Settings**, choose the **Account** tab, then **Plan & billing**.
### Pick the plan [#pick-the-plan]
Under **Where you sit**, select the plan you are considering. The code is checked against the plan you select, not the one you are on.
### Enter the code [#enter-the-code]
Under **Promo code**, enter the code, for example `LAUNCH50`, and select **Apply**.
### Check the price [#check-the-price]
The card reports the discounted price, for example "Discount applied: the monthly price on Team becomes" followed by the new price.
### Subscribe [#subscribe]
Select **Upgrade**. The code goes with you to checkout for that plan.
## If it doesn't work [#if-it-doesnt-work]
- **"We do not recognise that code."**: check the spelling.
- **"That code is not being accepted right now."**: the code has expired, has not started yet, or has been used up.
- **"That code is not valid for the ... plan."**: the code is limited to other plans. Select one of those and apply it again.
- **"That code could not be applied."**: try again, or contact support.
- **"This code cannot start a new account. Start the account, then apply the code from Plan & billing."**: create the account first, then use the code on its **Plan & billing** page.
## Related [#related]
- [Change your plan](https://transglot.ai/docs/administration/billing/change-your-plan)
- [Invoices and payment](https://transglot.ai/docs/administration/billing/invoices-and-payment)
# Change your plan (https://transglot.ai/docs/administration/billing/change-your-plan/)
**Who can do this:** the Owners and Billing members of the account. Some changes take an Owner: moving to Free, and any change that would delete workspaces or stop single sign-on, SCIM or the audit log in a workspace that uses it.
### Open Plan & billing [#open-plan--billing]
Open **Settings**, choose the **Account** tab, then **Plan & billing**.
### Pick a plan [#pick-a-plan]
Under **Where you sit**, select the plan you want. "Picking a row here changes nothing on its own: the one action underneath says exactly what it will do."
### Choose how you pay [#choose-how-you-pay]
Turn **Pay annually** on or off. Annual billing shows how much it saves.
### Apply a promo code (optional) [#apply-a-promo-code-optional]
If you have one, enter it under **Promo code** before you continue. See [Apply a promo code](https://transglot.ai/docs/administration/billing/apply-a-promo-code).
### Take the action [#take-the-action]
Select the action under the plans: **Upgrade**, **Switch plan** or **Downgrade to Free**. For Enterprise it is **Book a call**. Read the confirmation, then confirm.
## Subscribing for the first time [#subscribing-for-the-first-time]
When the account has no subscription yet, **Upgrade** first asks **Before you go to payment** for the **Company or billing name** ("Invoices are addressed to this name."). Select **Continue to payment** to pay on the secure checkout page. Back on **Plan & billing**, the page reads "Payment received. The plan changes when Stripe confirms it."
If the account is eligible for a free trial, the plan starts as a trial and the **Plan** card shows when it ends. **Start** followed by the plan's name, for example **Start Team now**, ends the trial early: the card on file is charged today, and the plan's allowance opens once the payment goes through.
## Moving between paid plans [#moving-between-paid-plans]
| Change | When it applies |
| --- | --- |
| A higher plan, or monthly to annual on the same plan | Now. "You are charged today, prorated to the day, and the unused part of your current plan is credited." |
| A lower plan, or annual to monthly | Now, if this cycle's words fit the lower plan's allowance. Otherwise at the end of the period: "This cycle has already used or started" more words than the lower plan includes. |
Features the new plan does not include stop when the change applies. Check before you move down: an integration that needs the higher plan stops, and a project setting that needs it (such as quality mode) turns off.
The plan changes only after the payment goes through. If your bank needs to confirm the payment, the page shows **A change waiting for payment** with **Finish payment** and **Cancel pending change**. Cancelling it voids the invoice it waits on, and nothing is charged.
## Moving to Free [#moving-to-free]
**Downgrade to Free** cancels the subscription at the end of the period you have paid for. See [What happens if I cancel?](https://transglot.ai/docs/administration/billing/what-happens-if-i-cancel).
## Enterprise [#enterprise]
Enterprise is not bought at checkout. Its row offers **Book a call**, and the **Contact sales** card describes it: "A word commitment instead of a cycle allowance, single sign-on and directory provisioning, an audit export, your logo and product name on the quality scorecard you hand to customers, and a contract your legal team can read."
## If it doesn't work [#if-it-doesnt-work]
- **"... does not fit what this account holds: ... Remove the excess, then change plan."**: the account has more seats, projects or languages than the lower plan allows. Remove the excess first.
- **"Only an account owner can cancel the subscription: ..."**: ask one of the Owners it names.
- **"This change deletes workspaces after the grace, so an account owner makes it: ..."** or **"This change stops single sign-on, SCIM or the audit log in a workspace that uses it, so an account owner makes it: ..."**: ask one of the Owners it names.
- **"Update the card on file first. Plan changes are paused while a payment is outstanding."**: fix the payment, then try again. See [Invoices and payment](https://transglot.ai/docs/administration/billing/invoices-and-payment).
- **"This subscription is already set to end at the close of the billing period."**: you have already moved to Free. To stay on your plan, select **Cancel scheduled change**.
- **"Your card was declined. Nothing changed."**: update the card in the payment portal and try again.
## Related [#related]
- [Your plan and seats](https://transglot.ai/docs/administration/billing/your-plan-and-seats)
- [What happens if I cancel?](https://transglot.ai/docs/administration/billing/what-happens-if-i-cancel)
- [Apply a promo code](https://transglot.ai/docs/administration/billing/apply-a-promo-code)
# Close an account (https://transglot.ai/docs/administration/billing/close-an-account/)
**Who can do this:** the Owners of the account.
Closing an account is how you stop paying and remove everything the account holds. To keep using transglot on Free instead, [move the account to Free](https://transglot.ai/docs/administration/billing/what-happens-if-i-cancel).
## Before you start [#before-you-start]
- Export anything you need from the account's workspaces.
- To keep a workspace, [move it to another account](https://transglot.ai/docs/administration/workspace/move-a-workspace-to-another-account) first.
- Read the summary under **Close this account**. For an account with a subscription, closing "Cancels the" plan's "subscription today, with no refund of the time left, and bills usage beyond the plan so far" on a final invoice.
### Open the account's General settings [#open-the-accounts-general-settings]
Open **Settings**, choose the **Account** tab, then **General**.
### Start closing [#start-closing]
Under **Close this account**, select **Close account**.
### Confirm it is you [#confirm-it-is-you]
Closing needs a confirmation from the last 15 minutes. Choose **Confirm your password**, or **Email me a code** and enter the 6-digit code under **Code from the email**, then select **Check code**.
### Type the account name [#type-the-account-name]
Type the account's name into the **Account name** box exactly as it is written.
### Confirm [#confirm]
Select **Close account**.
## What happens next [#what-happens-next]
- The subscription is cancelled and the final bill is issued, usually within 15 minutes. The final invoice is emailed to the billing address.
- Every workspace of the account becomes read-only straight away, and is deleted after the date shown.
- The account's **General** page reads **Closing on** followed by the day closing finishes and the timezone that day is written in, for example **Closing on 9 Nov, UTC**. Any Owner can select **Cancel closing** until the workspaces are deleted.
- Invoices stay available to the account's Owners and Billing members after the account has closed, until the date shown on **Plan & billing**.
An account with no workspaces that has never been billed closes at once.
## Cancel closing [#cancel-closing]
Select **Cancel closing** on the account's **General** page, or on the banner in any of its workspaces, then confirm. The workspaces are no longer scheduled for deletion. If the subscription was already cancelled, it cannot be restored, the time left on it is not refunded, and the account stays open on Free: subscribe again to get your plan back. Workspaces beyond what Free includes then become read-only, as they do after [a move to Free](https://transglot.ai/docs/administration/billing/what-happens-if-i-cancel).
If you cancel within the first few minutes, while the final bill is still being issued, the page asks you to wait until that is done.
## If it doesn't work [#if-it-doesnt-work]
- **"Type ... exactly as it is written to close it."**: the name must match exactly.
- **"Too many wrong codes. Send a new one."** or **"That code has expired. Send a new one."**: select **Email me a code** again.
- **"Verify your email address first, then send a code to it."**: confirm your email address, or use **Confirm your password**.
- **"... is closed. Its invoices stay available; start a new account to translate again."**: a closed account cannot be reopened.
## Related [#related]
- [What happens if I cancel?](https://transglot.ai/docs/administration/billing/what-happens-if-i-cancel)
- [Delete a workspace](https://transglot.ai/docs/administration/workspace/delete-a-workspace)
- [Invoices and payment](https://transglot.ai/docs/administration/billing/invoices-and-payment)
# Invoices and payment (https://transglot.ai/docs/administration/billing/invoices-and-payment/)
**Who can do this:** the Owners and Billing members of the account.
Everything here is on the account's **Plan & billing** page: open **Settings**, choose the **Account** tab, then **Plan & billing**. Card details, tax details and the billing email are edited in the payment portal, run by our payment provider, Stripe. They never reach transglot.
## Download an invoice [#download-an-invoice]
### Find the invoice [#find-the-invoice]
Scroll to **Invoices**. Each row shows the invoice, its **Date**, **Amount** and **Status**.
### Download it [#download-it]
Select **Download** on its row. The PDFs are hosted by Stripe.
Free accounts are not invoiced, so the list starts with the first paid cycle. An account on a trial shows "No invoices yet. The first one is issued on" the date the trial converts.
## Change the card or billing details [#change-the-card-or-billing-details]
### Open the payment portal [#open-the-payment-portal]
Select **Manage payment** at the top of **Plan & billing**, or **Update card** on the **Payment** card.
### Make the change [#make-the-change]
In the portal, change the card, the billing address, the tax details or the billing email.
### Return to transglot [#return-to-transglot]
Go back to **Plan & billing**. The **Payment** card shows the card on file, for example "Visa ending 4242", and when it expires.
**Company details** shows what invoices are addressed to: the **Name**, **Country** and **Billing email**. A billing email that belongs to nobody on the account is marked "not a member of this account". Select **Edit in the payment portal** to change them. Renaming the account does not change invoices already issued.
## When a payment fails [#when-a-payment-fails]
If a payment cannot be collected, **Plan & billing** shows **Payment failed.** and asks you to **Update your card** to keep your plan. Every workspace of the account shows a banner too, because "translation, pushes and new members are paused" in them. "Reading, editing and export still work."
### Update the card [#update-the-card]
Select **Update card** and replace the card in the payment portal. If your bank needs to confirm the payment, select **Confirm the payment** instead.
### Check the payment [#check-the-payment]
Back on **Plan & billing**, select **Check payment again**. When the payment has gone through, the message reads "Payment confirmed. Translation has resumed."
Translation runs that the failed payment stopped restart on their own if the payment goes through within 72 hours. Older runs are not restarted, because their source may have changed since; the workspace's developers are told instead.
While a payment is outstanding, plan changes are paused. If a renewal invoice stays unpaid for 30 days after its payment first failed, the subscription ends. The invoice stays payable, and the account stays paused until it is paid.
## If it doesn't work [#if-it-doesnt-work]
- **"Invoices could not be loaded from Stripe just now. Your plan and card are unaffected."**: select **Try again**.
- **"Stripe has not confirmed a payment yet."**: wait a moment and check again. **Check payment again** can be used once a minute.
- **There is no Manage payment button**: the account has never bought a plan. A payment method is added at checkout, when a paid plan is bought.
## Related [#related]
- [Your plan and seats](https://transglot.ai/docs/administration/billing/your-plan-and-seats)
- [Change your plan](https://transglot.ai/docs/administration/billing/change-your-plan)
- [What happens if I cancel?](https://transglot.ai/docs/administration/billing/what-happens-if-i-cancel)
# The open source plan (https://transglot.ai/docs/administration/billing/open-source-plan/)
**Who can apply:** the maintainers of a project with an OSI-approved licence and a public repository.
The open source plan gives an account the Team feature set at no cost. It has no price and never appears at checkout: a person reads each application, and transglot moves the account onto the plan when it is approved.
## What it includes [#what-it-includes]
- The Team plan's features, including AI translation, the glossary, quality mode, in-context editing and CDN publishing.
- The API, the CLI, the GitHub Action and webhooks.
- Unlimited projects, languages and seats.
- One workspace.
- A monthly word allowance that is a hard stop rather than a meter, so the plan can never produce a bill. Usage-based billing is not available on it.
The allowance and the full terms are on [transglot.ai/oss](https://transglot.ai/oss).
### Set up your account [#set-up-your-account]
[Create your account](https://transglot.ai/docs/first-steps/create-your-account) and the workspace for your project, if you have not already. The plan covers one workspace.
### Open the application form [#open-the-application-form]
Go to [transglot.ai/oss](https://transglot.ai/oss) and find **Tell us about the project.**
### Fill in the four fields [#fill-in-the-four-fields]
Enter the **Repository URL** (public, and https), choose the **Licence**, give a **Contact email** ("Where the decision goes.") and describe **What does the project do?** in up to 2,000 characters.
### Submit [#submit]
Select **Submit application**. The page confirms "Your application is in."
## What happens next [#what-happens-next]
Applications are read by hand, and the decision goes to the contact email you gave. There is no published turnaround. The repository URL is stored for a person to read and is never fetched by transglot's servers.
When the application is approved, the account's **Plan & billing** page reads "Open source plan, approved" with the date, followed by "One workspace, no card."
## Things to know [#things-to-know]
- **One workspace.** The plan covers a single workspace. Moving that workspace to another account ends the account's open source plan, so ask support to move the grant instead.
- **Subscribing ends the grant.** If you choose a paid plan on **Plan & billing**, the confirmation warns that subscribing ends the plan transglot provides.
- **The README badge.** You can show a badge with your project's published language count in your repository. See [Add a progress badge to your README](https://transglot.ai/docs/guides/delivery/add-a-progress-badge-to-your-readme).
## Related [#related]
- [Your plan and seats](https://transglot.ai/docs/administration/billing/your-plan-and-seats)
- [What counts towards my usage?](https://transglot.ai/docs/administration/billing/what-counts-towards-my-usage)
- [Create your account](https://transglot.ai/docs/first-steps/create-your-account)
# Turn on usage-based billing (https://transglot.ai/docs/administration/billing/turn-on-usage-based-billing/)
**Who can do this:** the Owners and Billing members of the account, on a paid plan with a working card on file.
Decide the cap first. It is a hard stop, not an alert, so pick an amount you are willing to be charged in full in one cycle.
### Open Usage [#open-usage]
Open **Settings**, choose the **Account** tab, then **Usage**.
### Turn on usage beyond the plan [#turn-on-usage-beyond-the-plan]
Under **Usage-based overage**, turn on **Usage beyond the plan**. The switch saves as you change it. "Usage beyond the plan is on. Set a spend cap below to start paying for words above the plan. Until then translation stops at the included words."
### Set the spend cap [#set-the-spend-cap]
Enter the **Spend cap a cycle, in USD**.
### Save the cap [#save-the-cap]
Select **Save cap**. "Spend cap saved. It applies to every workspace of the account."
## What happens next [#what-happens-next]
Once the included words are used up, translation carries on and the extra words are charged as usage until the cap is reached. At the cap, translation beyond the included words pauses in every workspace of the account until the next cycle or until you raise the cap. A banner names the cap and offers **Raise the cap**.
To go back to stopping at the included words, turn off **Usage beyond the plan**. "Words above the plan are no longer charged." Clearing the cap has the same effect: "Translation stops at the included words until you set one."
Changes to the cap are recorded in the account log.
## If it doesn't work [#if-it-doesnt-work]
- **"Turn on usage beyond the plan before you set a spend cap."**: the cap field is locked until the switch is on.
- **"... does not sell words beyond the plan. A paid plan does."**: the account is on Free or the open source plan. See [Change your plan](https://transglot.ai/docs/administration/billing/change-your-plan).
- **"Words beyond the trial are not sold."**: usage beyond the plan starts with your first paid cycle.
- **"Add a card in the payment portal first, so usage beyond the plan can be collected."** or **"The card on file has expired. Update it in the payment portal first."**: open **Manage payment** on **Plan & billing**. See [Invoices and payment](https://transglot.ai/docs/administration/billing/invoices-and-payment).
- **"Usage beyond the plan is billed in USD, and ... pays in another currency. Contact support to change it."**
- **"Usage beyond the plan is paused until the bill for ... is settled."**: an earlier cycle's usage has not been paid yet. Included words still work.
## Related [#related]
- [Usage-based billing](https://transglot.ai/docs/administration/billing/usage-based-billing)
- [What counts towards my usage?](https://transglot.ai/docs/administration/billing/what-counts-towards-my-usage)
- [Invoices and payment](https://transglot.ai/docs/administration/billing/invoices-and-payment)
# Usage-based billing (https://transglot.ai/docs/administration/billing/usage-based-billing/)
**Who can change it:** the Owners and Billing members of the account. Everyone in the account's workspaces is affected by it.
Your plan includes an allowance of AI translation each month. Usage is measured against that allowance, and what happens when you exceed it depends on whether usage-based billing is turned on for your workspace. The setting is called **Usage-based overage** and lives on the account's **Usage** page, so it applies to every workspace of the account at once. It is off by default.
## With usage-based billing off [#with-usage-based-billing-off]
When the included words are used up, AI translation stops in every workspace of the account until the words reset at the start of the next cycle, or until you change plan. A run that needs more words than are left is refused before it starts, and nothing is charged. Nothing unexpected appears on your bill.
Members of each workspace see that "The account this workspace belongs to has no AI words left", with the date the words reset and the names of the people who can change the plan.
Work that does not use words carries on: reading, editing by hand, reviewing, exporting, and translations reused from memory.
## With usage-based billing on [#with-usage-based-billing-on]
"Words above the plan's allowance are charged at the overage rate, up to the spend cap, instead of pausing translation." Translation carries on past the allowance, and the extra words are charged as usage on top of the plan.
The **Spend cap a cycle, in USD** is a ceiling, not a warning. When the account reaches it, translation beyond the included words pauses in every workspace until the next cycle or until you raise the cap, exactly as if usage-based billing were off. With usage-based billing on and no cap set, translation still stops at the included words.
While an account is new, the cap may be released in stages: part of it now, and the full amount once earlier usage charges are paid. The card on the **Usage** page shows both figures.
The overage rate is listed on [transglot.ai/pricing](https://transglot.ai/pricing). Before a run that would go past the allowance, its confirmation estimates what the extra words will add to this month's bill.
## Who can use it [#who-can-use-it]
Usage-based billing is available on the paid plans. It is not available:
- on Free or the open source plan, which stop at their allowance;
- during a trial ("Words beyond the trial are not sold.");
- without a working card on file;
- for an account that pays in a currency other than US dollars.
The card on the **Usage** page says which of these applies.
## Related [#related]
- [Turn on usage-based billing](https://transglot.ai/docs/administration/billing/turn-on-usage-based-billing)
- [What counts towards my usage?](https://transglot.ai/docs/administration/billing/what-counts-towards-my-usage)
- [Your plan and seats](https://transglot.ai/docs/administration/billing/your-plan-and-seats)
# What counts towards my usage? (https://transglot.ai/docs/administration/billing/what-counts-towards-my-usage/)
**Who this is for:** anyone watching the account's words. The account's Owners and Billing members see the full figures on the **Usage** page.
Your plan includes an allowance of AI translation each month. Usage is measured against that allowance, and what happens when you exceed it depends on whether usage-based billing is turned on for your workspace. See [Usage-based billing](https://transglot.ai/docs/administration/billing/usage-based-billing).
The allowance belongs to the account and is shared by every workspace in it.
## What counts [#what-counts]
Every word sent to Glossa counts towards your cycle, whatever it was sent for.
- **AI translation.** The source words of each string, once for every language it is translated into. Translating a 10-word string into three languages uses 30 words.
- **Quality checks.** Scoring a translation sends it to Glossa to read, so the source words of every string in the check count.
- **Brand voice drafts.** Asking Glossa to draft a style guide from translations you have already approved counts the words it reads.
- **Repairs.** A string that fails a check and is translated again counts its words again, on every try. Auto-heal does this without anyone pressing a button.
Before a run starts, its confirmation says how many words it will use and how many are left this cycle. If the run needs more words than you have left and usage-based billing is off, "The run is refused: nothing is started and nothing is charged."
AI suggestions, assistant replies and glossary extraction also each have their own limit per cycle, shared by the account's workspaces. The **Plan limits** card on the **Usage** page says when they reset.
## What does not count [#what-does-not-count]
- **Reused translations.** When the exact same source text has been translated before, transglot reuses that translation at no cost instead of translating it again. That is what **Words reused at $0** on your dashboard measures, and why keeping translation memory on lowers your usage.
- **Anything you or your team write by hand.**
- **Reading, filtering and approving.**
- **The quality scorecard**, which summarises findings the quality checks have already produced.
## How words are counted [#how-words-are-counted]
A word is a run of text between spaces that contains at least one letter or digit, so punctuation, bullets and arrows on their own do not count. Languages written without spaces between words are counted from their characters instead: in Chinese and Japanese each character counts as one word, following the convention translation tools use, and Thai, Lao, Khmer and Burmese are counted as their characters divided by a fixed average word length.
## Where to see your usage [#where-to-see-your-usage]
- **Usage**, in the account's settings, shows **Words this cycle** against the allowance, when the words reset, the words used **By workspace**, and the **Last six cycles**. Account Owners can also select **Show projects** to see a workspace's words by project.
- Members who reach a whole workspace see that workspace's AI words on its dashboard.
- The account's Owners and Billing members are emailed when usage reaches 50%, 75% and 100% of the plan's allowance.
## Keeping usage down [#keeping-usage-down]
- Keep translation memory on. It is the biggest single saving.
- Adding a language multiplies the work: every untranslated key in it is a translation.
- With **auto-translate** on, new and changed source strings are translated as they arrive, without anyone pressing a button. That is usually what you want, and it is also the setting most likely to surprise you on the meter.
## Related [#related]
- [Usage-based billing](https://transglot.ai/docs/administration/billing/usage-based-billing)
- [Words and usage](https://transglot.ai/docs/concepts/words-and-usage)
- [Translation memory](https://transglot.ai/docs/concepts/translation-memory)
- [AI translation settings](https://transglot.ai/docs/guides/translating/ai-translation-settings)
# What happens if I cancel? (https://transglot.ai/docs/administration/billing/what-happens-if-i-cancel/)
**Who can do this:** the Owners of the account. A Billing member cannot cancel: the message names the Owners who can.
Cancelling a paid plan means moving the account to Free. The subscription ends at the close of the current billing period, not straight away, and you keep everything your plan gives you until then.
## Cancel the subscription [#cancel-the-subscription]
### Pick Free [#pick-free]
Open **Settings**, choose the **Account** tab, then **Plan & billing**. Under **Where you sit**, select **Free**, then **Downgrade to Free**.
### Read what will change [#read-what-will-change]
**Move to Free?** states the date the subscription ends, which workspaces become read-only and when they would be deleted, and which seats and projects stop accepting new work.
### Choose the workspace that stays active [#choose-the-workspace-that-stays-active]
If the account has more than one workspace, choose one under **Which workspace stays active**. Free includes one workspace.
### Confirm [#confirm]
Select **Downgrade to Free**. The message reads "The subscription ends on" the date, and that the account moves to Free then.
Until the period ends, **Plan & billing** shows **A change at the period end**. To keep your plan after all, select **Cancel scheduled change**, then confirm. "Cancellation withdrawn."
## When the account moves to Free [#when-the-account-moves-to-free]
- **One workspace stays active.** Its projects, keys, translations, glossary and history are all still there.
- **Every other workspace becomes read-only** and is deleted after the date shown, unless you upgrade or move it to another account first. Members can still read and export everything in it. An Owner can change which workspace stays active on the account's **Workspaces** page, under **Which workspace stays active on Free**.
- **The Free limits apply.** Seats and projects above the Free limits stop accepting new work, and the Free word allowance applies. Limits are listed on [transglot.ai/pricing](https://transglot.ai/pricing).
- **Features above Free stop**: the API, CLI and GitHub Action, webhooks, the in-context editor, the glossary and CDN publishing, and on higher plans quality mode, AI profiles, single sign-on, SCIM, the audit log and branding.
- **Usage-based billing stops**, because Free does not sell words beyond the plan.
If your app loads translations from the CDN, new translations stop being published to it once the account is on Free. Plan for that before the period ends.
A person can own one Free account at a time. If an Owner of this account already owns another Free account, this one has no words once it moves to Free: resubscribe, move its workspaces, or close it.
## Cancelling during a trial [#cancelling-during-a-trial]
Moving to Free during a trial ends the trial on its end date without a charge. "Trial words stop now, and features stay until then. Nothing is charged."
## Other ways to stop [#other-ways-to-stop]
- To stop paying and remove everything, [close the account](https://transglot.ai/docs/administration/billing/close-an-account).
- Deleting a workspace does not stop billing. See [Delete a workspace](https://transglot.ai/docs/administration/workspace/delete-a-workspace).
## Related [#related]
- [Change your plan](https://transglot.ai/docs/administration/billing/change-your-plan)
- [Move a workspace to another account](https://transglot.ai/docs/administration/workspace/move-a-workspace-to-another-account)
- [Close an account](https://transglot.ai/docs/administration/billing/close-an-account)
# Your plan and seats (https://transglot.ai/docs/administration/billing/your-plan-and-seats/)
**Who can use it:** the Owners and Billing members of the account. Workspace roles, Admin included, do not see billing.
## One plan for the whole account [#one-plan-for-the-whole-account]
Your workspaces belong to an **account**, and the plan belongs to the account, not to a workspace. One plan covers every workspace in the account: the plan's words are shared by all of them, and its limits on seats, projects, languages and workspaces are counted across all of them. See [Account Owners and Billing members](https://transglot.ai/docs/administration/team/account-owners-and-billing-members) for who manages the account.
The plans are **Free**, **Starter**, **Team**, **Business** and **Enterprise**, which is arranged with sales rather than bought at checkout. Open-source projects can apply for the [open source plan](https://transglot.ai/docs/administration/billing/open-source-plan). Current prices and allowances are on [transglot.ai/pricing](https://transglot.ai/pricing).
## The Plan & billing page [#the-plan--billing-page]
Open **Settings**, choose the **Account** tab, then **Plan & billing**. The page shows:
- **The header**: the plan and when it renews, and **Manage payment**, which opens the payment portal.
- **Plan**: the **Current plan**, its **Plan price**, when it **Renews**, the **Words included** each cycle, and the plan's **Workspaces**, **Seats**, **Projects** and **Languages**, and its **Translation speed**. On Free, it also shows your **Welcome words**.
- **Payment** and **Company details**: the card on file and what invoices are addressed to. See [Invoices and payment](https://transglot.ai/docs/administration/billing/invoices-and-payment).
- **Where you sit**: every plan side by side, with a **Pay annually** switch and the one action that changes your plan. See [Change your plan](https://transglot.ai/docs/administration/billing/change-your-plan).
- **Compare in detail**: what each plan includes, row by row.
- **Invoices** and **Promo code**.
The words you have used this cycle are on the account's **Usage** page. See [What counts towards my usage?](https://transglot.ai/docs/administration/billing/what-counts-towards-my-usage).
## How the limits are counted [#how-the-limits-are-counted]
The **Plan limits** card on the **Usage** page lists what your plan allows across the account, and what counts:
| Limit | What counts |
| --- | --- |
| **Seats** | "Anyone in any workspace of the account, account owners included, counted once." |
| **Projects** | "Every project in every workspace of the account." |
| **Languages** | "Every distinct language across the account's projects, the source language included." A language one project already uses is free to add to another. |
| **Workspaces** | "Every workspace of the account." Free and the open source plan include one workspace. |
A waiting invitation holds a seat until it is accepted or expires. Team and the plans above it have no seat limit.
When a limit is reached, the action that would pass it is refused, and the message names the account's Owners, who can upgrade or free room.
## What each plan adds [#what-each-plan-adds]
| Feature | Lowest plan that includes it |
| --- | --- |
| API, CLI and GitHub Action | Starter |
| Webhooks | Starter |
| In-context editor | Starter |
| Glossary | Starter |
| CDN publishing | Starter |
| Quality mode | Team |
| AI profiles | Team |
| Service level agreement | Business |
| Single sign-on | Enterprise |
| SCIM provisioning | Enterprise |
| Audit log | Enterprise |
| White labelling | Enterprise |
| Priority support | Enterprise |
Roles, custom roles and per-project and per-language access are included on every plan, Free too.
**Translation speed** also rises with the plan: **Normal** on Free and Starter, **High** on Team, and **Max speed** on Business and Enterprise.
## Welcome words on Free [#welcome-words-on-free]
A new Free account receives welcome words on top of the monthly allowance. Part arrives when the account is activated, and the rest after a one-time mobile number check on the account's **Welcome words** page ("Each number works once."). Welcome words come once per person. The cycle's words are spent first, so a quiet month costs the welcome words nothing. Welcome words are used only on Free. The amounts are listed on [transglot.ai/pricing](https://transglot.ai/pricing).
## Related [#related]
- [Change your plan](https://transglot.ai/docs/administration/billing/change-your-plan)
- [What counts towards my usage?](https://transglot.ai/docs/administration/billing/what-counts-towards-my-usage)
- [Usage-based billing](https://transglot.ai/docs/administration/billing/usage-based-billing)
- [Invoices and payment](https://transglot.ai/docs/administration/billing/invoices-and-payment)
# Administration (https://transglot.ai/docs/administration/)
Administration in transglot happens on three levels, each with its own tab under **Settings**:
- **You**: your own profile, password and sign-in methods, notifications and appearance.
- **Workspace**: the people in one workspace, their roles, its security, single sign-on and branding.
- **Account**: the plan, usage, invoices and the Owners who manage the workspaces the account pays for.
## Common tasks [#common-tasks]
| I want to | Go to |
| --- | --- |
| Add a teammate | [Invite a teammate](https://transglot.ai/docs/administration/team/invite-a-teammate) |
| Give an agency access to one project | [Onboard a vendor or freelancer](https://transglot.ai/docs/administration/team/onboard-a-vendor-or-freelancer) |
| See what each role can do | [Roles and what each one can do](https://transglot.ai/docs/administration/team/roles-and-what-each-one-can-do) |
| Hand the account to someone else | [Account Owners and Billing members](https://transglot.ai/docs/administration/team/account-owners-and-billing-members) |
| Protect my login | [Turn on two-factor authentication](https://transglot.ai/docs/administration/security/turn-on-two-factor-authentication) |
| Make everyone use a second factor | [Require two-factor for a workspace](https://transglot.ai/docs/administration/security/require-two-factor-for-a-workspace) |
| Connect our identity provider | [Set up single sign-on](https://transglot.ai/docs/administration/security/set-up-single-sign-on) |
| Upgrade or switch to annual billing | [Change your plan](https://transglot.ai/docs/administration/billing/change-your-plan) |
| Keep translating past the plan's words | [Turn on usage-based billing](https://transglot.ai/docs/administration/billing/turn-on-usage-based-billing) |
| Download an invoice | [Invoices and payment](https://transglot.ai/docs/administration/billing/invoices-and-payment) |
## Who manages what [#who-manages-what]
| Role | What they manage |
| --- | --- |
| **Account Owner** | Everything: the plan and billing, every workspace of the account, single sign-on, SCIM, workspace two-factor requirements, branding, and deleting workspaces. |
| **Billing member** | The plan, the card, invoices, usage and company details. No access to workspaces. |
| **Admin** | One workspace: its members, roles, projects, access and integrations. Not billing. |
| **Developer, Reviewer, Translator** | Their own work in the workspace. See [Roles and what each one can do](https://transglot.ai/docs/administration/team/roles-and-what-each-one-can-do). |
# Add a passkey (https://transglot.ai/docs/administration/security/add-a-passkey/)
**Who can do this:** everyone, for their own login.
A passkey "never leaves the device and there is nothing to remember." It also counts as a second factor wherever a workspace requires two-factor authentication.
### Open Password & sign-in [#open-password--sign-in]
Open **Settings**, choose the **You** tab, then **Password & sign-in**. Confirm your password if you are asked.
### Add a passkey [#add-a-passkey]
Under **Passkeys**, select **Add passkey**.
### Name it [#name-it]
Enter a **Passkey name**, for example `MacBook Pro` or `iPhone`. "A name helps you identify this passkey later."
### Register it [#register-it]
Select **Register passkey** and follow your device's prompt: fingerprint, face, device PIN or a hardware security key.
## What happens next [#what-happens-next]
The passkey is listed under **Passkeys** with when it was **Added** and **Last used**. On the sign-in page you can now use it instead of typing your password.
Add one on each device you sign in from regularly.
## Remove a passkey [#remove-a-passkey]
Select **Remove** on its row, then **Remove passkey**. Removal is immediate: you can no longer use it to sign in. Keep another way in, such as your password or another passkey, before you remove your last one.
## If it doesn't work [#if-it-doesnt-work]
- **"Passkeys are not supported in this browser."**: use a browser or device that supports passkeys, or keep signing in with your password and two-factor authentication.
- **The device prompt does not appear**: check that your device has a screen lock or biometrics set up, then try again.
## Related [#related]
- [Secure your account](https://transglot.ai/docs/administration/security/secure-your-account)
- [Turn on two-factor authentication](https://transglot.ai/docs/administration/security/turn-on-two-factor-authentication)
- [Sign in to transglot](https://transglot.ai/docs/first-steps/sign-in)
# Require two-factor for a workspace (https://transglot.ai/docs/administration/security/require-two-factor-for-a-workspace/)
**Who can do this:** the Owners of the account that holds the workspace. The requirement is available on every plan.
With the requirement on, "Every member needs an authenticator app or a passkey on their login before they can open this workspace." It requires that each member holds a second factor, not that every sign-in asks for one: someone returning through a linked Google or GitHub sign-in is still signed straight in.
## Before you start [#before-you-start]
Add a second factor to your own login first: [turn on two-factor authentication](https://transglot.ai/docs/administration/security/turn-on-two-factor-authentication) or [add a passkey](https://transglot.ai/docs/administration/security/add-a-passkey). The page refuses to turn the requirement on while you hold none, because it would lock you out of the workspace.
### Open Security [#open-security]
Open **Settings**, choose the **Workspace** tab, then **Security**.
### Check who it affects [#check-who-it-affects]
**Who this affects** lists the members who do not hold a second factor yet. "Turning the requirement on now would close this workspace to them until they add an authenticator app or a passkey."
### Turn it on [#turn-it-on]
Turn on **Require two-factor for everyone**. The confirmation says how many members must still add one.
### Confirm [#confirm]
Select **Require two-factor**. The message reads "Two-factor is now required for everyone in this workspace."
## What happens next [#what-happens-next]
- Members who already hold a second factor notice nothing.
- Each member without one gets an email explaining what to do. Until they add one, opening the workspace takes them to their own security settings to set one up. Their login is not locked.
- Only the members who were short a factor when you turned the requirement on are emailed. Anyone who joins later, or removes their last passkey or turns off their authenticator, appears under **Who this affects** but is not told.
- The change is recorded in the audit log.
The **People** page shows the requirement under **Policy**, and its two-factor column shows who holds a second factor.
## Who is exempt [#who-is-exempt]
A member is exempt when an identity provider that enforces sign-in claims their email domain, even when that provider is configured in another workspace. The exception is an Owner of the account whose workspace configured the provider: an Owner keeps a password way in, so they are not exempt. See [Set up single sign-on](https://transglot.ai/docs/administration/security/set-up-single-sign-on).
## Turn the requirement off [#turn-the-requirement-off]
Turn off **Require two-factor for everyone**, then select **Stop requiring two-factor**. "Members can open" the workspace "without an authenticator app or a passkey. Members who already added one keep it, and nothing else about signing in changes."
## If it doesn't work [#if-it-doesnt-work]
- **"Turn on an authenticator app or add a passkey for your own login first."**: add a second factor to your own login, then try again.
- **You are locked out of People**: the **People** page sits behind the requirement too. If it is keeping you out, turn the requirement off on **Security** first.
- **You do not see Security in the menu**: you are not an Owner of the account that holds the workspace.
## Related [#related]
- [Turn on two-factor authentication](https://transglot.ai/docs/administration/security/turn-on-two-factor-authentication)
- [Add a passkey](https://transglot.ai/docs/administration/security/add-a-passkey)
- [The People page](https://transglot.ai/docs/administration/team/members-and-roles)
# Secure your account (https://transglot.ai/docs/administration/security/secure-your-account/)
**Who can do this:** everyone, for their own login.
Open **Settings**, choose the **You** tab, then **Password & sign-in**. You may be asked to confirm your password before the page opens. The page lists "Every way in to your login, and the way to take each of them back."
## Password [#password]
Enter your **Current password** ("Confirms it is really you making the change."), then the **New password** and **Confirm password**, and select **Save**. Changing your password signs every other session out.
Use a long, random password kept in a password manager.
## Two-factor authentication [#two-factor-authentication]
The **Authenticator app** row adds a one-time code from an app on your phone to every sign-in with your password. When you turn it on you receive recovery codes, which are your way back in if you lose the phone. See [Turn on two-factor authentication](https://transglot.ai/docs/administration/security/turn-on-two-factor-authentication).
## Passkeys [#passkeys]
A passkey "signs you in with the device you are holding": your fingerprint, face, device PIN or a hardware security key, instead of a password. See [Add a passkey](https://transglot.ai/docs/administration/security/add-a-passkey).
## Connected accounts [#connected-accounts]
If you signed up or signed in with Google or GitHub, that sign-in is listed under **Connected accounts**, with when it was connected and last used. A connected account signs you in without your password, and it keeps working after you change your password.
To revoke one, select **Disconnect** on its row and confirm. "Disconnecting takes effect immediately. If you find you cannot sign in afterwards, request a password reset from the sign-in page and follow the link sent to the email address you sign in with."
## A strong setup [#a-strong-setup]
The methods are independent, and you can hold all of them at once:
- A passkey on each device you sign in from, for everyday use.
- A password with two-factor authentication as the fallback.
- Your recovery codes stored somewhere other than the phone that holds your authenticator app.
A workspace can also require every member to hold a second factor. An authenticator app or a passkey both count. See [Require two-factor for a workspace](https://transglot.ai/docs/administration/security/require-two-factor-for-a-workspace).
## Related [#related]
- [Turn on two-factor authentication](https://transglot.ai/docs/administration/security/turn-on-two-factor-authentication)
- [Add a passkey](https://transglot.ai/docs/administration/security/add-a-passkey)
- [Sign in to transglot](https://transglot.ai/docs/first-steps/sign-in)
- [I can't sign in](https://transglot.ai/docs/resources/troubleshooting/i-cant-sign-in)
# Set up SCIM provisioning (https://transglot.ai/docs/administration/security/set-up-scim-provisioning/)
**Who can do this:** the Owners of the account that holds the workspace, on the Enterprise plan.
Set up and test [single sign-on](https://transglot.ai/docs/administration/security/set-up-single-sign-on) first, including verifying your email domain. SCIM only provisions email addresses at the connection's verified domain, and the people it provisions sign in through your identity provider.
### Open Single sign-on & SCIM [#open-single-sign-on--scim]
Open **Settings**, choose the **Workspace** tab, then **Single sign-on & SCIM**, and find **4. Directory sync (SCIM 2.0)**.
### Enable SCIM [#enable-scim]
Select **Enable SCIM**.
### Copy the token [#copy-the-token]
**Copy your SCIM token** shows the bearer token. "Shown only once. Paste it into your IdP's SCIM connector now. We store only its hash and cannot recover it." Select **Copy**, then **Done**.
### Configure your identity provider [#configure-your-identity-provider]
In your identity provider's SCIM connector, enter the **SCIM base URL**, `https://api.transglot.ai/scim/v2`, and the token as a bearer token. Then assign the users and groups who should have access.
### Map directory groups to roles (optional) [#map-directory-groups-to-roles-optional]
Under **Directory groups to roles**, select **Add mapping** for each group whose members should get a role other than Translator. See below.
## What your directory can do [#what-your-directory-can-do]
| Your directory does | What happens in the workspace |
| --- | --- |
| Assigns a user | They are added as a member. Unmapped users arrive as Translator. |
| Changes a user's role or group | Their role changes, within the limits below. |
| Deactivates a user (`active: false`) or deletes them | They are removed from this workspace. Their login is kept, because they may belong to other workspaces. |
| Pushes a group you mapped | Every member your directory puts in that group holds the role you chose. |
"Deactivating a user in your directory revokes their access here, except an Owner of" the account, "who keeps access through the account until you remove them from it." The account's Owners get an email when that happens.
Every user provisioned or deprovisioned through SCIM is recorded in the [audit log](https://transglot.ai/docs/administration/security/the-audit-log).
## Map directory groups to roles [#map-directory-groups-to-roles]
### Add a mapping [#add-a-mapping]
Under **Directory groups to roles**, select **Add mapping**.
### Identify the group [#identify-the-group]
Fill in the **Group ID**, the **Group name**, or both. The group ID is "Your provider's stable id for the group. Survives a rename." If you give both, the group ID is what transglot matches on. Group names are matched ignoring capitalisation.
### Choose the role [#choose-the-role]
Choose the **Role**: Admin, Developer, Reviewer, Translator or one of your custom roles. Select **Create mapping**.
"Group mapping created. It is applied on the next directory sync."
How roles are decided:
- **A group you mapped** is applied exactly as you set it, on every sync, because you created the mapping inside transglot.
- **A group or role you have not mapped** is raw directory data. A value named after a role the workspace has (such as `admin`, `developer`, `reviewer` or `translator`) is honoured up to Admin. Anything else, including a group called "owner", gives Translator. A mis-sync in your directory can never hand out more than an admin holds.
- **No sync, mapped or not, makes anyone an Owner of the account.** Account Owners are set on the account's **Owners & billing members** page.
- **Map every group you want kept in sync.** The groups your provider can read back are the built-in roles and the groups you mapped. An unmapped group is applied once, when your provider first pushes it, and your provider's next update to it fails with "Group not found".
Removing a mapping does not change anyone's current role. "Members already at that role keep it until your next directory sync, which is when the mapping stops being applied."
## Rotate the token or turn SCIM off [#rotate-the-token-or-turn-scim-off]
- **Rotate token** issues a new token and stops the old one working. Do this if the token may have been exposed, and update your identity provider straight away, because provisioning stops until you do.
- **Disable SCIM**: "The bearer token stops working and your directory stops syncing, so joiners and leavers will no longer reach this workspace on their own. Members already here keep their access. Turning SCIM back on mints a new token."
If the account moves off the Enterprise plan, provisioning stops at once. Your directory can still read and remove members for 30 days afterwards, so leavers are still removed.
## Technical reference [#technical-reference]
| Item | Value |
| --- | --- |
| Base URL | `https://api.transglot.ai/scim/v2` |
| Authentication | `Authorization: Bearer ` |
| Users | `GET /Users` (paged with `startIndex` and `count`, at most 100 a page), `POST /Users`, `GET /Users/`, `PUT` or `PATCH /Users/`, `DELETE /Users/` |
| Groups | `GET /Groups`, `POST /Groups`, `PUT` or `PATCH /Groups/`, `DELETE /Groups/` |
| Filter | `userName eq "person@example.com"` |
| User attributes read | `userName` (or the first `emails` value), `displayName` (or `name.givenName` and `name.familyName`), `active`, and an optional `role` or `roles` |
| Rate limit | 120 requests a minute per token |
`userName` must be an email address at the connection's verified domain. Other addresses are refused with an error naming the domain.
## If it doesn't work [#if-it-doesnt-work]
- **The token was not copied**: rotate it and copy the new one. A token cannot be recovered.
- **Provisioning fails**: check the base URL is exactly `https://api.transglot.ai/scim/v2`, including the version segment, and that the token is current.
- **"userName must be an address at a verified domain."**: verify your email domain under single sign-on first.
- **Everyone lands as Translator**: the group has no mapping, or the mapping's group ID does not match the one your provider sends. Try mapping on the group name instead.
- **Your provider reports "Group not found" for a group it synced before**: that group has no mapping. Add one, keyed on the group ID your provider sends.
- **"Another mapping already claims that directory group ID."** or **"Another mapping already claims that directory group name."**: edit the existing mapping instead. Names are compared ignoring capitalisation, so `Engineering-Leads` and `engineering-leads` are the same name.
- **"... is the name of a built-in role, which is already its own group here. Use your directory group's own ID or name instead."**: a group named `admin`, `developer`, `reviewer` or `translator` already provisions that role without a mapping.
## Related [#related]
- [Set up single sign-on](https://transglot.ai/docs/administration/security/set-up-single-sign-on)
- [The People page](https://transglot.ai/docs/administration/team/members-and-roles)
- [The audit log](https://transglot.ai/docs/administration/security/the-audit-log)
# Set up single sign-on (https://transglot.ai/docs/administration/security/set-up-single-sign-on/)
**Who can do this:** the Owners of the account that holds the workspace, on the Enterprise plan. Admins cannot: identity configuration decides who may enter the workspace at all, and an admin who could change it could give themselves a way back in after being removed.
The page puts it this way: "Configure it yourself: no support ticket, no engineering call. Verify your domain, test the connection, then enforce."
## Before you start [#before-you-start]
- Admin access to your identity provider, to create an application for transglot.
- Control of your email domain's DNS, to publish a TXT record.
- Choose the protocol. It "cannot be changed once the connection is saved."
| Protocol | Use it for | What you enter in transglot |
| --- | --- | --- |
| **SAML 2.0 (self-managed)** | Any SAML 2.0 identity provider, such as Okta, Microsoft Entra ID, Google Workspace or JumpCloud | **IdP entity ID**, **SSO URL**, **Signing certificate** |
| **OpenID Connect** | Any OpenID Connect provider, such as Microsoft Entra ID, Google Workspace, Okta, Auth0 or Keycloak | **Issuer URL**, **Client ID**, **Client secret** |
### Open Single sign-on & SCIM [#open-single-sign-on--scim]
Open **Settings**, choose the **Workspace** tab, then **Single sign-on & SCIM**.
### Describe your identity provider [#describe-your-identity-provider]
Under **1. Your identity provider**, choose the **Protocol** and enter your **Email domain**, for example `acme.com`. Then fill in the protocol's fields (see below) and select **Save configuration**.
### Prove you own the domain [#prove-you-own-the-domain]
Under **2. Prove you own** your domain, publish the TXT record shown on your domain's DNS. Its value starts with `transglot-domain-verification=`. Then select **Verify domain**. "Until the domain is verified, SSO cannot be enforced."
### Give your provider transglot's values [#give-your-provider-transglots-values]
Copy the values under **Values for your identity provider** into the application you created at your provider (see below). Copy them rather than typing them: a value that differs by one character fails at sign-in with an error from your provider.
### Test the connection [#test-the-connection]
Under **3. Test the connection**, select **Test connection**. The result lists each check that passed, or the first one that failed.
### Require SSO [#require-sso]
Once the domain is verified and the test passes, turn on **Require SSO for everyone in** your workspace, read the confirmation, then select **Require SSO**.
## SAML 2.0 fields [#saml-20-fields]
In transglot:
| Field | What to enter |
| --- | --- |
| **IdP entity ID** | "The issuer / entity ID your identity provider publishes, e.g. http://www.okta.com/exk1a2b3c." |
| **SSO URL** | "The IdP's HTTP-POST single-sign-on endpoint. Must be a public https URL." |
| **Signing certificate** | "The IdP's X.509 public certificate (PEM). Write-only: once saved, we only ever tell you whether it is present." |
At your identity provider, from **Values for your identity provider**:
| Value | Pattern |
| --- | --- |
| **Assertion consumer service (ACS) URL** | `https://app.transglot.ai/sso//acs` |
| **Service provider entity ID (audience)** | shown on the page |
| **SP metadata URL** | `https://app.transglot.ai/sso//metadata` |
`` is specific to your workspace's connection. The values appear once the configuration is saved.
transglot reads the person's email address from the SAML NameID, or from an `email`, `mail` or `emailaddress` attribute. It reads their name from `displayName` or `name`, or `givenName` and `sn`, and an optional role from a `role` or `roles` attribute.
## OpenID Connect fields [#openid-connect-fields]
In transglot:
| Field | What to enter |
| --- | --- |
| **Issuer URL** | Your provider's issuer. For Microsoft Entra ID, `https://login.microsoftonline.com//v2.0`, using the tenant ID rather than `common`. For Google Workspace, `https://accounts.google.com`. transglot reads the provider's `/.well-known/openid-configuration` from it. |
| **Client ID** | "The application (client) ID your provider issued for transglot." |
| **Client secret** | "Write-only: once saved, we only ever tell you whether it is present." |
At your identity provider, register the **Redirect URI (callback)** shown on the page. Its pattern is `https://app.transglot.ai/sso//oidc/callback`.
transglot asks for the `openid email profile` scopes, and reads the person's email address, their name, and an optional `role` or `roles` claim.
## What happens when SSO is required [#what-happens-when-sso-is-required]
"Everyone with an email address ending in @" your domain "is sent to your identity provider when they sign in with a password or a passkey, and signing in with Google or GitHub stops working for them." People with an address at any other domain sign in as they do now.
The Owners of the account keep their password and passkey sign-in, so a broken connection cannot lock you out. Someone has to be able to get in and turn enforcement off if the identity provider is unreachable.
## Who gets in, and with what role [#who-gets-in-and-with-what-role]
- **Existing members** sign in as they are. An SSO sign-in never changes an existing member's role.
- **New people at your verified domain** are added to the workspace the first time they sign in through your identity provider, as long as the workspace can take new members. They arrive as Translator.
- **A role sent by your provider** (`role` or `roles`) is honoured up to Admin, and only when the person is first added. "owner", an unknown value or no value gives Translator.
- **What SSO can never grant**: it never makes anyone an Owner of the account. Account Owners are set on the account's **Owners & billing members** page.
The sign-in only works for an email address at the connection's verified domain, which is what stops one workspace's identity provider signing people into another.
To keep roles in step with your directory after people join, set up SCIM. See [Set up SCIM provisioning](https://transglot.ai/docs/administration/security/set-up-scim-provisioning).
## Change or remove the connection [#change-or-remove-the-connection]
- Changing the **Email domain** resets its verification and its connection test, so enforcement stays off until both pass again.
- Pointing the connection at a different identity provider resets the test and enforcement until you test the new one.
- To stop requiring SSO, turn off **Require SSO for everyone in** your workspace and select **Stop requiring SSO**. People at your domain can then sign in with a password, a passkey, Google or GitHub again.
- **Remove SSO** deletes the connection and its SCIM token. "Everyone keeps their login and signs in with a password again, so make sure they have one set before you do this." Select **Remove connection** to confirm.
Every configuration change, connection test and SSO sign-in is recorded in the [audit log](https://transglot.ai/docs/administration/security/the-audit-log).
## If it doesn't work [#if-it-doesnt-work]
- **"Verify the domain and pass a connection test to unlock enforcement."**: the switch stays locked until both are done. Enforcing an untested connection could lock everyone out at once.
- **"No matching TXT record found on ... DNS can take a few minutes to propagate."**: wait, then select **Verify domain** again.
- **"... is already verified by another workspace."**: a domain can be verified by one workspace only.
- **"The signing certificate could not be parsed."** or **"That does not look like a PEM-encoded X.509 certificate."**: paste the full PEM certificate, including its BEGIN and END lines.
- **"The signing certificate expired on ..."**: download the current certificate from your provider.
- **"The issuer URL must use https."**: use your provider's https issuer.
- **"The issuer has changed, so the stored client secret no longer applies. Enter the secret from the new provider."**
- **"Enforcement is configured. It activates once an SSO provider with a login flow is connected. Until then, password login is not refused."**: finish the protocol's fields and verify the domain.
- **People cannot sign in**: see [My single sign-on login fails](https://transglot.ai/docs/resources/troubleshooting/my-single-sign-on-login-fails).
## Related [#related]
- [Set up SCIM provisioning](https://transglot.ai/docs/administration/security/set-up-scim-provisioning)
- [Require two-factor for a workspace](https://transglot.ai/docs/administration/security/require-two-factor-for-a-workspace)
- [My single sign-on login fails](https://transglot.ai/docs/resources/troubleshooting/my-single-sign-on-login-fails)
# The audit log (https://transglot.ai/docs/administration/security/the-audit-log/)
**Who can read it:** admins and the Owners of the account that holds the workspace, on the Enterprise plan. Members whose custom role includes **Read the audit log** can read it too.
The workspace audit log is "Every security-relevant act in this workspace: who let someone in, who granted power, who minted a credential. Append-only: entries are never edited or removed." Entries are kept for as long as the workspace exists, and are removed with it when a workspace is deleted.
transglot records these events on every plan. Reading and exporting the log is an Enterprise feature, so if you move to Enterprise, earlier entries are already there.
## Read the log [#read-the-log]
### Open the audit log [#open-the-audit-log]
Open **Settings**, choose the **Workspace** tab, then **Audit log**.
### Filter by action [#filter-by-action]
Under **Events**, entries are listed newest first, each with the act, who did it (or "by the system"), its **Category** and **When**. Use **Filter by action** to show one kind of event, or **All actions** for everything.
### Export to CSV [#export-to-csv]
Select **Export CSV** to download the log, or the filtered part of it, as a spreadsheet. The export holds every matching entry, with the time, action, the person's name and email address, what the act was about, the IP address and the details recorded with it.
## What is recorded [#what-is-recorded]
| Area | Examples of recorded acts |
| --- | --- |
| People and access | Member invited, joined, role changed or removed; invitations revoked or sent again; custom roles created, updated or deleted; review policy changed; two-factor requirement changed |
| Credentials | API tokens, publishable keys and CDN keys created or revoked; translations exported; export links ended |
| Integrations | Webhook endpoints; the Slack channel; Jira, GitHub, GitLab, Bitbucket and Azure Repos; CMS, Dropbox, Google Drive and S3 connections; integration add-ons; migration imports |
| Identity | SSO configured, tested or disabled; SSO sign-ins; SCIM token rotated or SCIM disabled; users provisioned or deprovisioned through SCIM; directory group mappings |
| Assignments | Translators assigned; assignments started, submitted, approved, sent back or withdrawn |
| Workspace and projects | Workspace renamed, moved to another account, deletion requested or cancelled; project web address changed; languages removed; projects deleted; branding updated |
The audit log is the security record. A project's activity feed is the product history of keys, translations and runs. Use activity to find out when a string changed, and the audit log to find out who was given the ability to change it. See [Project activity](https://transglot.ai/docs/guides/projects/project-activity).
## The account log [#the-account-log]
Changes to the account itself (its plan, card, invoices, seats, people and workspaces) are recorded in a separate **Account log**. Open **Settings**, choose the **Account** tab, then **Account log**. Use **Filter by category** to narrow it.
- Account Owners and Billing members can read the account log, on every plan.
- Billing members see the billing entries only, without the **IP address** column.
- Only account Owners can select **Export CSV**.
## If it doesn't work [#if-it-doesnt-work]
- **"Audit log is an Enterprise feature"**: "We record every security-relevant act regardless of plan. Reading and exporting the trail is an Enterprise feature." The panel has a **Contact sales** button, because Enterprise is arranged with sales rather than bought at checkout.
- **"Nothing to audit yet"**: nothing auditable has happened in this workspace yet.
- **"No entries for that action."**: the filter matches nothing. Choose **All actions**.
- **Audit log is not in the Workspace settings menu**: your role does not include reading the audit log.
## Related [#related]
- [Roles and what each one can do](https://transglot.ai/docs/administration/team/roles-and-what-each-one-can-do)
- [Set up SCIM provisioning](https://transglot.ai/docs/administration/security/set-up-scim-provisioning)
- [Project activity](https://transglot.ai/docs/guides/projects/project-activity)
# Turn on two-factor authentication (https://transglot.ai/docs/administration/security/turn-on-two-factor-authentication/)
**Who can do this:** everyone, for their own login. It matters most for admins and account Owners, who control access and billing.
Before you start, install an authenticator app that supports time-based codes (TOTP) on your phone, and decide where you will keep your recovery codes. Do not keep them on the same phone.
### Open Password & sign-in [#open-password--sign-in]
Open **Settings**, choose the **You** tab, then **Password & sign-in**. Confirm your password if you are asked.
### Start the setup [#start-the-setup]
Under **Two-factor authentication**, in the **Authenticator app** row, select **Enable 2FA**.
### Pair your app [#pair-your-app]
Scan the QR code with your authenticator app, or enter the setup key shown under "or, enter the code manually". Select **Continue**.
### Enter a code [#enter-a-code]
Type the 6-digit code your app shows, then select **Continue**.
### Save your recovery codes [#save-your-recovery-codes]
Under **2FA recovery codes**, select **View recovery codes** and store them somewhere safe, such as a password manager.
## What happens next [#what-happens-next]
The **Authenticator app** row shows **Enabled**. From now on, signing in with your password also asks for a code from your app.
Recovery codes let you get back in if you lose the phone. Each code works once. To replace them, select **Regenerate codes**: "The recovery codes you have now stop working immediately, including any you printed or saved."
If you closed the setup before entering a code, the row offers **Continue setup** so you can finish with the code you already scanned.
## Turn two-factor off [#turn-two-factor-off]
Select **Disable 2FA**. The confirmation explains that signing in with your password will no longer ask for a code and that your recovery codes stop working. It also names any workspace that requires two-factor and would stop opening for you, unless you still hold a passkey, which counts as a second factor. Select **Turn off two-factor** to confirm.
## If it doesn't work [#if-it-doesnt-work]
- **The code is rejected**: check that your phone sets its clock automatically. Time-based codes fail when the clock drifts.
- **You lost the phone**: on the code screen when you sign in, choose **log in using a recovery code** and enter one of your codes. Then set up two-factor again on the new phone.
- **You lost both the phone and the recovery codes**: contact support. See [Get help](https://transglot.ai/docs/resources/get-help).
## Related [#related]
- [Secure your account](https://transglot.ai/docs/administration/security/secure-your-account)
- [Add a passkey](https://transglot.ai/docs/administration/security/add-a-passkey)
- [Require two-factor for a workspace](https://transglot.ai/docs/administration/security/require-two-factor-for-a-workspace)
- [I can't sign in](https://transglot.ai/docs/resources/troubleshooting/i-cant-sign-in)
# Account Owners and Billing members (https://transglot.ai/docs/administration/team/account-owners-and-billing-members/)
Your workspaces belong to an **account**, and the account is what holds the plan, the card and the invoices. The people who manage an account have one of two roles on it, separate from any workspace role:
| Account role | What it covers |
| --- | --- |
| **Owner** | "Everything, including closing the account and inviting Owners. Takes a seat." An Owner reaches every workspace of the account with full control, and holds the four permissions no workspace role can have. |
| **Billing** | "The plan, the card, invoices and company details. No access to workspaces." |
**Who can do this:** account Owners. Billing members do not see the **Owners & billing members** page.
## Open the page [#open-the-page]
Open **Settings**, choose the **Account** tab, then **Owners & billing members**. It lists:
- **People who manage this account**: every Owner and Billing member, with their **Role** and when they were **Added**.
- **Waiting to accept**: open invitations, with the inviter and when each expires.
- **Everyone with a seat**: "One seat per person, counted once however many workspaces they reach.", with the workspaces each person reaches and when they were last active.
## Invite an Owner or a Billing member [#invite-an-owner-or-a-billing-member]
### Start the invitation [#start-the-invitation]
Select **Invite someone**.
### Enter the address and role [#enter-the-address-and-role]
Enter the **Email address** and choose the **Role on this account**: Owner or Billing.
### Send it [#send-it]
Select **Send invitation**. "They get an email with a link that works for seven days. The invitation is listed under Waiting to accept until they accept it or an Owner revokes it."
Sending a second invitation to the same address replaces its link, and the link in the earlier email stops working. To withdraw an invitation, select **Revoke** on its row.
## Change someone's account role [#change-someones-account-role]
Pick the new role in the person's **Role** column. The message confirms it, for example "Dana is now Owner on this account."
- A person must confirm their email address before they can become an Owner. If they have not, transglot sends them a link: promote them again after they open it.
- A person can own one Free account at a time, so someone who already owns a Free account cannot become an Owner of another Free account.
- While a payment for the account has failed, new Owners are paused. An invitation as Billing still works, so someone can fix the payment.
## Hand ownership to someone else [#hand-ownership-to-someone-else]
An account always needs at least one Owner. To pass the account on:
### Make the new person an Owner [#make-the-new-person-an-owner]
Invite them as an Owner, or change their existing role to **Owner**.
### Wait until they have accepted [#wait-until-they-have-accepted]
Their row must show them as an Owner under **People who manage this account**.
### Step back yourself [#step-back-yourself]
Select **Leave this account** on your own row, or ask the new Owner to change you to Billing or remove you.
If you try to leave or step down as the last Owner, the page refuses: "needs at least one Owner. Make someone else an Owner first."
To move a single workspace to a different account rather than handing over the whole account, see [Move a workspace to another account](https://transglot.ai/docs/administration/workspace/move-a-workspace-to-another-account).
## Remove an Owner or a Billing member [#remove-an-owner-or-a-billing-member]
Select **Remove** on their row. The confirmation explains that they lose access to billing and to the implicit control of the account's workspaces, that workspaces where they are also a member keep that membership, and that pending invitations they sent are revoked.
The dialog also lists access the person created that keeps working after they leave (API tokens, webhooks, CDN keys, publishable keys and CMS connections), with when each was created and last used. Tick the items you want revoked at the same time. "Unchecked items keep working after" they leave.
## Free a seat [#free-a-seat]
Under **Everyone with a seat**, **Remove from every workspace** takes a person out of every workspace of the account at once. They keep their standing on the account, and anything they created keeps working. An Owner reaches every workspace through the account, so you change an Owner to Billing before you can free their seat.
## Related [#related]
- [Roles and what each one can do](https://transglot.ai/docs/administration/team/roles-and-what-each-one-can-do)
- [Your plan and seats](https://transglot.ai/docs/administration/billing/your-plan-and-seats)
- [Close an account](https://transglot.ai/docs/administration/billing/close-an-account)
# Change a teammate's role (https://transglot.ai/docs/administration/team/change-a-teammates-role/)
**Who can do this:** admins, the Owners of the account that holds the workspace, and members whose role includes **Invite, re-role and remove members**. The picker only offers roles that carry no more than you hold.
### Find the person [#find-the-person]
Open **Settings**, choose the **Workspace** tab, then **People**. Find their row under **Who reaches what**.
### Pick the new role [#pick-the-new-role]
Choose the new role in the **Role** column: Admin, Developer, Reviewer, Translator or one of your custom roles.
### Confirm [#confirm]
The confirmation asks "Change" followed by their name and the new role, describes the role, and adds "It applies straight away, and you can change it back." Select **Change role**.
## What happens next [#what-happens-next]
The change applies at once, and the message reads "Role updated." followed by their name and new role. The change is recorded in the workspace audit log. The person is emailed their previous and new role, and the workspace's other admins and the account Owners receive a security email about it.
A role is a set of permissions, not a step on a ladder. Moving someone from Developer to Reviewer takes away adding keys and running AI translation, and gives them approving. Moving them from Reviewer to Translator takes approving and assignment reviews away. [Roles and what each one can do](https://transglot.ai/docs/administration/team/roles-and-what-each-one-can-do) lists every permission.
To change what someone can do on one project only, use a project grant instead. See [Grant access to one project](https://transglot.ai/docs/administration/team/grant-access-to-one-project).
## Account Owners are not changed here [#account-owners-are-not-changed-here]
The Owners of the account are listed under **Account Owners**, with no role picker, because they reach the workspace through the account. Nobody is made an account Owner from **People**. Their access is changed on the account's **Owners & billing members** page. See [Account Owners and Billing members](https://transglot.ai/docs/administration/team/account-owners-and-billing-members).
## If it doesn't work [#if-it-doesnt-work]
- **The Role column shows a role but no picker**: you cannot change that person's role.
- **The picker reads "A role this workspace no longer has"**: their custom role was deleted. Pick one that exists.
- **"You can only grant a role carrying capabilities you hold yourself"**: the role carries permissions you do not hold. Ask an admin or an account Owner.
- **The workspace is read-only**, for example while it waits to be deleted: a change that only takes permissions away still goes through, and any other change is refused with the reason.
## Related [#related]
- [Roles and what each one can do](https://transglot.ai/docs/administration/team/roles-and-what-each-one-can-do)
- [Grant access to one project](https://transglot.ai/docs/administration/team/grant-access-to-one-project)
- [The People page](https://transglot.ai/docs/administration/team/members-and-roles)
# Create a custom role (https://transglot.ai/docs/administration/team/create-a-custom-role/)
**Who can do this:** admins, the Owners of the account that holds the workspace, and members whose role includes **Invite, re-role and remove members**. Custom roles are available on every plan.
The four built-in roles cover most workspaces. A custom role is for a job title that does not match one of them. It holds exactly the permissions you tick, and you can only tick permissions you hold yourself.
### Open Roles [#open-roles]
Open **Settings**, choose the **Workspace** tab, then **Roles**, and select **New role**.
### Name it [#name-it]
Fill in **Name** (for example `Lead Linguist`) and the **Identifier**, which takes lowercase letters, numbers and hyphens (for example `lead-linguist`) and must be unique in the workspace. The names of the built-in roles are reserved. Add an optional **Description**, for example `Keeps the glossary for the German market.`
### Choose a level [#choose-a-level]
Pick **Translator level**, **Developer level** or **Admin level**. The level only orders the role against the built-in ones in the permissions table and in who may hand it out. It does not grant anything on its own: the permissions do that.
### Tick the permissions [#tick-the-permissions]
The permissions are grouped under **Project**, **Organization** and **Assignment**. The table behind the panel shows the role you are assembling beside the roles that already exist, so you can compare them before you save.
### Create the role [#create-the-role]
Select **Create role**. The message reads "Role “Lead Linguist” created." with your role's name.
The role now appears in the role pickers on **People**, in the invitation dialog and on project grants.
## What a custom role can never do [#what-a-custom-role-can-never-do]
- It can never hold the four permissions that belong to the Owners of the account: deleting the workspace, configuring single sign-on and SCIM, requiring two-factor for everyone, and managing white-label branding. These rows are marked "Account owners only. No workspace role can hold it."
- It never bypasses a per-project grant, the way an account Owner or an admin does. A member with a custom role, even at **Admin level**, can still be narrowed on one project.
- Languages are not narrowed on the role. "Narrowing this to specific languages is set on a per-project grant, not here."
## Edit or delete a custom role [#edit-or-delete-a-custom-role]
Select **Edit** on the role's row, change it, then select **Save role**. Changing a role changes what everyone holding it can do, immediately.
Select **Delete** to remove a role. If people hold it, choose a role for them under **Move them to** before you select **Delete role**, so nobody is left pointing at a role that no longer exists. If nobody holds it, nothing else changes.
## If it doesn't work [#if-it-doesnt-work]
- **"You can only grant capabilities you hold yourself."**: you ticked a permission your own role does not carry. Ask an admin or an account Owner to create the role.
- **"You cannot move members to a role that carries more than you hold"**: choose a replacement role with no more authority than your own.
- **"Choose a different role: this is the one being deleted."**: pick another role under **Move them to**.
## Related [#related]
- [Roles and what each one can do](https://transglot.ai/docs/administration/team/roles-and-what-each-one-can-do)
- [Change a teammate's role](https://transglot.ai/docs/administration/team/change-a-teammates-role)
- [Grant access to one project](https://transglot.ai/docs/administration/team/grant-access-to-one-project)
# Grant access to one project (https://transglot.ai/docs/administration/team/grant-access-to-one-project/)
**Who can do this:** admins, the Owners of the account that holds the workspace, and members whose workspace role includes **Grant per-project access**. A project grant cannot give this permission.
A project grant overrides a member's workspace role on that project only. Someone who is a Translator across the workspace can be a Developer on one project, or the other way round. A grant can also narrow a member to the locales they may write and approve in.
### Open Project access [#open-project-access]
Open **Settings**, choose the **Workspace** tab, pick the project, then open **Project access**.
### Choose the member [#choose-the-member]
Under **Project access**, pick the person in **Member to grant**.
### Choose their role on this project [#choose-their-role-on-this-project]
Pick the **Role on this project**.
### Limit the locales (optional) [#limit-the-locales-optional]
In the box that reads **locales (blank = all)**, list the locales they may work in, for example `de, pt-BR`. Leave it empty for every locale in the project.
### Grant access [#grant-access]
Select **Grant access**. The message reads "Access granted. An email is on its way to" followed by their name, "with what they can work on."
## What happens next [#what-happens-next]
The grant is listed under **Project access** with the person, their **Role here**, and their locales (or **all locales**). Locale limits are enforced on writing and approving: a member limited to German can open the project but can only edit and approve German.
Admins and account Owners always have full access to every project and cannot be limited. A grant for one of them is refused: "Account owners and admins already have full access to every project."
## Revoke a grant [#revoke-a-grant]
Select **Revoke** on the grant's row, then **Revoke access**. This removes the project-level grant only. Their workspace role applies again, which may still give them access to the project, and the work they have already done is untouched.
The **Assignments** section on the same page assigns a language to a translator as a tracked piece of work. Assigning opens that language to them and takes nothing away. To confine a translator to some languages, set the locales on their grant before you assign. An existing grant for all locales has to be revoked and granted again to narrow it. See [Assign a language to a translator](https://transglot.ai/docs/guides/translating/assign-a-language-to-a-translator).
## If it doesn't work [#if-it-doesnt-work]
- **"Unknown locale"**: use BCP-47 tags such as `de` or `pt-BR`.
- **"You can only grant a role carrying capabilities you hold yourself"**: pick a role with no more authority than your own.
- **The member is not in the list**: the list holds members whose workspace role is Developer, Reviewer or Translator and who have no grant on this project yet. Admins and account Owners already have full access. To change an existing grant, revoke it and grant it again. Someone who is not in the workspace yet has to be [invited](https://transglot.ai/docs/administration/team/invite-a-teammate) first.
## Related [#related]
- [Onboard a vendor or freelancer](https://transglot.ai/docs/administration/team/onboard-a-vendor-or-freelancer)
- [Roles and what each one can do](https://transglot.ai/docs/administration/team/roles-and-what-each-one-can-do)
- [Assign a language to a translator](https://transglot.ai/docs/guides/translating/assign-a-language-to-a-translator)
# Invite a teammate (https://transglot.ai/docs/administration/team/invite-a-teammate/)
**Who can do this:** admins, the Owners of the account that holds the workspace, and members whose role includes **Invite, re-role and remove members**. You can only invite someone at a role that carries no more than you hold.
### Open People [#open-people]
Open **Settings**, choose the **Workspace** tab, then **People**, and select **Invite someone**. The dialog has three steps and sends nothing until the last one.
### Enter the address and role [#enter-the-address-and-role]
Enter the **Email address**, then choose the **Role**: Admin, Developer, Reviewer, Translator or one of your custom roles. Each choice says what the role is for, and roles with more authority than your own are not offered. Select **Choose a scope**.
### Choose what they can open [#choose-what-they-can-open]
Leave **What they can open** on **All projects** for a normal teammate. To onboard a vendor or freelancer, pick one project instead: they will see nothing else in the workspace. Once you pick a project, **Locales they will own** appears. Leave it empty for every locale in that project, or narrow it, for example `de, pt-BR`.
### Review and send [#review-and-send]
Select **Review the invite**, check **What they will see**, then select **Send the invite**.
## What happens next [#what-happens-next]
The invitation appears under **Waiting to accept** on **People**, with its role, its project if it has one, and the date it expires, seven days after you send it. The person receives an email with a private link that takes them through signing in or signing up. Accepting adds them to the workspace with that role and, for a scoped invitation, the project access it promised. See [Accept an invitation](https://transglot.ai/docs/first-steps/accept-an-invitation).
A waiting invitation reaches nothing until it is accepted, but it holds a seat on your plan from the moment you send it until it is accepted or expires.
## Resend, change or revoke an invitation [#resend-change-or-revoke-an-invitation]
Until it is accepted, the invitation's row offers:
- **Resend**: sends the same link again. The link in the first email keeps working, and the invitation then expires seven days from the day you resend.
- **Revoke**: ends it after you confirm. The link in their email stops working.
If you type an address that already has an invitation waiting, the dialog stops on its first step and shows the waiting invitation (role, what they can open, when it was sent and when it expires). Upper and lower case do not matter. You then choose:
- **Resend the same invite**: the same as **Resend** on the row.
- **Change this invite**: continues through the dialog with the current values filled in. The last step lists **What changes**, and the button reads **Change and send the invite**. Changing it creates a new link, so the link in the first email stops working.
When the waiting invitation is at a role you cannot hand out, or at a role the workspace no longer has, **Change this invite** is the only choice, and **Resend** is not on its row.
## If it doesn't work [#if-it-doesnt-work]
- **"An invitation to ... is already waiting to be accepted."**: use **Resend the same invite** or **Change this invite**.
- **"That user is already a member."**: change their role on **People** instead.
- **"You cannot invite someone at a role with more authority than you hold."**: ask an admin or an Owner of the account to send it.
- **"That project does not belong to this workspace."**: the project you picked is not in this workspace.
- **"Unknown locale: use BCP-47 tags like de or pt-BR."**: one of the locale tags is not recognised.
- **"Nothing was sent to ..."**: email to that address is being held back, usually because an earlier message to it bounced. Nothing was saved, so a waiting invitation is unchanged.
- **"... is already a member of this workspace, so there was nothing to send."** after **Resend**: they joined another way. Revoke the invitation.
- **"The invitation to ... has expired and its link no longer works."**: invite them again.
- When the account has no free seat on its plan, the invitation is refused with the reason. Free a seat or upgrade the plan, then send it again. Changing an invitation that is already waiting is not refused this way, because it already holds its seat.
## Related [#related]
- [Onboard a vendor or freelancer](https://transglot.ai/docs/administration/team/onboard-a-vendor-or-freelancer)
- [Roles and what each one can do](https://transglot.ai/docs/administration/team/roles-and-what-each-one-can-do)
- [The People page](https://transglot.ai/docs/administration/team/members-and-roles)
# The People page (https://transglot.ai/docs/administration/team/members-and-roles/)
**People** is where you manage the members of one workspace. Open **Settings**, choose the **Workspace** tab, then **People**.
**Who can use it:** admins, the Owners of the account that holds the workspace, and members whose custom role includes **Invite, re-role and remove members**. Translators, reviewers and developers do not see the page.
## What the page shows [#what-the-page-shows]
### Invite someone [#invite-someone]
The **Invite someone** button at the top opens the invitation dialog. See [Invite a teammate](https://transglot.ai/docs/administration/team/invite-a-teammate).
### Account Owners [#account-owners]
When the Owners of the account reach this workspace, they are listed first, under **Account Owners**. The card reads "They control every workspace in" followed by the account's name, "and each takes one seat." Each row shows a name, an email address and whether that person holds a second factor. There is no role picker and no **Remove** on these rows, because their access is "changed on the account, not here". An account Owner also sees **Manage**, which opens the account's **Owners & billing members** page.
### Waiting to accept [#waiting-to-accept]
Invitations nobody has accepted yet, each with the role it was sent at (**Invited as**), what it will reach, and when it **Expires**. **Resend** appears beside an invitation at a role you can hand out, and **Revoke** beside every one. An unaccepted invitation reaches nothing.
### Who reaches what [#who-reaches-what]
Everyone else in the workspace, with their name and email address, their access (**all projects** or **project-scoped**), whether they hold a second factor, and their role. The role is a picker, and **Remove** takes someone out of the workspace. Both ask you to confirm first. While nobody but the account Owners reaches the workspace, this list reads "Nobody else reaches this workspace yet."
### What each role can do [#what-each-role-can-do]
The permissions table for every role in the workspace, including your custom roles. The same table is explained in [Roles and what each one can do](https://transglot.ai/docs/administration/team/roles-and-what-each-one-can-do).
### Policy [#policy]
Rules that apply to every project in the workspace:
- **Require a second reviewer**: "Nobody signs off a translation they wrote themselves, in any project, the account's Owners and admins included. Leave this off for a workspace where one person both translates and approves." The switch saves as you change it.
- The workspace's two-factor requirement, shown as **Required for everyone in this workspace** or **Not required in this workspace**, with a **Workspace security** button. Only an account Owner sees this row, and the switch itself is on the workspace **Security** page. See [Require two-factor for a workspace](https://transglot.ai/docs/administration/security/require-two-factor-for-a-workspace).
Each person who reaches any workspace of the account takes one seat, however many workspaces they reach. A waiting invitation also holds a seat until it is accepted or expires. Your plan's seat limit is listed on [transglot.ai/pricing](https://transglot.ai/pricing).
## Related [#related]
- [Invite a teammate](https://transglot.ai/docs/administration/team/invite-a-teammate)
- [Change a teammate's role](https://transglot.ai/docs/administration/team/change-a-teammates-role)
- [Remove a teammate](https://transglot.ai/docs/administration/team/remove-a-teammate)
- [Account Owners and Billing members](https://transglot.ai/docs/administration/team/account-owners-and-billing-members)
# Onboard a vendor or freelancer (https://transglot.ai/docs/administration/team/onboard-a-vendor-or-freelancer/)
**Who can do this:** admins, the Owners of the account that holds the workspace, and members whose role includes **Invite, re-role and remove members**.
Decide the project and the locales before you send the invitation. Scoping the invitation is what separates a contractor who sees one job from one who sees your whole workspace. As the **People** page puts it: "Widening a seat later is easy; narrowing one is a conversation."
### Start an invitation [#start-an-invitation]
Open **Settings**, choose the **Workspace** tab, then **People**, and select **Invite someone**.
### Enter their address and role [#enter-their-address-and-role]
Enter their **Email address** and choose **Translator** as the **Role**. Choose **Reviewer** instead if they should also approve translations. Select **Choose a scope**.
### Scope it to one project [#scope-it-to-one-project]
Under **What they can open**, pick the project they will work on instead of **All projects**.
### Name the locales [#name-the-locales]
In **Locales they will own**, list the languages, for example `de, pt-BR`. Leave it empty to give them every locale in that project.
### Review and send [#review-and-send]
Select **Review the invite**, check **What they will see**, then select **Send the invite**.
## What happens next [#what-happens-next]
When they accept, they join the workspace as a project-scoped member: they can open that one project and nothing else, and the **People** page shows their access as **project-scoped**. "Every other project, and every locale you leave out, is invisible to them." A project-scoped member also does not see the workspace's AI word usage.
A Translator can edit translations in the locales they hold and cannot approve them, so somebody else signs off their work. To give them a tracked job with a review step rather than open-ended access, assign them the language as well. See [Assign a language to a translator](https://transglot.ai/docs/guides/translating/assign-a-language-to-a-translator).
## If it doesn't work [#if-it-doesnt-work]
- **"That project does not belong to this workspace."**: the project you picked is not in this workspace.
- **"Unknown locale: use BCP-47 tags like de or pt-BR."**: check the locale tags.
- **They see nothing after accepting**: check their grant on the project's **Project access** page. See [Grant access to one project](https://transglot.ai/docs/administration/team/grant-access-to-one-project).
## Related [#related]
- [Invite a teammate](https://transglot.ai/docs/administration/team/invite-a-teammate)
- [Grant access to one project](https://transglot.ai/docs/administration/team/grant-access-to-one-project)
- [Remove a teammate](https://transglot.ai/docs/administration/team/remove-a-teammate)
# Remove a teammate (https://transglot.ai/docs/administration/team/remove-a-teammate/)
**Who can do this:** admins, the Owners of the account that holds the workspace, and members whose role includes **Invite, re-role and remove members**.
Removing a person does not revoke the API or deploy tokens they created. Tokens belong to the project, not to the person. If they created any, revoke those separately. See [Deploy tokens](https://transglot.ai/docs/developers/deploy-tokens).
### Find the person [#find-the-person]
Open **Settings**, choose the **Workspace** tab, then **People**. Find their row under **Who reaches what**.
### Remove them [#remove-them]
Select **Remove**. The confirmation names them and says: "They lose access to every project in this workspace straight away. Translations and reviews they have already done keep their name on them."
### Confirm [#confirm]
Select **Remove member**.
## What happens next [#what-happens-next]
They lose access to the workspace at once, and a message names who was removed from which workspace. The removal is recorded in the audit log. They are emailed that they were removed, and the workspace's other admins and the account Owners receive a security email about it. Their translations, reviews and history stay as they are.
Removing someone from one workspace frees their seat only if they reach no other workspace of the account. To take a person out of every workspace of the account at once, an account Owner can use **Remove from every workspace** on the account's **Owners & billing members** page.
## If it doesn't work [#if-it-doesnt-work]
- **There is no Remove on an account Owner**: the Owners of the account are listed under **Account Owners**, not under **Who reaches what**, because they reach every workspace through the account. They are removed on the account's **Owners & billing members** page, which refuses to remove the last Owner. See [Account Owners and Billing members](https://transglot.ai/docs/administration/team/account-owners-and-billing-members).
- **There is no Remove on anyone's row**: your role does not include removing members.
- **The person is managed by your directory**: if your workspace uses SCIM provisioning, remove them in your identity provider as well, so your directory and the workspace stay in step. See [Set up SCIM provisioning](https://transglot.ai/docs/administration/security/set-up-scim-provisioning).
## Related [#related]
- [Change a teammate's role](https://transglot.ai/docs/administration/team/change-a-teammates-role)
- [The People page](https://transglot.ai/docs/administration/team/members-and-roles)
- [Deploy tokens](https://transglot.ai/docs/developers/deploy-tokens)
# Roles and what each one can do (https://transglot.ai/docs/administration/team/roles-and-what-each-one-can-do/)
Every member of a workspace holds one role. A role is a set of permissions, not a rank on a ladder: Reviewer and Developer each add something different to what a Translator can do, and Admin holds both sets. The Owners of the account that holds the workspace are not given a role at all: they hold every permission through the account.
Admins and account Owners see the same table in the app, under **What each role can do** on the **People** and **Roles** settings pages. It is built from the same rules the app enforces, and your workspace's custom roles appear in it as extra columns.
## The built-in roles [#the-built-in-roles]
| Role | What it is for |
| --- | --- |
| **Translator** | Writes translations. Cannot approve their own work. |
| **Reviewer** | Writes and approves translations, and reviews assigned work. Cannot add keys or run AI translation. |
| **Developer** | Ships the integration: keys, languages, glossary and AI translation. |
| **Admin** | Runs the workspace: members, projects, access and approvals. |
| **Account owner** | Pays for this workspace through its account, and holds every permission in it. |
## Permissions by role [#permissions-by-role]
Row labels match the app.
| Permission | Translator | Reviewer | Developer | Admin | Account owner |
| --- | :-: | :-: | :-: | :-: | :-: |
| View the workspace | Yes | Yes | Yes | Yes | Yes |
| View projects, keys and translations | Yes | Yes | Yes | Yes | Yes |
| Edit translations | Yes | Yes | Yes | Yes | Yes |
| Edit translations in scoped locales | Yes | Yes | Yes | Yes | Yes |
| Approve (sign off) translations | No | Yes | No | Yes | Yes |
| Approve translations in scoped locales | No | Yes | No | Yes | Yes |
| View assignment work orders | No | Yes | No | Yes | Yes |
| Review (approve or request changes on) assignments | No | Yes | No | Yes | Yes |
| Add and remove languages | No | No | Yes | Yes | Yes |
| Add and edit keys | No | No | Yes | Yes | Yes |
| Run AI translation, QA and self-heal | No | No | Yes | Yes | Yes |
| Manage in-context screenshots | No | No | Yes | Yes | Yes |
| Manage glossary terms | No | No | Yes | Yes | Yes |
| Create projects | No | No | No | Yes | Yes |
| Edit project settings | No | No | No | Yes | Yes |
| Delete a project | No | No | No | Yes | Yes |
| Grant per-project access | No | No | No | Yes | Yes |
| Assign translators | No | No | No | Yes | Yes |
| Create and revoke API tokens | No | No | No | Yes | Yes |
| Manage publishable keys | No | No | No | Yes | Yes |
| Manage webhooks | No | No | No | Yes | Yes |
| Manage the CMS connection | No | No | No | Yes | Yes |
| Manage CDN delivery keys | No | No | No | Yes | Yes |
| Invite, re-role and remove members | No | No | No | Yes | Yes |
| Read the audit log | No | No | No | Yes | Yes |
| Manage integrations | No | No | No | Yes | Yes |
| Rename the workspace | No | No | No | Yes | Yes |
| Delete the workspace | No | No | No | No | Yes |
| Configure single sign-on and SCIM | No | No | No | No | Yes |
| Require two-factor for everyone in the workspace | No | No | No | No | Yes |
| Manage white-label branding | No | No | No | No | Yes |
| See this workspace's AI words | Yes | Yes | Yes | Yes | Yes |
A few rows need a note:
- The rows marked "in scoped locales" can be narrowed to specific languages on a per-project grant. See [Grant access to one project](https://transglot.ai/docs/administration/team/grant-access-to-one-project).
- The last four permission rows read "Account owners only. No workspace role can hold it." in the app. No built-in or custom role can carry them.
- **See this workspace's AI words** is held by every member except one limited to some projects.
- **Read the audit log** is a permission on every plan, but the log itself can be read on the Enterprise plan only. See [The audit log](https://transglot.ai/docs/administration/security/the-audit-log).
- Submitting an assignment for review is not a role permission. The translator an assignment is given to submits it.
## Edit versus approve [#edit-versus-approve]
The split worth understanding is between writing a translation and signing it off. A Translator or a Developer can edit a value but cannot approve it; the Reviewer is the role made for the second person. If you also turn on **Require a second reviewer** on the **People** page, nobody signs off a translation they wrote themselves, in any project, account Owners and admins included.
## Billing is not a workspace role [#billing-is-not-a-workspace-role]
No workspace role, Admin included, can see or change the plan, the card or the invoices. Those belong to the account, and its Owners and Billing members manage them. See [Account Owners and Billing members](https://transglot.ai/docs/administration/team/account-owners-and-billing-members).
## Custom roles and project grants [#custom-roles-and-project-grants]
- A custom role holds exactly the permissions ticked for it, and sits in the table beside the built-in role whose level it was given. See [Create a custom role](https://transglot.ai/docs/administration/team/create-a-custom-role).
- A per-project grant gives a member a different role on one project, and can narrow them to specific languages. Admins and account Owners always have full access and cannot be narrowed this way.
## Related [#related]
- [The People page](https://transglot.ai/docs/administration/team/members-and-roles)
- [Change a teammate's role](https://transglot.ai/docs/administration/team/change-a-teammates-role)
- [Grant access to one project](https://transglot.ai/docs/administration/team/grant-access-to-one-project)
- [Invite a teammate](https://transglot.ai/docs/administration/team/invite-a-teammate)
# Custom branding (https://transglot.ai/docs/administration/workspace/custom-branding/)
**Who can do this:** the Owners of the account that holds the workspace. Custom branding (white-label) is available on the Enterprise plan.
Branding is set per workspace and applies to every member of it. The three settings do not all appear in the same place, so check which is which before you promise a client anything:
| Setting | Where it appears |
| --- | --- |
| **Accent colour** | Across the console, for everyone in this workspace. |
| **Product name** | In the header of the printable quality scorecard, on scorecards you share by link, and in the scorecard CSV export in place of the workspace name. |
| **Logo** | In the header of the printable quality scorecard and on scorecards you share by link. |
The console header and the browser tab are not branded.
### Open Branding [#open-branding]
Open **Settings**, choose the **Workspace** tab, then **Branding**.
### Set the product name [#set-the-product-name]
Enter the **Product name**, for example `Acme Localization`. It can be up to 60 characters.
### Upload a logo [#upload-a-logo]
Choose an image file under **Logo**, up to 1 MB. A preview appears. To take a logo off, select **Remove current logo**.
### Pick an accent colour [#pick-an-accent-colour]
Turn on **Use a custom accent colour** and pick the colour. "Off keeps the colour the console ships with."
### Save [#save]
Select **Save branding**. The message reads "Branding updated." The change is recorded in the audit log.
## If it doesn't work [#if-it-doesnt-work]
- **"White-label the console"** with a **Contact sales** button: the workspace's account is not on the Enterprise plan. Enterprise is arranged with sales rather than bought at checkout.
- **Branding is not in the Workspace settings menu**: you are not an Owner of the account that holds the workspace.
- **The logo does not upload**: use an image file of 1 MB or less.
## Related [#related]
- [The per-language scorecard](https://transglot.ai/docs/guides/quality/the-per-language-scorecard)
- [Workspace settings](https://transglot.ai/docs/administration/workspace/workspace-settings)
- [Your plan and seats](https://transglot.ai/docs/administration/billing/your-plan-and-seats)
# Delete a workspace (https://transglot.ai/docs/administration/workspace/delete-a-workspace/)
**Who can do this:** the Owners of the account that holds the workspace. No workspace role can delete it, Admin included, because it ends the workspace for everyone in it.
The account keeps its plan. If this is the account's last workspace and the account pays for a plan, the card says so before you confirm: the account keeps billing with no workspaces. To stop billing, change the plan or [close the account](https://transglot.ai/docs/administration/billing/close-an-account).
Before you start, export anything you need. When the countdown ends, the workspace and every project, translation, usage record and audit entry in it are removed permanently.
### Open General settings [#open-general-settings]
Open **Settings**, choose the **Workspace** tab, then **General**.
### Start the deletion [#start-the-deletion]
Under **Delete this workspace**, select **Delete workspace**.
### Type the workspace name [#type-the-workspace-name]
Type the workspace's name into the **Workspace name** box exactly as it is written.
### Confirm [#confirm]
Select **Delete workspace**.
**Delete** on the workspace's row on the account's **Workspaces** page takes you to the same card.
## What happens next [#what-happens-next]
- The workspace becomes read-only at once, for 30 days. Every member can still read everything and export, and nobody can change anything. A banner tells everyone in the workspace, because they lose it too.
- The message reads "Deletion scheduled. Deleting the workspace does not cancel the subscription, so we have emailed you how to cancel it on the billing page."
- The account's **Workspaces** page shows the workspace as "Scheduled for deletion on" a date.
- When the countdown ends, the workspace and everything in it are removed permanently. It cannot be restored after that.
## Cancel the deletion [#cancel-the-deletion]
Until the countdown ends, any Owner of the account can select **Cancel deletion** on the banner. The workspace is writable again straight away, and the message reads "Deletion cancelled. The workspace is no longer read-only."
A cancellation can be refused when the workspace no longer fits the account's plan, for example when the account is on Free and already has its one active workspace. The message names what to upgrade or delete first.
## If it doesn't work [#if-it-doesnt-work]
- **"Type the workspace name exactly to confirm."**: the name must match exactly.
- **You do not see Delete this workspace**: you are not an Owner of the account that holds the workspace.
- **Every change is refused during the countdown**: that is the read-only state, not a fault.
## Related [#related]
- [Workspace settings](https://transglot.ai/docs/administration/workspace/workspace-settings)
- [Delete a project](https://transglot.ai/docs/guides/projects/delete-a-project)
- [Close an account](https://transglot.ai/docs/administration/billing/close-an-account)
# Move a workspace to another account (https://transglot.ai/docs/administration/workspace/move-a-workspace-to-another-account/)
**Who can do this:** a person who is an Owner of both accounts: the one the workspace is in now, and the one it moves to. Only accounts you own are offered as destinations.
To move a workspace to an account you do not own, ask an Owner of that account to make you an Owner of it first. You can then move the workspace, and they can remove you afterwards. See [Account Owners and Billing members](https://transglot.ai/docs/administration/team/account-owners-and-billing-members).
### Start the move [#start-the-move]
Open the workspace's **General** settings and select **Move to another account**, or select **Move** on the workspace's row on the account's **Workspaces** page.
### Choose the destination [#choose-the-destination]
Under **Destination**, pick the account to move the workspace to. If you own no other account, the page offers **New account** so you can create one first.
### Read what changes [#read-what-changes]
**What changes** lists what the move does: the plan the workspace runs on afterwards, the seats, projects and languages it brings against the destination's plan, and any features the destination's plan does not include. Tick each change to confirm it.
### Choose which credentials to revoke [#choose-which-credentials-to-revoke]
**Credentials in** the workspace lists its tokens and keys. "Ticked credentials are revoked when" the workspace moves. Those whose creator loses access to the workspace start ticked. "Unchecked credentials keep working after" the move.
### Confirm the move [#confirm-the-move]
Select **Move workspace**, type the workspace's name, then select **Move to** followed by the destination account's name.
## What happens next [#what-happens-next]
The message names the workspace, the account it moved to, and the plan it now runs on, for example "Docs moved to Acme Inc. It now runs on Team." From then on:
- The workspace runs on the destination account's plan, and the destination account pays for it.
- "Words already used this cycle stay on" the old account's usage. Invoices already issued stay with the old account.
- Features the destination's plan does not include stop working in the workspace once it moves.
- If the workspace used single sign-on, enforcement for its email domain stops, and the domain must be verified again in the new account.
- A workspace that was read-only because the old account was on Free becomes active, if the destination has room for it.
The move is recorded in the workspace's audit log.
## If it doesn't work [#if-it-doesnt-work]
The page explains why a move cannot go ahead yet. The common reasons:
- **The destination's plan has no room**: its plan allows fewer workspaces, seats, projects or languages than the move needs. Upgrade the destination first.
- **"... has an unpaid invoice ... Pay it before moving workspaces out."**: settle the old account's invoice on **Plan & billing**.
- **"... is scheduled for deletion. Cancel the deletion first."**: cancel the workspace's deletion, then move it.
- **The workspace is on the open source plan**: moving it would end the account's open source plan, so the page asks you to contact support to move the grant. The open source plan covers one workspace, so an account on it cannot receive another one either.
- **"You can move a workspace only between two accounts you own."**: become an Owner of the destination account first.
- **"You tried several moves in a minute. Wait a minute, then try again."**
## Related [#related]
- [Workspace settings](https://transglot.ai/docs/administration/workspace/workspace-settings)
- [Account Owners and Billing members](https://transglot.ai/docs/administration/team/account-owners-and-billing-members)
- [Your plan and seats](https://transglot.ai/docs/administration/billing/your-plan-and-seats)
# Workspace settings (https://transglot.ai/docs/administration/workspace/workspace-settings/)
A workspace's **General** settings page holds what the workspace is called, where it posts, the account it belongs to, and the one way to close it. Open **Settings**, choose the **Workspace** tab, then **General**.
**Who can use it:** every member can open the page. What each person can change depends on their role:
| Card | Who can change it |
| --- | --- |
| **Workspace name** | Admins and account Owners (permission **Rename the workspace**) |
| **Slack notifications** | Admins and account Owners (permission **Manage integrations**) |
| **The account it belongs to** | Read-only for members. Account Owners also see **Open account** and **Move to another account**. |
| **Delete this workspace** | Account Owners only |
When nothing on the page is yours to change, it says: "Nothing here is yours to change. An admin can rename this workspace and connect Slack, and only an Owner of its account can delete it."
## Rename the workspace [#rename-the-workspace]
### Enter the new name [#enter-the-new-name]
Under **Workspace name**, type the new name.
### Save it [#save-it]
Select **Save name**. The message reads "Workspace renamed to" followed by the new name.
The name is "Shown across the app, on your exports and in the emails this workspace sends." The workspace's web address does not change, so existing links, bookmarks and README badges keep working. The rename is recorded in the audit log.
## Connect Slack [#connect-slack]
Paste a Slack incoming-webhook URL into **Slack incoming-webhook URL** to post batch, QA, comment and review events to a channel. Select **Save**, or **Save & send test** to check the channel straight away. **Disconnect** stops the channel receiving this workspace's alerts. See [Connect Slack](https://transglot.ai/docs/integrations/notifications/connect-slack) for the full setup.
## The account it belongs to [#the-account-it-belongs-to]
This card names the account that pays for the workspace, its plan, and its Owners, for example "Acme Localization belongs to Acme Inc, on Team." Ask the Owners it lists about the plan, the card and the invoices.
- **Open account** opens the account's settings, for its Owners and Billing members.
- **Move to another account** starts moving the workspace to a different account you own. See [Move a workspace to another account](https://transglot.ai/docs/administration/workspace/move-a-workspace-to-another-account).
## Delete the workspace [#delete-the-workspace]
**Delete this workspace** starts a countdown before the workspace is removed. See [Delete a workspace](https://transglot.ai/docs/administration/workspace/delete-a-workspace).
## Other workspace settings [#other-workspace-settings]
The **Workspace** tab of **Settings** also holds:
- **People** and **Roles**: see [The People page](https://transglot.ai/docs/administration/team/members-and-roles) and [Create a custom role](https://transglot.ai/docs/administration/team/create-a-custom-role).
- **Security**: see [Require two-factor for a workspace](https://transglot.ai/docs/administration/security/require-two-factor-for-a-workspace).
- **Single sign-on & SCIM**: see [Set up single sign-on](https://transglot.ai/docs/administration/security/set-up-single-sign-on).
- **Branding**: see [Custom branding](https://transglot.ai/docs/administration/workspace/custom-branding).
- **Audit log**: see [The audit log](https://transglot.ai/docs/administration/security/the-audit-log).
## Related [#related]
- [Delete a workspace](https://transglot.ai/docs/administration/workspace/delete-a-workspace)
- [Move a workspace to another account](https://transglot.ai/docs/administration/workspace/move-a-workspace-to-another-account)
- [Workspaces and projects](https://transglot.ai/docs/concepts/workspaces-and-projects)
# Cancel a batch (https://transglot.ai/docs/api-reference/batches/cancel-batch/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get a batch (https://transglot.ai/docs/api-reference/batches/get-batch/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List batches (https://transglot.ai/docs/api-reference/batches/list-batches/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Retry a batch's failed pairs (https://transglot.ai/docs/api-reference/batches/retry-failed-batch/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Read one published version (https://transglot.ai/docs/api-reference/cdn/get-bundle-version/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Read the latest published bundle (https://transglot.ai/docs/api-reference/cdn/get-latest-bundle/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Publish a locale to the CDN (https://transglot.ai/docs/api-reference/cdn/publish-locale/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Create a glossary term (https://transglot.ai/docs/api-reference/glossary/create-glossary-term/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Delete a glossary term (https://transglot.ai/docs/api-reference/glossary/delete-glossary-term/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Export the glossary (https://transglot.ai/docs/api-reference/glossary/export-glossary/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Extract glossary candidates (https://transglot.ai/docs/api-reference/glossary/extract-glossary-candidates/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Import a glossary file (https://transglot.ai/docs/api-reference/glossary/import-glossary/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List glossary terms (https://transglot.ai/docs/api-reference/glossary/list-glossary-terms/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Replace a glossary term (https://transglot.ai/docs/api-reference/glossary/update-glossary-term/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# API reference (https://transglot.ai/docs/api-reference/)
The reference is generated from the API's OpenAPI document, so each page shows the exact parameters, request body, responses and errors of one operation. For how the API behaves as a whole (authentication, errors, rate limits, versioning), start with the [REST API overview](https://transglot.ai/docs/developers/api).
## Base URL and authentication [#base-url-and-authentication]
```bash
curl https://api.transglot.ai/v1/project \
-H "Authorization: Bearer $TRANSGLOT_TOKEN"
```
Every request under `/v1` sends a project [deploy token](https://transglot.ai/docs/developers/deploy-tokens) as a bearer token. The token decides which project the request acts on, so no URL carries a workspace or project identifier. Each operation needs one ability on the token, shown on its page. The two CDN read operations take a CDN key instead.
Bodies are JSON unless an operation says otherwise. Errors use the problem format described in [Errors](https://transglot.ai/docs/developers/api/errors), and a rate-limited request answers `429` with a `Retry-After` header ([Rate limits](https://transglot.ai/docs/developers/api/rate-limits)). API access needs the Starter plan or higher.
## Sections [#sections]
## Download the spec [#download-the-spec]
The OpenAPI 3.1 document behind these pages is published at [/openapi/transglot-v1.yaml](https://transglot.ai/docs/openapi/transglot-v1.yaml). Import it into an API client or a code generator to work against the API with typed requests.
# Get the project (https://transglot.ai/docs/api-reference/project/get-project/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Pull a locale as a file (https://transglot.ai/docs/api-reference/push-and-pull/pull/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Push a locale file (https://transglot.ai/docs/api-reference/push-and-pull/push/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Start a quality check (https://transglot.ai/docs/api-reference/quality/run-quality-check/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Start a translation run (https://transglot.ai/docs/api-reference/translation/translate/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Read one translation (https://transglot.ai/docs/api-reference/translations-single-values/get-translation/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Write one translation (https://transglot.ai/docs/api-reference/translations-single-values/put-translation/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Read many translations (https://transglot.ai/docs/api-reference/translations-single-values/read-translations/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Create a webhook endpoint (https://transglot.ai/docs/api-reference/webhooks/create-webhook/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Delete a webhook endpoint (https://transglot.ai/docs/api-reference/webhooks/delete-webhook/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get one event's catalog entry (https://transglot.ai/docs/api-reference/webhooks/get-webhook-event-sample/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List webhook events (https://transglot.ai/docs/api-reference/webhooks/list-webhook-events/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List webhook endpoints (https://transglot.ai/docs/api-reference/webhooks/list-webhooks/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# batch.completed (https://transglot.ai/docs/api-reference/webhooks/webhook-batch-completed/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# batch.failed (https://transglot.ai/docs/api-reference/webhooks/webhook-batch-failed/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# glossary.updated (https://transglot.ai/docs/api-reference/webhooks/webhook-glossary-updated/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# key.created (https://transglot.ai/docs/api-reference/webhooks/webhook-key-created/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# key.deleted (https://transglot.ai/docs/api-reference/webhooks/webhook-key-deleted/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# key.updated (https://transglot.ai/docs/api-reference/webhooks/webhook-key-updated/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# language.added (https://transglot.ai/docs/api-reference/webhooks/webhook-language-added/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# language.removed (https://transglot.ai/docs/api-reference/webhooks/webhook-language-removed/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# qa.completed (https://transglot.ai/docs/api-reference/webhooks/webhook-qa-completed/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# source_drift.repaired (https://transglot.ai/docs/api-reference/webhooks/webhook-source-drift-repaired/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# translation.reviewed (https://transglot.ai/docs/api-reference/webhooks/webhook-translation-reviewed/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# translation.updated (https://transglot.ai/docs/api-reference/webhooks/webhook-translation-updated/)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Authentication (https://transglot.ai/docs/developers/api/authentication/)
Every `/v1` request authenticates with a **deploy token** sent as a bearer token. The token belongs to one project, and the project it belongs to is the project the request acts on.
```bash title="Authenticated request"
curl https://api.transglot.ai/v1/project \
-H "Authorization: Bearer $TRANSGLOT_TOKEN"
```
## Deploy tokens [#deploy-tokens]
Owners and admins mint deploy tokens in the console under **Settings** → **Developer** → **API tokens**. See [Create a deploy token](https://transglot.ai/docs/developers/deploy-tokens) for the steps.
- **Send the whole value.** A token looks like `42|tgl_` followed by a random string. The number before the `|` is part of the credential.
- **Shown once.** The value appears once, at creation, and is stored hashed. If you lose it, revoke it and mint another.
- **Project-owned.** A token keeps working after the person who minted it leaves the workspace. Revoke it explicitly; revoking takes effect on the next request.
- **Expiry.** Choose **Never expires**, **30 days**, **90 days** or **365 days**. An expired token is refused with `401`, like a revoked one.
- **Limited to your own access.** You can only give a token abilities you hold yourself on that project.
transglot issues two other credentials that are not API tokens and do not work against `/v1`:
| Credential | Looks like | What it can do |
| --- | --- | --- |
| Deploy token | `42\|tgl_...` | Call the API with the abilities it was given |
| CDN key | `taicdn_...` | Read this project's published bundles from `GET /v1/cdn/...`, sent as `X-Transglot-Cdn-Key` or `?key=`. Nothing else |
| Publishable key | `taip_...` | Open the in-context editor in a browser. See [Publishable keys](https://transglot.ai/docs/developers/in-context/publishable-keys) |
## Abilities [#abilities]
A token carries one or more of five abilities. Each endpoint requires one, and abilities do not include each other: a `manage` token cannot read the glossary unless it also has `read`.
| Ability | Grants |
| --- | --- |
| `push` | Upload locale files |
| `pull` | Download locale files |
| `manage` | Start and stop paid work (translation runs, quality checks, glossary extraction), publish to the CDN, and change project configuration (glossary terms, webhooks) |
| `read` | Read single translation values and the glossary |
| `write` | Write single translation values |
### Ability per endpoint [#ability-per-endpoint]
| Endpoint | Ability |
| --- | --- |
| `GET /v1/project` | any of `push`, `pull`, `manage` |
| `POST /v1/push` | `push` |
| `GET /v1/pull` | `pull` |
| `POST /v1/translate` | `manage` |
| `GET /v1/batches` | any of `push`, `pull`, `manage` |
| `GET /v1/batches/{batch}` | any of `push`, `pull`, `manage` |
| `POST /v1/batches/{batch}/retry-failed` | `manage` |
| `POST /v1/batches/{batch}/cancel` | `manage` |
| `GET /v1/translations` | `read` |
| `POST /v1/translations/batch` | `read` |
| `PUT /v1/translations` | `write` |
| `POST /v1/qa/run` | `manage` |
| `POST /v1/cdn/publish` | `manage` |
| `GET /v1/glossary`, `GET /v1/glossary/export` | `read` |
| `POST /v1/glossary`, `PUT` and `DELETE /v1/glossary/{termId}`, `POST /v1/glossary/import`, `POST /v1/glossary/extract` | `manage` |
| `GET /v1/webhooks`, `GET /v1/webhooks/events`, `GET /v1/webhooks/events/{event}/sample` | any of `push`, `pull`, `manage` |
| `POST /v1/webhooks`, `DELETE /v1/webhooks/{webhook}` | `manage` |
A CI job that only syncs files needs `push` and `pull`. Give `manage` only to the jobs that start paid work or change configuration: it is the difference between a leaked token that can read strings and one that can start translation runs.
## 401: not authenticated [#401-not-authenticated]
A missing, malformed, unknown, revoked or expired token gets `401`:
```json title="401 Unauthorized"
{
"type": "/problems/unauthenticated",
"title": "Unauthenticated",
"status": 401,
"detail": "Unauthenticated."
}
```
The answer is the same for every reason, so a `401` never tells anyone whether a token existed. Check that the header is `Authorization: Bearer `, that you sent the whole value including the number and `|`, and that the token has not expired.
## 403: authenticated but refused [#403-authenticated-but-refused]
A `403` means the token is valid and the request was refused. Branch on `type`:
| `type` | Why | What to do |
| --- | --- | --- |
| `/problems/missing-ability` | The token lacks the ability the endpoint requires. `ability` names it | Mint a token with that ability |
| `/problems/plan-feature-required` | The account's plan does not include API access | An account owner upgrades the plan; the same token then works |
| `/problems/plan-limit` | The endpoint needs a plan feature the account does not have, for example quality checks | An account owner upgrades the plan |
| `/problems/ai-paused`, `/problems/workspace-read-only`, `/problems/workspace-closed` | The workspace's standing refuses this kind of request | An account owner resolves it in the console |
```json title="403 missing-ability"
{
"type": "/problems/missing-ability",
"title": "Missing ability",
"status": 403,
"detail": "The token is missing a required ability.",
"ability": "manage"
}
```
For an endpoint that accepts any of `push`, `pull` or `manage`, `ability` names the first of them, `push`.
A `403` does not clear by waiting, so do not retry it. [Errors](https://transglot.ai/docs/developers/api/errors) lists every problem type.
## Related [#related]
- [Create a deploy token](https://transglot.ai/docs/developers/deploy-tokens)
- [Errors](https://transglot.ai/docs/developers/api/errors)
- [Rate limits](https://transglot.ai/docs/developers/api/rate-limits)
- [API reference](https://transglot.ai/docs/api-reference)
# Errors (https://transglot.ai/docs/developers/api/errors/)
Every error from `api.transglot.ai` is an [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) problem document with `Content-Type: application/problem+json`. A client never has to parse prose to know what went wrong.
## The problem format [#the-problem-format]
```json title="422 Unprocessable Content"
{
"type": "/problems/locale-not-configured",
"title": "Locale not configured",
"status": 422,
"detail": "Locale \"pt-PT\" is not configured on this project."
}
```
| Member | What it is |
| --- | --- |
| `type` | `/problems/` followed by a slug. **Branch on this.** It is a stable identifier, not a URL to fetch |
| `title` | The slug in words: hyphens become spaces and the first letter is capitalised, so `/problems/rate-limited` has the title `Rate limited` |
| `status` | The HTTP status, repeated |
| `detail` | A sentence for a person reading a log. Its wording can change; do not parse it |
Some types add extension members beside these four, listed in the tables below. A `5xx` answer never carries internal detail: its `detail` is always `An unexpected error occurred.`, and an unexpected failure has the type `/problems/internal-error`. Retry a `5xx` with backoff.
## Error types [#error-types]
### Authentication and access [#authentication-and-access]
| `type` | Status | When | Extensions |
| --- | --- | --- | --- |
| `/problems/unauthenticated` | 401 | No token, or an unknown, revoked or expired one | |
| `/problems/missing-ability` | 403 | The token lacks the ability this endpoint requires | `ability` |
| `/problems/plan-feature-required` | 403 | The account's plan does not include API access (or, on the CDN read endpoints, CDN delivery) | |
| `/problems/plan-limit` | 403 | The endpoint needs a plan feature the account does not have: quality checks and glossary extraction need Team or higher; the glossary, webhooks and CDN publishing need Starter or higher | `resource`, `cap`, `upgrade_hint` |
| `/problems/ai-paused` | 403 | The workspace may not spend on AI or take in new work right now. Reads and single-value writes still work | |
| `/problems/workspace-read-only` | 403 | The workspace is read-only. Reads still work | |
| `/problems/workspace-closed` | 403 | The workspace is not available | |
| `/problems/free-account-held` | 403 | AI translation is paused for this workspace | |
| `/problems/email-verification-required` | 403 | AI translation starts once an owner of the account confirms their email address | |
### Requests [#requests]
| `type` | Status | When | Extensions |
| --- | --- | --- | --- |
| `/problems/not-found` | 404 | No such route, or the batch, term, key or endpoint is not in this project. Another project's ids answer `404`, never `403` | |
| `/problems/method-not-allowed` | 405 | The path exists but not with this HTTP method | |
| `/problems/validation-failed` | 422 | A field is missing or invalid, or a pushed file does not parse in the format you named | `errors`: field name to a list of messages |
| `/problems/locale-not-configured` | 422 | The locale is not a language of this project. A push never adds languages | |
| `/problems/active-batch` | 409 | A translation batch is already running for this project | `batch_id` of the running batch |
### Push and pull [#push-and-pull]
| `type` | Status | When | Extensions |
| --- | --- | --- | --- |
| `/problems/sync-removals-requires-source` | 422 | `mode=sync_removals` on a target-locale push | |
| `/problems/import-requires-target` | 422 | `import=repo` on a source-locale push | |
| `/problems/metadata-requires-source` | 422 | A metadata sidecar on a target-locale push | |
| `/problems/metadata-format-unsupported` | 422 | A metadata sidecar with a format that carries descriptions in the file itself | |
| `/problems/metadata-invalid` | 422 | The sidecar is not valid, or was sent as a form field instead of a file part | `errors` (each with `path`, `code`, `message`, at most 50) and `error_count` |
| `/problems/nested-key-collision` | 422 | A nested format cannot hold keys such as `checkout` and `checkout.submit` together | `keys` |
| `/problems/format-cannot-serialize` | 422 | The format cannot carry this project's keys | `format` |
### Glossary, webhooks and CDN [#glossary-webhooks-and-cdn]
| `type` | Status | When | Extensions |
| --- | --- | --- | --- |
| `/problems/glossary-term-exists` | 422 | An active term already uses this source term. Update that term instead | |
| `/problems/glossary-import-failed` | 422 | The import file could not be read | |
| `/problems/glossary-import-conflict` | 422 | Another write took a source term while the import ran. Retry | |
| `/problems/webhook-url-not-allowed` | 422 | The endpoint URL is not a public HTTPS address on port 443 | |
| `/problems/cdn-key-required` | 401 | A CDN read sent no key | |
| `/problems/cdn-key-invalid` | 401 | The CDN key is unknown or has been revoked | |
| `/problems/not-published` | 404 | The locale, version or format has no published bundle | |
| `/problems/invalid-format` | 422 | The `format` query parameter on a CDN read is not a known format | |
### Limits [#limits]
| `type` | Status | When | Extensions |
| --- | --- | --- | --- |
| `/problems/rate-limited` | 429 | Too many requests. See [Rate limits](https://transglot.ai/docs/developers/api/rate-limits) | Headers: `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` |
| `/problems/quota-exceeded` | 429 | The account has no AI words left this cycle, or translation beyond the plan is paused | `quota`: `reason`, `scope`, `requested`, `resets_at` |
| `/problems/extract-cap-reached` | 429 | The account, or this workspace's share of it, has used its glossary extractions for this cycle | `cap`: `kind`, `scope`, `resets_at` |
A `quota-exceeded` answer looks like this. `quota.reason` is `plan_allowance`, `spend_cap` or `overage_paused`, and `resets_at` is `null` when the reset is not known:
```json title="429 quota-exceeded"
{
"type": "/problems/quota-exceeded",
"title": "Quota exceeded",
"status": 429,
"detail": "The account this workspace belongs to has no AI words left for this cycle. They reset on 1 Nov 2026.",
"quota": {
"reason": "plan_allowance",
"scope": "account",
"requested": 4820,
"resets_at": "2026-11-01T00:00:00+00:00"
}
}
```
## Two answers that are not problem documents [#two-answers-that-are-not-problem-documents]
- **A push whose translation run could not start.** `POST /v1/push` still applies the file and answers `200`. The body says why the run did not start: `quota_exceeded: true`, or a code in `translation_paused`.
- **A conditional write that lost.** `PUT /v1/translations` with a stale `expected_hash` answers `409` with `{"error": "row-changed", "message": "...", "row": {...}}`, where `row` is the value as it stands now.
## Branching on errors [#branching-on-errors]
Decide by status first, then by `type`. A `403` or a `422` does not change by retrying; a `429` and a `5xx` can.
```ts title="handle-problem.ts"
type Problem = { type: string; title: string; status: number; detail: string; [extension: string]: unknown };
export async function startRun(token: string) {
const res = await fetch('https://api.transglot.ai/v1/translate', {
method: 'POST',
headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ scope: 'missing' }),
});
if (res.ok) return res.json(); // 202: the batch
const problem = (await res.json()) as Problem;
switch (problem.type) {
case '/problems/active-batch':
// Another run is going. Watch it instead of starting a second one.
return { watch: problem.batch_id };
case '/problems/rate-limited': {
const seconds = Number(res.headers.get('Retry-After') ?? '1');
await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
return startRun(token);
}
case '/problems/quota-exceeded':
// Lifts on its own at quota.resets_at (when set). Do not loop on it.
throw new Error(`No AI words left: ${problem.detail}`);
case '/problems/missing-ability':
throw new Error(`This token needs the "${problem.ability}" ability.`);
default:
throw new Error(`${problem.status} ${problem.type}: ${problem.detail}`);
}
}
```
## Related [#related]
- [Authentication](https://transglot.ai/docs/developers/api/authentication)
- [Rate limits](https://transglot.ai/docs/developers/api/rate-limits)
- [API reference](https://transglot.ai/docs/api-reference)
# REST API overview (https://transglot.ai/docs/developers/api/)
The transglot API covers everything the command line tool does, and more. It is scoped to a single project: the deploy token you send decides which one, so no URL carries a workspace or project identifier.
## Base URL [#base-url]
```text title="Base URL"
https://api.transglot.ai/v1
```
Every endpoint lives under `/v1`. The version is in the path and there is no version header to send. See [Versioning](https://transglot.ai/docs/developers/api/versioning) for what can change inside `/v1`.
## Authentication [#authentication]
Send a project [deploy token](https://transglot.ai/docs/developers/deploy-tokens) as a bearer token on every request:
```bash title="Your first request"
curl https://api.transglot.ai/v1/project \
-H "Authorization: Bearer $TRANSGLOT_TOKEN"
```
```json title="Response"
{
"id": 12,
"name": "Acme Web",
"slug": "acme-web",
"source_locale": "en",
"locales": [
{
"locale": "de",
"name": "German",
"rtl": false,
"is_source": false,
"progress": { "total": 1204, "reviewed": 310, "human": 42, "ai": 820, "empty": 32, "translated": 1172, "humanBacked": 352, "percent": 97 }
},
{ "locale": "en", "name": "English", "rtl": false, "is_source": true, "progress": null }
],
"keys_count": 1204,
"message_syntax": "auto",
"icu_dialect": "icu4c",
"auto_translate": true,
"first_run_pending": false
}
```
Each endpoint requires one ability on the token, such as `pull` or `manage`. [Authentication](https://transglot.ai/docs/developers/api/authentication) lists them per endpoint.
API access needs the Starter plan or higher. A Free workspace cannot mint a deploy token, and a token stops working if the account moves to a plan without API access. It works again after an upgrade, with nothing to re-issue.
## Content types [#content-types]
| Direction | Format |
| --- | --- |
| Request bodies | JSON with `Content-Type: application/json`, except `POST /v1/push` (`multipart/form-data`) and `POST /v1/glossary/import` (the raw CSV or TBX file as the body) |
| Responses | JSON, except `GET /v1/pull` and `GET /v1/glossary/export`, which return the file itself |
| Errors | `application/problem+json`, described in [Errors](https://transglot.ai/docs/developers/api/errors) |
A single resource comes back as a bare JSON object with no envelope, except the single-value reads and writes, which wrap theirs in `row` (or `rows`). Lists differ by endpoint: `GET /v1/batches` returns a bare array, while `GET /v1/glossary`, `GET /v1/webhooks` and `GET /v1/webhooks/events` wrap the list in `data`. Timestamps are ISO 8601 with an offset, for example `2026-10-12T09:41:00+00:00`.
## What the API covers [#what-the-api-covers]
| Group | Endpoints | What it is for |
| --- | --- | --- |
| Project | `GET /v1/project` | The project's languages, their progress and its settings that affect a push |
| Push and pull | `POST /v1/push`, `GET /v1/pull` | Upload a locale file, download a locale as a file |
| Translation | `POST /v1/translate` | Start a Glossa translation run |
| Batches | `GET /v1/batches`, `GET /v1/batches/{batch}`, `POST .../retry-failed`, `POST .../cancel` | Watch, retry and stop runs |
| Translations (single values) | `GET /v1/translations`, `POST /v1/translations/batch`, `PUT /v1/translations` | Read and write individual values by key name |
| Quality | `POST /v1/qa/run` | Start a quality check |
| CDN | `POST /v1/cdn/publish`, `GET /v1/cdn/{project}/{locale}`, `GET /v1/cdn/{project}/{locale}/v{version}` | Publish a locale, then read the bundle with a CDN key |
| Glossary | `GET`, `POST /v1/glossary`, `PUT`, `DELETE /v1/glossary/{termId}`, `GET /v1/glossary/export`, `POST /v1/glossary/import`, `POST /v1/glossary/extract` | Manage terms |
| Webhooks | `GET`, `POST /v1/webhooks`, `DELETE /v1/webhooks/{webhook}`, `GET /v1/webhooks/events` | Subscribe endpoints to project events |
Every endpoint, with its parameters, request bodies and response shapes, is in the [API reference](https://transglot.ai/docs/api-reference).
## A typical CI flow [#a-typical-ci-flow]
### Push the source file [#push-the-source-file]
```bash title="Push"
curl https://api.transglot.ai/v1/push \
-H "Authorization: Bearer $TRANSGLOT_TOKEN" \
-F file=@locales/en.json \
-F format=json_flat \
-F locale=en
```
With automatic translation on, a push that changes source strings starts a translation run and returns it as `batch`.
### Wait for the run [#wait-for-the-run]
```bash title="Poll the batch"
curl https://api.transglot.ai/v1/batches/4822 \
-H "Authorization: Bearer $TRANSGLOT_TOKEN"
```
Poll until `status` is `completed`, `completed_with_errors`, `failed` or `cancelled`, or subscribe to the `batch.completed` [webhook](https://transglot.ai/docs/developers/webhooks) instead of polling.
### Pull each locale [#pull-each-locale]
```bash title="Pull"
curl "https://api.transglot.ai/v1/pull?format=json_flat&locale=fr" \
-H "Authorization: Bearer $TRANSGLOT_TOKEN" \
-D headers.txt -o locales/fr.json
```
Check `X-Entry-Count` in `headers.txt` before you commit the file: an untranslated locale comes back as a valid empty file.
The [command line tool](https://transglot.ai/docs/developers/cli) and the [GitHub Action](https://transglot.ai/docs/developers/github-action) do all of this for you, with retries and rate-limit handling built in.
## Related [#related]
# Rate limits (https://transglot.ai/docs/developers/api/rate-limits/)
The API limits how many requests a credential can make per minute. Limits are counted per deploy token, so two tokens on the same project each have their own budget.
## The limits [#the-limits]
| Requests | Limit | Counted per |
| --- | --- | --- |
| Every `/v1` endpoint not listed below | 60 per minute | Deploy token |
| `POST /v1/push` | 300 per minute | Deploy token, in its own budget |
| `POST /v1/batches/{batch}/cancel` | 60 per minute | Deploy token, in its own budget |
| `GET /v1/cdn/{project}/{locale}` and `.../v{version}` | 300 per minute | CDN key and client IP address |
Push and cancel draw on budgets of their own, so they never compete with the general one:
- A repository upload is one push per file, so a project with many locale files can upload them all without touching the budget your status checks use.
- Polling a batch never uses up the requests you need to cancel it.
## Headers [#headers]
Responses from a limited endpoint carry the current state of the limit:
| Header | On | Meaning |
| --- | --- | --- |
| `X-RateLimit-Limit` | Every response to an authenticated request | Requests allowed per minute |
| `X-RateLimit-Remaining` | Every response to an authenticated request | Requests left in the current minute |
| `Retry-After` | `429` only | Seconds to wait before the next request will be accepted |
| `X-RateLimit-Reset` | `429` only | Unix time, in seconds, when the limit resets |
When you exceed a limit, the answer is `429` with the problem type `/problems/rate-limited`:
```http title="429 Too Many Requests"
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 42
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1791820920
{"type":"/problems/rate-limited","title":"Rate limited","status":429,"detail":"Too many requests."}
```
`/problems/quota-exceeded` and `/problems/extract-cap-reached` are also `429`, but they mean the account has used its AI allowance for the cycle. They carry no `Retry-After` and do not clear in seconds; `resets_at` in the body says when they lift. Branch on `type` before you retry. See [Errors](https://transglot.ai/docs/developers/api/errors).
## Backing off [#backing-off]
Wait for `Retry-After` when it is present. When it is not (a `5xx`, or a dropped connection), back off exponentially with jitter, and give up after a few attempts.
```ts title="request-with-backoff.ts"
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
export async function requestWithBackoff(url: string, init: RequestInit, attempts = 5): Promise {
for (let attempt = 0; ; attempt++) {
const res = await fetch(url, init);
const retryable =
res.status >= 500 ||
(res.status === 429 && (await res.clone().json()).type === '/problems/rate-limited');
if (!retryable || attempt === attempts - 1) return res;
const retryAfter = Number(res.headers.get('Retry-After'));
const delay = retryAfter > 0
? retryAfter * 1000
: Math.min(30_000, 1000 * 2 ** attempt) + Math.random() * 250;
await sleep(delay);
}
}
```
Recent versions of curl honour `Retry-After` on a `429` when you ask them to retry:
```bash title="curl with retries"
curl --retry 4 --retry-max-time 120 \
https://api.transglot.ai/v1/batches/4822 \
-H "Authorization: Bearer $TRANSGLOT_TOKEN"
```
## Staying under the limits [#staying-under-the-limits]
- **Poll with backoff.** When you watch a batch, start at one second and double the interval up to about fifteen. A run takes minutes, not seconds.
- **Use webhooks instead of polling.** Subscribe an endpoint to `batch.completed` and `batch.failed` and you need no status requests at all. See [Webhooks](https://transglot.ai/docs/developers/webhooks).
- **Read many values at once.** `POST /v1/translations/batch` reads up to 1,000 keys in one request where `GET /v1/translations` reads one.
- **Revalidate instead of downloading.** Send the `ETag` you have as `If-None-Match` on `GET /v1/pull` and the CDN reads. A `304` is still a request, but it carries no body.
- **One token per pipeline.** Each token has its own budget, so a busy CI pipeline does not slow down another job that uses a different token.
The [command line tool](https://transglot.ai/docs/developers/cli) already waits for `Retry-After` and backs off while it polls.
## Related [#related]
- [Errors](https://transglot.ai/docs/developers/api/errors)
- [Authentication](https://transglot.ai/docs/developers/api/authentication)
- [Connect your app to the CDN](https://transglot.ai/docs/guides/delivery/connect-your-app-to-the-cdn)
# Versioning (https://transglot.ai/docs/developers/api/versioning/)
The API is versioned by URL prefix. Everything published so far lives under `/v1`, which is the only prefix in use. There is no version header, no date pinning and nothing to configure.
## What can change inside /v1 [#what-can-change-inside-v1]
`/v1` changes additively:
- **New endpoints** can be added.
- **New response fields** can be added to existing responses.
- **New response headers** can be added. `X-Skipped-Keys` and `X-Missing-Source-Keys` on `GET /v1/pull` were added this way, rather than by changing the file body.
A field you already parse does not change shape and does not disappear. If a change cannot be made additively, it ships under a new version prefix, and `/v1` keeps working.
## Writing a client that keeps working [#writing-a-client-that-keeps-working]
Additive changes are only safe for a client that expects them:
| Do | Because |
| --- | --- |
| Ignore JSON fields you do not recognise | New fields are added to existing responses |
| Ignore headers you do not recognise | New headers are added the same way |
| Branch on a problem's `type`, and fall back to its `status` for a type you do not know | New endpoints can bring problem types of their own |
| Handle an unknown value in a field such as a batch's `status` or a webhook's `event` instead of failing | A client that degrades on the unexpected keeps running while you update it |
| Never parse `detail` | It is a sentence for a person and its wording can change |
| Subscribe webhooks to the events you handle, by name | A new event never reaches an endpoint that did not subscribe to it |
```ts title="Tolerant parsing"
type Batch = { id: number; status: string; total: number; completed: number; failed: number };
function isFinal(batch: Batch): boolean {
switch (batch.status) {
case 'pending':
case 'processing':
return false;
case 'completed':
case 'completed_with_errors':
case 'failed':
case 'cancelled':
return true;
default:
// A status this client does not know yet. Log it and keep polling.
console.warn(`Unknown batch status ${batch.status}`);
return false;
}
}
```
## Deprecations and the changelog [#deprecations-and-the-changelog]
Every change to `/v1` is recorded in the [API changelog](https://transglot.ai/api-changelog), dated, separately from product releases. Its deprecation register lists every published surface with the release that shipped it. Nothing has been deprecated or removed: the removal column reads "none scheduled" for every row. A removal would appear there with a date long before it happened, and the row would stay in the table afterwards.
## Related [#related]
- [REST API overview](https://transglot.ai/docs/developers/api)
- [Errors](https://transglot.ai/docs/developers/api/errors)
- [API reference](https://transglot.ai/docs/api-reference)
# Command reference (https://transglot.ai/docs/developers/cli/commands/)
```text
transglot [options]
```
| Command | What it does | Token ability |
| --- | --- | --- |
| [`init`](#init) | Finds the locale files, signs in through the browser, sets up and translates. | **push**, **pull** or **manage** (with `TRANSGLOT_TOKEN`) |
| [`push`](#push) | Uploads files per `sources` in `transglot.json`. | **push** |
| [`pull`](#pull) | Downloads files per `pull` in `transglot.json`. | **pull** |
| [`status [batchId]`](#status) | Prints the project summary and active batches, or one batch. | **push**, **pull** or **manage** |
| [`cancel `](#cancel) | Stops a running translation batch. | **manage** |
A batch is one translation run. Its id is the number the CLI prints after `#`.
## Global options [#global-options]
| Option | Description |
| --- | --- |
| `--config ` | The configuration file. Default: `./transglot.json`. |
| `--version`, `-v` | Prints the CLI version. |
| `--help`, `-h` | Prints the help text. `transglot help` does the same. |
Running `transglot` with no command prints the help text and exits with code 1. An unknown command or flag stops the CLI with exit code 1:
```text
error: Unknown flag --locale for "push".
error: hint: Run transglot --help for usage.
```
## init [#init]
Sets up the repository in the current folder: scans it for locale files, signs you in through the browser, writes `transglot.json`, uploads your strings and runs the first translation. The walk-through is on [The command line tool](https://transglot.ai/docs/developers/cli#set-up-a-repository).
```bash
npx transglot@latest init
```
| Flag | Description |
| --- | --- |
| `--yes` | Accept the defaults without asking. |
| `--no-browser` | Show the sign-in link without opening a browser. |
| `--no-translate` | Upload, but leave the first translation for later. |
| `--targets ` | Languages to translate into, for example `fr,de`. |
| `--source ` | The source language, when the files cannot tell. |
| `--path ` | The locale files, for example `messages/{locale}.json`. |
| `--format ` | The file format. Read only together with `--path`. |
| `--url ` | The transglot server. Default: `https://api.transglot.ai`. |
| `--json` | Print events as JSON lines on stdout. |
| `--force` | Set up again when `transglot.json` exists. |
| `--confirm ` | The 2-digit number your browser shows when the browser and terminal are on different networks. |
What `init` does depends on the folder and the environment:
- **No `transglot.json`.** The full setup: scan, browser sign-in, write the file, upload, first translation.
- **A `transglot.json` this machine has no link for.** `init` signs you in and links the folder on this machine only. It does not change the file and uploads nothing.
- **A `transglot.json` this folder is already linked for.** `init` stops with `transglot.json already exists and this folder is linked on this machine.` Pass `--force` to scan again and rewrite the file.
- **`TRANSGLOT_TOKEN` is set.** No browser and no upload. `init` reads the token's project, scans the repository for the layout, and writes `transglot.json` for that project. It stops if `transglot.json` exists unless you pass `--force`, and if the repository's source language differs from the project's. It ends with `Next: transglot push --wait && transglot pull`.
When `transglot.json` names a server other than `https://api.transglot.ai`, `init` asks before it signs in or sends a token there. Outside a terminal it stops instead and tells you to pass that address with `--url`.
Outside an interactive terminal (a script, CI, or a coding agent), and with `--yes` or `--json`, `init` asks nothing and takes every choice from flags. Browser sign-in never runs in CI: there, `init` stops with `Browser sign-in does not run in CI.` unless `TRANSGLOT_TOKEN` is set.
```bash title="Set up without questions"
npx transglot@latest init --yes --path "src/locales/{locale}.json" --format json_nested --targets fr,de,ja
```
## push [#push]
Uploads the files the `sources` rules name. Each source file updates the project's keys and source text; a file for another locale uploads its existing translations.
```bash
npx transglot@latest push --wait
```
| Flag | Description |
| --- | --- |
| `--wait` | Wait for the queued translation batch to finish. |
| `--timeout ` | Maximum seconds to wait. Default: `600`. |
| `--sync-removals` | Also delete keys on the server that are missing from the pushed source file. |
Before the first upload, `push` plans every path and reads every file. A missing file, a file over 10 MiB, or a bad sidecar stops the run with nothing uploaded. Files then upload one locale at a time, up to four files at once.
For each file it prints what changed:
```text
push locales/en.json (en, json_nested)
keys_created 12
keys_deleted 0
source_updated 3
translations_written 0
Batch: #4821
```
`Batch: #` appears when the upload queued a translation batch, which happens when the project translates new strings automatically. Depending on the upload, `push` also lists `conflicts:`, `unknown keys:` and `warnings:`, and with a [metadata sidecar](https://transglot.ai/docs/developers/cli/configuration#key-metadata-sidecar) `descriptions_updated` and `max_lengths_updated`.
`push` returns as soon as the batch is queued. With `--wait` it polls until the batch finishes, printing a progress line on each check:
```text
waiting: batch #4821 processing 120/400
```
If the batch fails or is cancelled, `push --wait` lists the failed keys and exits with code 4:
```text
error: batch #4821 finished completed_with_errors (2 of 400 failed)
error: - checkout.total (de):
```
When the word limit stops the batch, the files are still uploaded and `push` prints `error: quota exceeded: translation batch suppressed by monthly word quota` and exits with code 3.
### Removing keys [#removing-keys]
`--sync-removals` deletes server keys the pushed source file no longer contains. It only applies to the source locale. The CLI refuses it when more than one file uploads for the same locale (each upload would delete the keys of the others), and when `TRANSGLOT_TOKEN` belongs to a different project from the one this folder is linked to.
## pull [#pull]
Writes the files the `pull` rules name, one request per file.
```bash
npx transglot@latest pull
```
| Flag | Description |
| --- | --- |
| `--wait` | Wait for active translation batches to finish before downloading. |
| `--batch ` | Wait on one specific batch. Requires `--wait`. Use it to resume an interrupted wait. |
| `--timeout ` | Maximum seconds to wait. Default: `600`. |
| `--allow-empty` | Let an empty file overwrite an existing one. Refused by default. |
For each file, `pull` prints one line:
```text
written locales/fr.json
unchanged locales/de.json
```
A file is rewritten only when its content changed, and the write is atomic, so an interrupted pull never leaves a half-written file. Missing folders are created.
A pulled file holds what the project has for that locale, not one entry per key. A key nobody has translated yet is absent, and so is a key a `min_state` filter leaves out. On a project whose message syntax is ICU, a translation that is not valid ICU MessageFormat is left out too, so it cannot break your app at render time. `pull` names those under the file:
```text
written messages/fr.json
omitted 3 invalid ICU translation(s) for fr: cart.items, cart.total, and 1 more
```
Fix those translations in transglot and the next `pull` writes them. If your i18n library does not fall back to the source language for a missing key, pull the source locale too and merge it under each target.
### Empty files are not written over existing ones [#empty-files-are-not-written-over-existing-ones]
If the server has no entries for a locale, `pull` refuses to replace an existing non-empty file and exits with code 1:
```text
error: refusing to overwrite locales/fr.json with an empty bundle: the server returned 0 entries for this locale
```
This happens when a locale has not been translated yet, when `min_state: reviewed` matches nothing so far, or when a `push` is still translating. Run `push --wait` before `pull` rather than the bare pair. Writing to a path that does not exist yet is not affected. If you mean to clear the file, pass `--allow-empty`.
### Waiting [#waiting]
With `--wait`, `pull` waits for every active batch of the project, or only `--batch `, before it downloads anything. If a batch failed or was cancelled, `pull` still writes the files, then exits with code 4. If the wait runs out, it exits with code 5 and prints the command that resumes it:
```text
error: Timed out after 600s waiting for batch(es): #4821.
error: hint: Resume with: transglot pull --wait --batch 4821 --timeout 600
```
## status [#status]
Prints the project and its active batches. It always exits with code 0 unless the lookup itself fails.
```bash
npx transglot@latest status
```
```text
Project Storefront (storefront)
Source locale en
Locales en, fr, de
Keys 412
Active batches:
#4821 processing 120/400
```
With a batch id, it prints that batch, its per-language counts and, once it has finished, any failed keys:
```bash
npx transglot@latest status 4821
```
```text
Batch #4821
Status completed
Progress 400/400 (400 ok, 0 failed)
Started 2026-10-12T09:14:03+00:00
Finished 2026-10-12T09:16:41+00:00
```
## cancel [#cancel]
Stops a running translation batch. It needs `TRANSGLOT_TOKEN` set to a token with the **manage** ability; the token stored by `init` cannot cancel.
```bash
TRANSGLOT_TOKEN=tgl_xxx npx transglot@latest cancel 4821
```
```text
Batch #4821 is cancelled.
```
Cancelling a batch that has already finished is not an error: the CLI prints `Batch #4821 had already finished (completed), nothing to cancel.` and exits with code 0, so a cleanup step can cancel defensively.
## Environment variables [#environment-variables]
| Variable | Description |
| --- | --- |
| `TRANSGLOT_TOKEN` | A project token. When set, every command uses it instead of the token stored for this folder, and never opens a browser. `cancel` always needs it. |
| `TRANSGLOT_URL` | The server address. Overrides `url` in `transglot.json`. |
| `TRANSGLOT_CONFIG_DIR` | The absolute path of the folder that holds `credentials.json`. |
| `TRANSGLOT_BROWSER` | `none` never opens a browser; any other value is the command that opens the sign-in link. The link is printed either way. |
| `TRANSGLOT_INTERACTIVE` | `0` never asks a question; `1` asks even where the CLI would otherwise assume an automated environment. |
| `NO_COLOR` | Turns coloured output off. Colour is also off outside a terminal and in CI. |
## Output [#output]
Results go to stdout. Errors go to stderr, prefixed `error: `, followed by a `hint:` line that says what to do next. Scripts can rely on the lines `Batch: #`, `written ` and `unchanged `; the [GitHub Action](https://transglot.ai/docs/developers/github-action) reads them.
Every command exits with one of the [documented exit codes](https://transglot.ai/docs/developers/cli/exit-codes). Pressing Ctrl+C prints `Cancelled.` and exits with code 130.
# Configuration file (https://transglot.ai/docs/developers/cli/configuration/)
The CLI reads `transglot.json` from the folder you run it in. `transglot init` writes one for you; this page describes every field so you can write or change it by hand. Pass `--config ` to read a file from somewhere else.
```json title="transglot.json"
{
"url": "https://api.transglot.ai",
"sources": [
{ "path": "locales/{locale}.json", "format": "json_nested" }
],
"pull": [
{ "path": "locales/{locale}.json", "format": "json_nested" }
]
}
```
`push` uploads the files the `sources` rules name. `pull` writes the files the `pull` rules name. The two lists are independent, so you can pull into a different layout or format from the one you push.
## Top-level fields [#top-level-fields]
The file must be a JSON object with only these three fields. Any other field stops the CLI with `Unknown config field "". Allowed fields: url, sources, pull.`
`url` is required unless `TRANSGLOT_URL` is set. For transglot it is `https://api.transglot.ai`.
## Rule fields [#rule-fields]
Each entry in `sources` and `pull` is a rule: one path template, one file format, and the locales it applies to.
### Locale placeholders [#locale-placeholders]
`{locale}` is replaced by each locale the rule covers, everywhere it appears in the path. With `"locales": ["fr", "de"]`, the path `locales/{locale}/common.json` stands for `locales/fr/common.json` and `locales/de/common.json`.
When a pull rule leaves `locales` out, `{locale}` is filled with each locale's id as transglot stores it, such as `fr` or `pt_BR`. If your files spell locales differently, for example `pt-BR`, list them in your spelling. transglot accepts any letter case and either `-` or `_` as the separator, so `"locales": ["fr", "pt-BR"]` writes `pt-BR.json` and still reads the project's `pt_BR` translations.
A locale used in a path must be a plain tag of letters, digits, `-` and `_`. Every planned path must stay inside the folder you run the CLI in, symbolic links included. Two locales that would land on the same file are refused before anything is sent: a rule that covers more than one locale needs `{locale}` in its path.
A sources rule can name a locale other than the source. `push` then uploads that file as existing translations for that locale. The locale must already be a language of the project: `push` never adds one, and answers `Locale "" is not configured on this project. Push never adds locales.`
### Formats [#formats]
Every rule names one of these formats. `transglot init` detects it from your files.
| Format | Default extension | Format | Default extension |
| --- | --- | --- | --- |
| `json_flat` | `.json` | `gettext_po` | `.po` |
| `json_nested` | `.json` | `yaml` | `.yml` |
| `android_xml` | `.xml` | `csv` | `.csv` |
| `ios_strings` | `.strings` | `xlsx` | `.xlsx` |
| `ios_stringsdict` | `.stringsdict` | `xliff_20` | `.xlf` |
| `flutter_arb` | `.arb` | `java_properties` | `.properties` |
| `laravel_php` | `.php` | `resx` | `.resx` |
| `laravel_json` | `.json` | `markdown` | `.md` |
| `xliff_12` | `.xlf` | `unity_csv` | `.csv` |
| `ios_xcstrings` | `.xcstrings` | `unreal_po` | `.po` |
`unity_csv` and `unreal_po` are the game engine formats (Unity string tables and Unreal `.po` catalogs). Each format has its own page under [File formats](https://transglot.ai/docs/developers/formats).
### Several rules [#several-rules]
A project can have as many rules as you have files. List one rule per file family; the same locale can appear in several rules.
```json title="transglot.json"
{
"url": "https://api.transglot.ai",
"sources": [
{ "path": "locales/{locale}/common.json", "format": "json_nested" },
{ "path": "locales/{locale}/checkout.json", "format": "json_nested" }
],
"pull": [
{ "path": "locales/{locale}/common.json", "format": "json_nested" },
{ "path": "locales/{locale}/checkout.json", "format": "json_nested" }
]
}
```
`push` uploads the files of one locale at a time, in the order the rules first mention each locale, so list your source locale first. Files of the same locale upload in parallel.
With several source files for one locale you cannot use `push --sync-removals`: each upload would delete the keys the other files define. The CLI refuses that combination before it uploads anything.
## Key metadata sidecar [#key-metadata-sidecar]
A key's description is the context translators and Glossa read, and its `max_length` is the limit a translation is checked against. Formats such as `json_flat`, `json_nested`, `android_xml` or `ios_strings` have nowhere to store either, so a sources rule can name a sidecar file that does (CLI 0.5.0 and later).
```json title="transglot.json"
{
"url": "https://api.transglot.ai",
"sources": [
{
"path": "messages/{locale}.json",
"format": "json_nested",
"metadata": "i18n/en.meta.json"
}
],
"pull": [
{ "path": "messages/{locale}.json", "format": "json_nested" }
]
}
```
```json title="i18n/en.meta.json"
{
"cart.title": { "description": "Heading of the cart page", "max_length": 40 },
"cart.items": { "description": "Item count under the cart heading" },
"legacy.banner": { "description": null }
}
```
- Keys are the project's key names, dotted the way the project stores them.
- A field you leave out is not changed; `null` clears it.
- `max_length` is a whole number from 1 to 100000. `description` is at most 2,000 characters.
- The file is at most 1 MiB and 50,000 keys, and names each key once.
`push` reads and checks the sidecar before it uploads anything, so a bad sidecar stops the run with nothing sent. The sidecar travels with the rule's source-locale upload, which goes after that locale's other files, so keys a sibling file creates exist by the time their descriptions arrive.
The CLI refuses, as a configuration error:
- `metadata` on a pull rule;
- a sidecar path with a `{locale}` or any other `{…}` placeholder (a rule has exactly one sidecar);
- a rule that plans no upload, or more than one, for the source locale;
- a sidecar path outside the working folder, including through a symbolic link;
- a format that carries descriptions in the file itself: `flutter_arb`, `xliff_12`, `ios_xcstrings`, `gettext_po`, `csv`, `xlsx`, `unity_csv` and `unreal_po`.
## Examples [#examples]
Nested JSON with one folder per language, as i18next and most JavaScript libraries use. The locales are listed because the files spell regions with a hyphen.
```json title="transglot.json"
{
"url": "https://api.transglot.ai",
"sources": [
{ "path": "public/locales/{locale}/translation.json", "format": "json_nested" }
],
"pull": [
{
"path": "public/locales/{locale}/translation.json",
"format": "json_nested",
"locales": ["fr", "de", "pt-BR"]
}
]
}
```
The source file sits in `values/`, which has no locale in its name, so its rule names the path in full and pins its locale. A region such as `values-pt-rBR` uses Android's own spelling, so it gets a literal path too.
```json title="transglot.json"
{
"url": "https://api.transglot.ai",
"sources": [
{
"path": "app/src/main/res/values/strings.xml",
"format": "android_xml",
"locales": ["en"]
}
],
"pull": [
{
"path": "app/src/main/res/values-{locale}/strings.xml",
"format": "android_xml",
"locales": ["fr", "de", "ja"]
},
{
"path": "app/src/main/res/values-pt-rBR/strings.xml",
"format": "android_xml",
"locales": ["pt-BR"]
}
]
}
```
`.strings` files in one `.lproj` folder per language. Add a second rule with `ios_stringsdict` for plural rules kept in `Localizable.stringsdict`.
```json title="transglot.json"
{
"url": "https://api.transglot.ai",
"sources": [
{
"path": "App/Resources/{locale}.lproj/Localizable.strings",
"format": "ios_strings"
}
],
"pull": [
{
"path": "App/Resources/{locale}.lproj/Localizable.strings",
"format": "ios_strings",
"locales": ["fr", "de", "zh-Hans"]
}
]
}
```
Laravel's JSON translation files, one per language in `lang/`. For PHP array files, use `laravel_php` with a path such as `lang/{locale}/messages.php`.
```json title="transglot.json"
{
"url": "https://api.transglot.ai",
"sources": [
{ "path": "lang/{locale}.json", "format": "laravel_json" }
],
"pull": [
{ "path": "lang/{locale}.json", "format": "laravel_json" }
]
}
```
ARB files as `flutter gen-l10n` reads them. ARB carries key descriptions in the file itself, so a sidecar is not allowed here.
```json title="transglot.json"
{
"url": "https://api.transglot.ai",
"sources": [
{ "path": "lib/l10n/app_{locale}.arb", "format": "flutter_arb" }
],
"pull": [
{ "path": "lib/l10n/app_{locale}.arb", "format": "flutter_arb" }
]
}
```
## Validation errors [#validation-errors]
The CLI checks the whole file before it sends a request and exits with code 1 on the first problem. The messages name the field, for example:
```text
error: Config field "url" is required (or set TRANSGLOT_URL).
error: Unknown config field "sources[0].file". Allowed fields: path, format, locales, min_state, metadata.
error: Config field "pull[0].min_state" must be "human_edited" or "reviewed".
error: Config field "pull[0].metadata" is only allowed on a sources rule.
```
See [Exit codes](https://transglot.ai/docs/developers/cli/exit-codes) for how to handle them in a pipeline.
# Use the CLI in CI (https://transglot.ai/docs/developers/cli/continuous-integration/)
In CI the CLI authenticates with a deploy token in the `TRANSGLOT_TOKEN` environment variable. It never opens a browser and never asks a question there. On GitHub, the [GitHub Action](https://transglot.ai/docs/developers/github-action) wraps the same steps; this page covers every other CI system.
## Before you start [#before-you-start]
1. **Commit `transglot.json`.** Run `npx transglot@latest init` once on your machine, or write the file by hand from the [configuration reference](https://transglot.ai/docs/developers/cli/configuration).
2. **Create a deploy token** with the **push** and **pull** abilities. Add **manage** only if the job also cancels batches. See [Deploy tokens](https://transglot.ai/docs/developers/deploy-tokens).
3. **Store it as a secret** named `TRANSGLOT_TOKEN` in your CI system. Never put the token in `transglot.json` or in the pipeline file.
## The two commands [#the-two-commands]
Every pipeline runs the same pair:
```bash
npx --yes transglot@latest push --wait
npx --yes transglot@latest pull
```
`push --wait` uploads the source strings and waits until the translation batch finishes. `pull` then writes the translated files into the checkout. Without `--wait`, `pull` would run before anything is translated.
What happens to the pulled files is up to the pipeline: commit them, open a merge request, or keep them as a build artifact.
To make builds reproducible, pin a version instead of `@latest`, for example `npx --yes transglot@0.5.0`. The CLI needs Node.js 22 or later on the runner.
## Environment variables [#environment-variables]
| Variable | Description |
| --- | --- |
| `TRANSGLOT_TOKEN` | Required. The deploy token. |
| `TRANSGLOT_URL` | Optional. Overrides `url` from `transglot.json`. |
| `NO_COLOR` | Optional. Colour is already off in CI. |
The CLI recognises CI from the variables CI systems set, including `CI`, `GITLAB_CI`, `CIRCLECI`, `BUILDKITE`, `JENKINS_URL` and `BITBUCKET_BUILD_NUMBER`. In CI it asks nothing, prints no colour, and refuses browser sign-in with `Browser sign-in does not run in CI.`
## GitLab CI [#gitlab-ci]
This job runs on the default branch and keeps the pulled files as an artifact.
```yaml title=".gitlab-ci.yml"
translations:
image: node:22
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
script:
- npx --yes transglot@latest push --wait
- npx --yes transglot@latest pull
artifacts:
paths:
- locales/
```
Add `TRANSGLOT_TOKEN` under **Settings** → **CI/CD** → **Variables** in GitLab, masked and protected. Replace `locales/` with the folders your `pull` rules write to.
## CircleCI [#circleci]
```yaml title=".circleci/config.yml"
version: 2.1
jobs:
translations:
docker:
- image: cimg/node:22.20
steps:
- checkout
- run:
name: Push source strings and wait for translations
command: npx --yes transglot@latest push --wait
- run:
name: Pull translated files
command: npx --yes transglot@latest pull
- store_artifacts:
path: locales
workflows:
localize:
jobs:
- translations:
context: transglot
filters:
branches:
only: main
```
Store `TRANSGLOT_TOKEN` in a CircleCI context (here named `transglot`) or in the project's environment variables.
## Plain shell [#plain-shell]
Any runner with Node.js 22 and git can sync and commit in one script. This one commits only when a translation file changed.
```bash title="scripts/sync-translations.sh"
#!/usr/bin/env bash
set -euo pipefail
: "${TRANSGLOT_TOKEN:?Set TRANSGLOT_TOKEN to a deploy token}"
npx --yes transglot@latest push --wait
npx --yes transglot@latest pull
if [ -n "$(git status --porcelain)" ]; then
git add -A locales
git commit -m "chore(i18n): sync translations from transglot"
git push
fi
```
With `set -e`, the script stops at the first non-zero exit code. To keep going when the word limit is reached or some translations failed, branch on the exit code instead; see [Exit codes](https://transglot.ai/docs/developers/cli/exit-codes#react-to-codes-in-a-script).
## Recipes [#recipes]
### Push on every merge, pull on a schedule [#push-on-every-merge-pull-on-a-schedule]
Uploading is quick; translation takes as long as the batch. Push without waiting on every merge, and pull in a scheduled job:
```bash
# on merge to main
npx --yes transglot@latest push
# nightly
npx --yes transglot@latest pull --wait
```
`pull --wait` waits for every active batch of the project before it downloads.
### Resume a wait that timed out [#resume-a-wait-that-timed-out]
`--wait` gives up after 600 seconds by default and exits with code 5. The batch keeps running on the server. Raise the limit with `--timeout`, or pick up where the job stopped:
```bash
npx --yes transglot@latest pull --wait --batch 4821 --timeout 1800
```
The CLI prints the exact command, with the batch id, when the wait times out.
### Stop a batch when a job is cancelled [#stop-a-batch-when-a-job-is-cancelled]
A cleanup step can stop a running batch. `cancel` needs a token with the **manage** ability and exits with code 0 even when the batch has already finished:
```bash
npx --yes transglot@latest cancel "$BATCH_ID"
```
`push` prints the id as `Batch: #`. Read it from the output:
```bash
BATCH_ID=$(npx --yes transglot@latest push | sed -n 's/^Batch: #\([0-9]*\).*/\1/p' | head -n 1)
```
### Only translations someone has checked [#only-translations-someone-has-checked]
To ship only translations a person edited or reviewed, add `min_state` to the pull rules in `transglot.json`:
```json title="transglot.json"
{
"url": "https://api.transglot.ai",
"sources": [{ "path": "locales/{locale}.json", "format": "json_nested" }],
"pull": [{ "path": "locales/{locale}.json", "format": "json_nested", "min_state": "reviewed" }]
}
```
## Troubleshooting [#troubleshooting]
| Message | Cause |
| --- | --- |
| `TRANSGLOT_TOKEN is not set.` | The secret is not exposed to this job, or is misspelled. |
| `The server did not accept TRANSGLOT_TOKEN.` (hint) | The token was revoked, has expired, or belongs to another server. |
| `The token lacks the "pull" ability.` (hint) | Create a token with the abilities the job needs. |
| `Config file not found: ...` | The job does not run in the folder that holds `transglot.json`. Pass `--config`. |
| `refusing to overwrite ... with an empty bundle` | `pull` ran before anything was translated. Use `push --wait` first. |
Every code the CLI exits with is listed in [Exit codes](https://transglot.ai/docs/developers/cli/exit-codes).
# Exit codes (https://transglot.ai/docs/developers/cli/exit-codes/)
Every CLI command exits with one of these codes. They are stable across the 0.x releases, so scripts can branch on them.
| Code | Meaning | Typical causes | What to do |
| --- | --- | --- | --- |
| `0` | Success. | | Nothing. |
| `1` | Configuration or usage. | `transglot.json` missing or invalid; a source file missing or over 10 MiB; an unknown command or flag; a batch id that does not exist; a locale that is not a language of the project; `pull` refusing to write an empty file over a full one; a choice `init` needs a flag for outside a terminal. | Fix the input the message names. Retrying does not help. |
| `2` | Sign-in, token or access refused. | `TRANSGLOT_TOKEN` missing, revoked or expired; the token lacks the ability the command needs; the plan does not include API access; the workspace or account is suspended, read-only or closing; browser sign-in attempted in CI. | Read the hint: it names the missing ability or what to change. Replace the token or ask an admin. |
| `3` | Word limit reached. | The upload went through but the translation batch was held back because the workspace's words are used up, or AI translation is paused for the account. | Your files are synced. Raise the limit or wait for the reset, then push again. |
| `4` | A translation batch failed or was stopped. | With `--wait`, a batch finished as `failed` or `completed_with_errors`, or was cancelled. | The failed keys are listed with their reasons. Translations that did complete are still written by `pull`. Select **Retry failed** on the run in the project's **Runs** page to re-run only the strings that failed. |
| `5` | Timed out while waiting. | `--wait` ran longer than `--timeout` (default 600 seconds). | The batch keeps running on the server. Resume with the command in the hint, for example `transglot pull --wait --batch 4821`. |
| `6` | Server or network error. | The server could not be reached, answered with a server error or an unexpected response, redirected the request, or was still rate-limiting after two retries. | Retry later. Check that `url` points at `https://api.transglot.ai`. |
| `130` | Interrupted. | You pressed Ctrl+C. | Nothing. |
## How the CLI picks a code [#how-the-cli-picks-a-code]
- **Worst signal wins.** When one `push --wait` both hits the word limit and has a failed batch, it exits with `4`, because missing translations need attention first.
- **`pull` writes first, then reports.** With `--wait`, a failed batch makes `pull` exit with `4`, but only after it has written every file it could.
- **`status` and `cancel` are read-outs.** They exit with `0` whenever the request succeeds, including for a failed batch or one that had already finished.
- **Rate limits are retried for you.** A `429` is retried up to two times, waiting as long as the server asks (at most 60 seconds), before the CLI gives up with `6`.
Errors are printed on stderr as `error: ` and `error: hint: `. A token that lacks an ability, for example, reads:
```text
error: hint: The token lacks the "push" ability. Issue a token that has it.
```
## React to codes in a script [#react-to-codes-in-a-script]
Treat `3` and `4` as warnings if a partial result is acceptable, and everything else as a failure:
```bash title="sync-translations.sh"
#!/usr/bin/env bash
set -u
npx --yes transglot@latest push --wait
code=$?
case "$code" in
0) ;;
3) echo "Word limit reached: sources synced, nothing new translated." ;;
4) echo "Some translations failed: pulling what finished." ;;
*) exit "$code" ;;
esac
npx --yes transglot@latest pull
```
The [GitHub Action](https://transglot.ai/docs/developers/github-action) follows the same idea: it pulls and commits after `0`, `3` and `4`, skips the pull after any other code, and fails the job with the worst code of the run.
# The command line tool (https://transglot.ai/docs/developers/cli/)
The command line tool is the npm package `transglot`. It reads a `transglot.json` file in your repository, uploads your source strings to a project, and writes the translations back into your locale files. It has no runtime dependencies.
## Requirements [#requirements]
- **Node.js 22 or later.** On an older version the CLI stops before doing anything and prints `transglot needs Node.js 22 or later.` followed by the version it found.
- **A plan with API access.** The CLI, the API and the GitHub Action start on the Starter plan. See [pricing](https://transglot.ai/pricing).
- **An admin to approve the connection.** Connecting a repository creates a project token, so the login that approves it in the browser must be an admin of the workspace or an owner of its account.
## Install [#install]
You can run the CLI without installing it, install it globally, or add it to your project.
```bash tab="npx"
npx transglot@latest init
```
```bash tab="Global"
npm install -g transglot
transglot init
```
```bash tab="Dev dependency"
npm install --save-dev transglot
npx transglot init
```
Run it as `npx transglot@latest` rather than `npx transglot`. In a repository that lists an older transglot as a development dependency, npx runs that older version unless you ask for `@latest`.
Check the installed version with `transglot --version`.
## Set up a repository [#set-up-a-repository]
`init` connects a repository to a project, writes `transglot.json`, and runs the first translation. Run it in the root of your repository, on a machine with a browser.
### Scan the repository [#scan-the-repository]
```bash
npx transglot@latest init
```
`init` finds your locale files and works out the source language. Nothing is sent to transglot yet. If it cannot tell which files are your locale files, pass the layout with `--path`, for example `--path messages/{locale}.json`.
### Sign in through the browser [#sign-in-through-the-browser]
The terminal prints a link and a code such as `WDJB-MJHT`, and opens the link. The page is titled **Connect the CLI**. Sign in or sign up there.
Under **Connect this terminal?**, check that the page shows the same code as your terminal, then select **Approve**. Approve only a request you started yourself; otherwise select **Decline**.
When your browser and the terminal reach transglot from different networks (SSH, a container, a VPN that covers only one of them), the page shows **Type this number in your terminal**. Type the two digits into the terminal, or pass them as `--confirm`.
### Choose the workspace and project [#choose-the-workspace-and-project]
If you have no workspace yet, the page asks you to name one under **Create your workspace**. If the workspace's account is on the Free plan, its owners and billing members are offered **Start the free trial** (or a paid plan when the account cannot have a trial) before they continue. Other members are told who can change the plan.
Under **Choose the project for this repository**, connect an existing project or create the one the terminal proposed from your files. The page then says **Your terminal is connected**.
### Upload and translate [#upload-and-translate]
Back in the terminal, `init` writes `transglot.json`, uploads your source strings and the translations you already have, shows how many words the first translation needs, and asks once before it starts. It then translates and writes the finished files into your repository.
A file that holds strings the server does not have is kept, and the terminal says which and why.
Commit `transglot.json`. `init` lists the files to commit when it finishes.
If the repository already has a `transglot.json`, `init` only signs you in and links the folder on this machine. It does not change the file and uploads nothing, so an old branch never replaces your team's source text. Pass `--force` to scan the repository again and rewrite the file.
## Where the token is kept [#where-the-token-is-kept]
Approving in the browser creates an ordinary project token with the **push** and **pull** abilities, named after your machine. It appears with the project's other tokens under **Settings** → **Developer**, where deleting it disconnects the terminal. See [Deploy tokens](https://transglot.ai/docs/developers/deploy-tokens).
The CLI keeps the token in `credentials.json`, in the first of these folders that applies:
1. `TRANSGLOT_CONFIG_DIR`, when it is set (it must be an absolute path).
2. `$XDG_CONFIG_HOME/transglot`, when `XDG_CONFIG_HOME` is an absolute path.
3. `%LOCALAPPDATA%\transglot` on Windows.
4. `~/.config/transglot` otherwise.
On macOS and Linux only your user can read the file. A token is only ever sent to the server it was created for.
`init` also writes `.transglot/project.json` in the repository and adds `.transglot/` to `.gitignore`. That file links the folder to the token on this machine only, so a copy of the folder on another machine selects nothing. In a linked folder, `push`, `pull` and `status` use the stored token without any setup.
## Everyday commands [#everyday-commands]
```bash
npx transglot@latest push --wait # upload source strings, wait for the translations
npx transglot@latest pull # write translations into your locale files
npx transglot@latest status # the project and its active runs
```
`push` returns as soon as a translation run is queued, so use `push --wait` before `pull`. See the [command reference](https://transglot.ai/docs/developers/cli/commands) for every command and flag.
## In CI [#in-ci]
In CI there is no browser sign-in. Create a deploy token, store it as the `TRANSGLOT_TOKEN` secret, and the CLI uses it. While `TRANSGLOT_TOKEN` is set it always wins over a token stored on the machine, and the CLI never opens a browser. See [Use the CLI in CI](https://transglot.ai/docs/developers/cli/continuous-integration) and [The GitHub Action](https://transglot.ai/docs/developers/github-action).
## Troubleshooting [#troubleshooting]
Run the command in your terminal again for a new code.
The request was declined, or the terminal typed the wrong number twice. Run the command again for a new code.
Connecting the CLI creates a project token, which needs an admin of the workspace. The page names the admins who can; ask one of them to connect the repository, or to create a deploy token for you.
The CLI detected a CI environment. Store a deploy token as the `TRANSGLOT_TOKEN` secret instead. See [Use the CLI in CI](https://transglot.ai/docs/developers/cli/continuous-integration).
This folder is not linked on this machine and no token is in the environment. Run `npx transglot@latest init` to sign in and link it, or export a deploy token as `TRANSGLOT_TOKEN`.
## Next steps [#next-steps]
# Deploy tokens (https://transglot.ai/docs/developers/deploy-tokens/)
A deploy token is a secret that authenticates one project. The CLI, the GitHub Action, the [REST API](https://transglot.ai/docs/developers/api), the [MCP server](https://transglot.ai/docs/mcp) and the [language server](https://transglot.ai/docs/developers/tools/language-server) all use one. Tokens start with `tgl_`, and the console calls them **API tokens**.
A token belongs to the project, not to the person who created it. Removing that person from the workspace does not revoke their tokens; revoke them explicitly. The token list shows who created each one.
## Before you start [#before-you-start]
- **Role.** Admins can create and revoke tokens, as can members whose custom role includes **Create and revoke API tokens**.
- **Plan.** Tokens work on plans with API access, Starter and above. See [pricing](https://transglot.ai/pricing). If the account moves to a plan without it, tokens stay saved and work again after an upgrade.
## Abilities [#abilities]
Each token carries one or more abilities, and every API request checks them. Give a token only what its job needs: a leaked token that can only `pull` reads strings, while one with `manage` can start translation runs that use your word allowance.
| Ability | What it allows | Used by |
| --- | --- | --- |
| `push` | Upload source files and existing translations. Price and start the first translation run of a new project. | `transglot push`, `transglot init` |
| `pull` | Download translated files. | `transglot pull` |
| `manage` | Start, retry and cancel translation batches, run quality checks, publish to the CDN, change the glossary, and create or delete webhook endpoints. | `transglot cancel`, the MCP server's batch, quality and glossary tools |
| `read` | Read single translations and the glossary. | The MCP server, your own scripts |
| `write` | Write single translations. With `read`, it also lets your backend authorize the [in-context editor](https://transglot.ai/docs/developers/in-context). | The MCP server, your own backend |
Any one of `push`, `pull` or `manage` also lets a token read the project's details and its batches, which `transglot status` and every `--wait` need.
New tokens start with `push` and `pull` selected, which is what the CLI and the GitHub Action need. Add `manage` only for a job that cancels batches or starts translation runs itself.
A token carries no language restriction and no role, so you can only give it access you hold on the project yourself. If your access is narrower, some abilities are not offered and the dialog says: "Some abilities are not listed: a token carries no language scope and no role, so it can only be given access you hold on this project yourself. An admin can mint the rest."
## Create a token [#create-a-token]
### Open Developer settings [#open-developer-settings]
Open the project, then **Settings** → **Developer**. Under **API tokens**, select **New token**.
### Fill in the dialog [#fill-in-the-dialog]
The **Create API token** dialog asks for three things:
- **Name**: where the token will live, such as `ci-deploy` (up to 100 characters).
- **Abilities**: one or more of `push`, `pull`, `manage`, `read` and `write`.
- **Expiry**: **Never expires**, **30 days**, **90 days** or **365 days**.
Select **Create token**.
### Copy the value [#copy-the-value]
**Copy your new API token** shows the token once: "This token is shown only once. Store it in your CI secrets now. It cannot be recovered later." Select **Copy**, store it, then select **Done**.
transglot keeps only a hash of the token, so nobody can show it to you again. If you close the dialog without copying, revoke the token and create another.
## Store the token [#store-the-token]
Every transglot tool reads the token from the `TRANSGLOT_TOKEN` environment variable:
| Tool | Where the token goes |
| --- | --- |
| CLI in CI | A CI secret exposed as `TRANSGLOT_TOKEN`. See [Use the CLI in CI](https://transglot.ai/docs/developers/cli/continuous-integration). |
| GitHub Action | A repository secret named `TRANSGLOT_TOKEN`, passed to the action's `token` input. See [The GitHub Action](https://transglot.ai/docs/developers/github-action). |
| MCP server | The `TRANSGLOT_TOKEN` entry in your MCP client's configuration. |
| REST API | The `Authorization: Bearer ` header. See [Authentication](https://transglot.ai/docs/developers/api/authentication). |
Never commit a token to `transglot.json` or to a workflow file.
On a laptop you rarely need to create a token by hand: `transglot init` signs you in through the browser and creates a token with `push` and `pull`, named after your machine. It is listed with the project's other tokens.
## Track and revoke tokens [#track-and-revoke-tokens]
The **API tokens** list shows each token's name and creator, its abilities, when it was **last used**, and when it **expires** (`never` for tokens without an expiry). The project's **Releases** page also charts calls per token over the last 14 days under **Token usage**, in its **Connect & SDK** view.
To revoke a token, select **Revoke** on its row. The confirmation explains: "Any CLI or CI job authenticating with this token starts failing on its next run. The token value cannot be recovered, so a replacement has to be created and stored again." Type the token's name to continue, then select **Revoke token**. Revoking takes effect immediately.
To rotate a token without downtime, create the replacement first, update the secret everywhere it is used, then revoke the old one.
## Other credentials [#other-credentials]
A project has three other kinds of credential. They are created on the same **Developer** settings page, and none of them can replace a deploy token.
| Credential | Looks like | Secret? | What it is for |
| --- | --- | --- | --- |
| Deploy token | `tgl_…` | Yes, shown once | The CLI, the GitHub Action, the REST API and the MCP server. |
| [Publishable key](https://transglot.ai/docs/developers/in-context/publishable-keys) | `taip_…` | No. Safe to embed in client JavaScript, limited to the origins you allow, and listed so you can copy it again. | Loading the in-context editor SDK in your app. |
| [CDN key](https://transglot.ai/docs/guides/delivery/connect-your-app-to-the-cdn) | `taicdn_…` | Yes, shown once | Read-only access to a project's published runtime bundles. |
| [Webhook signing secret](https://transglot.ai/docs/developers/webhooks/verify-signatures) | | Yes, shown once | Verifying that a webhook delivery came from transglot. |
See [Project developer settings](https://transglot.ai/docs/developers/project-developer-settings) for the whole page.
# Android XML (https://transglot.ai/docs/developers/formats/android/)
| Format | Identifier | Extension |
| --- | --- | --- |
| Android XML | `android_xml` | `.xml` |
```xml title="res/values-fr/strings.xml"
AcmeBonjour, %1$s !Appuyez sur \"Partager\" pour envoyer l\'invitation%d article%d articles
```
## Keys [#keys]
The root element must be ``. Each `` and `` child is a key named by its `name` attribute.
- A missing `name`, or the same name twice, is an import error.
- Other elements, such as ``, `` or ``, are skipped with a warning.
- **`translatable="false"`** (in any letter case) marks a string Android never translates, such as an app name or a URL. transglot does not create a key for it, translate it, or count its words.
## Plurals [#plurals]
`` becomes a plural key, one form per ``. Each quantity must be a category the locale uses: Android lint often suggests `zero` or `two` for English, but English has only `one` and `other`, so such an item is an import error. A category the file leaves out is stored empty.
On export, a plural key is written as `` with an `` for every category of the locale, in order.
## Escaping [#escaping]
Import decodes Android's string escapes: `\'`, `\"`, `\\`, `\n`, `\t`, `\@`, `\?` and `\uXXXX` (including surrogate pairs). An unknown escape loses its backslash. XML entities (`&`, `<`) decode as usual.
Export applies the reverse, in this order: backslashes are doubled; newlines, `'` and `"` are escaped; `&`, `<` and `>` become entities; a value starting with `@` or `?` gets a leading backslash so Android does not read it as a resource reference.
## Markup inside strings [#markup-inside-strings]
A string is read as its text content. Inline elements inside a ``, such as ``, `` or ``, are not kept: only the text between them is imported. On export, `<`, `>` and `&` in a translation are written as entities, so markup in a translation reaches Android as text. Split a string that needs inline styling into separate keys.
## Placeholders [#placeholders]
Format arguments such as `%1$s`, `%d` and `%.2f` are kept exactly as written. See [Placeholders](https://transglot.ai/docs/developers/formats#placeholders).
## What the file must be [#what-the-file-must-be]
- UTF-8. Other encodings, and files containing NUL bytes, are rejected.
- No `DOCTYPE`. Android resource files never have one, and a file that does is rejected.
- Comments are skipped on import and are not written on export.
## Export [#export]
The file starts with an XML declaration and a `` root, four-space indentation, one `` or `` per key in byte order of the key names. An API pull names the file `strings-{locale}.xml` in its `Content-Disposition` header.
## Related [#related]
- [Plural forms](https://transglot.ai/docs/guides/projects/plural-forms)
- [File formats](https://transglot.ai/docs/developers/formats)
# Apple (https://transglot.ai/docs/developers/formats/apple/)
| Format | Identifier | Extension | Holds |
| --- | --- | --- | --- |
| Apple Strings | `ios_strings` | `.strings` | Simple strings |
| Apple Stringsdict | `ios_stringsdict` | `.stringsdict` | Plural strings only |
| Apple String Catalog | `ios_xcstrings` | `.xcstrings` | Simple and plural strings |
With `.strings` and `.stringsdict`, keep simple strings in one and plural strings in the other, as Xcode does. A String Catalog holds both.
## Strings [#strings]
```text title="fr.lproj/Localizable.strings"
/* Home screen title */
"home.title" = "Bon retour";
"home.greeting" = "Bonjour, %@ !";
"share.hint" = "Appuyez sur \"Partager\"";
```
- Each entry is `"key" = "value";`. Both sides must be double-quoted.
- `/* ... */` and `//` comments are skipped, including in the middle of the file; the same characters inside a quoted string are kept. Comments are not imported as descriptions and are not written on export.
- Escapes decoded: `\"`, `\\`, `\n`, `\t`, `\r`. Any other backslash sequence, including `\U` Unicode escapes, loses its backslash.
- A duplicate key, a missing `=` or `;`, or an unterminated string or comment is an import error that names the problem.
- The file must be UTF-8. Convert UTF-16 `.strings` files first, for example with `iconv -f UTF-16 -t UTF-8`.
On export, each key is one line, `\\`, `\"` and newlines are escaped, and plural keys are left out (they belong in `.stringsdict`).
## Stringsdict [#stringsdict]
```xml title="fr.lproj/Localizable.stringsdict"
itemsNSStringLocalizedFormatKey%#@value@valueNSStringFormatSpecTypeKeyNSStringPluralRuleTypeNSStringFormatValueTypeKeydone%d articleother%d articles
```
Each top-level `` is a plural key. Its `NSStringLocalizedFormatKey` must reference a variable (`%#@name@`, any name), and that variable's dictionary must be `NSStringPluralRuleType`, with one `` per plural category.
- Each category must be one the locale uses. `zero` in an English file is an import error, because English has only `one` and `other`.
- **One variable per entry.** When the format key references several variables (`%#@files@ in %#@folders@`), only the first variable's forms are imported, with a warning.
- **The format key is not kept.** Export always writes `%#@value@` as the format key, a variable named `value`, and `NSStringFormatValueTypeKey` `d`. Text around the variable in your format key (`%#@count@ remaining`) is not carried; put it in each plural form instead.
- The standard Apple `DOCTYPE` is accepted. A `DOCTYPE` with its own declarations is rejected.
On export, simple keys are left out, so a project with no plural keys exports an empty plist. Export uses four-space indentation.
## String Catalog [#string-catalog]
Xcode 15 String Catalogs are JSON files holding every language of a table:
```json title="Localizable.xcstrings"
{
"sourceLanguage": "en",
"strings": {
"home.title": {
"comment": "Home screen title",
"localizations": {
"fr": { "stringUnit": { "state": "translated", "value": "Bon retour" } }
}
},
"items": {
"localizations": {
"fr": {
"variations": {
"plural": {
"one": { "stringUnit": { "state": "translated", "value": "%lld article" } },
"other": { "stringUnit": { "state": "translated", "value": "%lld articles" } }
}
}
}
}
}
},
"version": "1.0"
}
```
### Import [#import]
A catalog is read for one locale at a time: the locale you import picks the matching `localizations` entry (`pt-BR` and `pt_BR` match). Keys with no localization for that locale are skipped, which is normal for a catalog. When you import the catalog's `sourceLanguage` and a key has no explicit localization, the key itself is the value, as Xcode does.
- `comment` becomes the key's description.
- `variations.plural` becomes a plural key. Each category must be one the locale uses.
- Device and width variations, and `substitutions`, are skipped with a warning.
- The `state` of a string unit is not imported: an import never marks a translation as reviewed.
- Only catalog `version` `1.0` is read.
### Export [#export]
An export is a catalog with a single locale: `version` `1.0`, `sourceLanguage` set to the project's source locale, `comment` from the key's description, and every unit with state `translated`. It is not a replacement for a multi-language catalog in your Xcode project, which holds every language in one file. `transglot init` does not set up String Catalogs.
## Placeholders [#placeholders]
Import and export keep format specifiers such as `%@`, `%d`, `%lld` and `%1$@` exactly as written. The [quality checks](https://transglot.ai/docs/concepts/quality-checks) compare the printf-style ones (`%d`, `%1$s`) between source and translation; see [Placeholders](https://transglot.ai/docs/developers/formats#placeholders) for the syntaxes they recognize.
## Related [#related]
- [Plural forms](https://transglot.ai/docs/guides/projects/plural-forms)
- [File formats](https://transglot.ai/docs/developers/formats)
# Flutter ARB (https://transglot.ai/docs/developers/formats/flutter-arb/)
| Format | Identifier | Extension |
| --- | --- | --- |
| Flutter ARB | `flutter_arb` | `.arb` |
ARB is JSON with metadata members: `@@locale` names the file's locale, and `@key` holds metadata about `key`.
```json title="lib/l10n/app_fr.arb"
{
"@@locale": "fr",
"greeting": "Bonjour, {name} !",
"@greeting": {
"description": "Shown at the top of the home screen."
},
"itemCount": "{count, plural, one{{count} article} other{{count} articles}}"
}
```
## Keys [#keys]
Each member whose name does not start with `@` is a key, and its name is the key name. Values must be strings.
- `@@locale` is checked against the locale you are importing; a mismatch is accepted with a warning. Other `@@` members are ignored.
- `@key.description` becomes the key's description. Other metadata, such as `placeholders`, is not read.
- A `@key` with no matching key is accepted with a warning.
## Plurals [#plurals]
A value shaped like an ICU plural message, `{variable, plural, category{...} ...}`, is imported as a plural key, with one form per category. Any variable name is accepted. Braces nest inside a form (`one{{count} article}`), and ICU apostrophe quoting is understood.
- Every category must be one the locale uses. `few` in an English file is an import error. A category the file leaves out is stored empty.
- A plural message with an exact-value selector, such as `=0{No items}`, is kept whole as an ordinary string, so its `=N` branches are not lost. The same goes for `select` messages. Either way the message is written back exactly as it came in.
- A value that is not a plural message is an ordinary string.
On export, a plural key is written as `{count, plural, ...}` with the locale's categories in order. The variable is always `count`.
## Placeholders [#placeholders]
Placeholders such as `{name}` and `{count}` are kept as written. Inside plural forms, any other literal brace is written with ICU quoting (`'{'`, `'}'`), and an apostrophe is doubled (`''`), so a form can never break the message structure. Import decodes the same quoting.
## Export [#export]
- `@@locale` comes first and is the exported locale.
- Keys follow in byte order, each followed by `@key` with its `description` when the key has one.
- Two-space indentation, one trailing newline.
- Untranslated keys are left out.
Because only `description` is written to `@key`, other metadata from your files (such as `placeholders` declarations) is not in an export. Keep your template ARB (the source-language file gen_l10n reads metadata from) as a file you edit yourself, and pull only the target locales.
## Runtime delivery [#runtime-delivery]
`flutter_arb` is one of the four delivery formats the [runtime SDKs](https://transglot.ai/docs/developers/sdks) read, and the only one of them that carries plural keys. See [Delivery formats](https://transglot.ai/docs/developers/sdks/javascript#delivery-formats).
## Related [#related]
- [Plural forms](https://transglot.ai/docs/guides/projects/plural-forms)
- [File formats](https://transglot.ai/docs/developers/formats)
# gettext PO (https://transglot.ai/docs/developers/formats/gettext/)
| Format | Identifier | Extensions |
| --- | --- | --- |
| gettext PO | `gettext_po` | `.po`, `.pot` (exports use `.po`) |
| Unreal PO | `unreal_po` | `.po` |
Both formats share the PO syntax but key their entries differently. gettext keys on the source text; Unreal keys on an identity it stores in `msgctxt`. transglot never guesses Unreal PO: choose `unreal_po` explicitly for files from Unreal's Localization Dashboard.
## gettext PO [#gettext-po]
```po title="locale/fr.po"
msgid ""
msgstr ""
"Language: fr\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Plural-Forms: nplurals=2; plural=(n > 1);\n"
#. Shown on the home screen
msgid "Welcome back"
msgstr "Bon retour"
msgctxt "menu"
msgid "Open"
msgstr "Ouvrir"
msgid "%d item"
msgid_plural "%d items"
msgstr[0] "%d article"
msgstr[1] "%d articles"
```
### Keys [#keys]
The `msgid` is the key, because gettext keys on the source text. An entry with a `msgctxt` is keyed `context|msgid`: the file above imports the keys `Welcome back`, `menu|Open` and `%d item`. On export, the key is split at the first unescaped `|` back into `msgctxt` and `msgid`. A literal `|` or `\` in a context, or a `|` in a `msgid` without context, is escaped with a backslash in the key name, so every key maps back to exactly one entry.
### What is imported [#what-is-imported]
- `#.` extracted comments become the key's description.
- Entries flagged `#, fuzzy` are skipped with a warning, as gettext tools treat them as unreliable.
- Entries with an empty `msgstr` are untranslated and are skipped. So are obsolete `#~` entries.
- `#:` references, `#|` previous strings and `#` translator comments are not imported.
- The header's `Language` is checked against the locale you import; a mismatch is accepted with a warning.
- Strings may span several quoted lines, and the C escape sequences (`\n`, `\t`, `\"`, `\\`, octal and hex escapes) decode.
- A duplicate entry, a second header, or a `msgstr[N]` without `msgid_plural` is an error that names the line.
### Plurals [#plurals]
An entry with `msgid_plural` becomes a plural key. transglot reads the header's `Plural-Forms` expression to work out which CLDR category each `msgstr[N]` belongs to:
- A standard two-form file maps `msgstr[0]` to `one` and `msgstr[1]` to `other`.
- A three-form file for Russian, Ukrainian, Polish and similar languages maps to `one`, `few` and `many`, and also fills `other` from `many`.
- A form that has no CLDR category for the locale is dropped with a warning. A `Plural-Forms` expression transglot does not recognize falls back to first form as `one` and last as `other`, with a warning saying exactly what was mapped.
- A file without a `Plural-Forms` header is read with the locale's standard convention.
- A `msgstr[N]` beyond the declared `nplurals` is an error.
On export, transglot writes the locale's standard `Plural-Forms` line and orders `msgstr[N]` to match it, so `msgfmt --check` accepts the file. `msgid_plural` is the source locale's plural text when there is one.
### Export [#export]
Exports start with a header holding `Language`, `MIME-Version`, `Content-Type` (UTF-8), `Content-Transfer-Encoding` and `Plural-Forms`. There is no date in it, so pulling twice with no changes gives identical files. Each entry has its description as `#.` lines. A key whose name is empty cannot be exported, because it would collide with the header.
Exports keep translations that are not valid ICU, because PO is a format for reviewers as well as apps.
## Unreal PO [#unreal-po]
The `.po` files Unreal Engine's Localization Dashboard exports and imports (Export Text and Import Text).
```po title="Content/Localization/Game/fr/Game.po"
msgid ""
msgstr ""
"Language: fr\n"
"Content-Type: text/plain; charset=UTF-8\n"
#. Key: MainMenu_Play
#. SourceLocation: /Game/UI/MainMenu.MainMenu
msgctxt "MainMenu,MainMenu_Play"
msgid "Play"
msgstr "Jouer"
```
### Keys [#keys-1]
- The key is the `msgctxt` (`Namespace,Key`), and `msgid` is the source text, not the key.
- A file without `msgctxt` falls back to the `#. Key:` comment. Without either, the entry is keyed on its `msgid`, with a warning.
- `#. SourceLocation:` and `#. InfoMetaData:` comments and `#:` references are Unreal's own scaffolding and are dropped. Any other `#.` line becomes the key's description.
- Fuzzy entries are skipped with a warning; untranslated (empty `msgstr`) entries are skipped.
- Escapes decoded: `\\`, `\"`, `\n`, `\t`, `\r`. Any other escape is kept as written, with a warning.
### Export [#export-1]
Each entry is written as `msgctxt` (the key), `msgid` (the source text) and `msgstr` (the translation), with the description as `#.` lines, after a date-free header.
Unreal handles plurals in the engine, not in PO files, so Unreal PO carries simple strings only and plural keys are left out of an export. If you need plural forms in a PO file, use `gettext_po`.
## Related [#related]
- [XLIFF](https://transglot.ai/docs/developers/formats/xliff)
- [Plural forms](https://transglot.ai/docs/guides/projects/plural-forms)
- [File formats](https://transglot.ai/docs/developers/formats)
# File formats (https://transglot.ai/docs/developers/formats/)
transglot reads and writes twenty file formats. Each has an identifier, the string you put in the `format` field of a [CLI rule](https://transglot.ai/docs/developers/cli/configuration), in API requests, and in **Delivery format** for the [runtime SDKs](https://transglot.ai/docs/developers/sdks).
## Formats [#formats]
| Format | Identifier | Extensions | Plurals | Nested keys | Descriptions |
| --- | --- | --- | --- | --- | --- |
| [JSON (flat)](https://transglot.ai/docs/developers/formats/json) | `json_flat` | `.json` | No | No | No |
| [JSON (nested)](https://transglot.ai/docs/developers/formats/json) | `json_nested` | `.json` | No | Yes, split on `.` | No |
| [Laravel JSON](https://transglot.ai/docs/developers/formats/laravel) | `laravel_json` | `.json` | No | No | No |
| [Laravel PHP](https://transglot.ai/docs/developers/formats/laravel) | `laravel_php` | `.php` | No | No | No |
| [YAML](https://transglot.ai/docs/developers/formats/yaml) | `yaml` | `.yml`, `.yaml` | No | Yes, split on `.` | No |
| [Flutter ARB](https://transglot.ai/docs/developers/formats/flutter-arb) | `flutter_arb` | `.arb` | Yes, ICU plural messages | No | Yes |
| [Android XML](https://transglot.ai/docs/developers/formats/android) | `android_xml` | `.xml` | Yes, `` | No | No |
| [Apple Strings](https://transglot.ai/docs/developers/formats/apple#strings) | `ios_strings` | `.strings` | No | No | No |
| [Apple Stringsdict](https://transglot.ai/docs/developers/formats/apple#stringsdict) | `ios_stringsdict` | `.stringsdict` | Plural keys only | No | No |
| [Apple String Catalog](https://transglot.ai/docs/developers/formats/apple#string-catalog) | `ios_xcstrings` | `.xcstrings` | Yes | No | Yes |
| [XLIFF 1.2](https://transglot.ai/docs/developers/formats/xliff) | `xliff_12` | `.xlf`, `.xliff` | No | No | Yes |
| [XLIFF 2.0](https://transglot.ai/docs/developers/formats/xliff) | `xliff_20` | `.xlf`, `.xliff` | No | No | No |
| [gettext PO](https://transglot.ai/docs/developers/formats/gettext) | `gettext_po` | `.po`, `.pot` | Yes, `msgid_plural` | No | Yes |
| [Unreal PO](https://transglot.ai/docs/developers/formats/gettext#unreal-po) | `unreal_po` | `.po` | No | No | Yes |
| [Java properties](https://transglot.ai/docs/developers/formats/java-properties) | `java_properties` | `.properties` | No | No | No |
| [.NET resx](https://transglot.ai/docs/developers/formats/resx) | `resx` | `.resx` | No | No | No |
| [CSV](https://transglot.ai/docs/developers/formats/spreadsheets) | `csv` | `.csv` | Yes, one row per form | No | Yes |
| [Excel](https://transglot.ai/docs/developers/formats/spreadsheets) | `xlsx` | `.xlsx` | Yes, one row per form | No | Yes |
| [Unity CSV](https://transglot.ai/docs/developers/formats/spreadsheets#unity-csv) | `unity_csv` | `.csv` | No | No | Yes |
| [Markdown / MDX](https://transglot.ai/docs/developers/formats/markdown) | `markdown` | `.md`, `.mdx` | No | Not key-based | No |
**Descriptions** means the file has a place for a note to translators, which becomes the key's description when you import and is written back when you export. In the other formats, keep descriptions in the console.
## How a format is chosen [#how-a-format-is-chosen]
- **CLI and API.** Every CLI rule names its format, and the API takes it as a parameter. `transglot init` proposes one from your files.
- **Browser upload.** transglot guesses from the file name and contents, and shows the guess with a control to change it before anything is imported. When it cannot tell, it asks rather than guessing.
The guess uses the extension first, then the contents for extensions several formats share:
- `.json`: `@@locale` means Flutter ARB; `sourceLanguage` with `strings` means an Apple String Catalog; any nested object means JSON (nested); a key containing a space means Laravel JSON; otherwise JSON (flat).
- `.xml`: `` means Android, `` with `` means .NET resx, `` means Stringsdict.
- `.xlf` and `.xliff`: the `version` on ``, or the namespace, picks 1.2 or 2.0.
Unity CSV and Unreal PO are never guessed, because their files look like CSV and gettext PO. Choose them explicitly.
## One file, one locale [#one-file-one-locale]
Every format is read and written one locale at a time. A file that holds several languages (an Apple String Catalog, a Unity string table) is read for the locale you are importing, and an export contains that one locale.
## Keys [#keys]
Each format derives key names in its own way, described on its page. Two rules apply everywhere:
- A key name appears once per file. A duplicate is an error, not a silent overwrite.
- **Nested formats** (JSON (nested) and YAML) join nested object keys with `.` when you import (`{"home": {"title": ...}}` becomes `home.title`) and split on `.` when you export. A project that holds both `home` and `home.title` cannot be exported to them, because `home` would have to be both a string and an object. The export fails and names the colliding keys; publishing in such a format fails with the problem type `nested-key-collision`. Flat formats keep dots as part of the key.
## Plurals [#plurals]
transglot stores a plural key as one form per CLDR plural category of each locale: `one` and `other` for English, `one`, `few`, `many` and `other` for Polish, and so on. See [Plural forms](https://transglot.ai/docs/guides/projects/plural-forms).
- Formats with a plural construct (the ones marked in the table) read and write those forms. A category the file leaves out is stored empty. In most of them, a category the locale does not use, such as `few` in an English file, is an import error; each format's page says how it handles one.
- Formats without one cannot carry a plural key. Exporting to them leaves plural keys out and counts them (the `X-Skipped-Keys` response header on an API pull).
- In any format, a string can hold an ICU message such as `{count, plural, one {# item} other {# items}}`. It is stored as an ordinary string and written back unchanged.
## Placeholders [#placeholders]
Placeholders are read and written exactly as they appear in the file; no format rewrites them. transglot recognizes these syntaxes, and its [quality checks](https://transglot.ai/docs/concepts/quality-checks) flag a translation that loses or alters one:
| Syntax | Examples |
| --- | --- |
| Double braces | `{{name}}` |
| Single braces (ICU, .NET, Python, Rails `%{name}`) | `{name}`, `{0}`, `{ user.name }` |
| printf | `%s`, `%d`, `%1$s`, `%.2f`, `%%` |
| HTML tags | ``, ``, `` |
| Laravel parameters | `:name`, `:count` |
## What an export leaves out [#what-an-export-leaves-out]
An export, a CLI pull, or an API pull contains only translated keys the format can carry. The API's pull response reports each kind of omission in its own header:
| Header | Counts |
| --- | --- |
| `X-Omitted-Empty-Keys` | Keys with no translation yet in that locale. |
| `X-Skipped-Keys` | Keys the format cannot carry, such as plural keys in JSON, or simple keys in Stringsdict. |
| `X-Omitted-Invalid-Icu-Keys` | On a project whose message syntax is ICU, translations left out because they are not valid ICU. |
The export screen in the console warns before you choose a format that would leave keys out, and blocks one that cannot produce a usable file for the project.
## Encoding [#encoding]
Files are read as UTF-8. A leading byte order mark is ignored in the JSON, ARB, String Catalog, Apple Strings, YAML, Java properties, CSV and Unreal PO formats and in the XML-based formats. Other encodings are not supported: convert UTF-16 files (common for older Apple `.strings`) to UTF-8 first.
## Related [#related]
- [Which file formats can I use?](https://transglot.ai/docs/guides/projects/which-file-formats-can-i-use)
- [Import content](https://transglot.ai/docs/guides/projects/import-content)
- [CLI configuration](https://transglot.ai/docs/developers/cli/configuration)
# Java properties (https://transglot.ai/docs/developers/formats/java-properties/)
| Format | Identifier | Extension |
| --- | --- | --- |
| Java properties | `java_properties` | `.properties` |
The format `java.util.Properties` and `ResourceBundle` read, also used by Spring's `messages_{locale}.properties`.
```properties title="messages_fr.properties"
# Home screen
home.title=Bon retour
home.greeting=Bonjour, {0} !
cart.summary = Vous avez {0} articles \
dans votre panier
```
## Keys [#keys]
Each logical line is one key. The whole left-hand side is the key name, dots included; keys are never nested.
- The separator is `=`, `:` or the first run of whitespace. Whitespace around an `=` or `:` is ignored.
- A line whose first non-blank character is `#` or `!` is a comment and is not imported.
- A line ending in an odd number of backslashes continues on the next line. The backslash is dropped, and so is the next line's leading whitespace.
- A key that appears twice is an error.
## Escapes [#escapes]
Import decodes `\n`, `\t`, `\r`, `\f`, `\\`, `\uXXXX`, and the escaped separators `\=`, `\:`, `\#`, `\!` and `\ ` (space). Any other backslash is dropped, as Java does. A malformed `\u` escape is an error.
The file must be UTF-8. Older files that store accented characters as raw Latin-1 bytes are rejected; files that use `\uXXXX` escapes for them are plain ASCII and read fine.
## Plurals [#plurals]
Properties files have no plural construct. Plural keys are left out of an export. A `MessageFormat` choice pattern (`{0,choice,0#no files|1#one file|1<{0} files}`) is an ordinary string and is written back unchanged.
## Placeholders [#placeholders]
`MessageFormat` arguments (`{0}`, `{1,number}`) and `%s`-style specifiers are kept as written. See [Placeholders](https://transglot.ai/docs/developers/formats#placeholders).
## Export [#export]
Each key is written as `key=value` on its own line, in byte order. The output is pure ASCII, so it loads under a Latin-1 reader too:
- Backslashes, tabs, newlines, carriage returns and form feeds are escaped, as are `=`, `:`, `#` and `!`, and spaces that are leading or inside the key.
- Every character above U+007F, and the remaining control characters, is written as `\uXXXX` (characters outside the Basic Multilingual Plane as a surrogate pair).
Comments are not kept.
## Related [#related]
- [File formats](https://transglot.ai/docs/developers/formats)
# JSON (https://transglot.ai/docs/developers/formats/json/)
| Format | Identifier | Extension |
| --- | --- | --- |
| JSON (flat) | `json_flat` | `.json` |
| JSON (nested) | `json_nested` | `.json` |
Laravel's `lang/{locale}.json` files use the same flat shape under their own identifier, `laravel_json`. See [Laravel](https://transglot.ai/docs/developers/formats/laravel).
## JSON (flat) [#json-flat]
A single object of string values. The key is the property name, dots and all.
```json title="locales/en.json"
{
"home.title": "Welcome back",
"home.greeting": "Hello, {name}!",
"cart.items_one": "{count} item",
"cart.items_other": "{count} items"
}
```
- Every value must be a string. A number, boolean or `null` is an import error.
- A value that is an object or array is an error: `Key "home" holds a nested group, which the JSON (flat) format cannot read. This file needs JSON (nested).`
## JSON (nested) [#json-nested]
Objects nest to any depth. On import, the path to each string is joined with `.` to form the key; on export, keys are split on `.` to rebuild the objects.
```json title="locales/en.json"
{
"home": {
"title": "Welcome back",
"greeting": "Hello, {name}!"
},
"cart": {
"items_one": "{count} item",
"items_other": "{count} items"
}
}
```
This file imports the keys `home.title`, `home.greeting`, `cart.items_one` and `cart.items_other`.
- Every leaf must be a string.
- Arrays are read like objects whose keys are the indexes (`steps.0`, `steps.1`), and are written back as objects with those keys, not as arrays.
- A property name that contains a dot is joined like any other segment, so `{"a.b": {"c": "x"}}` imports as `a.b.c` and exports as `{"a": {"b": {"c": "x"}}}`.
- If two paths flatten to the same key (`{"a.b": "x", "a": {"b": "y"}}`), the import fails with a duplicate-key error.
- A project where one key is a prefix of another (`home` and `home.title`) cannot be exported as nested JSON. See [Keys](https://transglot.ai/docs/developers/formats#keys).
## Plurals [#plurals]
Neither JSON format has a plural construct. You have two options:
- **Suffix keys**, as i18next does (`items_one`, `items_other`). transglot stores each as an ordinary key, so each suffix is translated separately. Add the suffixes the target language needs (`items_few`, `items_many`) as keys of their own.
- **ICU messages** in a value, as react-intl and next-intl expect: `"{count, plural, one {# item} other {# items}}"`. The whole message is one string.
Plural keys you create in transglot (with one form per category) are not written to JSON: an export leaves them out and counts them. Use [Flutter ARB](https://transglot.ai/docs/developers/formats/flutter-arb), [Android XML](https://transglot.ai/docs/developers/formats/android) or a [spreadsheet](https://transglot.ai/docs/developers/formats/spreadsheets) to carry them, or publish `flutter_arb` for the runtime SDKs.
## Placeholders [#placeholders]
Values are read and written exactly as they are, so `{name}`, `{{name}}`, `%s` and ICU arguments survive a round trip. See [Placeholders](https://transglot.ai/docs/developers/formats#placeholders).
## Export [#export]
Exports are UTF-8 with two-space indentation, keys in byte order, non-ASCII characters and slashes written as themselves rather than escaped, and one trailing newline. Untranslated keys are left out.
JSON has no place for descriptions; keep them in the console.
## Related [#related]
- [File formats](https://transglot.ai/docs/developers/formats)
- [Runtime SDKs](https://transglot.ai/docs/developers/sdks)
- [i18next backend](https://transglot.ai/docs/developers/sdks/i18next)
# Laravel (https://transglot.ai/docs/developers/formats/laravel/)
| Format | Identifier | Extension | Typical path |
| --- | --- | --- | --- |
| Laravel JSON | `laravel_json` | `.json` | `lang/{locale}.json` |
| Laravel PHP | `laravel_php` | `.php` | `lang/{locale}/messages.php` |
## Laravel JSON [#laravel-json]
The file Laravel's `__('...')` helper reads when you key strings by their source sentence. It is a flat JSON object, and transglot reads and writes it exactly like [JSON (flat)](https://transglot.ai/docs/developers/formats/json): every value must be a string, and nested objects are an error.
```json title="lang/fr.json"
{
"Welcome back": "Bon retour",
"Hello, :name!": "Bonjour, :name !",
"You have :count new messages.": "Vous avez :count nouveaux messages."
}
```
The key is the source sentence. When transglot guesses the format of a `.json` file, a flat file with a space in any key is taken as Laravel JSON.
## Laravel PHP [#laravel-php]
A PHP file returning a flat array of strings:
```php title="lang/fr/messages.php"
'Bon retour',
'greeting' => 'Bonjour, :name !',
];
```
transglot never runs the file. It reads it with a strict scanner that accepts only this exact shape:
- the file starts with ` 'value'`, separated by commas (a trailing comma is fine),
- `\\` and `\'` as the only escapes.
Anything else is an import error, including comments (such as the doc-comment header Laravel's own language files start with), double-quoted strings, nested arrays, constants, concatenation and function calls. A nested array fails with `Nested arrays are not supported in Laravel PHP files.`
So Laravel PHP suits files you let transglot own. For Laravel's bundled files with nested arrays (such as `validation.php`), or files with comments, use Laravel JSON instead. The browser upload does not offer `.php` files; push them with the CLI or the API.
On export, transglot writes the same shape, four-space indented, keys in byte order. An empty file is `return [];`.
## Plurals [#plurals]
Neither format has a plural construct. Laravel's pipe syntax (`'{0} No messages|{1} One message|[2,*] :count messages'`) is an ordinary string to transglot and is stored and written back as one value. Plural keys created in transglot are left out of a Laravel export.
## Placeholders [#placeholders]
`:name`-style parameters (and their `:Name` and `:NAME` variants) are written back exactly as they are, and the [quality checks](https://transglot.ai/docs/concepts/quality-checks) flag a translation that drops one.
## Related [#related]
- [JSON](https://transglot.ai/docs/developers/formats/json)
- [File formats](https://transglot.ai/docs/developers/formats)
# Markdown / MDX (https://transglot.ai/docs/developers/formats/markdown/)
| Format | Identifier | Extensions |
| --- | --- | --- |
| Markdown / MDX | `markdown` | `.md`, `.mdx` (exports use `.md`) |
Markdown is a document, not a list of strings, so it works differently from every other format: transglot splits the document into blocks, one key per block, and rebuilds a document with the same structure on export.
## How a document becomes keys [#how-a-document-becomes-keys]
Each block gets a key made of its type and its position in the document. This file:
````md title="docs/getting-started.md"
---
title: Getting started
---
# Getting started
Install the **CLI** with [npm](https://npmjs.com).
- Create a project
- Push your files
```bash
npx transglot push
```
| Command | What it does |
| --- | --- |
| push | Uploads files |
> Tip: run pull after push.
````
imports as:
| Key | Content |
| --- | --- |
| `fm:0` | The front matter, verbatim |
| `h1:1` | `Getting started` |
| `p:2` | `Install the **CLI** with [npm](https://npmjs.com).` |
| `ul:3.0`, `ul:3.1` | Each list item |
| `code:4` | The fenced code block, verbatim |
| `td:5.0.0` ... `td:5.1.1` | Each table cell, by row and column |
| `bq:6` | `Tip: run pull after push.` |
- **Translatable blocks**: headings, paragraphs, list items, table cells and blockquote text. Inline markup (`**bold**`, links, `` `code` ``) stays inside the text, so translators keep it in place.
- **Blocks kept verbatim**: YAML (`---`) or TOML (`+++`) front matter, fenced code blocks, raw HTML and MDX JSX blocks, and MDX `import` and `export` statements. They are stored with their exact text so export can put them back. Text inside front matter, such as a `title`, is part of that verbatim block.
Because keys are positions, they only make sense for that document. Adding a paragraph near the top of the source shifts the keys of every block after it.
## Export [#export]
Export rebuilds the document from the keys, in position order. The result has the same structure, written in a canonical style:
- one blank line between blocks, LF line endings, no trailing whitespace,
- ordered lists renumbered from 1,
- table delimiter rows written as `---` (column alignment is dropped),
- thematic breaks written as `---`.
Running the output through transglot again gives the same document, but it is not byte-for-byte your original file.
Only a project whose keys all came from a Markdown document can be exported as Markdown. The export screen blocks the format for any other project.
## Limitations [#limitations]
- Setext headings (text underlined with `===` or `---`) are not recognized. They become a paragraph followed by a thematic break; use `#` headings.
- Indented (four-space) code blocks are read as paragraph text. Use fenced code blocks.
- Lazy continuation lines in lists and blockquotes become blocks of their own.
- Hard-wrapped paragraphs keep their line breaks; they are not re-wrapped.
- The file must be UTF-8, and an unclosed code fence is an import error naming the line it opened on.
- Markdown has no plurals.
## Related [#related]
- [Import content](https://transglot.ai/docs/guides/projects/import-content)
- [File formats](https://transglot.ai/docs/developers/formats)
# .NET resx (https://transglot.ai/docs/developers/formats/resx/)
| Format | Identifier | Extension |
| --- | --- | --- |
| .NET resx | `resx` | `.resx` |
```xml title="Resources/Strings.fr.resx"
text/microsoft-resxBon retourBonjour, {0} !
```
## Keys [#keys]
The root element must be ``. Each string `` element is a key: `name` is the key name and the text of `` is the translation.
- Only string resources are read. A `` with a `type` attribute (an image, an icon) or a `mimetype` attribute (base64 binary) is skipped.
- ``, ``, `` and the `` block are skipped.
- A `` without `name` or without ``, or a name that appears twice, is an error.
- XML entities decode as usual, and `xml:space="preserve"` is honoured, so leading and trailing spaces in a value are kept.
- `` elements are not imported. Keep descriptions in the console.
- A `DOCTYPE` with its own declarations is rejected.
## Plurals [#plurals]
ResX has no plural construct. Plural keys are left out of an export.
## Placeholders [#placeholders]
Composite format items such as `{0}` and `{1:N2}` are kept as written. See [Placeholders](https://transglot.ai/docs/developers/formats#placeholders).
## Export [#export]
An export is a minimal ResX file: the four standard `` entries (`resmimetype` `text/microsoft-resx`, `version` `2.0`, and the `System.Resources` reader and writer), then one `` per key in byte order, two-space indented. It has no `` block.
Carriage returns are written as `
`, and control characters XML cannot represent are replaced with U+FFFD, so the file is always well-formed. Resources other than strings in your original file (images, binary data) are not part of an export, so keep them in a separate `.resx`.
## Related [#related]
- [File formats](https://transglot.ai/docs/developers/formats)
# Spreadsheets (https://transglot.ai/docs/developers/formats/spreadsheets/)
| Format | Identifier | Extension |
| --- | --- | --- |
| CSV | `csv` | `.csv` |
| Excel | `xlsx` | `.xlsx` |
| Unity CSV | `unity_csv` | `.csv` |
CSV and Excel share one table layout for one locale. Unity CSV is the multi-language sheet Unity's Localization package exports; transglot never guesses it, so choose `unity_csv` explicitly for those files.
## CSV and Excel [#csv-and-excel]
```csv title="fr.csv"
"key","value","description"
"home.title","Bon retour","Home screen title"
"home.greeting","Bonjour, {name} !",""
"items[one]","{count} article","Item count in the cart"
"items[other]","{count} articles",""
```
### Columns [#columns]
| Column | Required | Holds |
| --- | --- | --- |
| `key` | Yes | The key name. |
| `value` | Yes | The translation, or one plural form. |
| `description` | No | The key's description. |
- The first non-blank row is the header. Column names are matched without regard to case or surrounding spaces, in any order. Other columns are ignored with a warning; a header without `key` and `value` is an error.
- Blank rows, and rows with an empty key, are skipped.
- A key that appears twice is an error.
- Excel files are read from the **first worksheet** only. Numbers, booleans and dates in cells are read as text. Very large sheets are refused above an import row limit.
- CSV files follow RFC 4180: quoted or bare fields, commas, line breaks and doubled quotes (`""`) inside quoted fields, and CRLF, LF or CR line endings. A leading byte order mark (Excel writes one) is ignored.
### Plurals [#plurals]
A table has no place for plural categories, so a plural key takes one row per category, with the category in square brackets after the key: `items[one]`, `items[other]`. The rows are combined into one plural key on import.
- The bracketed suffix is read as a category only when it is one of the locale's plural categories. Any other bracketed suffix (`filters[advanced]`) is part of an ordinary key name.
- A key used both on its own and with a category suffix is an error.
- The description can be on any of the key's rows; the first non-empty one is used. On export it is written on the first row.
- A category the sheet leaves out is stored empty.
### Formula safety [#formula-safety]
A cell that starts with `=`, `+`, `-`, `@`, a tab or a carriage return can run as a formula when the file is opened in Excel or Google Sheets. On export, such a cell gets a leading apostrophe (`'=SUM(A1)`) so it opens as text, and on import that apostrophe is removed again, so values such as `+5 Gold` round-trip unchanged.
### Export [#export]
- Columns are always `key`, `value`, `description`, in that order, one row per key (or per plural category) in byte order of the key names.
- CSV exports quote every field, use LF line endings and UTF-8 without a byte order mark.
- Excel exports write every value as a text cell. An Excel file differs byte for byte between exports (the file is a zip with timestamps), but its contents are the same.
## Unity CSV [#unity-csv]
The string table CSV that Unity's Localization package (`com.unity.localization`) exports and imports: a `Key` column, an optional `Shared Comments` column, and one column per language, named `Language(code)`.
```csv title="UI Text.csv"
Key,Shared Comments,English(en),French(fr)
MainMenu_Play,Main menu button,Play,Jouer
MainMenu_Quit,,Quit,Quitter
```
### Import [#import]
The sheet is read for the locale you import:
- The value column is the one whose header ends in `(code)` for that locale, such as `French(fr)` for `fr`, or whose header is the locale code itself. Codes match regardless of case and of `-` or `_`. A sheet with no matching column is an error.
- `Key` is the key name and is required. A key that appears twice is an error.
- `Shared Comments` (or `Description`) becomes the key's description.
- Other languages' columns and per-language comment columns are ignored, each reported once.
- An empty cell for the locale is skipped, so it never clears an existing translation.
### Export [#export-1]
An export has three columns, `Key`, `Shared Comments` and the locale code, which Unity's importer maps back to the language. Cells get the same formula protection as CSV. Unity models plurals as Smart Strings, which have no column in this sheet, so plural keys are left out; use `csv`, `xlsx` or `gettext_po` if you need plural forms in a file.
## Related [#related]
- [Plural forms](https://transglot.ai/docs/guides/projects/plural-forms)
- [File formats](https://transglot.ai/docs/developers/formats)
# XLIFF (https://transglot.ai/docs/developers/formats/xliff/)
| Format | Identifier | Extensions |
| --- | --- | --- |
| XLIFF 1.2 | `xliff_12` | `.xlf`, `.xliff` (exports use `.xlf`) |
| XLIFF 2.0 | `xliff_20` | `.xlf`, `.xliff` (exports use `.xlf`) |
XLIFF is bilingual: each unit carries the source text and its translation. transglot reads the translation for the locale you import and writes both sides on export, so a translator or tool receiving the file sees the source next to each string. When transglot guesses the format of an `.xlf` file, the `version` on `` (or the namespace) picks 1.2 or 2.0.
## XLIFF 1.2 [#xliff-12]
```xml title="fr.xlf"
Welcome backBon retourHome screen title
```
### Import [#import]
- The key is the `resname` attribute, or `id` when there is no `resname`. A unit with neither is an error, and so is a key that appears twice.
- The value is the `` text. A unit with no ``, or an empty one, is skipped with a warning, except when you import the file's source language: then `` is the value.
- `` elements become the key's description (several notes are joined with newlines).
- Units inside `` elements are read. Other elements, such as `` and ``, are ignored.
- `target-language` is checked against the locale you import; a mismatch is accepted with a warning.
- The `state` attribute is not imported: an import never marks a translation as reviewed.
## XLIFF 2.0 [#xliff-20]
```xml title="fr.xlf"
Welcome backBon retour
```
### Import [#import-1]
- The XLIFF 2.0 namespace is required. A 1.2 document is rejected rather than read as 2.0.
- The key is the `` `id`. A unit without one is an error, and so is a key that appears twice.
- A unit with several `` elements is read as one string, the segments joined in order.
- The value is the `` text; a unit with no `` is read from its ``.
- Only units that are direct children of `` are read. Units inside `` elements are not imported.
- ``, `` and elements from other namespaces (such as the metadata, matches or glossary modules) are ignored. XLIFF 2.0 files do not carry descriptions into transglot.
## Inline markup [#inline-markup]
transglot stores plain text. A unit whose `` or `` contains inline elements (``, ``, ``, `` in 1.2; ``, ``, ``, ``, `` in 2.0) is skipped with a warning naming it, rather than imported with its placeholders silently removed. Text placeholders such as `%1$s` and `{name}` are ordinary text and are kept. CDATA and XML entities decode like any text.
## Plurals [#plurals]
Neither version has a plural construct. Plural keys are left out of an XLIFF export, and an ICU plural message inside a unit is an ordinary string.
## Export [#export]
- One unit per key, in byte order, with `` from the project's source locale and `` from the exported locale. 1.2 writes `id` and `resname` (both the key), `state="translated"`, and a `` with the key's description. 2.0 writes one `` per unit.
- Language attributes are BCP 47 (`pt-BR`).
- When a key has no source text, `` is empty rather than filled with the translation, so the file never labels translated text as source.
- Carriage returns are written as `
`, and control characters XML cannot represent are replaced with U+FFFD, so the file is always well-formed.
- Unlike files for apps, XLIFF exports keep translations that are not valid ICU, because a reviewer needs to see them.
## Security [#security]
A `DOCTYPE` with its own declarations is rejected, external DTDs are never fetched, and entities are never expanded from them.
## Related [#related]
- [gettext PO](https://transglot.ai/docs/developers/formats/gettext)
- [File formats](https://transglot.ai/docs/developers/formats)
# YAML (https://transglot.ai/docs/developers/formats/yaml/)
| Format | Identifier | Extensions |
| --- | --- | --- |
| YAML | `yaml` | `.yml`, `.yaml` (exports use `.yml`) |
The layout Rails I18n and similar libraries use: a single top-level key naming the locale, with the strings nested under it.
```yaml title="config/locales/fr.yml"
fr:
home:
title: "Bon retour"
greeting: "Bonjour, %{name} !"
cart:
items:
one: "%{count} article"
other: "%{count} articles"
```
## Keys [#keys]
Nested map keys are joined with `.`, below the locale root: the file above imports `home.title`, `home.greeting`, `cart.items.one` and `cart.items.other`. On export, keys are split on `.` to rebuild the maps, with the same rules as [JSON (nested)](https://transglot.ai/docs/developers/formats/json#json-nested): a project where one key is a prefix of another (`home` and `home.title`) cannot be exported as YAML, and two paths that flatten to the same key are an import error.
## What the file must contain [#what-the-file-must-contain]
- **Exactly one root key**, the locale. A different root key than the locale you are importing is accepted with a warning; both `pt-BR` and `pt_BR` match `pt_BR`. An empty root (`fr:` with nothing under it) is a valid empty file.
- **Maps and strings only.** Every leaf must be a string. A sequence (a YAML list, such as Rails' `day_names`) is an error, and so is an unquoted number or boolean (`count: 5`, `enabled: true`): quote such values if they are text.
- Comments, either quote style, multi-line strings and anchors are all accepted. Alias expansion is bounded, so a file built to expand without limit is rejected.
## Plurals [#plurals]
YAML has no plural construct of its own. Rails-style plurals (`items.one`, `items.other`) are ordinary nested keys to transglot, each translated as its own string. Add the categories a target language needs (`few`, `many`) as keys of their own. Plural keys you create in transglot are left out of a YAML export.
## Placeholders [#placeholders]
`%{name}` (Rails), `{name}` and `%s` are kept exactly as written. See [Placeholders](https://transglot.ai/docs/developers/formats#placeholders).
## Export [#export]
Exports are written so that they load the same way in every YAML parser:
- The root key is the locale in hyphenated form (`pt-BR`, `zh-CN`), which is how Rails names locales.
- Two-space indentation.
- Every value is double-quoted, with `\n`, `\t`, `\r`, `\"` and `\\` escapes, so multi-line text never folds.
- A key is written bare only when it is a plain identifier that no YAML parser would read as something else; keys such as `no`, `on`, `true` or digits are double-quoted.
Comments and anchors from the file you imported are not kept.
## Related [#related]
- [JSON](https://transglot.ai/docs/developers/formats/json)
- [File formats](https://transglot.ai/docs/developers/formats)
# The GitHub Action (https://transglot.ai/docs/developers/github-action/)
The transglot GitHub Action runs the [CLI](https://transglot.ai/docs/developers/cli) in a workflow. On each run it pushes your source strings, waits for the translation batch to finish, pulls the translated files, and commits them to the branch the workflow ran on. Reference it as `transglot/transglot-action@v1`; the `v1` tag moves to each new release of the action.
## Before you start [#before-you-start]
1. **Commit `transglot.json`** to the repository. Run `npx transglot@latest init` in your checkout to write one, or see the [configuration reference](https://transglot.ai/docs/developers/cli/configuration).
2. **Create a deploy token** with the **push** and **pull** abilities. With **push** alone the action uploads strings but cannot bring translations back. See [Deploy tokens](https://transglot.ai/docs/developers/deploy-tokens).
3. **Add the token as a repository secret** named `TRANSGLOT_TOKEN`, under **Settings** → **Secrets and variables** → **Actions** in GitHub. The token never goes in the workflow file.
## Add the workflow [#add-the-workflow]
Create `.github/workflows/transglot.yml`:
```yaml title=".github/workflows/transglot.yml"
name: transglot
on:
push:
branches: [main]
jobs:
localize:
runs-on: ubuntu-latest
permissions:
contents: write # the action commits pulled translations back to a branch
steps:
- uses: actions/checkout@v7
- uses: transglot/transglot-action@v1
with:
token: ${{ secrets.TRANSGLOT_TOKEN }}
url: https://api.transglot.ai
```
The project's **Releases** page shows the same workflow in its **Connect & SDK** view, under **GitHub Action**: "Drop this into .github/workflows/transglot.yml and add TRANSGLOT_TOKEN to your repo secrets."
`permissions: contents: write` is required for the default commit mode. Without it, the commit step fails with a 403 because the job's token is read-only.
A commit made with the workflow's own `GITHUB_TOKEN` does not start another workflow run, so committing translations to `main` does not trigger this workflow again.
## Inputs [#inputs]
The action accepts only these inputs. GitHub ignores an input the action does not declare and only prints a warning, so check the spelling if a setting seems to have no effect.
## Outputs [#outputs]
| Output | Description |
| --- | --- |
| `batch_id` | The id of the translation batch the push queued. Empty when nothing needed translating. |
| `files_changed` | How many files the pull rewrote. `0` when every file was already up to date. |
## What a run does [#what-a-run-does]
1. **Installs the CLI** on Node.js 22, once per run.
2. **Pushes** your source files (`transglot push`, with `--wait` unless `wait` is `"false"`). With `--wait`, the step waits up to 600 seconds.
3. **Pulls** the translated files (`transglot pull`). It pulls when the push succeeded, when the word limit held the batch back (your sources are still synced), and when the batch failed, because translations that did complete can still be pulled. After any other error it skips the pull.
4. **Commits or uploads** the pulled files, depending on `commit`. In `branch` mode it stages only the files the pull wrote, commits as `github-actions[bot]` with the message `chore(i18n): sync translations from transglot`, and pushes. When nothing changed, or every pulled file is ignored by `.gitignore`, it skips the commit. In `artifact` mode it uploads them as an artifact named `transglot-files`.
5. **Reports** the result. The job fails with the worst [CLI exit code](https://transglot.ai/docs/developers/cli/exit-codes) of the push and the pull. Because this step runs last, a failed batch still commits the translations that finished and sets both outputs before the job turns red.
## Examples [#examples]
### Upload files as an artifact [#upload-files-as-an-artifact]
Use `commit: artifact` when the branch is protected, or to review the files before they land:
```yaml title=".github/workflows/transglot.yml"
name: transglot
on:
push:
branches: [main]
jobs:
localize:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: transglot/transglot-action@v1
with:
token: ${{ secrets.TRANSGLOT_TOKEN }}
commit: artifact
```
The run's summary page lists the `transglot-files` artifact. This mode needs no write permission.
### Open a pull request with the translations [#open-a-pull-request-with-the-translations]
With `commit: none` the files stay in the workspace, so a later step can do anything with them. This workflow opens a pull request with a third-party action:
```yaml title=".github/workflows/transglot.yml"
name: transglot
on:
push:
branches: [main]
jobs:
localize:
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
steps:
- uses: actions/checkout@v7
- uses: transglot/transglot-action@v1
id: transglot
with:
token: ${{ secrets.TRANSGLOT_TOKEN }}
commit: none
- if: steps.transglot.outputs.files_changed != '0'
uses: peter-evans/create-pull-request@v8
with:
branch: transglot/translations
commit-message: "chore(i18n): sync translations from transglot"
title: Sync translations from transglot
```
### Push now, pull on a schedule [#push-now-pull-on-a-schedule]
Large batches can take longer than you want a merge job to run. Push without waiting on every merge, and pull on a schedule with the CLI's `pull --wait`, which waits for every active batch of the project:
```yaml title=".github/workflows/transglot.yml"
name: transglot
on:
push:
branches: [main]
schedule:
- cron: "0 3 * * *"
jobs:
push-strings:
if: github.event_name == 'push'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 22
- run: npx --yes transglot@0.5.0 push
env:
TRANSGLOT_TOKEN: ${{ secrets.TRANSGLOT_TOKEN }}
pull-translations:
if: github.event_name == 'schedule'
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 22
- run: npx --yes transglot@0.5.0 pull --wait --timeout 1800
env:
TRANSGLOT_TOKEN: ${{ secrets.TRANSGLOT_TOKEN }}
- run: |
if [ -n "$(git status --porcelain)" ]; then
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add -A
git commit -m "chore(i18n): sync translations from transglot"
git push
fi
```
Setting `wait: "false"` on the action is not the same: it pulls straight after pushing, before anything is translated. A locale with no translations yet then stops the pull, because `pull` refuses to overwrite an existing file with an empty one.
### Use the outputs [#use-the-outputs]
```yaml
- uses: transglot/transglot-action@v1
id: transglot
with:
token: ${{ secrets.TRANSGLOT_TOKEN }}
- if: steps.transglot.outputs.batch_id != ''
run: echo "Translated in batch ${{ steps.transglot.outputs.batch_id }}, ${{ steps.transglot.outputs.files_changed }} file(s) changed"
```
## Troubleshooting [#troubleshooting]
| What you see | Cause and fix |
| --- | --- |
| A 403 when the action pushes the commit | The job's token is read-only. Add `permissions: contents: write`, or use `commit: artifact`. |
| Authentication errors in the log (exit code 2) | The `TRANSGLOT_TOKEN` secret is missing, misspelled, revoked or expired, or the token lacks **push** or **pull**. |
| A configuration error (exit code 1) | `transglot.json` is missing from the checkout, or a path in it matches no file. |
| The job reports a failed or cancelled batch (exit code 4) | The translations that did complete were still pulled and committed. Retry the failed strings from the project's **Runs** page. |
| The job reports the word limit (exit code 3) | Your sources were uploaded; only the translation was held back. Raise the limit or wait for the reset. |
| The job reports a timeout (exit code 5) | The batch was still running after 600 seconds. It finishes on its own; the next run pulls the result. |
| The run succeeds but commits nothing | Nothing changed since the last run, or the pulled files are ignored by `.gitignore`. |
| A setting has no effect | It is not one of the inputs above. GitHub ignores undeclared inputs. |
# In-context editor (https://transglot.ai/docs/developers/in-context/)
The in-context editor runs inside your own app. A reviewer holds ALT (Option on a Mac) to see which strings are editable, ALT+clicks one, and edits its translation in a panel on top of the page, without hunting for the key in the console. Saves go straight to your transglot project.
This section is for the developer who embeds it. For what reviewers do once it is running, see [Connect the in-context editor](https://transglot.ai/docs/guides/quality/connect-the-in-context-editor).
## How it fits together [#how-it-fits-together]
### Your app marks its strings [#your-app-marks-its-strings]
You wrap your existing translate function. Every string it returns gets an invisible watermark that maps it back to its key and locale. What users see does not change.
### The editor mounts with a publishable key [#the-editor-mounts-with-a-publishable-key]
A publishable key (`taip_...`) is a public id that you ship in your page. From an allowed origin, it buys a short-lived, read-only session. See [Publishable keys](https://transglot.ai/docs/developers/in-context/publishable-keys).
### Your backend grants write access [#your-backend-grants-write-access]
To let a reviewer save, your server asks transglot for a single-use nonce using a project token with write access, naming the keys this reviewer may change. The editor trades the nonce for a session that can write those keys.
### Reviewers edit in place [#reviewers-edit-in-place]
With editing mode on, ALT+click opens the string under the pointer. A save updates the translation in transglot and the text on the page.
## What reviewers see [#what-reviewers-see]
When editing mode is on, a floating bar sits on the page. It shows the locale being edited and each language's completion, lets the reviewer switch locale or add a language (when the session allows it), and has **Done** to leave editing mode. A read-only session is marked **Read only**.
ALT+click on a marked string opens the editing panel:
- the key, the **Source** text, and the **Target** for the current locale (one field per plural category for a plural key),
- live checks on the draft, the same ones the console editor runs against the project's rules, such as placeholders, plural forms and glossary terms,
- translation memory matches, each with **Use this**,
- **Suggest with AI**, which asks Glossa for a translation,
- **Revert** and **Save**.
If someone else saved the same string after the panel opened, the save is refused and the panel shows **Their version** next to the reviewer's draft, with **Keep mine** to put their own wording back.
A string a reviewer saves counts as edited by a person, so it is never overwritten by AI afterwards. Each save is attributed to the publishable key and to the reviewer label your app passes.
When the session can write, the editor also captures a screenshot of the element before asking Glossa for a suggestion, and the capture lands in the project's [screenshot library](https://transglot.ai/docs/guides/quality/the-screenshot-library). Capture uses the optional `html2canvas` package; without it, suggestions still work from the text alone.
## Who should see it [#who-should-see-it]
The editor is for reviewers. Do not show it to the public. The bar reports how complete each of your languages is, and anyone in editing mode can open every marked string on the page.
The SDK cannot tell a reviewer from a visitor, or your staging site from production, so mounting is inert by default: nothing appears until your app turns editing mode on. Render the editor only for people your app knows may review translations, and either pass `enterOnMount` for them or call `session.enter()` from your own control.
## Requirements [#requirements]
- The Starter plan or above. Creating publishable keys and opening sessions both need it.
- An admin on the project to create the publishable key.
- For saving: a project token with write access on your server. See [Deploy tokens](https://transglot.ai/docs/developers/deploy-tokens).
- A browser. The editor works on any page; the watermark has to stay inside one text node, so a translation that renders as several elements (text with inline markup) can be opened but is not updated on the page after a save.
## Next steps [#next-steps]
# Install the in-context editor (https://transglot.ai/docs/developers/in-context/install/)
There are two packages:
| Package | Use it for |
| --- | --- |
| `@transglot/react` | React 18 and 19 apps. A `TransglotProvider` component and a `useIncontextT` hook. |
| `@transglot/incontext` | Any other page: Vue, Svelte, Angular, server-rendered HTML or plain scripts. `mountIncontextEditor` and `wrapT`. The React adapter is a thin layer over it. |
Both need a [publishable key](https://transglot.ai/docs/developers/in-context/publishable-keys) whose allowed origins include the page's origin.
`@transglot/react` is the in-context editor. To deliver published translations to your users, use [`@transglot/react-i18n`](https://transglot.ai/docs/developers/sdks/react).
## Install [#install]
```npm
npm install @transglot/react
```
`@transglot/incontext` is installed with it. React and React DOM 18 or 19 are peer dependencies.
```npm
npm install @transglot/incontext
```
The package is ESM only and has no dependencies.
To capture screenshots for the [screenshot library](https://transglot.ai/docs/guides/quality/the-screenshot-library) when a reviewer asks for a suggestion, also install the optional peer dependency:
```npm
npm install html2canvas
```
Without it, everything else works and suggestions use the text alone.
## React [#react]
Render the provider only for people who may review translations, and mark strings with the `t` from `useIncontextT()`:
```tsx title="src/ReviewProvider.tsx"
import { TransglotProvider } from '@transglot/react';
import type { ReactNode } from 'react';
import { i18n } from './i18n';
export function ReviewProvider({ user, locale, children }: { user: User; locale: string; children: ReactNode }) {
if (!user.canReviewTranslations) {
return children;
}
return (
i18n.t(key, ...args)}
reviewer={user.email}
writableKeys={user.reviewableKeys}
getNonce={(keys) =>
fetch('/api/transglot-nonce', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ keys }),
})
.then((response) => response.json())
.then((body) => body.nonce)
}
enterOnMount
>
{children}
);
}
```
```tsx title="src/Hero.tsx"
import { useIncontextT } from '@transglot/react';
export function Hero() {
const t = useIncontextT();
return