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

# Localizely API

Jentic publishes the only available OpenAPI specification for Localizely API, keeping it validated and agent-ready. Localizely is a translation management platform built around uploading and downloading localization files, with branch and project organisation. The API is intentionally narrow: it covers file upload, file download, branch creation, and translation status checks, designed to be wired into curl scripts and CI pipelines that move translation files in and out of the platform. Authentication is by per-account API token in the X-API-Token header.

## For AI agents

Upload and download localization files, create branches, and check translation status against a Localizely project from CI or agent workflows.

## Scope

Does not handle machine translation, key-level CRUD, or in-app translation rendering - use for project file upload, download, and translation status only.

## Capabilities

- Upload localization files into a Localizely project for translation
- Download translated files in the source format for build-time consumption
- Create a branch in a project to isolate work-in-progress translations
- Check the translation status of a project to gate releases on completion
- Authenticate with an admin-role API token via the X-API-Token header
- Wire the file upload and download flow into curl scripts or CI jobs

## Use cases

### Translation File CI Pipeline

Engineering teams that ship localised apps want translations pulled into the build at CI time. Localizely's download endpoint returns the latest translation file in the source format, and the status endpoint exposes per-language completion. A CI step calls download for each release and optionally fails the build if a key language is below threshold.

Example prompt: Call GET `/v1/projects/{project_id}/files/download` for each language in the build, check GET `/v1/projects/{project_id}/status`, and fail if completion is below the configured threshold.

### Source String Upload from Source Control

When developers add new strings to the codebase, those strings need to land in Localizely so translators can pick them up. POST `/v1/projects/{project_id}/files/upload` accepts the source localization file. Combined with the branch endpoint, teams can isolate new strings on a feature branch until they are ready for production translators.

Example prompt: Call POST `/v1/projects/{project_id}/branches/{branch}` to create a feature branch then POST `/v1/projects/{project_id}/files/upload` with the new source strings.

### AI Agent Release Gate

An AI agent running release checks can call Localizely through Jentic to confirm translations are complete before approving a deployment. The agent searches Jentic for the status operation, executes it with the project ID, and reports back per-language completion. The API token stays in your Jentic One instance.

Example prompt: Use Jentic to call GET `/v1/projects/{project_id}/status` and report any language below 95% complete to the deployment workflow.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/projects/{project_id}/files/upload` | Upload a localization file |
| GET | `/v1/projects/{project_id}/files/download` | Download translated files |
| POST | `/v1/projects/{project_id}/branches/{branch}` | Create a project branch |
| GET | `/v1/projects/{project_id}/status` | Get translation completion status |

## Key resources

- **Files** — Upload source files and download translated files
- **Branches** — Create branches inside a project to isolate work-in-progress
- **Status** — Check translation completion status per language

## Why Jentic

- **Setup:** Wiring the Localizely API by hand means setting up its API-token header auth, attaching it to every call against api.localizely.com, and handling retries yourself across file upload and download. Through Jentic you install once, import the Localizely API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Localizely puts the project id in the URL path (`/v1/projects/{project_id}/...`), so a rule can pin your agent to one project: it can download files and check translation status there and nothing else. You choose the operations it may call, so a file upload with POST `/v1/projects/{project_id}/files/upload` is not included unless you add it.
- **Credential handling:** Your Localizely admin token is stored once, encrypted, by your own Jentic One instance and injected as the API-token header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'download translated files' or 'check translation status', and Jentic returns the matching Localizely operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Phrase API** — Alternative translation management platform with a deeper API surface beyond file upload and download
- **POEditor API** — Alternative file-based translation management platform with similar upload and export operations
- **Smartling API** — Alternative enterprise translation management platform with managed translation services

## FAQ

### Why is there no official OpenAPI spec for Localizely API?

Localizely does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Localizely API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Localizely API use?

Localizely uses an API token sent in the X-API-Token header. The token must belong to a user with the Admin role in the project. Through Jentic, the token is stored encrypted in the vault and injected at execution time, so the raw value never enters agent context.

### Can I work on translations in a feature branch instead of the main project?

Yes. POST `/v1/projects/{project_id}/branches/{branch}` creates a branch inside a project. Subsequent file upload and download calls scoped to that branch keep work-in-progress translations isolated until you merge them back.

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

Rate limits are not declared in the spec. Localizely applies plan-level limits at the account level; check your plan or contact support for the exact thresholds.

### How do I check translation completion before shipping a release through Jentic?

Search Jentic for 'check translation completion status'. Jentic returns the GET `/v1/projects/{project_id}/status` operation. Load the schema, supply the project ID, and execute. The response is per-language completion that you can gate the deployment on.

### Which file formats can I upload and download?

Localizely supports a range of localization file formats including JSON, YAML, .properties, .strings, and Android XML. The upload and download endpoints accept the file format you configured at the project level on the Localizely dashboard.

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

Yes. Because you run Jentic One yourself, your own rules decide which Localizely operations and credentials the agent may use. Since the project id sits in the URL path (`/v1/projects/{project_id}/...`), a rule can pin the agent to a single project and grant only read operations such as GET `/v1/projects/{project_id}/files/download` and GET `/v1/projects/{project_id}/status.` Write operations like POST `/v1/projects/{project_id}/files/upload` stay off unless you explicitly add them.