Bring Your Own Engine

The Bring Your Own Engine (BYO Engine) feature integrates external machine translation (MT) engines into Phrase for use in translation workflows like any other MT provider. An engine connects either through a hosted API adapter or, with BYO Engine Lite (Beta), through a JSON template that describes the API of the engine.

BYO Engine is suited for:

Enterprises with domain-specific MT models.
LSPs with custom client engines or preferred AI stacks.
Organizations with internal policies that require using specific engines (e.g., Gemini, internal LLMs).

Custom-trained engines can be used, or translations can be routed to in-house LLMs or MT providers to maintain full control over quality, privacy, and cost while continuing to benefit from Phrase’s translation memories (TM), glossaries, quality performance score QPS and the CAT editor.

Where a BYO Engine Can Be Used

Once integrated, a BYO Engine is available for pre-translation. Configure it in a Phrase Language AI Profile and use that profile to pre-translate from Phrase TMS projects, Phrase Portal, Phrase Strings projects, Phrase Studio, and Phrase Language AI via API.

Connection Methods

BYO Engine offers three connection methods. The method is selected under Engine API when the engine is configured.

Method	What Phrase calls	What the organization provides
Phrase BYO API adapter	A hosted adapter that implements the BYO Engine API and calls the engine	A built, tested, and hosted adapter
Pre-built template (Lite)	The API of the engine directly, using a template maintained by Phrase	The base engine URL and credentials
Custom template (Lite)	The API of the engine directly, using a template written by the organization	The base engine URL, credentials, and a JSON template

Use the adapter when the engine requires custom processing, multiple upstream calls per request, or an API that a template cannot describe. Use a template when the API of the engine can be used as it is, for example an OpenAI-compatible API.

Configure a Bring Your Own Engine

Build the Adapter

Building an adapter is required only for the Phrase BYO API adapter method. The Pre-built template and Custom template methods do not need an adapter.

The organization must build and test a lightweight API adapter. This adapter enables communication between Phrase and the engine.

The adapter must support:
- Translation requests
- Language pair support
- Engine status check (Phrase sends a status request)
The backing infrastructure (MT engine or LLM) must be hosted and maintained by the organization.
Phrase requires permissions to connect to that infrastructure.
The adapter must return translations with the same segment count and order.

Integrating the Engine in an MT Profile

Once the engine is available, it can be selected in MT profiles in Phrase Language AI and assigned to projects.

To connect a BYO Engine to an MT profile:

From the Phrase Language AI MT profile page, click Connect MT engines.

The Connect MT engine page is displayed.
Select Bring Your Own (BYO) Engine.

The BYO engine configuration page opens.
Under Engine API, select the connection method:
- Phrase BYO API adapter: for a hosted adapter.
- Pre-built template: then select OpenAI-compatible.
- Custom template: then upload the template file or paste the JSON into the editor.
Enter the Base engine URL.

For the template methods, include the API version in the URL, for example https://api.openai.com/v1.
Select the Authentication method and provide the credentials:
- HTTP header: enter the Header name (usually Authorization) and the Header value. Phrase sends the value exactly as entered, so include any prefix, for example Bearer followed by the key.
- Client credentials (OAuth 2.0): enter the OAuth 2.0 client credentials.
Select whether to Use translation cache. Enabled by default.

Reduces traffic and speeds up translation response by reusing segments translated within the last 30 days. This is a call performance optimization only. It does not reduce translation cost. Keep it enabled by default and disable only while the underlying engine adapter is under active development.
If required, provide any additional information for the engine under Custom labels.
Click Validate connection to check if the engine integration works.
Click Add.

The engine is now available to enable in the profile.

Tip

When using a BYO Engine, do not enable any other engine in the MT profile. This ensures the BYO Engine is selected for pre-translation.

BYO Engine Lite (Beta)

BYO Engine Lite connects an engine that already has an HTTP API, such as an OpenAI-compatible API, without a hosted adapter. Phrase calls the API of the engine directly, using a JSON template that describes the request and the response.

Refer to the BYO Lite (Beta) guide in the Phrase developer documentation for the template structure, variables, limits, and troubleshooting.

Note

BYO Engine Lite is in beta and is enabled per organization. Contact your Customer Success Manager or Phrase Support to enable it.

Pre-Built Template

The OpenAI-compatible template supports OpenAI and services that implement the OpenAI chat completions API. Only the base engine URL and credentials are required.

Set the following Custom labels as needed:

