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

# Phrase API

Jentic publishes the only available OpenAPI specification for Phrase API, keeping it validated and agent-ready. Phrase provides a translation management system API for multi-language content workflows including project management, translation key organization, locale configuration, job tracking, file uploads, and translation downloads. The API supports 15 endpoints covering the complete localization lifecycle from source string extraction through translator assignment to final export in multiple file formats.

## For AI agents

Manage translation projects, upload source files, configure locales, assign translation jobs, and download localized content in multiple formats through Phrase's localization platform.

## Scope

Does not handle machine translation, terminology databases, or translation memory matching - use for translation project management and file exchange only.

## Capabilities

- Create and configure translation projects with multiple target locales and file format support
- Upload source files for string extraction and translation key generation
- Manage translation keys with tags, descriptions, and pluralization rules
- Download translated content in format-specific exports (JSON, XLIFF, Android XML, iOS strings)
- Assign translation jobs to translators with deadlines and status tracking
- Configure locale-specific settings including fallback languages and completion thresholds

## Use cases

### Continuous Localization Pipeline

Automate the localization cycle by uploading source files to Phrase whenever code deploys, tracking translation progress per locale, and downloading completed translations for integration into the build pipeline. Phrase handles string extraction, key deduplication, and translator notification automatically. Supports CI/CD integration where new strings are detected on every push and translated content is pulled before each release.

Example prompt: Upload a JSON source file to project PROJECT123 via POST `/projects/{project_id}/uploads`, then check locale completion status with GET `/projects/{project_id}/locales`

### Multi-Platform Translation Export

Export translated content in platform-specific formats for simultaneous deployment across web, iOS, and Android. Phrase stores translations in a format-agnostic key-value structure and exports to JSON (web), Localizable.strings (iOS), strings.xml (Android), XLIFF, and other formats. A single source of truth serves all platforms without manual format conversion.

Example prompt: Download translations for locale 'de' from project PROJECT123 in Android XML format via GET `/projects/{project_id}/downloads` with format parameter set to xml

### Translation Job Management

Assign translation tasks to specific translators or teams with deadlines and scope definitions. Jobs in Phrase track which keys need translation, who is responsible, and the current progress. Project managers can monitor completion rates per job and locale to identify bottlenecks before release deadlines.

Example prompt: Create a translation job for all untranslated keys in locale 'fr' of project PROJECT123 using POST `/projects/{project_id}/jobs` with a deadline of next Friday

### AI Agent Localization Workflow via Jentic

AI agents managing product releases can automate the localization workflow through Jentic - uploading new source strings, checking translation completeness per locale, and downloading finished translations for deployment. Jentic handles bearer token authentication and Phrase API discovery so agents can focus on the workflow logic rather than API integration details.

Example prompt: Search Jentic for 'upload source file for translation', load the Phrase upload operation, execute with a JSON file, then check completion status for all configured locales

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/projects` | List all translation projects |
| POST | `/projects` | Create a new translation project |
| GET | `/projects/{project_id}/keys` | List translation keys in a project |
| GET | `/projects/{project_id}/translations` | List translations for a project |
| GET | `/projects/{project_id}/locales` | List configured locales for a project |
| POST | `/projects/{project_id}/uploads` | Upload a source file for translation |
| GET | `/projects/{project_id}/downloads` | Download translated files in specified format |
| GET | `/projects/{project_id}/jobs` | List translation jobs in a project |

## Key resources

- **Projects** — Create and manage translation projects with locale and format configuration
- **Keys** — Manage translation keys with metadata, tags, and pluralization rules
- **Translations** — View and manage translated content per key and locale
- **Locales** — Configure target languages and locale-specific settings
- **Uploads** — Upload source files for string extraction and key creation
- **Downloads** — Export translated content in platform-specific file formats
- **Jobs** — Assign and track translation tasks with deadlines and progress

## Why Jentic

- **Setup:** Wiring the Phrase API by hand means setting up its bearer or apiKey token against api.phrase.com/v2 and formatting the project, key, and file upload requests yourself. Through Jentic you install once, import the Phrase API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Phrase puts the project id in the URL path (`/projects/{project_id}/keys`, /translations, /uploads), so a rule can pin your agent to one project: it can read that project's keys, translations, and locales. You choose the operations it may call, so writes like creating a project or uploading a file are not included unless you add them.
- **Credential handling:** Your Phrase token 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 'list translation keys in a project', and Jentic returns the matching Phrase operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Smartling API** — Enterprise translation management with neural machine translation and quality estimation
- **OpenAI API** — Language model for machine translation drafts before human review in Phrase
- **SendGrid API** — Email delivery for sending localized content to international audiences

## FAQ

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

Phrase does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Phrase 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 Phrase API use?

Phrase supports two authentication methods: Bearer token authentication and API token authentication via the Authorization header with format 'token YOUR_TOKEN'. API tokens are generated in the Phrase dashboard. Through Jentic, tokens are stored in your Jentic One instance and injected into request headers automatically.

### Can I upload source files in multiple formats to Phrase?

Yes. The POST `/projects/{project_id}/uploads` endpoint accepts various source file formats including JSON, YAML, XLIFF, Android XML, iOS Localizable.strings, and many more. Phrase automatically extracts translation keys from the uploaded file structure.

### How do I download translations in a specific file format?

Use GET `/projects/{project_id}/downloads` with the locale and format parameters. Supported export formats include JSON, XLIFF, Android XML, iOS strings, Ruby YAML, PHP, and others. The response contains the translated file ready for integration into your build pipeline.

### How do I automate localization uploads through Jentic?

Search Jentic for 'upload source file for translation' to find the POST `/projects/{project_id}/uploads` operation. Load the schema to see accepted file formats and parameters, then execute with your source file. Jentic handles token authentication and multipart upload formatting.

### Can I track translation completion per locale?

Yes. Use GET `/projects/{project_id}/locales` to retrieve all configured locales with their completion statistics. Each locale entry includes the total key count, translated count, and completion percentage, letting you identify which languages need attention before release.

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

Yes. Because you run Jentic One yourself and set the rules, you decide which Phrase operations and credentials your agent may use. Since Phrase carries the project id in the URL path (`/projects/{project_id}/keys`, /translations, /locales), a rule can pin the agent to a single project and grant only read access to that project's keys, translations, and locales. Write operations like creating a project via POST /projects or uploading a source file via POST `/projects/{project_id}/uploads` stay off limits unless you explicitly add them.