# 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.

{% tabs %}
{% tab title="Localized API Request (en\_US)" %}

```javascript
$.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"
    }
});
```

{% endtab %}
{% endtabs %}

### 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)

{% tabs %}
{% tab title="Localized API Post (en\_US)" %}

```javascript
$.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) {
    // ...
});
```

{% endtab %}
{% endtabs %}

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"

{% tabs %}
{% tab title="Localized API POST (fr\_FR)" %}

```javascript
$.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) {
    // ...
});
```

{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="Localized API Request (en\_US)" %}

```javascript
$.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"
    }
});
```

{% endtab %}

{% tab title="Response (en\_US)" %}

```javascript
{
    "data": [
        {
            "_id": "5d0552f04b373401003aba6a",
            "c_greeting": "hello",
            "object": "c_my_object"
        }
    ],
    "hasMore": false,
    "object": "list"
}
```

{% endtab %}

{% tab title="Localized API Request (fr\_FR)" %}

```javascript
$.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": "fr-FR",
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"
    }
});
```

{% endtab %}

{% tab title="Response (fr\_FR)" %}

```javascript
{
    "data": [
        {
            "_id": "5d0552f04b373401003aba6a",
            "c_greeting": "bonjour",
            "object": "c_my_object"
        }
    ],
    "hasMore": false,
    "object": "list"
}
```

{% endtab %}
{% endtabs %}

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'`}).

{% tabs %}
{% tab title="Include Optional Locales Property" %}

```javascript
 $.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"
}
*/
```

{% endtab %}
{% endtabs %}