--- title: "Localisation" framework: javascript 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/javascript/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 import { AgChartOptions, AgCharts, 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 options: 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, }, }; options.container = document.getElementById("myChart"); const chart = AgCharts.create(options); ``` [Live example: Installing a Locale](https://www.ag-grid.com/charts/typescript/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 import { AG_CHARTS_LOCALE_EN_US, AgChartOptions, AgCharts, 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 options: 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", }, }, }; options.container = document.getElementById("myChart"); const chart = AgCharts.create(options); ``` [Live example: Custom Text Values](https://www.ag-grid.com/charts/typescript/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/javascript/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 #### FormatJS ```js import { createIntl } from '@formatjs/intl'; const intl = createIntl({ locale: 'fr-FR', messages: { contextMenuDownload: 'Téléchargez une copie de ce tableau', }, }); AgCharts.create({ // ... locale: { getLocaleText({ key, variables }) { if (!intl.messages[key]) { // Fallback to default behaviour for missing messages return undefined; } return intl.formatMessage({ id: key }, variables); }, }, }); ``` #### I18Next ```js import i18next from 'i18next'; await i18next.init({ lng: 'fr', resources: { fr: { translation: { contextMenuDownload: 'Téléchargez une copie de ce tableau', }, }, }, }); AgCharts.create({ // ... locale: { getLocaleText({ key, variables }) { if (!i18next.exists(key)) { // Fallback to default behaviour for missing messages return undefined; } return i18next.t(key, variables); }, }, }); ``` ## 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)