---
title: "Localisation"
framework: angular
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/angular/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

```ts
// Angular entry point file
import '@angular/compiler';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component';

bootstrapApplication(AppComponent);
```

[Live example: Installing a Locale](https://www.ag-grid.com/charts/angular/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

```ts
// Angular entry point file
import '@angular/compiler';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component';

bootstrapApplication(AppComponent);
```

[Live example: Custom Text Values](https://www.ag-grid.com/charts/angular/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/angular/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.

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