This document describes the technical requirements to build a content exchange hosted connector that works with Lokalise content engine. The connector is a service that will be installed and hosted on Lokalise and integrates with a third party content platform so translatable content can be exchanged between the two platforms.

Introduction

When you build a hosted connector, Lokalise will take care of the user interface required to handle two user flows: 1) connecting Lokalise to the third party content platform and 2) dealing with the content exchange between that platform and Lokalise.

Therefore, you will only need to focus on implementing the following endpoints for each user flow:

• App setup user flow: Install the app on Lokalise and connect it to the content platform.
  • /auth: Define the user authentication process type used by connector - an API token or an OAuth flow.
  • /auth (POST): Initiate the user authentication process.
  • /auth/response: OAuth flow-only endpoint to support OAuth authorization process.
  • /auth/refresh: Renew an expired token.
  • /env: Get locales available in a third party, default locale and list of additional untranslatable fields and labels presented for the user.
• Content exchange user flow: Get translatable content into Lokalise, and send it back to the content platform once it’s translated.
  • /cache: Get the identifiers of translatable items.
  • /cache/items: Get the translatable items using their identifiers.
  • /translate: Get translatable content from the content platform.
  • /publish: Transfer translated content to the content platform.
• Additional technical endpoints:
  • /: Healthcheck.
  • /health: Healthcheck with optional additional data.

You can find the connector API specification and links to code skeletons below. If you’re familiar with the third party platform’s API and content types, it shouldn’t take more than a few days to build your own connector.

Please, make sure you've gone through the feasibility assessment, and let us know through the App submission portal that you plan to build your own connector so we can offer our guidance and be ready to speed up the launch.

App setup: install and connect to the content platform

The flow to authorize Lokalise to see what content is available on the third party platform is initiated when the user clicks on "Install", on the Lokalise Apps page:

• Lokalise calls the /auth endpoint to know which authorization flow is used by this connector: OAuth 2.0 or API token.
• Lokalise presents a UI where the user can enter the data required by connector. It will contain any data needed by the connector to perform the authorization process, as well as any additional data necessary for connector to perform content exchange. These data will then be added to all requests as a custom header CE-Config containing a base64-encoded object.

• If the connector uses the API token flow, Lokalise sends a request to the connector /auth endpoint to validate the user authorization credentials. The connector uses a third party service to validate the credentials. On success, it returns the authorization data Lokalise, and Lokalise saves it.
• If the connector uses the OAuth 2.0 flow, then Lokalise redirects the user to the third party authentication page, and handles the user authentication result.
  • Lokalise sends the redirect URL to the connector though the /auth endpoint, and receives the authorization URL in the response.
  • Lokalise then redirects the user to the authorization URL for authorization.
  • Once the user finishes the authorization on the third party successfully, they will be redirected to Lokalise with the third party authentication result data.
  • Lokalise will send the data to the /auth/response endpoint to obtain the final authentication result. On success, the connector returns the authorization data to Lokalise, and Lokalise saves it.
• The authorization data obtained will be added to all content exchange requests as a custom header CE-Auth containing a base64-encoded object.
  • Lokalise handles the refreshing of expired authorization credentials. Whenever an OAuth access token needs to be refreshed, Lokalise will send a request to /auth/refresh connector endpoint providing the authorization data; Lokalise will then get new authorization data in the response. For the following requests, this data will be included in the CE-Auth header.

App configuration

Lokalise sends a request to the /env endpoint to learn what languages and additional fields are available on the third party system (e.g, the content type, the creation date, the last update date, etc.). The result of this call will indicate which languages will be presented to the users, and which columns will show on the Lokalise UI. Locales provided by the connector should match the locales set up by the user in the Lokalise project in order to be available for content exchange.

List translatable content

Lokalise keeps a cache with the content items that can be imported from the third party platform for translation. Therefore, before performing any content exchange, Lokalise needs to obtain the list of items that can be translated (we call them “cache items“).

• When user clicks on the “Refresh“ button, Lokalise sends a request to the /cache endpoint to obtain a list of all translatable items available on the third party. The connector should gather a list of all items, with their identifiers and linking data (UniqueItemIdentifier), and return them to Lokalise.
• Based on the list, Lokalise will perform subsequent requests to the /cache/items endpoint to gather the context fields data defined by the connector in /env. Lokalise will store the data received as cache items.

Note that the cache refresh is also initiated automatically right after the app is installed for the first time.

