BYO Engine

​

What you’ll build

• Engine status — lets Phrase check your engine is healthy before routing jobs to it.
• Supported languages — tells Phrase which source/target language pairs your engine can translate.
• Synchronous translation — translates a batch of segments and returns the result in the same request.
• Asynchronous translation — accepts a batch of segments, returns immediately with a job ID, and lets Phrase poll for status and results.

​

Prerequisites

• An HTTPS endpoint you control that can implement the OpenAPI schema below.
• Either an OAuth 2.0 client credentials setup or an API token to authenticate incoming requests from Phrase.
• For a working starting point, see the reference adapter implementation, which demonstrates a basic integration and includes additional guidance.

​

Authentication

• OAuth 2.0 client credentials flow. Phrase requests a token from your token endpoint and sends it as Authorization: Bearer <token>. Scopes are granted per operation:

  Scope	Grants access to
  languages:read	POST /languages
  status:read	POST /status
  translate:write	POST /translate
  translateAsync:write	POST /translateAsync
  translateAsyncStatus:read	GET /translateAsyncStatus/{id}
  translateAsyncResult:read	GET /translateAsyncResult/{id}

• API token. Phrase sends a static token in the X-Api-Token header.

​

Dynamic metadata

{
  "formality": "informal",
  "model": "model123",
  "domain": "legal",
  "project_uid": "{project_uid}",
  "job_uid": "{job_uid}",
  "idm_organization_uid": "{idm_organization_uid}"
}

​

Engine status

{
  "status": "ok"
}

​

Supported languages

{
  "languagePairs": [
    { "sourceLanguage": "en", "targetLanguage": "es" },
    { "sourceLanguage": "en", "targetLanguage": "de" }
  ]
}

​

Synchronous translation

{
  "sourceLanguage": "en",
  "targetLanguage": "es",
  "segments": [
    { "idx": "1", "text": "Hello World!" }
  ],
  "glossary": [
    { "term": "hello", "translation": "hola" }
  ],
  "metadata": {
    "project_uid": "{project_uid}"
  }
}

{
  "sourceLanguage": "en",
  "targetLanguage": "es",
  "segments": [
    { "idx": "1", "text": "Hello World!", "translatedText": "¡Hola Mundo!" }
  ]
}

​

Asynchronous translation

​

1. Submit the job

{
  "id": "ffffffff-ffff-ffff-ffff-ffffffffffff"
}

​

2. Poll for status

{
  "status": "done"
}

​

3. Fetch the result

​

Glossaries and custom metadata

• Glossaries — pass a glossary array of { term, translation } pairs (0–500 entries, each field 1–50 characters) on either /translate or /translateAsync to enforce specific terminology during translation.
• Custom metadata — pass a metadata object at the request level on either endpoint. Combine it with dynamic metadata placeholders to pass job context to your engine without extra integration work. A metadata object can also be set per segment, but this field is currently a reserved placeholder for future use — don’t rely on your engine receiving it yet.

​

Rate limiting and errors

HTTP/1.1 429 Too Many Requests
Retry-After: 30

{
  "error": "Unauthorized, Invalid token"
}

​

Stability and performance recommendations

• DNS infrastructure & routing — ensure DNS resolution is stable and all entries are correctly configured. Misconfigurations or propagation delays can result in intermittent resolution failures, elevated latency, or request timeouts.
• Application & proxy server tuning (e.g. Nginx) — optimize proxy/gateway servers for high-concurrency traffic. Review keep-alive settings and worker process limits to avoid TCP connection resets or dropped requests under load.
• Load & concurrency testing — perform synthetic load tests from external endpoints before going to production. Validate your adapter against a sustained concurrency of 100–200 requests per second (RPS) to confirm that performance remains linear and stable.

​

Reference

• Demo implementation — a reference adapter demonstrating a basic integration.
• OpenAPI schema — implement your adapter in accordance with this schema.