Building a plugin

​

Overview

Integrating with Phrase TMS provides seamless content exchange between third-party systems and Phrase, which is critical for reducing manual labor, minimizing errors, and improving efficiency in translation processes. This integration is particularly beneficial for businesses with frequent updates and high-volume translation needs, enabling continuous localization and immediate availability of translated content in target languages.

​

User flow

When building an integration into Phrase from an external system, you’ll need to consider the following User Flow:

This covers the basic requirements for a Plugin into Phrase. There are other actions that may be included, such as canceling a Job that is currently “In Progress” or Assigning Vendors, handling multiple workflow steps or setting up a continuous monitoring and import based on a change to content in a 3rd party system. These additional use cases are not fully covered in this document, please review our API documentation to discover how to implement these additional requirements.

​

File types

Phrase TMS supports a variety of file types for integration purposes, which include:

1. XLIFF (1.2 and 2.0): XML Localisation Interchange File Format, commonly used for exchanging translation data between different tools.
2. JSON: JavaScript Object Notation, used for structured data interchange.
3. XML: Extensible Markup Language, offering versatile import options.
4. Markdown: Lightweight markup language with plain text formatting syntax.
5. Plain Text: Unformatted text files.

Additionally, Phrase supports various import options and parsing settings for these file types, which can be saved as custom file types and/or in project templates to optimize the integration setup.

​

Building the Phrase Plugin

​

Authentication

Phrase TMS uses two main authentication methods for API access: API Token and OAuth 2.0.

1. API Token:
   • Call the auth/login API to obtain a token, valid for 24 hours.
   • Use the token in the Authorization header for subsequent API calls.
   • Example: ApiToken OKTiI2V7QqRDu0HADR2Fk2b9hCteI1pT06bOSk5OD8HSc3oCOHMzIgVtOtLV65hi.
2. OAuth 2.0:
   • Register an OAuth app in Phrase settings.
   • Use the generated Client ID for authorization via the Auth URL and Token URL.
   • This method is recommended for applications to ensure secure and efficient access​(TMS Integration Guide -…)​.

​

Sending a File into a Phrase Project and Creating a Job

1. Login:
   • Connect to your App using your Phrase credentials
   • OAuth app in Phrase settings.
2. Create Project from Template:
   • POST /projects/applyTemplate to create a project using a predefined template.
   • API Documentation
3. Generate and upload the preview package (optional)
   • See below for more details
   • API Documentation
4. Create Job:
   • POST /jobs to create a job within the project.
   • API Documentation
5. Assign Providers (optional):
   • POST /jobs/{jobUid}/providers to assign linguists or MT providers from the template.
   • API Documentation
6. Create Analysis (optional):
   • POST /jobs/{jobUid}/analyses to perform word count and other analyses.
   • API Documentation
7. Notify Assigned Users (optional):
   • POST /jobs/{jobUid}/notify to notify assigned users about the new job.
   • API Documentation

​

Monitoring Job Progress

1. List Parts:
   • GET /jobs/{jobUid}/parts to check the status of each job part.
   • API Documentation
2. Webhooks:
   • Set up webhooks to get notifications about job status changes.
   • Webhooks Documentation
   • API Documentation
3. Check Async Requests:
   • GET /asyncRequests/{asyncRequestId} to check the status of asynchronous operations.
   • API Documentation

​

Exporting the Translated File Back Out of Phrase

1. Download Completed File:
   • GET /jobs/{jobUid}/targetFile to download the translated file.
2. Edit Job Status:
   • POST /jobs/{jobUid}/status to set the job status to DELIVERED, indicating that the content has been retrieved.
   • API Documentation

​

Adding Live Preview to the CAT Editor

One commonly desidered feature is Live Preview. Live preview is an HTML-based visual representation of localized content, accessible within the editor and navigable by segments. It provides translators and editors with additional context. Its content is updated as segments are localized (it is live in that sense).

There are different ways this can be achieved.

​

Option 1: Choose an HTML File for Localization

When creating a job in TMS, you have to specify the file format that you want to localize. If you choose HTML and upload HTML for localization, it will be rendered as a live preview in the editor. This is not necessarily feasible for all CMSs as they often organize content into fields that they represent in complicated data structures which would be difficult to convert to HTML and then back.

​

Option 2: Upload a Preview Reference Package when Creating the Job via the TMS API

Since Option 1 is not always available, we’ve created an alternative approach that allows users to upload a separate preview package that will then be rendered as a part of the job. The steps you need to take are as follows:

1. Create a ZIP file with assets (images, CSS, JS) and a single HTML which will be rendered by the editor
   1. The HTML needs to have the assets linked as relative links
   2. Absolute links (https://google.com) and assets linked in this way will be preserved but may not work correctly. This is intended to work around the issue of assets being unavailable via the Internet or requiring authentication for access.
2. Call this endpoint to upload the job preview package created in the previous step, save the returned ID.
3. When creating the job using the Create job endpoint, add the ID from the previous step as a parameter jobPreviewPackageFileUidRef in the Memsource header. Once the job is created, it should have a live preview created and visible in the editor.

​

Limitations

• Rate Limits: Information on Phrase Rate Limits
• File Types: Information on File Types and limitations

​

Error Messaging

When integrating with the Phrase TMS API, you may encounter several common error codes. Here are the most frequent ones, along with their meanings and how to handle them

​

Other Considerations

• Continuous Updates: Use the updateSource endpoint for continuous localization to update only changed segments.
  • Update Source
• Reporting: To help us provide reporting on the impact and value that your Plugin provides our customers please consider adding the following:
  While using the plugin to call TMS endpoint POST /api2/v1/projects/$project_id/jobs for creating a job.
  As a part of the Memsource header, you can append a sourceData object to the JSON:

{
  "targetLangs": [
    "de"
  ],
  "sourceData": {
    "clientType": "MY_PLUGIN",
    "clientVersion": "1.2.4",
    "hostVersion": "4.5.2"
  }
}

clientType identifies the plugin type
clientVersion holds the version of your plugin
hostVersion holds the version of 3rd party system

Only the clientType value is required, clientVersion and hostVersion are optional and only should be used if relevant.

The value used in clientType needs to be registered with Phrase. Please reach out to us to register your plugin as a recognized client.

​

Glossary

You can review all the terminology of Phrase products and terms in our help center. Here is a list of the major ones you’ll interact with: