Introduction

This guide is for Phrase TMS plugins. It does not cover Phrase Strings, Language AI, or other Phrase products.

A TMS plugin is software that lives in a third-party system and connects that system to Phrase TMS. It sends source content for localization, monitors translation progress, and retrieves completed translations back into the source system.

New to this flow? Start with Quick Start, then return here for the reference sections.

What you’ll build

A production plugin usually follows this lifecycle:

Select source content in the third-party system.
Authenticate with Phrase Platform and call TMS APIs.
Create a project from a project template.
Create one or more jobs by uploading source content.
Monitor job progress (webhooks, async status, or job-part polling).
Export translated files when jobs are complete.
Set job status (for example DELIVERED) after successful import.

Choose your path

Quick Start

Build a working baseline plugin flow in four steps.

Full Workflow

Add production behavior, monitoring, and hardening.

Error Handling & Limits

Handle failures, retries, limits, and operational safeguards.

Supported file types

Common file types used in plugin integrations:

File type	Typical use
XLIFF 1.2 / 2.0	Standard localization exchange format
JSON	Structured application or CMS content
XML	Structured content and metadata
Markdown	Documentation and content workflows
Plain text	Simple non-structured content

For import-specific parsing behavior, see file import settings.

Key concepts

Term	Definition
Project template	Reusable configuration used to create projects with standard settings and workflow steps.
Project	Container for related translation jobs.
Job	A translation unit for one file and one target language.
Workflow	Ordered translation/review steps that jobs move through.
`asyncRequest`	Identifier for asynchronous API operations that complete later.
Locale	Source or target language/region identifier used in localization.
Machine translation	Automated translation used in workflow steps, often combined with human review.
Markup language	Structured formats (for example HTML/XML) where text and tags must be handled safely.
Segmentation	Splitting content into translatable segments used for progress and QA operations.
Translation memory	Reusable translation database used to improve consistency and speed.

Core objects and data models (minimum)

Use these core object shapes in your plugin data layer.

Object	Purpose	Key fields to persist
Project Template	Defines default project configuration	`uid`, `templateName`, `sourceLang`, `targetLangs[]`
Project	Container for jobs	`uid`, `name`, `status`, `sourceLang`, `targetLangs[]`
Job	Translation unit for a target language	`uid`, `status`, `targetLang`, `workflowLevel`, `filename`
Async Request	Tracks asynchronous work	`id`, `action`, `dateCreated`
Async Response	Completion payload for async work	`errorCode`, `errorDesc`, `warnings[]`

Representative JSON shapes:

{
  "projectTemplate": {
    "uid": "pt-uid-1",
    "templateName": "Website Default",
    "sourceLang": "en",
    "targetLangs": ["de", "fr"]
  },
  "project": {
    "uid": "proj-uid-1",
    "name": "Website Translation",
    "status": "NEW"
  },
  "job": {
    "uid": "job-uid-1",
    "status": "NEW",
    "targetLang": "de",
    "workflowLevel": 1
  },
  "asyncRequest": {
    "id": "async-req-1",
    "action": "PRE_ANALYSE"
  },
  "asyncResponse": {
    "errorCode": null,
    "errorDesc": null
  }
}

Next steps

Start Quick Start

Build the minimum end-to-end flow first.

Go to Full Workflow

Expand to a production-ready integration.

Add Live Preview

Add editor preview capabilities for translators.

BYO Engine

Build a TMS Plugin

Managing TMS Connectors

Managing Automated Project Creation

What you’ll build

Choose your path

Quick Start

Full Workflow

Error Handling & Limits

Supported file types

Key concepts

Core objects and data models (minimum)

Next steps

Start Quick Start

Go to Full Workflow

Add Live Preview

​What you’ll build

​Choose your path

Quick Start

Full Workflow

Error Handling & Limits

​Supported file types

​Key concepts

​Core objects and data models (minimum)

​Next steps

Start Quick Start

Go to Full Workflow

Add Live Preview

What you’ll build

Choose your path

Supported file types

Key concepts

Core objects and data models (minimum)

Next steps