Translatize

Get an overview of the Translatize project this server is connected to: its name and id, the configured languages and the source language, the base branch the API token is bound to, the token's role, the branch scope (fixed = only the base branch is writable; create-own = the token may also create and manage its own branches), the names of the branches this token may write to, the total number of label (translation-key) records, and per-language completeness percentages. Use this first to learn which project, branch, languages and scope you are working with. Takes no arguments.

无需输入参数。

List translation label keys on a branch, optionally filtered by namespace (a dotted key prefix, so "checkout" matches "checkout.title") and/or status. Returns each label's key, status and tags; pass include_values=true to also get the per-language translation strings. Use this to browse or enumerate keys. Values are omitted by default to keep the response small. When include_values is true and more than 300 labels match, only the first 300 are returned with a note; narrow the result using the namespace filter. Reads the token's base branch unless `branch` names another allowed branch.

Fetch the full record (all per-language values, status and tags) for a specific set of label keys on a branch. Use this when you already know the exact keys you need, for example from list_labels or search_labels, and want their complete translations. Returns the found labels plus a not_found list of any requested keys that do not exist on the branch. Reads the token's base branch unless `branch` names another allowed branch.

Case-insensitive substring search across labels on a branch. Set in='keys' to match only key names, in='values' to match only translation text, or in='both' (the default) for either. Returns matching labels with their full values, capped at 100 matches. Use this to find keys by a fragment of the key path or by the wording of an existing translation. Reads the token's base branch unless `branch` names another allowed branch.

Create or update a single label on a branch (upsert by key). Provide the key plus any of values (an object of languageCode -> string), status, or tags. Every language in values must be configured on the project, or the call is rejected with unknown_languages. Returns whether the label was created or updated and its resulting stored state. Use this to add a new translation key or change an existing one. Give every NEW key its `context` (a description of the UI element, plus charLimit/location when known) so translators and the AI get it right. Writes to the token's base branch unless `branch` names another allowed branch.

Create or update many labels on a branch in one call (batched automatically, with no client-side size limit). Pass labels as an array of { key, values?, status?, tags?, context? }. Returns counts of created and updated labels plus a failed list of any individual items the server rejected (for example, an unknown language on one item). Use this instead of repeated upsert_label calls when writing more than a couple of keys, and give every new key its `context` (description, plus charLimit/location when known). Writes to the token's base branch unless `branch` names another allowed branch.

Report translation coverage on a branch: for every configured language, the total number of keys, how many are translated (have a non-empty value), how many are missing, and up to 50 example missing keys. Use this for a quick coverage overview; use get_missing_translations to get the actual keys and source text to translate. Reads the token's base branch unless `branch` names another allowed branch.

List every branch in the project, each flagged with writable (whether this token may read/write/export it) and createdByThisToken (whether this token created it). Also returns baseBranch (the branch the token is bound to) and branchScope (fixed = only the base branch is writable; create-own = the token may additionally create branches and manage the ones it creates). Use this to see which branches exist and which you are allowed to act on before compare/merge/delete. Takes no arguments.

无需输入参数。

Create a new branch, forked from the token's base branch (you cannot choose a different base), then work on it by passing its name as `branch` to the label tools. Requires a create-own scoped token and the developer role or higher. A fixed-scope token fails with branch_scope_fixed; when that happens, tell the user to issue a create-own token under Project Settings -> Integrations. Name rules: 1-100 characters matching ^[a-zA-Z0-9_-]+$, and not "main". Returns the created branch. This is the typical first step of a change: create a branch, edit/translate on it, review_changes, then merge_branch back into the base and delete_branch.

Compare a branch (the source) against the token's base branch (the target): returns the changed, added and deleted keys, each with the differing per-language source/target values, plus a summary of counts. The branch must be in the token's allowed set. Use this to see exactly what a branch would bring into the base before merging. For a capped, human-oriented review view, use review_changes instead.

