Localization

Cortex supports localization through custom localized string properties. Localization for a string property can be enabled via string property options. Once enabled, you can write to and read from that property in any specified locale.

Specifying Locale

Via API

When making api requests, locale can be specified by a locale identifier via the Accept-Language header. The locale identifier consists of a 2 or 3 letter language tag optionally followed by a hyphenated region. For example, en, en-US, en-UK, etc.

Localized API Request (en_US)

$.ajax({
    url: "https://api.dev.medable.com/example/v2/c_my_object",
    type: "GET",
    contentType: "application/json; charset=UTF-8",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Accept-Language": "en-US",
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    }
});

Within Scripts

Within scripts, you can specify locale using the .locale() method for the given query cursor or insert/update operation. In scripts, the locale identifier must be separated by _. For example, en, en_US, en_UK, etc.

Localized Query Cursor

return org.objects.c_my_object.find({_id: '5d0552f04b373401003aba6a'}).locale('en_US').passthru()

Localized Insert Operation return org.objects.c_my_object.insertOne({c_greeting: 'hello'}).locale('en_US').execute()

Localized Update Operation return org.objects.c_my_object.updateOne({_id: '5d0552f04b373401003aba6a'}, {$set: {c_greeting: 'bonjour'}}).locale('fr_FR').execute()

Reading and Writing to a Localized String Property

Reading from and writing to a localized string property occurs in the locale specified. If a locale isn't specified, then the default locale for the organization is used.

For example, below is a localized c_greeting property in the object c_my_object, and a value is written to it while specifying the en_US locale.

Localized API POST (en_US)

Localized API Post (en_US)

$.ajax({
    url: "https://api.dev.medable.com/example/v2/c_my_object",
    method: "POST",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq",
        "Accept-Language": "en-US"
    },
    data: {
        "c_greeting": "hello"
    }
}).done(function(data) {
    // ...
});

When requesting that instance of c_my_object in the en_US locale, we can expect to always receive the c_greeting of "hello".

However, if we specify a different locale, we can write additional values to that property. For example, below we update that property with a value while specifying the locale "fr-FR"

Localized API POST (fr_FR)

$.ajax({
    url: "https://api.dev.medable.com/example/v2/c_my_object/5d0552f04b373401003aba6a",
    method: "PUT",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq",
        "Accept-Language": "fr-FR"
    },
    data: {
        "c_greeting": "bonjour"
    }
}).done(function(data) {
    // ...
});

Now, depending on the locale we specify, we can retrieve different values for that same property when getting that c_my_object instance.

Localized API Request (en_US)

$.ajax({
    url: "https://api.dev.medable.com/example/v2/c_my_object",
    type: "GET",
    contentType: "application/json; charset=UTF-8",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Accept-Language": "en-US",
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    }
});

Response (en_US)

Localized API Request (fr_FR)

Response (fr_FR)

This allows for translations to be provided to client applications seamlessly simply by specifying the appropriate locale.

Additionally, when a string property is localized, you may also include the optional locales property to retrieve all localized string values at once. Inside the locales property, each localized string property is represented by an array of documents containing each locale and value that have been written (e.g. {locale: 'en_US', value: 'hello'}).

Include Optional Locales Property

 $.ajax({
    url: "https://api.dev.medable.com/example/v2/c_my_object?include=locales",
    type: "GET",
    contentType: "application/json; charset=UTF-8",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Accept-Language": "en-US",
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    }
});

/* response
{
    "data": [
        {
            "_id": "5d0552f04b373401003aba6a",
            "c_greeting": "hello",
            "locales": {
                "c_greeting": [
                    {
                        "_id": "5d0552f0229d2f010075979b",
                        "locale": "es",
                        "value": "hola"
                    },
                    {
                        "_id": "5d06ba1cba9d3f010039c668",
                        "locale": "fr_FR",
                        "value": "bonjour"
                    },
                    {
                        "_id": "5d06ba26ba9d3f010039c6d4",
                        "locale": "en_US",
                        "value": "hello"
                    }
                ]
            },
            "object": "c_my_object"
        }
    ],
    "hasMore": false,
    "object": "list"
}
*/