Content exchange

Once the content platform has been connected to Lokalise, users can start managing the translations. They'll see the list of translatable items, split in three views according to their status:

The actions that a user can trigger from each view depend on items status.

• Available for import view
  • Users can select which items to transfer to Lokalise for translation and press “Import to Lokalise“
    • Lokalise sends a /translate request to the connector, in order to transfer the actual translatable content from the third party to Lokalise for translation.
    • The connector returns the content to Lokalise; Lokalise creates or updates the keys, and determines the translation status of each key taking into account all the target languages.
    • At this point, users can use the Lokalise Editor to see all the keys that need to be translated.
• Translation in progress view
  • The items were transferred to Lokalise and are currently in progress. These items can be translated and marked as reviewed in Lokalise editor. The user can select items to be transferred to the third party system.
  • Lokalise gathers the content and sends a /publish request to the connector. The connector will publish the content in the third party system. If the result is successful, Lokalise will change the item status to published.
• Translation exported view
  • This view shows the items that have already been transferred to the third party system, and for which the third party content hasn’t changed since the last refresh action.
  • The user can refresh the list to check whether the source item changed after publishing the translation; in that case, Lokalise will change the item status and the item will move back to the Available for import view.

Connector API (Beta)

This is the API contract between Lokalise and the connector you'll be building. Please note this API specification is in beta; we don’t expect to introduce any breaking changes, but the API is still subject to change based on feedback we'll be collecting from app developers such as yourself. Don't hesitate to send your suggestions and questions.

OpenAPI schema is available on https://github.com/lokalise/ce-connector-api

Error handling

In case of error connecting with the third party platform, the connector should return an error with the following format:

{  
  statusCode: 500,  
  payload: {  
    message: "Unknown error",  
    errorCode: "UNKNOWN_ERROR",  
    details: {  
      ... (All info on the error)  
    }  
  }  
}

The response HTTP code should match Status code.

Additional error codes and Lokalise handling strategy will be published soon.

Code examples

For a faster start, Lokalise can provide you with application skeletons in the following languages:

• NodeJS
• PHP

Package your app

A connector is a simple HTTP service. It should handle only requests specified in the API schema (above). The source code should be shared with Lokalise through version control system hosting services like Github, Gitlab or others.

The service should be virtualised with Docker. It should not contain any persistence mechanisms.

Register your app

To get your app listed, please follow the Review and publish your app instructions. We’ll ask for information such as:

• App description
• App logo
• Link to the source code
• List of installation fields with labels required by the connector

Additional guidelines for advanced cases

Conversion of translatable items into cache items

In order to ensure the ability to consistently retrieve and publish content items, it is necessary to use the UniqueItemIdentifier object to link the information between the connector and the third party platform. This object consists of the following fields:

• uniqueId - A custom unique identifier. It should be unique per item across the whole exchange process. It must not contain double colon symbol ::.
• groupId - This identifier is used to group items that expected to be translated and published together. The user will be presented with translation items joined by this identifier. It must not contain double colon symbol ::.
• metadata - This is a custom structure JSON object that the connector can use to help identify and match the content item. Lokalise will store it, but will not process it in any way.

Let's see an example with a third party content platform that allows users to publish articles. An article consists of a title and a body. Therefore, a connector between Lokalise and the platform should convert the article into two separate cache items with different unique ids; and they should have the same group id in order to ensure that they're processed, translated and published together. The metadata could contain properties like field, in order to help the connector identify which part of the original article the translated content is referring.

What are “groupTitle” and “title“ cache item fields

Both field purpose is to help user link a cache item to third party content.

“Group title“ is usually a third party content entity title. It should be same for all cache items in the group. “Title“ is a description for the type of content part cache item is related to.

For example, if we are translating an article with title “[Sample] FAQ“ and body, the group title should be “[Sample] FAQ“. Cache item that is linked to article title has 'title' field as “Article title“, while cache item linked to article body has 'title' field as “Article body“.

When the third party platform does not support localisation

If the third party platform does not have an internal way to handle localised content, or the locales cannot be obtained by connector, Lokalise will use the languages set up on the Lokalise project where the app is installed. The connector should be able to handle these languages and use them conveniently during the content exchange.

When the third party platform original content language cannot be defined

If the third party platform does not know what the default language is, Lokalise will send the default locale on each content exchange request. The connector should associate the original content with the locale provided.