MCP tools

Each tool answers one text block that holds JSON. When the API refuses, the tool answers isError: true and the text <status> — <message>.

repository is always the id of a repository, from i18n_repositories. language is a tag such as fr or pt-BR. file is a file name such as common, never a path.

Call i18n_me first. It names the repositories and the languages that the token can write. Then call i18n_keys, and send its commit back to i18n_propose as readAt. Only i18n_propose writes: each other tool only reads, and its MCP annotation readOnlyHint is true.

i18n_repositories

read-only

The repositories to translate. Which repositories the editor translates, their source language and their targets.

Input: none.

The repositories that the account can read. An admin reads all of them. Any other account reads the repositories where it is a member.

Answer: a list of repositories.

Field	What it is
id	The identifier that the other tools take.
owner, name	The repository on GitHub.
branch	The base branch.
localesPath	The folder of the locale files.
manifestPath	The manifest, from the root of the repository.
publishMode	commit or pull_request.
source	The source language.
targets	The other languages.

i18n_me

read-only

What this token may do. The repositories where this account is a member, and in each one its role, the languages it may propose in, and whether it writes the source. A translator writes proposals and does not publish. A reviewer or an owner also publishes.

Input: none.

A token gives the rights of its account, and no more (Access tokens).

Answer:

{
  "admin": false,
  "memberships": [{ "repositoryId": "…", "role": "translator", "languages": ["en", "de"], "writesSource": false }]
}

role is translator, reviewer or owner. A translator proposes. A reviewer or an owner also publishes, in the editor.

i18n_keys

read-only

The keys of a language. Every key of the source beside what one language says about it, filtered by state and by file. The answer carries the commit the values were read at; a proposal takes it back.

Input:

Field	Type	Required	What it is
repository	string	yes	The repository to read, from i18n_repositories. At least 1 character.
language	string	yes	The language to read, which the repository must translate into. Matches ^[A-Za-z0-9_-]+$.
state	"missing", "review", "translated", "all"	no	Which keys to answer. missing is what there is work on. review is a translation whose source changed: was holds the old source. Default: "missing".
file	string	no	Only the keys of this file, for example common. Matches ^[A-Za-z0-9_-]+$.
offset	integer	no	Where to start, for a catalogue past one answer. Default: 0.

200 keys for each answer.

Answer:

Field	What it is
commit	The revision of the base branch that the values come from. Send it back as readAt.
source	The source language.
language	The language read.
total	How many keys match the filter.
offset, returned	Where the page starts, and how many keys it holds.
more	true if another page follows. Call again with offset + returned.
filesWithNoVersion	The files that this language does not have. They take no proposal.
entries	The keys. See below.

Each entry:

Field	What it is
file	The file of the key.
key	The dotted path of the key.
source	The source text now.
value	The text of the language on the base branch, or null.
state	missing, translated or review.
was	For review only: the source text that the translation answers.
empty	true if the key is left empty on purpose in this language. value is "".

The server holds one reading of a catalogue for 5 minutes. Every page of a listing answers the commit of the first page.

i18n_key

read-only

One key, with its context. One key: what the source says, what the target says, and its state. The file and the dotted path are the context — analysis.requests_export_hint says what the string is for, and a translation without it is a wrong translation.

Input:

Field	Type	Required	What it is
repository	string	yes	The repository to read, from i18n_repositories. At least 1 character.
language	string	yes	The language to read, which the repository must translate into. Matches ^[A-Za-z0-9_-]+$.
file	string	yes	The file of the key, for example common. Matches ^[A-Za-z0-9_-]+$.
key	string	yes	The dotted path of the key, as i18next reads it. At least 1 character.

Answer: { "found": true, "commit": "…", "source": "fr", "entry": { … } }, with the same entry as i18n_keys.

If the key does not exist, or if the file has no version in the language, the answer is { "found": false, "reason": "…" }.

i18n_propose

writes It writes a commit on the repository, and deletes nothing.

Propose a batch of translations. Writes a whole batch as one commit on the branch of its language. Three hundred keys are one commit, not three hundred. Nothing is published: a reviewer does that.

Input:

Field	Type	Required	What it is
repository	string	yes	The repository to read, from i18n_repositories. At least 1 character.
language	string	yes	The language to read, which the repository must translate into. Matches ^[A-Za-z0-9_-]+$.
readAt	string	yes	The commit the keys were read at, taken from i18n_keys or i18n_key. Every page of one listing answers the same one. It is what lets a publication refuse a key whose source moved since — never invent one, and never mix the values of two listings in one call. Matches ^[0-9a-f]{40}$.
values	array of object	yes	The whole batch. One call is one commit, so three hundred keys are three hundred keys, not three hundred commits. From 1 to 2000 items.

Each item of values:

Field	Type	Required	What it is
file	string	yes	The file of the key, for example common. Matches ^[A-Za-z0-9_-]+$.
key	string	yes	The dotted path of the key. At least 1 character.
value	string	yes	The text in the language of the batch.
empty	boolean	no	true leaves the key empty on purpose in this language, with value "". Use it only when the source asks for no text in this language, never to skip a key. A key sent without it loses its mark.

The branch is i18n/<language>.

Answer:

{ "commit": "…", "branch": "i18n/en", "readAt": "…", "keys": 42, "files": ["common", "checkout"] }

i18n_proposals

read-only

What is waiting on a language. The batches the branch of a language holds and the base does not, with who wrote each one.

Input:

Field	Type	Required	What it is
repository	string	yes	The repository to read, from i18n_repositories. At least 1 character.
language	string	yes	The language to read, which the repository must translate into. Matches ^[A-Za-z0-9_-]+$.

Answer: a list of batches.

Field	What it is
commit	The commit of the batch.
message	Its commit message.
author	The account that proposed it.
at	When.
readAt	The revision that the batch answers.