Bring Your Own Engine

The Bring Your Own Engine (BYO Engine) feature allows the integration of external machine translation (MT) engines into Phrase to be used in translation workflows like any other MT provider.

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, etc.).

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, 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.

Configure a Bring Your Own Engine

Building the Adaptor

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 API adapter is implemented and deployed, the BYO Engine becomes available in Phrase Language AI for selection in MT profiles and can be 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.
Enter the Base engine URL.
Provide credentials depending on the Authentication method (HTTP header or Client credentials (OAuth 2.0)).
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 enabled by default, 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.

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 Metadata 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 BYOE 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" }