List the per-key, per-language merge conflicts between a branch (source) and the token's base branch (target): the cases where both sides hold a different non-empty value. Returns a flat conflicts array plus hasConflicts / conflictCount. An empty list means the branch is safe to merge with the default (overwrite) strategy. When there ARE conflicts and you want to resolve each one explicitly, use this first, then pass the resolutions to merge_branch with strategy "manual". The branch must be in the token's allowed set.

Merge a branch this token created back into the token's base branch (the implicit, only-allowed target). Requires a create-own token with the developer role or higher. The merge does NOT delete the source branch. Call delete_branch afterwards to clean it up. Strategies: overwrite (default; a non-destructive union where the source wins conflicts and keys only on the base are kept), keep-newer (whichever side changed more recently wins), manual (you supply per-conflict resolutions obtained from get_merge_conflicts), branch-changes (only labels created or changed on the branch since it was created are applied, the source winning for those; everything else on the base stays as it is and deletions are not carried over; the result's overlappingKeys lists merged keys the base also changed meanwhile – show them to the user to recheck), and replace (DESTRUCTIVE: the base becomes an exact copy of the source; use only when the user explicitly asks to replace). Merging into main needs an ADMIN-role token; any other token fails with admin_token_required_for_main, and then the user merges in the web app instead. The QA merge gate can refuse the merge with qa_gate_blocked: call run_qa and check_merge_gate first and fix the errors (tokens cannot override the gate). Only merge after the user has reviewed and approved the changes.

Delete a branch this token created (createdByThisToken=true in list_branches). Requires the developer role or higher. The base branch and any branch the token did not create can never be deleted; deleting them fails with not_token_branch. Use this to clean up after a successful merge_branch.

Find labels that still need translation on a branch. For each key with at least one empty target-language value, returns { key, source: { lang, value }, missing: [languages] }, where the source language is the project's source language (see get_project_info). Optionally restrict to specific `languages` and cap the rows with `limit` (default 200); the response reports the true total and notes truncation. Use this to translate the missing values YOURSELF (works on any plan) and then write them back with upsert_labels. For server-side AI on paid plans, use auto_translate instead. Reads the token's base branch unless `branch` names another allowed branch.

Trigger Translatize's PLATFORM AI to fill in missing translations on a branch as a background job. It is available only on plans that include it (professional/agency), and it is metered against the AI quota. It translates from the project's source language. Optionally scope to specific target_languages (defaults to every project language except the source), specific label_keys, and set overwrite_translated to re-translate values that already exist. Returns the started job (poll it with translation_job_status) or a no-op when nothing needs translating. If it fails with feature_not_available, the plan has no platform AI; fall back to get_missing_translations and translate the values yourself. Other failures: ai_quota_exceeded (the quota is exhausted; report used/limit to the user) and translation_already_running (a job is already in flight; check translation_job_status). Targets the token's base branch unless `branch` names another allowed branch.

Report the project's current or most-recent AI translation job: its status (queued/running/completed/failed), target languages, progress counts, and (while queued) its position in the global queue. Also returns the AI quota (used / limit / remaining; a limit of -1 means unlimited). Use this to watch a job started by auto_translate, or to check the remaining quota before starting one. Takes no arguments.

无需输入参数。

Set the workflow status of many labels at once (draft, review, approved or rejected) WITHOUT changing their translation values. Pass the keys and the target status. Use this to mark keys as reviewed or approved as part of a review workflow. Returns the updated/created counts and any per-key failures. Writes to the token's base branch unless `branch` names another allowed branch.

Produce a review packet for a branch: the added and changed keys (with their new per-language values, and the previous values for changed keys), a summary of counts, the deleted keys, and a platformUrl a human can open to review on the Translatize web app. Capped at 100 keys with a truncation note. After you finish translation work on a branch, use this, then ASK THE USER whether they want to review the changes here in the conversation or on the Translatize platform (share the platformUrl). Wait for their decision, and for their approval to merge, before calling merge_branch. Defaults to the token's base branch when `branch` is omitted.

