Feasibility assessment for content engine hosted connectors

Use this guide to assess the technical feasibility of a new content exchange hosted connector, and to estimate its complexity.

Introduction

A connector is a service that will be installed and hosted on Lokalise, and serves as a bridge with a third party content platform (from now on, the content platform) so translatable content can be exchanged between the two platforms. If you haven't already done so, please get familiar with the Lokalise content engine architecture.

This guide includes several sections for you to figure out:

How content localization is done on the content platform.
What content types will be transferable to Lokalise .
What are the API endpoints available for the development.
What are the available authentication types.

It's advisable to create an account in the content platform and Lokalise, with some data for testing.

Here's a scheme of this analysis process:

Step 1. Figure out how content localization is done on the content platform

You should understand how users work with multilingual content in the content platform. Some content platforms already provide multilingual support, while some others require workarounds, or additional plugins, or advanced options that can be used for managing multilingual data.

The main question to figure out at this point is how multilingual content will be stored in the content platform after it is localised on Lokalise.

After going through the questions below, you should have a high-level understanding of the localization workflow on your content platform. There are basically two options:

A. Multilingual support is available: When Lokalise users export localised content, the translations will be seamlessly associated to the existing items.
B. Multilingual support is not available: When Lokalise users export localised content, new items will be created on the content platform.

Let's go through these options.

Option A) Multilingual support is available

If your content platform handles localised content, how does it work?

Architecture of multilingual support

If your content platform handles localised content, how does it work? Here are some things you can check:

Does each text item include all translations?
Does every text item include a language parameter? Are different text items with a language parameter linked between each other?
Is multilingual content organized in separate folders or another type of hierarchical structure?
Is there a default language?

Stored languages

Now let's check the way languages are stored in the content platform:

Do users need to enable multilingual features on purpose for different content types? Or does the content platform enable it by default for all content types?
Is there a predefined list of languages available to all customers? Is this list of languages limited or unlimited? Can users define their own custom languages?
Does the content platform identify languages through ISO codes? If so, are they similar to the standard codes used by Lokalise?
Can users add custom ISO codes or modify the current ones? In this case, are there any naming conventions that these codes must follow? Could they match the ISO codes used on Lokalise?
- Note that Lokalise custom codes include underscores (e.g, en_US). Your content platform might use dashes or other custom codes. If language codes don't match Lokalise's by default, then users can use custom language codes on Lokalise to make them match in both platforms.

Option B) Multilingual support is not available

If your content platform doesn't handle localised content, then you need to know what workarounds are often used by the content platform users to overcome that limitation, or document a solution of your own.

Here are some things you can check:

Is there any plugin or additional service for managing multilingual content?  If there is one, is there a way to work with it through an API? And how exactly are multilingual properties stored?
Is there a specific way to save translated content? For example, there are tabs, branches or ad hoc components that can be used for multilingual purposes?  If so, then you should check if these elements are accessible through an API.
Alternatively, if none of the previous options are available on your content platform, you can check if the translated elements can be stored as new items, and if whether those items support additional properties.
- For example, your content platform provides email templates but it doesn't have multilingual support. Then perhaps your only option is to create new emails translated to different languages, and link them to the original email template through a custom property.

Step 2. Decide what content types will be transferable to Lokalise

The result of this step will be a list of all the content types that your users will be able to transfer to Lokalise. Therefore, you should go deeper and understand what groupings, content types and fields you want to make available for your users to localise, and how you'll turn them into items that can be translated.

Go over the content types available in the content platform (e.g, articles, emails, templates, etc.).
Based on your user knowledge and their common localisation needs, select the subset of content types that you'd like them to be able to send to Lokalise.
Find out the multilingual options for the selected content types, and check how the translated content can be stored in the content platform.
- For example, imagine your content platform works with emails but there is no multilingual support for them. Is there a way you can create new emails as translations of the initial one, and link them all?

Step 3. Get familiar with the content platform API

At this point you should validate whether your required workflow is reproducible through an API.

At least you should double check that the selected content types are accessible through an API endpoint, and that you'll be able to create translations or new items through the API as well. But if the API doesn't provide any endpoints to manage the selected content types, then there is no possibility to build a connector.