model: the model name. Required for services other than OpenAI.
custom_instructions: additional rules added to every translation prompt.
languages: comma-separated locale codes, for example en,de,fr, to limit the language pairs offered by the engine.

Custom Template

A custom template fits APIs that the pre-built template does not cover, for example a different request format or different paths. The pre-built template can be downloaded as a starting point. Phrase validates the template when Validate connection is clicked.

Edit a Bring Your Own Engine

To edit a BYO Engine, click the edit icon on the engine tile.

Delete a Bring Your Own Engine

To delete a BYO Engine:

Click the edit icon on the engine tile.
Click Remove Bring Your Own Engine.

FAQ

Q:	Why is the status request required? Is it sent by Phrase to the engine, or is it expected to be handled by the customer?
A:	Phrase sends the request to check whether the engine works or not.
Q:	One request may contain 500 `maxItems` in `segments`. Does this imply that 500 source sentences must be translated in real time?
A:	Synchronous and asynchronous calls both accept 1–500 segments. In practice, synchronous calls from the editor contain a single segment, while API and batch workflows (pre-translation, analysis) can send many, up to 500. The asynchronous flow uses the same limit and only separates submitting the job from fetching the result. The async timeout is about 30 minutes. We don't automatically fall back from sync to async if your adapter rejects a request. For more details on what to expect from Phrase (segment counts, the engine validation test, retries, and time limits), see the BYO engine guide.
Q:	Are all terms of a glossary sent in a request, or a subset?
A:	All terms of the glossary are sent.
Q:	Is it possible to plug in an LLM?
A:	It should be possible with a wrapper. As long as the engine returns segments as defined in the schema, Phrase does not require a specific engine or LLM.
Q:	Is custom quality evaluation (QE) possible?
A:	Third-party QE is not supported.
Q:	How are tags handled?
A:	The content Phrase receives is pre-processed. HTML tags are converted into marks, and those marks are passed through as is.
Q:	Can we implement only the async approach? Will it work correctly in all Phrase areas (pre-translation, Editor, etc.)?
A:	No, both approaches (ideally all endpoints) must be implemented. The synchronous endpoint is used, for example, by the Editor, while the asynchronous one is used in areas such as pre-translation.
Q:	What happens when the engine gets multiple requests at the same time?
A:	The engine must be able to handle this. Ensure proper handling of concurrency and thread safety across all endpoints, particularly asynchronous ones.
Q:	How does request retadata work?
A:	Request metadata, configured as Custom labels in the BYO Engine configuration, supports dynamic placeholders that are resolved before the request reaches the adapter: `{project_uid}`, `{job_uid}`, and `{idm_organization_uid}`. For example, a Custom label with key `project_uid` and value `{project_uid}` sends the actual Phrase TMS project UID to the adapter.Placeholder resolution only applies inside text values. An unknown placeholder is sent to the adapter as written, without resolution.
Q:	How does Segment Metadata work?
A:	Currently, it needs to be part of the schema.
Q:	During MT processing, does BYO Engine use RAG to retrieve context?
A:	No, BYOE does not use RAG. Users can leverage TMs to determine which segments are translated, but they are not used within the MT process itself. This is because MT engines must be specifically designed to incorporate TM data via RAG, and in BYOE scenarios there is no control over how engines are built or configured.

Adapter Schema Reference

The adapter must return responses that match the following field names and enum values exactly. A mismatch results in a generic INTERNAL_ERROR from Phrase even when the adapter itself returns a 200 OK response.

POST /status must return a status field with a strict lowercase enum value of either ok or not_ok. Example: { "status": "ok" }
POST /languages must return a languagePairs array (camelCase), with each entry containing a sourceLanguage field and a targetLanguage field. Example: { "languagePairs": [ { "sourceLanguage": "en", "targetLanguage": "es" } ] }
POST /translate and GET /translateAsyncResult/{id} must return top-level sourceLanguage and targetLanguage fields, plus a segments array where each segment includes both a text field (the echoed source text) and a translatedText field. Returning only translatedText, or using a different key name, causes a deserialization failure.
POST /translateAsync requires only an id field in its response. A status field is not part of this response schema and is ignored if present.
GET /translateAsyncStatus/{id} must return a status field using one of three enum values: running for a job still processing, done for a successfully completed job, or failed for a failed job. For a failed job, an optional detail field can describe the failure. Example values: { "status": "running" }, { "status": "done" }, { "status": "failed", "detail": "Description of translation failure" }