React 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:

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 { 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({ key, variables }) {
                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>
    );
}

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

await 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({ key, variables }) {
                if (!i18n.exists(key)) {
                    // Fallback to default behaviour for missing messages
                    return undefined;
                }
                return t(key, variables);
            },
        },
    };

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

API Reference

All Built-In Translations