Locales

Locales in amCharts 4 are used to apply translations to common prompts, as well as national settings, like number and date formats.

Using locales

By default, all charts and objects are created using a so called International English.

Loading a locale

Before a locale can be used, it needs to be loaded, just like any other resource:

// ... other imports
import am4lang_en_US from "@amcharts/amcharts4/lang/en_US";

<!-- other includes -->
<script src="//www.amcharts.com/lib/4/lang/en_US.js"></script>

NOTE In JavaScript, when you load a locale, it will be accessible in handy am4lang_[locale] object. In TypeScript, you can name imported locale whatever you want, but for the sake of this article (and anywhere else in our documentation), we're going to use the same naming convention, e.g. am4lang_en_US.

Setting a locale

Each object in amCharts 4 universe has a property language. It's an instance of the Language class, which is responsible for translating stuff to whatever locale you have set for your chart. (if it's other than International English)

So that Language knows which locale to use, it has a property, predictably named locale, which you can set to a locale reference we've already checked how to load.

chart.language.locale = am4lang_en_US;

chart.language.locale = am4lang_en_US;

{
  // ...
  "language": {
    "locale": "en_US"
  }
}

Using multiple locales

Same chart can use different locales for different purposes.

For example, you might want to use English prompts (default locale) but German number and date formats.

That is easy, since virtually any object is not restricted to using chart's global language object. It can have it's own.

This means that we can set separate Language instances with different locales for our number and date formatters:

chart.language.locale = am4lang_en_US;
chart.numberFormatter.language = new am4core.Language();
chart.numberFormatter.language.locale = am4lang_de_DE;
chart.dateFormatter.language = new am4core.Language();
chart.dateFormatter.language.locale = am4lang_de_DE;

chart.language.locale = am4lang_en_US;
chart.numberFormatter.language = new am4core.Language();
chart.numberFormatter.language.locale = am4lang_de_DE;
chart.dateFormatter.language = new am4core.Language();
chart.dateFormatter.language.locale = am4lang_de_DE;

{
  // ...
  "language": {
    "locale": "en_US"
  },
  "numberFormatter": {
    "language": {
      "type": "Language",
      "locale": "de_DE"
    }
  },
  "dateFormatter": {
    "language": {
      "type": "Language",
      "locale": "de_DE"
    }
  }
}

US English

It's worth mentioning a special bundled locale "en_US". While it does not add any new prompt translations, it overrides default international number and date formats with the ones commonly used in the United States.

Bundled locales

There are a number for locales bundled with amCharts 4. Check this link for a list of available locale files.

Creating and updating locales

Please refer to the tutorial "Creating Locales" for in-depth information on how to updated existing locales as well as create and contribute new ones.

Overriding formats

Each locale brings not only prompt translations, but also technical stuff, like date and number formats.

For example, default date format in International English is "Jan 1", while if you set your locale to, say, German, that default changes to "01. Jan".

While in most cases it's OK, sometimes language and formatting locales might differ. In some UIs user might prefer using English prompts, but German date formats, and vice versa.

One option would be to create a separate locale just for dates, as it is described in the previous chapter.

Another - much simpler one - is to override certain elements of the current locale.

Dates

This can be done easily by accessing chart.language.locale ant setting specific keys. E.g.:

chart.language.locale["_date_millisecond"] = "mm:ss SSS";
chart.language.locale["_date_second"] = "HH:mm:ss";
chart.language.locale["_date_minute"] = "HH:mm";
chart.language.locale["_date_hour"] = "HH:mm";
chart.language.locale["_date_day"] = "MM/dd";
chart.language.locale["_date_week"] = "ww";
chart.language.locale["_date_month"] = "MMM";
chart.language.locale["_date_year"] = "yyyy";

chart.language.locale["_date_millisecond"] = "mm:ss SSS";
chart.language.locale["_date_second"] = "HH:mm:ss";
chart.language.locale["_date_minute"] = "HH:mm";
chart.language.locale["_date_hour"] = "HH:mm";
chart.language.locale["_date_day"] = "MM/dd";
chart.language.locale["_date_week"] = "ww";
chart.language.locale["_date_month"] = "MMM";
chart.language.locale["_date_year"] = "yyyy";

{
  // ...
  "language": {
    "locale": {
      "_date_millisecond": "mm:ss SSS",
      "_date_second": "HH:mm:ss",
      "_date_minute": "HH:mm",
      "_date_hour": "HH:mm",
      "_date_day": "MM/dd",
      "_date_week": "ww",
      "_date_month": "MMM",
      "_date_year": "yyyy"
    }
  }
}

See the Pen VNYaBv by amCharts team (@amcharts) on CodePen.

Numbers

This works for number formatting as well, where you can override decimal and thousand separator:

chart.language.locale["_decimalSeparator"] = ",";
chart.language.locale["_thousandSeparator"] = " "; 

chart.language.locale["_decimalSeparator"] = ",";
chart.language.locale["_thousandSeparator"] = " "; 

{
  // ...
  "language": {
    "locale": {
      "_decimalSeparator": ",",
      "_thousandSeparator": " "
    }
  }
}