Switching the Localisation Language in AG Charts

AG Charts, our JavaScript Charting Library, is used worldwide. Localisation, therefore, is an important topic.

In this blog, we'll show you how to:

• Switch the localisation of AG Charts to one of 31 supported languages
• Customise the values of a locale
• Localise your chart titles, labels, tooltips, and other text elements
• Integrate AG Charts into your broader application's localisation functionality

To skip straight to the AG Charts documentation on localisation, select your framework:

Sample App

To demonstrate the different localisation features available, we've created a React Chart that lets you dynamically change the locale of the chart by selecting a language from the dropdown. You can also customise the value of any key in the locale by selecting a key and changing its value in the text box:

A Closer Look at Locales

AG Charts provides a set of localisation files that contain translations for chart strings in 31 languages. These locales are available in the ag-charts-locale package.

Each locale file is a simple list of key-value pairs—the key identifies where the string is used within the chart, and the value is what is displayed to the user. For example, here's a snippet from the default English (US) locale:

export const AG_CHARTS_LOCALE_EN_US: Record<string, string> = {
  // Screen reader announcement when focusing an item in the chart
  ariaAnnounceHoverDatum: '${datum}',
  // Screen reader announcement when focusing a chart
  ariaAnnounceChart: 'chart, ${seriesCount}[number] series',
  // Screen reader announcement when focusing a hierarchy chart
  ariaAnnounceHierarchyChart: 'hierarchy chart, ${caption}',
  // Screen reader announcement when focusing a gauge chart
  ariaAnnounceGaugeChart: 'gauge chart, ${caption}',
  ...
}

Each locale contains the same keys, but the values are translated into the relevant language. For example, here's the same snippet from the German locale file:

export const AG_CHARTS_LOCALE_DE_DE: Record<string, string> = {
  ariaAnnounceChart: 'Diagramm, ${seriesCount}[number] Reihen',
  ariaAnnounceFlowProportionLink: 'Link ${index} von ${count}, von ${from} bis ${to}, ${sizeName} ${size}',
  ariaAnnounceFlowProportionNode: 'Knoten ${index} von ${count}, ${description}',
  ariaAnnounceGaugeChart: 'Tachometerdiagramm, ${caption}',
  ...
}

Our GitHub repository contains all the localisation files available within the ag-charts-locale package.

Setting the Locale of Your Chart

With the localisation module, choosing a locale for your chart is as simple as importing your chosen translation and applying it via the locale chart option.

First, install the ag-charts-locale package:

npm install ag-charts-locale

Then, import the desired locale and apply it to your chart:

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

const options = {
  // ...other chart options
  locale: {
    localeText: AG_CHARTS_LOCALE_DE_DE,
  },
};

return <AgCharts options={options} />;

Customising a Locale

To customise a provided locale, you can create a new object and merge the provided locale with your customisations. For example, to modify the toolbarZoomZoomOut key:

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

const customGermanLocale = {
  ...AG_CHARTS_LOCALE_DE_DE,
  toolbarZoomZoomOut: 'Some Custom Value',
  // Customise other keys as needed
};

const options = {
  // ...other chart options
  locale: {
    localeText: customGermanLocale,
  },
};

return <AgCharts options={options} />;

In this example, we're:

• Creating a new customGermanLocale object to hold our customisations.
• Copying the AG_CHARTS_LOCALE_DE_DE object into customGermanLocale using the spread operator.
• Overriding the toolbarZoomZoomOut key with a custom value.
• Setting the locale.localeText chart option to use the new customGermanLocale.

Additionally, some translations have parameters, which can be included in the translation using '${value}' syntax:

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

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

Localising Titles, Labels, and Tooltips

You'll need to provide your own translations to localise your chart's titles, labels, and tooltips. We achieve this in our demo by:

• Creating a translations dictionary with the translations for our data (e.g., the chart titles, axis labels, tooltip content, etc..).
• Using the translation dictionary to set the chart's title, subtitle, series, and axes options dynamically based on the selected language.

Here's how the translations object looks:

// translations.js
export const translations = {
  English: {
    title: 'Revenue by Industry',
    subtitle: 'Actual vs Target',
    currency: '$',
    target: 'Target Revenue',
    actual: 'Actual Revenue',
    technology: 'Technology',
    healthcare: 'Healthcare',
    energy: 'Energy',
    // ...other translations
  },
  German: {
    title: 'Umsatz nach Branche',
    subtitle: 'Ist vs. Ziel',
    currency: '€',
    target: 'Zielumsatz',
    actual: 'Ist-Umsatz',
    technology: 'Technologie',
    healthcare: 'Gesundheitswesen',
    energy: 'Energie',
    // ...other translations
  },
  // ...other languages
};

In our chart options, we can then lookup the translation for any given language, and apply these via the title.text, subtitle.text, series.yName and axes.label.formatter properties, etc...:

const options = {
  data: getData(),
  title: {
    text: translations[language].title,
  },
  subtitle: {
    text: translations[language].subtitle,
  },
  series: [
    {
      type: 'area',
      xKey: 'industry',
      yKey: 'targetRevenue',
      yName: translations[language].target,
    },
    {
      type: 'area',
      xKey: 'industry',
      yKey: 'actualRevenue',
      yName: translations[language].actual,
    },
  ],
  axes: [
    {
      type: 'category',
      position: 'bottom',
      label: {
        rotation: -90,
        formatter: (params) =>
          translations[language][params.value.toLowerCase()] || params.value,
      },
    },
    // ...other axes
  ],
  // ...other options
};

This ensures that the chart titles, axis labels, series names, and other text elements display the correct translations based on the selected language.

Updating Locales Dynamically

To update the locale of your chart dynamically, all you need to do is mutate the options property - the chart will automatically detect any changes and apply them for you:

const [options, setOptions] = useState({...})

setOptions((prev) => ({
  ...prev,
  locale: {
    localeText: locale,
  },
}));

return <AgCharts options={options} />;

Integrating AG Charts into Your App's Localisation

If you want the chart to use your application's localisation system, you can integrate it 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.

For example, integrating into the React Intl library might look something like this:

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

In this snippet, we're using the getLocaleText callback to look up translations within the Intl framework for each key within our Locale. If the key does not exist, we return undefined to use the default value instead.

Implementing Localisation in AG Charts v9.3 and Earlier

The localisation package does not exist in AG Charts 9.3 and earlier, which means that you'll need to create your own translations. To help speed this up, you can manually copy the localisations you need from our GitHub and add these directly to your application.

Bear in mind, some keys may have been removed/added/changed in your version, so you'll need to thoroughly test your application to ensure all the translations are present.

Conclusion

It's easy to build localised charts with AG Charts; simply import the Locale(s) you want to use, and set them via the chartOptions.locale property. All of our examples were based on React, but the core principles are framework-agnostic.

If you would like to start adding JavaScript Charts to your application, you can get started for free: