Javascript ChartsLocalisation

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

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:

LocaleBCP 47 TagImport name
Arabic (Egyptian)ar-EGAG_CHARTS_LOCALE_AR_EG
Bulgarianbg-BGAG_CHARTS_LOCALE_BG_BG
Chinese (Hong Kong)zh-HKAG_CHARTS_LOCALE_ZH_HK
Chinese (Simplified)zh-CNAG_CHARTS_LOCALE_ZH_CN
Chinese (Taiwan)zh-TWAG_CHARTS_LOCALE_ZH_TW
Croatianhr-HRAG_CHARTS_LOCALE_HR_HR
Czechcs-CZAG_CHARTS_LOCALE_CS_CZ
Danishda-DKAG_CHARTS_LOCALE_DA_DK
Dutchnl-NLAG_CHARTS_LOCALE_NL_NL
Finnishfi-FIAG_CHARTS_LOCALE_FI_FI
Frenchfr-FRAG_CHARTS_LOCALE_FR_FR
Germande-DEAG_CHARTS_LOCALE_DE_DE
Greekel-GRAG_CHARTS_LOCALE_EL_GR
Hebrewhe-ILAG_CHARTS_LOCALE_HE_IL
Hungarianhu-HUAG_CHARTS_LOCALE_HU_HU
Italianit-ITAG_CHARTS_LOCALE_IT_IT
Japaneseja-JPAG_CHARTS_LOCALE_JA_JP
Koreanko-KRAG_CHARTS_LOCALE_KO_KR
Norwegian (Bokmål)nb-NOAG_CHARTS_LOCALE_NB_NO
Persianfa-IRAG_CHARTS_LOCALE_FA_IR
Polishpl-PLAG_CHARTS_LOCALE_PL_PL
Portuguesept-PTAG_CHARTS_LOCALE_PT_PT
Portuguese (Brazil)pt-BRAG_CHARTS_LOCALE_PT_BR
Romanianro-ROAG_CHARTS_LOCALE_RO_RO
Slovaksk-SKAG_CHARTS_LOCALE_SK_SK
Spanishes-ESAG_CHARTS_LOCALE_ES_ES
Swedishsv-SEAG_CHARTS_LOCALE_SV_SE
Turkishtr-TRAG_CHARTS_LOCALE_TR_TR
Ukrainianuk-UAAG_CHARTS_LOCALE_UK_UA
Urdu (Pakistan)ur-PKAG_CHARTS_LOCALE_UR_PK
Vietnamesevi-VNAG_CHARTS_LOCALE_VI_VN

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.

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

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

{
    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].

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

Please see 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.

{
    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

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);
        },
    },
});
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

All Built-In Translations