canonical: https://jentic.com/apis/multilocale.com/multilocale

# MultiLocale API

The MultiLocale API stores and serves the translation strings of an organization's apps and websites as phrases, each a key, a value, and a language belonging to one or more projects. Clients list phrases filtered by project, key, and language with cursor pagination, upsert one phrase or a batch, replace a phrase by id, and delete every language of a key in a project at once. Projects are created, renamed, and looked up by id or by name, each with its list of languages. Writes accept an Idempotency-Key for safe retries, and an unauthenticated sandbox serves demonstration phrases and an asynchronous translation job to try the API first.

## For AI agents

Read and write localization phrases and projects in MultiLocale: list strings by project, key, and language, upsert batches, and manage each project's languages.

## Scope

Does not machine-translate phrases outside the sandbox demo, manage translator vendors, or parse resource files. Use for storing and reading localization phrases and projects only.

## Capabilities

- List phrases filtered by project, key, and language with cursor pagination over large string sets
- Upsert one phrase or a batch of phrases with key, value, language, and projects in a single request
- Delete every language of one translation key in a project at once
- Create a project with its languages, rename it, or look it up by id or by name
- Retry writes safely with an Idempotency-Key honoured for 24 hours
- Try demonstration phrases and an asynchronous translation job in the sandbox without a key

## Use cases

### AI coding agent syncing new UI strings

An AI coding agent that adds a feature also adds new interface strings, and they need to reach the translation store. Through Jentic the agent searches for 'add translation phrases to a project', loads the MultiLocale batch upsert operation with its input schema, and sends each new key with its English value and project name, with the key secret injected at call time. Translators then see the new keys in the project.

Example prompt: Call POST `/api/v1/phrases/batch` with phrases for keys checkout_title and checkout_cta in language en and projects ["website"], sending an Idempotency-Key

### Pulling translations into a build

A build step fetches every phrase for one project and language to bundle into the app. The phrases list accepts project and language filters, and with pagination set to cursor it returns items and a nextCursor ordered by id, so the step can walk large string sets without skipping rows.

Example prompt: Call GET `/api/v1/phrases` with project=website, language=de, and pagination=cursor, following nextCursor until it is empty

### Setting up a project for a new market

Launching in a new region means adding a language to a project. A project carries a name and a languages array, so a script can read the project by name, append the new language code, and update it by id, then start filling phrases for that language.

Example prompt: Call GET `/api/v1/projects/{projectName}` for website, then PUT `/api/v1/projects/{projectId}` with languages extended to include pt

### Removing retired strings

After a feature is removed, its strings should not linger in every language. Deleting a phrase by key and project removes all of its translations together and emits a phrase.deleted event per row, which keeps the store clean without one call per language.

Example prompt: Call DELETE `/api/v1/phrases` with key=legacy_banner and project=website

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/phrases` | List phrases |
| POST | `/api/v1/phrases` | Create or update phrases |
| POST | `/api/v1/phrases/batch` | Upsert a batch of phrases |
| DELETE | `/api/v1/phrases` | Delete a key in all languages |
| GET | `/api/v1/projects` | List projects |
| POST | `/api/v1/projects` | Create a project |
| PUT | `/api/v1/projects/{projectId}` | Update a project |
| GET | `/api/v1/sandbox/phrases` | Read sandbox phrases without auth |

## Key resources

- **Phrases** — Key, value, and language triples in one or more projects; list, upsert, batch upsert, replace, and delete by key
- **Projects** — Named projects with their languages; list, create, update, and look up by id or name
- **Sandbox** — Unauthenticated demonstration phrases and an asynchronous translation job

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 64 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 61 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 53 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 89 / 100
- **View full report:** https://jentic.com/apis/multilocale.com/multilocale/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring MultiLocale by hand means choosing between a Basic-encoded key secret, a dashboard Token, or an OAuth PKCE flow, then handling cursor pagination and Idempotency-Key headers on writes. Through Jentic you install once, import MultiLocale from the API Directory, store the key secret once, and your agent calls it.
- **Permission scoping:** MultiLocale carries the project as a query parameter or body field on phrase routes, so rules bound which operations your agent may call, not which project's phrases. You choose the operations it may call, so destructive ones like deleting a key across all languages are not included unless you add them.
- **Credential handling:** Your MultiLocale key secret is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'add translation phrases to a project' or 'list phrases for a language', and Jentic returns the matching MultiLocale operation with its input schema, so the agent sends the right filters and phrase fields.

## Related APIs

- **Phrase** — Localization platform for software strings, translation workflows, and translators
- **Crowdin** — Localization management with file sync, translation memory, and crowd translation
- **LibreTranslate** — Open-source machine translation API

## FAQ

### What authentication does the MultiLocale API use?

The MultiLocale OpenAPI spec declares three schemes for the phrase and project routes. An API key secret is sent with HTTP Basic auth as Authorization: Basic base64 of the secret, an operator session token from the dashboard is sent as Authorization: Token, and OAuth 2.0 authorization code with PKCE grants delegated access with scopes such as phrases:read and projects:write. The three sandbox routes need no credential. Through Jentic your key secret is held by your own instance and injected at call time.

### Can I fetch only one language of a project with the MultiLocale API?

Yes. GET `/api/v1/phrases` takes project, key, and language query parameters, plus a fields selector. Setting pagination to cursor switches the response to items and nextCursor ordered by id for stable traversal of large projects.

### What are the rate limits for the MultiLocale API?

The OpenAPI spec does not publish numeric limits. It documents a rate limit exceeded error, and the sandbox routes return the standard RateLimit response headers under an anonymous pacing limit. Check https://www.multilocale.com/docs/api/versioning/ and the related docs for current limits.

### How do I add new strings to MultiLocale through Jentic?

Search Jentic for 'add translation phrases to a project', load the POST `/api/v1/phrases/batch` operation, and execute it with an array of phrases carrying key, value, language, and projects. Send an Idempotency-Key so a retry does not double-write. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the MultiLocale API?

Yes. Write a rule that allows only GET `/api/v1/phrases` and POST `/api/v1/phrases/batch`, and the agent can read and add strings but cannot delete keys or create and rename projects. Every call it makes is logged, so you can review which keys it wrote.

### Can I try MultiLocale without an account?

Yes. GET `/api/v1/sandbox/phrases` returns fixed demonstration phrases in the same key, value, and language shape, and POST `/api/v1/sandbox/translationjobs` starts a demonstration job you poll at GET `/api/v1/sandbox/translationjobs/{jobId}` until its status is succeeded.