---
title: "Localisation"
framework: react
version: "14.1.0"
---

# Localisation

All the displayed text in AG Charts is customisable for the purposes of localisation.

> **Note**
>
> Localisation controls the language of chart UI text.  
> See [RTL Text & Layout](https://www.ag-grid.com/charts/react/rtl/) for RTL language support and layout mirroring.

This is done by providing locale information to charts for the required language. Either provide an object of key/value pairs via the `localeText` property, or provide a `getLocaleText` callback to hook charts up to your application's localisation.

We include a minimal internationalisation implementation and full set of American English translations, each of which can be replaced. The built-in internationalisation implementation is optimised for file size.

## Provided Locales

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

| Locale | BCP 47 Tag | Import name |
| --- | --- | --- |
| Arabic (Egyptian) | ar-EG | `AG_CHARTS_LOCALE_AR_EG` |
| Bulgarian | bg-BG | `AG_CHARTS_LOCALE_BG_BG` |
| Chinese (Hong Kong) | zh-HK | `AG_CHARTS_LOCALE_ZH_HK` |
| Chinese (Simplified) | zh-CN | `AG_CHARTS_LOCALE_ZH_CN` |
| Chinese (Taiwan) | zh-TW | `AG_CHARTS_LOCALE_ZH_TW` |
| Croatian | hr-HR | `AG_CHARTS_LOCALE_HR_HR` |
| Czech | cs-CZ | `AG_CHARTS_LOCALE_CS_CZ` |
| Danish | da-DK | `AG_CHARTS_LOCALE_DA_DK` |
| Dutch | nl-NL | `AG_CHARTS_LOCALE_NL_NL` |
| Finnish | fi-FI | `AG_CHARTS_LOCALE_FI_FI` |
| French | fr-FR | `AG_CHARTS_LOCALE_FR_FR` |
| German | de-DE | `AG_CHARTS_LOCALE_DE_DE` |
| Greek | el-GR | `AG_CHARTS_LOCALE_EL_GR` |
| Hebrew | he-IL | `AG_CHARTS_LOCALE_HE_IL` |
| Hungarian | hu-HU | `AG_CHARTS_LOCALE_HU_HU` |
| Italian | it-IT | `AG_CHARTS_LOCALE_IT_IT` |
| Japanese | ja-JP | `AG_CHARTS_LOCALE_JA_JP` |
| Korean | ko-KR | `AG_CHARTS_LOCALE_KO_KR` |
| Norwegian (Bokmål) | nb-NO | `AG_CHARTS_LOCALE_NB_NO` |
| Persian | fa-IR | `AG_CHARTS_LOCALE_FA_IR` |
| Polish | pl-PL | `AG_CHARTS_LOCALE_PL_PL` |
| Portuguese | pt-PT | `AG_CHARTS_LOCALE_PT_PT` |
| Portuguese (Brazil) | pt-BR | `AG_CHARTS_LOCALE_PT_BR` |
| Romanian | ro-RO | `AG_CHARTS_LOCALE_RO_RO` |
| Slovak | sk-SK | `AG_CHARTS_LOCALE_SK_SK` |
| Spanish | es-ES | `AG_CHARTS_LOCALE_ES_ES` |
| Swedish | sv-SE | `AG_CHARTS_LOCALE_SV_SE` |
| Turkish | tr-TR | `AG_CHARTS_LOCALE_TR_TR` |
| Ukrainian | uk-UA | `AG_CHARTS_LOCALE_UK_UA` |
| Urdu (Pakistan) | ur-PK | `AG_CHARTS_LOCALE_UR_PK` |
| Vietnamese | vi-VN | `AG_CHARTS_LOCALE_VI_VN` |

> **Warning**
>
> Translations are provided as a starting point and may contain errors. We recommend you audit these files before using them in production.

## Installing a Locale

To change the locale, set the `localeText` property in `locale` options to one of the built-in locales.

Each built-in locale is available from the `ag-charts-locale` package, with each export defined in the table above.

The locale `AG_CHARTS_LOCALE_EN_US` is also exported from `ag-charts-community`/`ag-charts-enterprise`.

#### Installing a Locale

```tsx
import React, { useState } from "react";
import { createRoot } from "react-dom/client";
import { AgCharts } from "ag-charts-react";
import {
  AgChartOptions,
  AnimationModule,
  CategoryAxisModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  LineSeriesModule,
  LocaleModule,
  ModuleRegistry,
  NumberAxisModule,
  ZoomModule,
} from "ag-charts-enterprise";
import { AG_CHARTS_LOCALE_FR_FR } from "ag-charts-locale";

ModuleRegistry.registerModules([
  AnimationModule,
  CategoryAxisModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  LineSeriesModule,
  LocaleModule,
  NumberAxisModule,
  ZoomModule,
]);

const ChartExample = () => {
  const [options, setOptions] = useState<AgChartOptions>({
    title: {
      text: "French Language",
    },
    subtitle: {
      text: "Hover zoom buttons for tooltips, right click to show context menu",
    },
    data: [
      { month: "Jan", avgTemp: 2.3, iceCreamSales: 162000 },
      { month: "Mar", avgTemp: 6.3, iceCreamSales: 302000 },
      { month: "May", avgTemp: 16.2, iceCreamSales: 800000 },
      { month: "Jul", avgTemp: 22.8, iceCreamSales: 1254000 },
      { month: "Sep", avgTemp: 14.5, iceCreamSales: 950000 },
      { month: "Nov", avgTemp: 8.9, iceCreamSales: 200000 },
    ],
    series: [
      {
        type: "line",
        xKey: "month",
        yKey: "iceCreamSales",
        yName: "Ice Cream Sales",
      },
    ],
    contextMenu: {
      enabled: true,
    },
    zoom: {
      enabled: true,
    },
    legend: {
      enabled: true,
    },
    locale: {
      localeText: AG_CHARTS_LOCALE_FR_FR,
    },
  });

  return <AgCharts options={options} />;
};

const root = createRoot(document.getElementById("root")!);
root.render(<ChartExample />);
```

[Live example: Installing a Locale](https://www.ag-grid.com/charts/reactFunctionalTs/localisation/examples/installing-locale)

```js
import { AG_CHARTS_LOCALE_FR_FR } from 'ag-charts-locale';

const options = {
    locale: {
        localeText: AG_CHARTS_LOCALE_FR_FR,
    },
};
```

In the above example:

- Hover over the zoom toolbar buttons to see the translated tooltips.
- Right click on the series area to see the translated context menu options.
- Click on the legend item to see the translated "no visible series" overlay.

If a locale is provided but is missing values, the default English values will be used for the missing values.

## Customising Text Values

Overrides for individual translations can be done by applying overrides to an existing locale.

#### Custom Text Values

```tsx
import React, { useState } from "react";
import { createRoot } from "react-dom/client";
import { AgCharts } from "ag-charts-react";
import {
  AG_CHARTS_LOCALE_EN_US,
  AgChartOptions,
  AnimationModule,
  CategoryAxisModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  LineSeriesModule,
  LocaleModule,
  ModuleRegistry,
  NumberAxisModule,
  ZoomModule,
} from "ag-charts-enterprise";

ModuleRegistry.registerModules([
  AnimationModule,
  CategoryAxisModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  LineSeriesModule,
  LocaleModule,
  NumberAxisModule,
  ZoomModule,
]);

const ChartExample = () => {
  const [options, setOptions] = useState<AgChartOptions>({
    title: {
      text: "Custom Context Menu Text",
    },
    subtitle: {
      text: "Hover zoom buttons for tooltips, right click to show context menu",
    },
    data: [
      { month: "Jan", avgTemp: 2.3, iceCreamSales: 162000 },
      { month: "Mar", avgTemp: 6.3, iceCreamSales: 302000 },
      { month: "May", avgTemp: 16.2, iceCreamSales: 800000 },
      { month: "Jul", avgTemp: 22.8, iceCreamSales: 1254000 },
      { month: "Sep", avgTemp: 14.5, iceCreamSales: 950000 },
      { month: "Nov", avgTemp: 8.9, iceCreamSales: 200000 },
    ],
    series: [{ type: "line", xKey: "month", yKey: "iceCreamSales" }],
    contextMenu: {
      enabled: true,
    },
    zoom: {
      enabled: true,
    },
    locale: {
      localeText: {
        ...AG_CHARTS_LOCALE_EN_US,
        toolbarZoomZoomOut: "Zoom Out of the Chart",
        toolbarZoomZoomIn: "Zoom In to the Chart",
        toolbarZoomPanLeft: "Pan the Chart Left",
        toolbarZoomPanRight: "Pan the Chart Right",
        toolbarZoomPanStart: "Pan the Chart to the Start",
        toolbarZoomPanEnd: "Pan the Chart to the End",
        toolbarZoomReset: "Reset the Chart's Zoom",
        contextMenuDownload: "Save this Chart to My Computer",
        contextMenuZoomToCursor: "Zoom the Chart to Your Cursor",
        contextMenuPanToCursor: "Pan the Chart to Your Cursor",
      },
    },
  });

  return <AgCharts options={options} />;
};

const root = createRoot(document.getElementById("root")!);
root.render(<ChartExample />);
```

[Live example: Custom Text Values](https://www.ag-grid.com/charts/reactFunctionalTs/localisation/examples/custom-text-values)

```js
{
    locale: {
        localeText: {
            ...AG_CHARTS_LOCALE_EN_US,
            toolbarZoomZoomOut: 'Zoom Out of the Chart',
            toolbarZoomZoomIn: 'Zoom In to the Chart',
            toolbarZoomPanLeft: 'Pan the Chart Left',
            toolbarZoomPanRight: 'Pan the Chart Right',
            toolbarZoomPanStart: 'Pan the Chart to the Start',
            toolbarZoomPanEnd: 'Pan the Chart to the End',
            toolbarZoomReset: "Reset the Chart's Zoom",
            contextMenuDownload: 'Save this Chart to My Computer',
            contextMenuZoomToCursor: 'Zoom the Chart to Your Cursor',
            contextMenuPanToCursor: 'Pan the Chart to Your Cursor',
        },
    },
}
```

In this configuration, `localeText` is a dictionary mapping translation keys to the translated text.

Some translations have parameters, which can be included in the translation using `'${value}'` syntax. Provided strings should not use backticks.

Values can be formatted by appending a format style in square brackets, like `'${value}[percent]'`. The available formatters are `[number]`, `[percent]`, `[date]`, `[time]`, and `[datetime]`.

```js
{
    locale: {
        localeText: {
            ...AG_CHARTS_LOCALE_EN_US,
            ariaAnnounceChart: 'chart with ${seriesCount} series',
            ariaValuePanRange: '${min}[percent] to ${max}[percent]',
        },
    },
}
```

Please see [All Built-In Translations](https://www.ag-grid.com/charts/react/localisation/#all-built-in-translations) for a full list of built-in translations.

## Using External Frameworks

You can integrate the internationalisation framework using the `getLocaleText` option within the `locale` options.

```js
{
    locale: {
        getLocaleText({ key, defaultValue, variables }) {
            return internationalisationFramework.getLocaleText({ key, defaultValue, variables });
        },
    },
}
```

If you return `undefined` from this function, it will fall back to the default behaviour of using `localeText` with the default formatter.

### Framework Integration Examples

#### React Intl

```tsx
import { IntlProvider, useIntl } from 'react-intl';

const messages = {
    contextMenuDownload: 'Téléchargez une copie de ce tableau',
};

const MyChart = () => {
    const intl = useIntl();

    const options = {
        // ...
        locale: {
            getLocaleText(params) {
                const { key, variables } = params;
                if (!intl.messages[key]) {
                    // Fallback to default behaviour for missing messages
                    return undefined;
                }
                return intl.formatMessage({ id: key }, variables);
            },
        },
    };

    return <AgCharts options={options} />;
};

const App = () => {
    return (
        <IntlProvider locale="fr-FR" messages={messages}>
            <MyChart />
        </IntlProvider>
    );
};
```

#### React I18Next

```tsx
import i18next from 'i18next';
import { initReactI18next, useTranslation } from 'react-i18next';

i18next.use(initReactI18next).init({
    lng: 'fr',
    resources: {
        fr: {
            translation: {
                contextMenuDownload: 'Téléchargez une copie de ce tableau',
            },
        },
    },
});

const MyChart = () => {
    const { i18n, t } = useTranslation();

    const options = {
        // ...
        locale: {
            getLocaleText(params) {
                const { key, variables } = params;
                if (!i18n.exists(key)) {
                    // Fallback to default behaviour for missing messages
                    return undefined;
                }
                return t(key, variables);
            },
        },
    };

    return <AgCharts options={options} />;
};
```

## API Reference

#### Locale

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| localeText | Record |  | A record of locale texts keyed by id. |
| getLocaleText | Formatter |  | Formatter that generates the text displayed to the user. |

## All Built-In Translations

[View snippet source: `en-US.esm.mjs`](https://www.ag-grid.com/charts/dev/ag-charts-locale/dist/package/en-US.esm.mjs)