JavaScript Data GridLocalisation

The grid's displayed text can be customised for localisation. You can achieve this by providing locale information in the required language. Use the localeText property to apply one of the provided locales, create a custom locale, or use the getLocaleText callback to integrate the grid with your application's localisation system.

Provided Locales

The default language of the grid is American English, however, we provide a number of translations that can be used as a starting point for commonly requested languages:

Using a Provided Locale Module

All of the provided locales listed above are available in the @ag-grid-community/locale package. To use any of the provided locales in your application, follow these steps:

First, import the desired locale module from the @ag-grid-community/locale package. For example, to use the German locale, import AG_GRID_LOCALE_DE:

import { AG_GRID_LOCALE_DE } from '@ag-grid-community/locale';

Next, assign the imported locale object to the localeText property in your Grid Options:

const gridOptions = {
    localeText: AG_GRID_LOCALE_DE,

    // other grid options ...
}

Finally, ensure the @ag-grid-community/locale module is listed as a dependency in your application's package configuration:

"dependencies": {
    "@ag-grid-community/locale": "~33.0.1-beta.20241221.1523",
    ...
}

The following example demonstrates applying the AG_GRID_LOCALE_DE locale to the grid:

Customising a Provided Locale

If you want to customise a provided locale, you can do so by creating a new object and merging the provided locale with your customisations.

import { AG_GRID_LOCALE_DE } from '@ag-grid-community/locale';

const customGermanLocale = {
    ...AG_GRID_LOCALE_DE,
    // customise the locale here
};

const gridOptions = {
    localeText: customGermanLocale,
};

The example below shows this in action by adding a "zzz" prefix to each Locale key to create a new zzzLocale object, and then applying this customised locale to the grid:

Changing Locale

The grid uses the locale as it is needed. It does not refresh as the locale changes. If your application allows changing the locale for the application, you must destroy and recreate the grid for it to use the new locale.

Creating a Locale

By default, the grid does not require a locale. If no locale is provided, the grid will default to English. If a locale is provided but is missing values, the default English will be used for the missing values.

All locales provided are listed above, and are also available in the @ag-grid-community/locale package.

To support other languages, the first step is to import the @ag-grid-community/locale package and reference the locale you're interested in.

There is a single locale file which covers all modules across all of AG Grid Enterprise and AG Grid Community. This was done on purpose as having a separate localisation file for each module would be harder to manage.

Locale Callback

Providing a locale for the grid does not fit in with localisation libraries or localisation for a broader application. If you want the grid to take from an application wide locale, then implement the getLocaleText to act as a bridge between the grid and the applications localisation.

The example below shows providing a callback for the grid's localisation. The example for simplicity just returns the default value in upper case. In a real world application, the callback would use the applications localisation.

In a real world application, the callback would look something like this:

const getLocaleText = (params) => {
    // to avoid key clash with external keys, we add 'grid' to the start of each key.
    const gridKey = 'grid.' + params.key;

    // look the value up using an application wide service
    return applicationLocaleService(gridKey);
}