Introduction

If you wish to support articles and pages in multiple languages, Cortex provides support for content creators to create and manage the relationships between translations. This document presents the relevant API calls available.

Note that in Cortex, supported languages are ‘locales’, and follow the standards laid down in BCP 47 (Best Current Practices) for language tags. The syntax for these languages is the IANA code for the language followed by a regional sub-tag. For example, En-AU for Australian English or es-MX for Mexican Spanish. For more on this, see The BCP 47 Standard for Language Tags.

API calls using locales

Below are the two most common API calls you are likely to use in working with locales.

To return a list of all the locales that have been set up within a client:

💻

GET {environment-id}/v2/locales?clientId={clientId}

In which:

{environment-id} is the URL for stage (test) or production (live).

• Stage: https://stage-article-cms.cortextech.io
• Production: https://article-cms.cortextech.io
• Production (US environment): https://article-cms.cortextech.us

{clientId} is your client ID, assigned during onboarding.

So, for example, this call fetches a list of all the languages set up within the client ID: DEMO.

💻

GET https://article-cms.cortextech.io/v2/locales?clientId=DEMO

To return a list of all the localised versions of an article:

💻

GET {environment-id}/v2/articles/{articleId}/localizations?clientId={clientId}

In which:

{environment-id} and {clientId} are as described above.

{articleId} is the ID of the article for which you want to see the localization detail.

So, for example, this call returns all the localised versions of the article with ID: ca0e730e-b99a-4eb5-bf95-9ecca4077b4a.

💻

GET https://article-cms.cortextech.io/v2/articles/ca0e730e-b99a-4eb5-bf95-9ecca4077b4a/localizations?clientId=DEMO]

In that example, the original article is in English, and it has two translations, in Spanish and Greek, so the latter pair are returned.

To return articles filtered by language (locale):

Both the main articles endpoint (explained in full here) and the feed builder endpoint (explained in full here) can be queried by locale, using the parameter ?language={locale}, in which:

{locale} is the code for the locale to be requested. In the article in Cortex, this is set in the locales field, and will follow the BCP-47 standard (for example, it could include either or both of es for Spanish in general or es-AR for Spanish (Argentina))

To add a fallback language to your API query:

Where using the ?language parameter, as described above, you can additionally specify a set of fallback languages to be used where there is no match for the primary language in the request. This can be achieved using the parameter ?fallbackLanguages={language1},{language2},{language3}, in which:

{language1},{language2},{language3} is the list of fallback languages, comma separated, in the order in which they should be prioritised. Each language should be specified using a code from the BCP-47 standard.

So, for example, this call fetches a list of all the articles set up in the client ID: DEMO with the main language (locale) set to German (de) and the fallback languages set firstly to Spanish (es) and secondly to English (en):

💻

GET https://article-cms.cortextech.io/v2/articles?clientId=DEMO&tags=fallback-languages&language=de&fallbackLanguages=es,en

This would mean that:

• If there is a German variant of a given article, then the German version will always be included. All other versions of that article will be excluded
• If there is not a German variant of the article, but there is a Spanish version, then the Spanish version will be provided. Any other version will be excluded.
• If there is neither German or a Spanish variant of the article, but there is an English version, then the English version will be provided.
• If there is no German, Spanish, or English version of the article, then no version of the article will appear in the response, even if there is, say, a French version.

Working with languages in Cortex

Before developing a multilingual front end powered by the Cortex CMS, you will need to set up the languages you will support. To do this:

1. Log in to Cortex. On the left-hand side, click Content and then select the Settings icon ([⚙️])
2. You are presented with the Settings screen. Select the Locales tab.

Here you can select from the many dozens of languages and regional variations available under the BCP 47 standard. As you can see, the languages you choose are listed in the Locales box in the central panel; along with your selected default language.

The languages you choose will become available to content editors in drop-down lists.

Languages within categories

There is an option when creating a category to assign a language from a drop-down list. At the same time, the category name and slug can be given translations for ease of use in the alternative language. These fields can be useful in creating web pages that are categorised by language whilst retaining the site structure and fixed set of categories in that language. So, for example, a Spanish version of the website could use the translated version of the slug text in its URL in order to ensure the user is taken to the Spanish site and article.

Content categories can be created and edited by following the instructions in Content categories for articles and pages.