For each content type selected on the previous step, identify an API endpoint that would allow you to:

Get a list of all translatable items, and some identifier for each one of them.
Get the actual content of those items.
Update the items with their translations, or create new items that will be somehow linked to the original item.

While you're looking into the API, check any rate limits or quotas that might impact the connector usage.

Get the list of translatable items

This endpoint is used for building the Cache endpoint on Lokalise side.

For each of selected content type you should have a Get listor Retrieve all instances or a similar API call.

Usually this endpoint provides the list of all existing entities with an entity identifier that will be used to retrieve the item content (that is, the text to be localised).

Here you should also start preparing the list of fields that users will use for filtering the content on Lokalise side (eg., creation date, tags, folder, etc.).

Retrieve the items to translate

This endpoint is used for building the Translate endpoint on Lokalise side.

Once you have the item identifiers, you need a call to get the content itself. You need to find a Get content values or Get content details or similar API call.

Note that it is necessary to get any previous localized versions as well, and not only the items in the original language. Otherwise, the translated items wouldn't be updated correctly, and the connector might create duplicates or inconsistencies.

Each item might consist of different fields; for example, an article might consist of a title, a description, a body and some additional fields. If this is the case:

Choose the field that better identifies the whole group, so users can work in a similar way on the content platform and Lokalise (e.g, for an article, it would be the title).
Lokalise will create different keys for the different fields, but the item fields will always be transferred together between the the content platform and Lokalise, as explained in What are “groupTitle” and “title“ cache item fields.
Choose which other fields are suitable for filtering content in Lokalise: creation date, tags, labels and any other relevant properties.
If there are any elements that you don't want to show on Lokalise, the connector should have a way to filter them out. For instance, you might not want to show elements with multilingual support disabled. In this case, you should be ready to filter these elements out on the API call.

Send the localized items back to the content platform

This endpoint is used for building the Publish endpoint on Lokalise side.

If your content types support languages natively, you might be looking for an Update element or similar API call.
Otherwise, you'll need a Create new element or similar API call.

Option A) Multilingual support is available

The usual workflow for defining languages on a content platform is one of the following:

Users add or select languages for their workspaces (AKA profiles, or projects, or folders, or spaces) in the content platform.
There's a predefined list of languages across the content platform and users can select any of them for each content item; that is, they don't need to select the relevant languages on purpose for their workspace.

In any case, you'll need an endpoint to retrieve which languages are relevant for localising the content items. Look for an API endpoint such as Get all languages or Get default language or Get other languages, which are needed for building the Environment endpoint on the connector.

If these calls are unavailable, then:

The translated content will be exported back to the content platform with the locale codes from Lokalise. In this case, any custom language code in Lokalise should be the same as the ISO codes on the content platform; otherwise, they won't match and translations won't be exported correctly.
The list of languages can be hardcoded on the connector, which could be the last resort if your content platform provides a limited list of languages. Beware the list shouldn't be over a dozen languages because users will need to select languages manually on each import and export action.

Also look for a Get language for each item for all selected content types. The language parameter might be presented in the Get content values response or a similar endpoint.

Option B) Multilingual support is not available

This section only applies when your content platform doesn't support multiple languages and there is no workaround for adding them (languages can't be added as a custom property or the content can't be structured in folders).

In this case you need to figure out how localized entities can be linked with the original one, as it's mandatory to store this relationship. Here are some usual workarounds:

Store the identifier of the original item in an editable field of the localized items.
Store the identifier of the original item in the name of localized items.
If it is possible to create folders in the content platform, add the language code as part of the folder name.
Create a custom object.

Step 4. Select the authorization method

Select how your users will grant Lokalise read and write access to their contents:

OAuth 2.0
API key

You can only select one method. The main difference is that API tokens incorporate the user account, while OAuth usually performs an authorization not necessarily linked to an account. When you make a choice of using an API token or an OAuth app, you must consider the specific requirements of the API of selected endpoints.

For a detailed description of the authentication flow see App setup: install and connect to the content platform.

If you got to this point and all the questions are clear, congrats, you're good to start your connector!