---
title: "Localisation"
framework: javascript
version: "2.1.2"
---

# Localisation

The displayed text in Studio can be customised for localisation. You can achieve this by providing locale information in the required language. Use the `localeText` property to apply one of the provided locales, create a custom locale, or use the `getLocaleText` callback to integrate Studio with your application's localisation system.

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `localeText` ([Initial](https://www.ag-grid.com/studio/javascript/studio-interface#initial-studio-properties)) | `AgStudioLocaleText` |  | A map of key->value pairs for localising text within Studio. |
| `getLocaleText` ([Initial](https://www.ag-grid.com/studio/javascript/studio-interface#initial-studio-properties)) | `Function` |  | A callback for localising text within Studio. |

## Provided Locales

The default language of Studio is American English, however, we provide a number of translations that can be used as a starting point for commonly requested languages:

| Language | BCP47 Tag | Locale Module |
| --- | --- | --- |
| Arabic (Egyptian) | ar-EG | AG_STUDIO_LOCALE_EG |
| Bulgarian | bg-BG | AG_STUDIO_LOCALE_BG |
| Chinese (Traditional) | zh-HK | AG_STUDIO_LOCALE_HK |
| Chinese (Simplified) | zh-CN | AG_STUDIO_LOCALE_CN |
| Chinese (Taiwan) | zh-TW | AG_STUDIO_LOCALE_TW |
| Croatian | hr-HR | AG_STUDIO_LOCALE_HR |
| Czech | cs-CZ | AG_STUDIO_LOCALE_CZ |
| Danish | da-DK | AG_STUDIO_LOCALE_DK |
| Dutch | nl-NL | AG_STUDIO_LOCALE_NL |
| Finnish | fi-FI | AG_STUDIO_LOCALE_FI |
| French | fr-FR | AG_STUDIO_LOCALE_FR |
| German | de-DE | AG_STUDIO_LOCALE_DE |
| Greek | el-GR | AG_STUDIO_LOCALE_GR |
| Hebrew | he-IL | AG_STUDIO_LOCALE_IL |
| Hungarian | hu-HU | AG_STUDIO_LOCALE_HU |
| Italian | it-IT | AG_STUDIO_LOCALE_IT |
| Japanese | ja-JP | AG_STUDIO_LOCALE_JP |
| Korean | ko-KR | AG_STUDIO_LOCALE_KR |
| Norwegian (Bokmål) | nb-NO | AG_STUDIO_LOCALE_NO |
| Persian | fa-IR | AG_STUDIO_LOCALE_IR |
| Polish | pl-PL | AG_STUDIO_LOCALE_PL |
| Portuguese | pt-PT | AG_STUDIO_LOCALE_PT |
| Portuguese (Brazil) | pt-BR | AG_STUDIO_LOCALE_BR |
| Romanian | ro-RO | AG_STUDIO_LOCALE_RO |
| Slovak | sk-SK | AG_STUDIO_LOCALE_SK |
| Spanish | es-ES | AG_STUDIO_LOCALE_ES |
| Swedish | sv-SE | AG_STUDIO_LOCALE_SE |
| Turkish | tr-TR | AG_STUDIO_LOCALE_TR |
| Ukrainian | uk-UA | AG_STUDIO_LOCALE_UA |
| Urdu (Pakistan) | ur-PK | AG_STUDIO_LOCALE_PK |
| Vietnamese | vi-VN | AG_STUDIO_LOCALE_VN |

> **Note**
>
> Translations are provided as an illustration only and are not guaranteed to be accurate or error free. They are designed to show developers where to store their chosen phrase or spelling variant in the target language.

## Using a Provided Locale Module

All of the provided locales listed above are available in the `ag-studio-locale` package. To use any of the provided locales in your application, follow these steps:

First, import the desired locale module from the `ag-studio-locale` package. For example, to use the German locale, import `AG_STUDIO_LOCALE_DE`:

```js
import { AG_STUDIO_LOCALE_DE } from 'ag-studio-locale';
```

Next, assign the imported locale object to the `localeText` property in your Studio properties:

```js
const studioProperties = {
    localeText: AG_STUDIO_LOCALE_DE,

    // other studio properties ...
}
```

Finally, ensure the `ag-studio-locale` module is listed as a dependency in your application's package configuration:

```js
"dependencies": {
    "ag-studio-locale": "2.1.2",
    ...
}
```

The following example demonstrates applying the `AG_STUDIO_LOCALE_DE` locale to Studio:

#### Localisation

```ts
import { AG_STUDIO_LOCALE_DE } from "ag-studio-locale";
import {
  AgReportState,
  AgStudioApi,
  AgStudioProperties,
  createStudio,
} from "ag-studio";

const initialState: AgReportState = {
  pages: [
    {
      id: "a",
      widgets: {
        "1": {
          type: "grid",
          dataMapping: {
            cols: [
              { id: "medals.country" },
              { id: "medals.sport" },
              { id: "medals.gold", aggregation: "sum" },
              { id: "medals.silver", aggregation: "sum" },
              { id: "medals.bronze", aggregation: "sum" },
              { id: "medals.total", aggregation: "sum" },
            ],
          },
        },
        "2": {
          type: "column-chart-grouped",
          dataMapping: {
            categoryKey: [{ id: "medals.country" }],
            valueKey: [
              { id: "medals.gold", aggregation: "sum" },
              { id: "medals.silver", aggregation: "sum" },
              { id: "medals.bronze", aggregation: "sum" },
            ],
            tooltipKey: [],
          },
        },
      },
      widgetLayout: {
        "1": {
          xTrack: 0,
          yTrack: 0,
          xSpan: 24,
          ySpan: 16,
        },
        "2": {
          xTrack: 0,
          yTrack: 16,
          xSpan: 24,
          ySpan: 16,
        },
      },
    },
  ],
  selectedPageId: "a",
  panels: {
    filters: {
      collapsed: true,
    },
  },
};

const studioProperties: AgStudioProperties = {
  mode: "edit",
  initialState,
  localeText: AG_STUDIO_LOCALE_DE,
};

let studioApi: AgStudioApi;

// setup Studio after the page has finished loading
const studioDiv = document.querySelector<HTMLElement>("#myStudio")!;
studioApi = createStudio(studioDiv, studioProperties);
fetch("https://www.ag-grid.com/studio/example-assets/olympic-winners.json")
  .then((response) => response.json())
  .then((data) =>
    studioApi!.setProperty("data", {
      sources: [{ id: "medals", data }],
    }),
  );
```

[Live example: Localisation](https://www.ag-grid.com/studio/examples/localisation/localisation/typescript/)

> **Note**
>
> Some localisation variables have `${variable}` in them. When this occurs, it means that part of the string will be replaced by a variable value.

## Customising a Provided Locale

If you want to customise a provided locale, you can do so by creating a new object and merging the provided locale with your customisations.

```
import { AG_STUDIO_LOCALE_DE } from 'ag-studio-locale';

const customGermanLocale = {
    ...AG_STUDIO_LOCALE_DE,
    // customise the locale here
};

const studioProperties = {
    localeText: customGermanLocale,
};
```

The example below shows this in action by adding a `"zzz-"` prefix to each Locale value to create a new `ZZZ_LOCALE` object, and then applying this customised locale to Studio:

#### Customised Localisation

```ts
import { AG_STUDIO_LOCALE_DE } from "ag-studio-locale";
import {
  AgReportState,
  AgStudioApi,
  AgStudioLocaleKey,
  AgStudioLocaleText,
  AgStudioProperties,
  createStudio,
} from "ag-studio";

const ZZZ_LOCALE = ((locale: AgStudioLocaleText) => {
  const modifiedLocale: AgStudioLocaleText = {};
  (Object.keys(locale) as AgStudioLocaleKey[]).forEach((key) => {
    modifiedLocale[key] = "zzz-" + locale[key];
  });
  return modifiedLocale;
})(AG_STUDIO_LOCALE_DE);

const initialState: AgReportState = {
  pages: [
    {
      id: "a",
      widgets: {
        "1": {
          type: "grid",
          dataMapping: {
            cols: [
              { id: "medals.country" },
              { id: "medals.sport" },
              { id: "medals.gold", aggregation: "sum" },
              { id: "medals.silver", aggregation: "sum" },
              { id: "medals.bronze", aggregation: "sum" },
              { id: "medals.total", aggregation: "sum" },
            ],
          },
        },
        "2": {
          type: "column-chart-grouped",
          dataMapping: {
            categoryKey: [{ id: "medals.country" }],
            valueKey: [
              { id: "medals.gold", aggregation: "sum" },
              { id: "medals.silver", aggregation: "sum" },
              { id: "medals.bronze", aggregation: "sum" },
            ],
            tooltipKey: [],
          },
        },
      },
      widgetLayout: {
        "1": {
          xTrack: 0,
          yTrack: 0,
          xSpan: 24,
          ySpan: 16,
        },
        "2": {
          xTrack: 0,
          yTrack: 16,
          xSpan: 24,
          ySpan: 16,
        },
      },
    },
  ],
  selectedPageId: "a",
  panels: {
    filters: {
      collapsed: true,
    },
  },
};

const studioProperties: AgStudioProperties = {
  mode: "edit",
  initialState,
  localeText: ZZZ_LOCALE,
};

let studioApi: AgStudioApi;

// setup Studio after the page has finished loading
const studioDiv = document.querySelector<HTMLElement>("#myStudio")!;
studioApi = createStudio(studioDiv, studioProperties);
fetch("https://www.ag-grid.com/studio/example-assets/olympic-winners.json")
  .then((response) => response.json())
  .then((data) =>
    studioApi!.setProperty("data", {
      sources: [{ id: "medals", data }],
    }),
  );
```

[Live example: Customised Localisation](https://www.ag-grid.com/studio/examples/localisation/custom-localisation/typescript/)

## Changing Locale

Studio uses the locale as it is needed. It does not refresh as the locale changes. If your application allows changing the locale for the application, you must destroy and recreate Studio for it to use the new locale.

## Creating a Locale

By default, Studio does not require a locale. If no locale is provided, Studio will default to English. If a locale is provided but is missing values, the default English will be used for the missing values.

To create a new locale, translate based off of one of the provided locales in `ag-studio-locale` (it is recommended to use `AG_STUDIO_LOCALE_EN`).

## Locale Callback

Providing a locale for Studio may not fit in with localisation libraries or localisation for a broader application. If you want Studio to take from an application-wide locale, then implement the `getLocaleText` callback to act as a bridge between Studio and the application's localisation.

The example below shows providing a callback for localisation. The example for simplicity just returns the default value in upper case. In a real world application, the callback would use the application's localisation.

#### Callback

```ts
import {
  AgReportState,
  AgStudioApi,
  AgStudioGetLocaleTextParams,
  AgStudioProperties,
  createStudio,
} from "ag-studio";

const initialState: AgReportState = {
  pages: [
    {
      id: "a",
      widgets: {
        "1": {
          type: "grid",
          dataMapping: {
            cols: [
              { id: "medals.country" },
              { id: "medals.sport" },
              { id: "medals.gold", aggregation: "sum" },
              { id: "medals.silver", aggregation: "sum" },
              { id: "medals.bronze", aggregation: "sum" },
              { id: "medals.total", aggregation: "sum" },
            ],
          },
        },
        "2": {
          type: "column-chart-grouped",
          dataMapping: {
            categoryKey: [{ id: "medals.country" }],
            valueKey: [
              { id: "medals.gold", aggregation: "sum" },
              { id: "medals.silver", aggregation: "sum" },
              { id: "medals.bronze", aggregation: "sum" },
            ],
            tooltipKey: [],
          },
        },
      },
      widgetLayout: {
        "1": {
          xTrack: 0,
          yTrack: 0,
          xSpan: 24,
          ySpan: 16,
        },
        "2": {
          xTrack: 0,
          yTrack: 16,
          xSpan: 24,
          ySpan: 16,
        },
      },
    },
  ],
  selectedPageId: "a",
  panels: {
    filters: {
      collapsed: true,
    },
  },
};

const studioProperties: AgStudioProperties = {
  mode: "edit",
  initialState,
  getLocaleText: (params: AgStudioGetLocaleTextParams) =>
    params.defaultValue.toLocaleUpperCase(),
};

let studioApi: AgStudioApi;

// setup Studio after the page has finished loading
const studioDiv = document.querySelector<HTMLElement>("#myStudio")!;
studioApi = createStudio(studioDiv, studioProperties);
fetch("https://www.ag-grid.com/studio/example-assets/olympic-winners.json")
  .then((response) => response.json())
  .then((data) =>
    studioApi!.setProperty("data", {
      sources: [{ id: "medals", data }],
    }),
  );
```

[Live example: Callback](https://www.ag-grid.com/studio/examples/localisation/callback/typescript/)

In a real world application, the callback would look something like this:

```js
const getLocaleText = (params) => {
    // to avoid key clash with external keys, we add 'studio' to the start of each key.
    const studioKey = 'studio.' + params.key;

    // look the value up using an application wide service
    return applicationLocaleService(studioKey);
}
```

## RTL Text Direction (Right to Left)

For languages that are displayed right to left, e.g. Hebrew and Arabic, the `enableRtl` property can be set to display in RTL format.

#### RTL

```ts
import { AG_STUDIO_LOCALE_EG } from "ag-studio-locale";
import {
  AgReportState,
  AgStudioApi,
  AgStudioProperties,
  createStudio,
} from "ag-studio";

const initialState: AgReportState = {
  pages: [
    {
      id: "a",
      widgets: {
        "1": {
          type: "grid",
          dataMapping: {
            cols: [
              { id: "medals.country" },
              { id: "medals.sport" },
              { id: "medals.gold", aggregation: "sum" },
              { id: "medals.silver", aggregation: "sum" },
              { id: "medals.bronze", aggregation: "sum" },
              { id: "medals.total", aggregation: "sum" },
            ],
          },
        },
        "2": {
          type: "column-chart-grouped",
          dataMapping: {
            categoryKey: [{ id: "medals.country" }],
            valueKey: [
              { id: "medals.gold", aggregation: "sum" },
              { id: "medals.silver", aggregation: "sum" },
              { id: "medals.bronze", aggregation: "sum" },
            ],
            tooltipKey: [],
          },
        },
      },
      widgetLayout: {
        "1": {
          xTrack: 0,
          yTrack: 0,
          xSpan: 24,
          ySpan: 16,
        },
        "2": {
          xTrack: 0,
          yTrack: 16,
          xSpan: 24,
          ySpan: 16,
        },
      },
    },
  ],
  selectedPageId: "a",
  panels: {
    filters: {
      collapsed: true,
    },
  },
};

const studioProperties: AgStudioProperties = {
  mode: "edit",
  initialState,
  localeText: AG_STUDIO_LOCALE_EG,
  enableRtl: true,
};

let studioApi: AgStudioApi;

// setup Studio after the page has finished loading
const studioDiv = document.querySelector<HTMLElement>("#myStudio")!;
studioApi = createStudio(studioDiv, studioProperties);
fetch("https://www.ag-grid.com/studio/example-assets/olympic-winners.json")
  .then((response) => response.json())
  .then((data) =>
    studioApi!.setProperty("data", {
      sources: [{ id: "medals", data }],
    }),
  );
```

[Live example: RTL](https://www.ag-grid.com/studio/examples/localisation/rtl/typescript/)