Localization ​

Localization (i18n) is the process of adapting a piece of content's full meaning for a new region, including translation, associated imagery, and cultural elements that influence how your content will be perceived. Zurich Design System considers the localization as one of the key features and provides all the necessary configurations and utils that could be required for localizing the base components of ZDS.

As a general rule, the WebComponents will be always more flexible and suitable for localization; encapsulating in many cases the necessary basic translations.

Locales ​

Locales are a way to specify the regional and language settings for software applications. They define various aspects such as date and time formats, number formats, currency symbols, and language translations. They allow developers to adapt their applications to different regions and languages, providing a more user-friendly experience for users around the world.

Locales are defined using a ISO 639 alpha-2 language code that can be followed by an ISO 3166-1 alpha-2 country code, separated by a hyphen. An example, en would be English, and en-US would be English for United States.

The currently supported languages and locales are:

  • ar - Arabic
  • ca - Catalan/Valencian
  • da - Danish
  • de - German
  • en - English
  • en-UK - English (UK)
  • en-US - English (US)
  • es - Spanish
  • eu - Basque
  • fr - French
  • gl - Galician
  • hi - Hindu
  • id - Indonesian
  • it - Italian
  • jp - Japanese
  • ko - Korean
  • nl - Dutch
  • pl - Polish
  • pt - Portuguese
  • ta - Tamil
  • th - Thai
  • ur - Urdu
  • vi - Vietnamese
  • zh - Chinese

Missing locales

if you don't find a locale that you require, please contact the ZDS team for us to add it.

This list of locales is available in:

ts
import { LOCALES } from "@zurich/dev-utils/code";

The acquisition chain (from more relevant to least) on the locale value is:

  • The instance locale attribute.
  • The lang attribute of the <html> tag.
  • The navigator.language value.

Intl API ​

JavaScript has a built-in Intl object that might be really helpful for cases that are out of the scope of the components like lists or pluralizations.

An example:

ts
function localizeDogs (amount: number) {
  if (!amount) return 'No dogs';
  return new Intl.PluralRules('en').select(amount) === 'one' ? 'A dog' : `${amount} dogs`;
}

localizeDogs(0);   // 'No dogs'
localizeDogs(1);   // 'A dog'
localizeDogs(15);  // '15 dogs'

Localization and WebComponents ​

Most WebComponents have proposed translations for the different localizations if the component includes default texts. But this translations need to ve loaded in the frontend in order to be used. They are available as part of the @zurich/dev-utils as @zurich/dev-utils/locales and then importing the locale code (in snake_case) or under @zurich/dev-utils/locales/<code> exported as LOCALES.

ts
import { LOCALES } from '@zurich/dev-utils/locales/en-US'
import { es, en_US } from '@zurich/dev-utils/locales'

Locales fallback

All WebComponent will have en as locale fallback

These locales need to be added to the window.ZDS_LOCALES object (to be created when the operation is done) using kebab-case for the key:

ts
import { es, en_US } from '@zurich/dev-utils/locales'

window.ZDS_LOCALES = {
  es,
  'en-US': en_US,
}

If you want to add types:

ts
import type { Locale } from '@zurich/dev-utils/code';
import type { LocalesMap } from '@zurich/dev-utils/locales';

declare global {
  interface Window {
    ZDS_LOCALES: Partial<Record<Locale, LocalesMap>>;
  }
}

Custom texts ​

If you want to customize the localization texts, you cna do it globally overriding keys in the maps provided:

ts
import { es } from '@zurich/dev-utils/locales'

window.ZDS_LOCALES = {
  es: { ...es, today: 'Ahorita mismo' },
}

But each instance admits also its own text via property or slot:

Escogido

Localized display ​

We offer some WebComponent that help you with the localization:

  • Number. Used for numbers, and it can include physical units.
  • Date Used for date or times in the future or the past. It can show the current date too
  • Time Used for day time formats. It can be used to verbalize relative time to the current one. It can show the current time too (not dynamic).

Localized inputs ​

The are some inputs that might be affected for the localization. These are basically the ones related to date, time and numbers. This localization is done by the native <input> element by using the user's OS' or Browser's localization settings. This is done in order to accommodate the input of data to the final user's preferences. Here's the explanation of the standard about the topic and the reasoning for this to be a desirable behavior.

With that said, some of our WebComponents offer the possibility of forcing the localization with some tradeoffs (like not being capable of using the numerical manipulation and having to use the date picker).

Attention!

We recommend not to use force localization for inputs for many reasons. So even when we offer the possibility for satisfying possible use cases, we strongly encourage you to think about the real need of forcing the localization.

NumberInput ​

We won't localize the NumberInput because of the incompatibilities that this can cause. locale will only affect here the units display.

DateInput ​

We can check this in DateInput:

This approach doesn't affect the model, but only the display. In Arab, the numeric representation is different:

There are cases that the whole system might be weird:

In Thailand they use the year zero as the year in which the Buddha attained parinibbāna. That's why, in this situation, we need todo a value conversion to other localizations.

The locale will apply to the Calendar too if custom-ui is used (or the system one). Notice how the names of the weekdays and the months are adjusted:

TimeInput ​

Also for TimeInput, where in this case, localization only makes sense for the 12h format:

Even with seconds:

The localization, in the vast majority of cases, makes only sense if you want to represent a 12h format. Otherwise, the re presentation doesn't change.

Select ​

In case of using with-search, the texts will use the given locale (or the system one):

Calendar ​

Uses the provided locale or the one detected to adjust the names of the months and week days, but also some translations used for navigation:

The first-weekday can also be adjusted.

VerticalStepper ​

Uses the provided locale or the one detected:

FileInput ​

...