---
name: phrase
description: Use when building localization workflows, managing translation
  projects, syncing translation files with repositories, handling multi-language
  content, integrating machine translation, or automating translation management
  at scale. Phrase provides APIs for Strings (software localization), TMS
  (translation management), and Language AI (machine translation).
metadata:
  mintlify-proj: phrase
  version: "1.0"
---

# Phrase API Skill

## Product Summary

Phrase is a localization management platform with three main API products: **Strings API** (software translation management), **TMS API** (enterprise translation workflows), and **Language AI** (machine translation). Agents use Phrase to manage translation projects, sync source strings with code repositories, handle multi-language content, and automate translation workflows. The Strings API base URL is `https://api.phrase.com/v2/` (EU) or `https://api.us.app.phrase.com/v2/` (US). Authentication uses JWT Bearer tokens generated in Phrase Platform settings. Key resources: projects, locales, keys, translations, jobs, releases, and distributions. See the [Phrase Developer Hub](https://developers.phrase.com) for full documentation.

## When to Use

Reach for this skill when:

- **Syncing translations**: Pushing source strings from code to Phrase, pulling translated files back
- **Managing projects**: Creating projects, adding target languages, configuring workflows
- **Automating workflows**: Uploading files, triggering machine translation, polling for completion
- **Handling releases**: Creating distributions, publishing releases, managing over-the-air (OTA) updates
- **Integrating with CI/CD**: Automating translation imports/exports in build pipelines
- **Managing translation memory**: Creating glossaries, term bases, and translation memories for consistency
- **Webhook automation**: Triggering actions when translation jobs complete or status changes
- **Multi-language content**: Creating locales, managing translations per language, downloading locale files

Do not use this skill for: UI-only operations, account billing, user management (use SCIM API instead), or authentication setup beyond token generation.

## Quick Reference

### API Endpoints

| Endpoint | Purpose |
|----------|---------|
| `POST /projects` | Create a project |
| `POST /projects/{id}/locales` | Add a language to a project |
| `POST /projects/{id}/uploads` | Upload source file |
| `GET /projects/{id}/locales/{locale_id}/download` | Download translated file |
| `POST /projects/{id}/keys` | Create a translation key |
| `POST /projects/{id}/translations` | Create a translation |
| `POST /accounts/{account_id}/distributions` | Create a distribution for OTA |
| `POST /accounts/{account_id}/distributions/{id}/releases` | Create a release |
| `POST /projects/{id}/webhooks` | Set up webhook for events |

### Authentication

Generate a JWT token in Phrase Platform (Settings > Access Tokens), then pass it as a Bearer token:

```bash
curl -H "Authorization: Bearer <JWT_TOKEN>" https://api.phrase.com/v2/projects
```

Or use email + password for basic auth (not recommended for production):

```bash
curl -u email:password https://api.phrase.com/v2/projects
```

### Common Parameters

| Parameter | Use |
|-----------|-----|
| `page`, `per_page` | Pagination (default 25 items, max 100) |
| `branch` | Specify a branch for the operation |
| `autotranslate` | Enable machine translation on upload |
| `file_format` | Format for upload/download (simple_json, xliff, etc.) |
| `locale_id` | Target language identifier |

### Rate Limits

- **1000 requests per 5 minutes** (per user)
- **4 concurrent requests** (parallel limit)
- Response headers: `X-Rate-Limit-Limit`, `X-Rate-Limit-Remaining`, `X-Rate-Limit-Reset`
- 429 response = rate limit exceeded; check `X-Rate-Limit-Reason` header

### File Formats Supported

JSON, XLIFF, XML, Markdown, YAML, Properties, PO, CSV, and others. Specify with `file_format` parameter.

## Decision Guidance

| Scenario | Use Strings API | Use TMS API |
|----------|-----------------|-----------|
| Software localization, CI/CD integration | ✓ | — |
| Enterprise translation workflows, jobs, providers | — | ✓ |
| Simple key-value translations | ✓ | — |
| Complex multi-step workflows, analysis, pricing | — | ✓ |
| Over-the-air (OTA) updates, releases | ✓ | — |
| Translation memory, term bases, glossaries | ✓ | ✓ |

| Task | Approach |
|------|----------|
| **Upload and auto-translate** | POST upload with `autotranslate=true`, then poll pre_translations status |
| **Download translations** | GET locale download endpoint; use `file_format` to specify output format |
| **Sync with Git** | Use repo sync endpoints or webhooks to trigger imports on push |
| **Publish OTA updates** | Create distribution → create release → publish release |
| **Bulk operations** | Use batch endpoints (e.g., add tags to multiple keys) |

## Workflow

### Typical Strings API Workflow

1. **Create project**: POST `/projects` with name, format, and autotranslate settings
2. **Add locales**: POST `/projects/{id}/locales` for source (default=true) and each target language
3. **Upload source file**: POST `/projects/{id}/uploads` with file, format, source locale, and `autotranslate=true`
4. **Poll pre-translation**: GET `/projects/{id}/pre_translations` until status is "success"
5. **Download translations**: GET `/projects/{id}/locales/{locale_id}/download?file_format=simple_json`
6. **Set up webhooks** (optional): POST `/projects/{id}/webhooks` to trigger actions on events

### Typical TMS API Workflow

1. **Create project**: POST `/api2/v2/projects` with name and settings
2. **Add target languages**: POST `/api2/v2/projects/{id}/targetLanguages`
3. **Upload file**: POST `/api2/v2/projects/{id}/jobs` to create jobs
4. **Assign providers**: POST to assign translators/vendors to jobs
5. **Monitor status**: GET job status, poll for completion
6. **Download target file**: GET `/api2/v2/projects/{id}/jobs/{job_id}/downloadTargetFile`

### OTA Release Workflow

1. **Create distribution**: POST `/accounts/{account_id}/distributions`
2. **Create release**: POST `/accounts/{account_id}/distributions/{id}/releases` with locales and tags
3. **Publish release**: POST `/accounts/{account_id}/distributions/{id}/releases/{id}/publish`
4. **Set up release trigger** (optional): POST to schedule automatic releases

## Common Gotchas

- **Missing User-Agent header**: All requests must include a User-Agent header (e.g., `User-Agent: MyApp (contact@example.com)`), or you'll get 400 Bad Request
- **Forgetting to set default locale**: When creating locales, mark the source language with `"default": true`, or downloads may fail
- **Polling too early**: Pre-translation jobs are async; always poll status before downloading, or files come back empty
- **Rate limit bursts**: Limit concurrent requests to 4; use exponential backoff on 429 responses
- **Locale ID vs code**: Use locale `id` (UUID) in API calls, not the language code (e.g., "en")
- **Branch parameter**: If using branches, always specify the branch in requests, or you'll operate on the main branch
- **Async operations**: File uploads, pre-translations, and exports are async; always poll or use webhooks to detect completion
- **Pagination defaults**: Default page size is 25; use `per_page=100` to reduce API calls, but don't exceed 100
- **Conditional requests**: Use ETag/Last-Modified headers on downloads to avoid re-downloading unchanged files (304 responses don't count against rate limits)
- **Webhook secrets**: Always verify webhook payloads using the secret token to prevent spoofing

## Verification Checklist

Before submitting work with Phrase APIs:

- [ ] Authentication token is valid and has required scopes (read/write)
- [ ] User-Agent header is included in all requests
- [ ] Project ID and locale IDs are correct (use UUIDs, not language codes)
- [ ] File format matches the project's main_format or is explicitly specified
- [ ] For uploads: source locale is set correctly and file is valid
- [ ] For downloads: pre-translation status is "success" before downloading
- [ ] Pagination is handled correctly (use Link headers or page/per_page params)
- [ ] Rate limits are respected (4 concurrent max, 1000 per 5 min)
- [ ] Async operations are polled or monitored via webhooks
- [ ] Error responses are checked for validation errors (422) or auth failures (401/403)
- [ ] Webhook payloads are verified using secret token
- [ ] Branch parameter is specified if using branches

## Resources

- **Comprehensive navigation**: [Phrase llms.txt](https://developers.phrase.com/llms.txt) — page-by-page reference for all APIs
- **Strings API overview**: [Phrase Strings Introduction](https://developers.phrase.com/en/api/strings/introduction)
- **TMS API overview**: [Phrase TMS Introduction](https://developers.phrase.com/en/api/tms/latest/introduction)
- **Authentication guide**: [Phrase Platform Authentication](https://developers.phrase.com/en/api/platform/authentication)

---

> For additional documentation and navigation, see: https://developers.phrase.com/llms.txt