Localization

Calcite Design System's components provide localization, meaning their language can be adapted to a specific language market or country and its culture. Support includes changing the display language, regional formatting, differing numbering systems, and right-to-left (RTL) bidirectional content.

Languages

Internationalization enables you to create solutions by translating strings extracted from source code and providing it to translators. The result is providing behavior and text in line with a specified language, region, and culture.

You can also override the provided strings using the messageOverrides property for supported components, such as Chip.

Use dark colors for code blocksCopy
1
document.querySelector("calcite-chip").messageOverrides = { dismissLabel: "Remove" };

The lang attribute

In Calcite Design System the lang attribute is used for two main localization purposes. When you set the lang in your application to a Calcite supported language

  1. The component's strings will translate to the specified language, and
  2. Date, time, and number formats will be localized, when applicable

The lang attribute is also necessary to support accessibility, and in particular, assistive technologies.

The lang attribute inheritance

An element inherits language in the following sequence, where lang is set on:

  • The element itself
  • The element's closest parent element
  • The html tag

If a language is defined and is not supported by Calcite, the component's default language will be set to English, where lang="en". To dynamically set the language to the user's browser settings, you can set the HTMLElement.lang.

Components with regional formatting

Some components such as Input Date Picker contain specific localization for desired language and country formats.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
<!-- Sets the component's lang to English -->
<!-- Dates are formatted MM/DD/YYYY -->
<calcite-input-date-picker lang="en"></calcite-input-date-picker>

<!-- Sets the component's lang to English - Canada -->
<!-- Dates are formatted YYYY-MM-DD -->
<calcite-input-date-picker lang="en-CA"></calcite-input-date-picker>

<!-- Sets the component's lang to English - UK -->
<!-- Dates are formatted DD/MM/YYYY -->
<calcite-input-date-picker lang="en-GB"></calcite-input-date-picker>

In cases were a lang is not set on a component, the html's lang value will represent the default language on the component. In the following example, the component will be interpreted in French.

Use dark colors for code blocksCopy
1
2
3
<html lang="fr">
  <calcite-input-date-picker></calcite-input-date-picker>
</html>

The following components use the lang attribute for date, time, and numbering formatting:

Types for different languages

Internationalization and typography is very dynamic, and Calcite has this in mind with font types for different languages.

Calcite supported languages

  • Arabic (ar)
  • Bosnian (bs)
  • Bulgarian (bg)
  • Catalan (ca)
  • Chinese Simplified (zh-CN)
  • Chinese Traditional - Hong Kong (zh-HK)
  • Chinese Traditional - Taiwan (zh-TW)
  • Croatian (hr)
  • Czech (cs)
  • Danish (da)
  • Dutch (nl)
  • English (en)
  • English - Australia (en-AU)*
  • English - Canada (en-CA)*
  • English - United Kingdom (en-GB)*
  • Estonian (et)
  • Finnish (fi)
  • French (fr)
  • French - Switzerland (fr-CH)*
  • German (de)
  • German - Austria (de-AT)*
  • German - Switzerland (de-CH)*
  • Greek (el)
  • Hebrew (he)
  • Hindi (hi)†
  • Hungarian (hu)
  • Indonesian (id)
  • Italian (it)
  • Italian - Switzerland (it-CH)*
  • Japanese (ja)
  • Korean (ko)
  • Latvian (lv)
  • Lithuanian (lt)
  • Macedonian (mk)†
  • Norwegian (nb)
  • Polish (pl)
  • Portuguese (pt)
  • Portuguese - Portugal (pt-PT)
  • Romanian (ro)
  • Russian (ru)
  • Serbian (sr)
  • Slovak (sk)
  • Slovenian (sl)
  • Spanish (es)
  • Spanish - Mexico (es-MX)*
  • Swedish (sv)
  • Thai (th)
  • Turkish (tr)
  • Ukrainian (uk)
  • Vietnamese (vi)

* The language subtag will be used for string translations. For instance, the language subtag of "es-MX" is "es".

† String translations are not available.

Numbering system

A numbering system conveys numbers using digits or symbols in a consistent format, which can be coordinated with the lang attribute.

To resolve browser inconsistencies, the numbering system for Arabic languages is set to Latin digits, or latn by default. You can change the default value by setting the numberingSystem property to a standard Unicode numeral system.

Use dark colors for code blocksCopy
1
<calcite-input numbering-system="arab" type="number" value="10"></calcite-input>

Explore the MDN documentation to learn more on the numberingSystem property.

Calcite supported numbering systems

  • All supported languages
    • Latin digits (latn)
  • Arabic language (ar)
    • Latin digits (latn), default
    • Arabic-Indic digits (arab)
    • Extended Arabic-Indic digits (arabext)

Components with numbering system

Right-to-left (RTL)

Calcite Components also provide bidirectional support for languages such as Arabic and Hebrew. To change the direction, set the dir attribute to rtl to the component, or in the <html> or <body> tag.

Use dark colors for code blocksCopy
1
<calcite-color-picker dir="rtl"></calcite-color-picker>
Use dark colors for code blocksCopy
1
<html dir="rtl"></html>
Left-to-right (LTR)Right-to-left (RTL)
Map with Calcite Components left-to-right Map with Calcite Components right-to-left

Mirroring icons

Icon and icons in other components can be mirrored for RTL, such as left and right icons used for navigation.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
<!-- Flip the Icon's element direction with flipRtl -->
<calcite-icon flip-rtl icon="arrow-bold-left"></calcite-icon>

<!-- Components with one icon pass iconFlipRtl as a boolean -->
<calcite-chip icon-flip-rtl icon="arrow-bold-left"></calcite-chip>

<!-- Components with multiple icons pass a string value to iconFlipRtl to flip one or both icons -->
<calcite-button icon-start="arrow-bold-left" icon-flip-rtl="start" icon-end="app-update" label="Return"></calcite-button>

Icons should be mirrored for:

  • Navigation arrows
  • Forward movement, such as running
  • Slider movements for volume controls

However, icons should not be mirrored for:

  • Logos or branding
  • Clocks and circular directions of time, such as refresh

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.