Set translator context on existing keys in one batch, without touching their values: a description of which UI element the key is and where it appears, a charLimit when the UI clearly limits the length, the source location as path:line, doNotTranslate for text that stays the same in every language (product names, brands, codes), and tags. AI translation and the QA length check use this context, so give every key you create one. Only the fields you pass are sent. A key that does not exist fails with label_not_found (create it with upsert_labels first). Needs the developer role or higher. Writes to the token's base branch unless `branch` names another allowed branch.

Get the project's glossary (project terms plus its workspace's): each term with its required translation per language, whether it is case-sensitive, and whether it is prohibited. A translation equal to the term means "do not translate"; a prohibited term must never appear in a translation. Read it before writing or translating copy so terminology stays consistent – the QA glossary check enforces it. Takes no arguments.

无需输入参数。

Look up earlier approved or human-edited translations of similar source texts (fuzzy, placeholder-aware). For each text, returns up to 3 matches with the stored translation, a match score (100 = exact) and its quality. Use it when translating yourself, to reuse wording the project already uses. source_lang defaults to the project's source language. Takes no branch – the memory is shared across branches.

Run the rule-based QA checks on a branch now and return the result: counts per severity (error / warning / info) and the issues, each with key, language, check, code and params. Checks: placeholders, ICU syntax and plural categories, HTML tags, length vs charLimit, whitespace, untranslated, glossary, numbers and punctuation. It changes no translation. Use it after translating: fix every error (rewrite the value or fix its placeholders), run it again, then call check_merge_gate before merging. Pass `keys` to re-check only some keys. Checks the token's base branch unless `branch` names another allowed branch.

List the stored QA issues of a branch, one page at a time, with the counts per severity. Filter by severity, key, language or source (rule = the built-in checks, ai = AI review findings). Pass nextCursor back as `cursor` for the next page. Reads the token's base branch unless `branch` names another allowed branch.

Preview the QA merge gate for merging a branch into the token's base branch. The gate re-checks only the key × language pairs the merge would change. Returns its mode (off / warn / block), whether it applies to this target, whether it would BLOCK the merge, and the error and warning counts with the issues. When blocked, merge_branch fails with qa_gate_blocked until the errors are fixed. Pass the strategy you will give merge_branch: the pairs differ per strategy (branch-changes checks only what changed on the branch, overwrite every key that differs from the base). Call it after run_qa and before asking the user to approve a merge.

Start a platform AI review of a branch's translations as a background job: each key × language pair gets a score and findings (accuracy, fluency, terminology, style, length, placeholders). Findings are warnings at most and never block a merge. Professional plan or higher, billed on its own AI review quota by the characters of target text reviewed – so scope it with `keys` / `langs` when you can. Needs the developer role. Poll ai_review_status; the findings then appear in get_qa_issues with source "ai". Errors: feature_not_available (plan), ai_review_quota_exceeded, ai_review_in_progress. Reviews the token's base branch unless `branch` names another allowed branch.

Report the project's latest AI review job: status (queued / running / completed / failed), its branch, progress counts (total, reviewed, failed, issues found) and the characters billed. Returns job: null when no review has run. Takes no arguments.

无需输入参数。

List the project's over-the-air delivery distributions: id, name, the branch each one publishes, its format, whether it publishes all values or approved labels only, its status, the latest published version and the public manifest URL apps load strings from. Only distributions on branches this token may use are listed. Takes no arguments.

无需输入参数。

Publish a distribution's branch to the CDN as a new version. Live apps using the Translatize OTA SDK pick it up on their next refresh, so this changes what end users see, and everything published is PUBLIC. Only call it when the user has explicitly asked to publish, and pass confirm: true – without it nothing is published. Needs the developer role, and the distribution's branch must be in the token's allowed set (otherwise branch_not_allowed). Get the id from list_distributions.