import { Meta, Subtitle } from '@storybook/blocks';

Localization

Localization is the process of adapting software to different languages and regional differences. It involves translating text, adjusting layouts, and adapting cultural elements to meet the needs of users in various locales. Effective localization ensures that your application is accessible and user-friendly across different regions and languages.

Our component library is designed with localization in mind, allowing you to easily create multilingual applications. By separating the text content from the component structure, we enable seamless integration of translations without altering the core functionality of the components.

Localization not only involves translating text but also adapting to regional formatting conventions, such as date and number formats. Our localized components handle these variations automatically, ensuring a consistent user experience across different locales.

How Does It Work?

We've chosen to implement localization using i18next and react-i18next. This decision was made to facilitate easy integration with applications that already use this popular localization infrastructure.

i18next provides a robust framework for managing translations, while react-i18next offers React-specific bindings that make it simple to use localized content within our components. This approach allows for dynamic language switching and efficient management of translation resources.

String interpolation

Our localization system utilizes the ICU (International Components for Unicode) Message Format instead of the default i18next syntax for string interpolation and pluralization. This format provides a more powerful and standardized way to handle complex localization scenarios.

What is ICU Message Format?

ICU Message Format is a standardized localization format used widely in software internationalization. It allows for sophisticated string formatting, including pluralization, gender, and selectional mechanisms. This format is more expressive than simple key-value pairs and can handle a wide variety of linguistic rules across different languages.

How It Works

ICU Message Format uses placeholders and formatting instructions within curly braces {}. These placeholders can be simple variables, or they can include formatting options for numbers, dates, and pluralization.

Syntax Examples

Basic String Interpolation

To insert a variable into a string, use the variable name within curly braces:

"Hello, {name}!"

When providing the translation, you would use:

{
  "greeting": "Hello, {name}!"
}

And in your code:

t('greeting', { name: 'Alice' });

This would result in: "Hello, Alice!"

Pluralization

For pluralization, use the plural keyword followed by the variable and the different forms:

"{count, plural, =0 {No items} one {{count} item} other {{count} items}}"

In your translation file:

{
  "itemCount": "{count, plural, =0 {No items} one {{count} item} other {{count} items}}"
}

In your code:

t('itemCount', { count: 0 }); // "No items"
t('itemCount', { count: 1 }); // "1 item"
t('itemCount', { count: 5 }); // "5 items"

Integration into Existing Apps

Integrating our localized components into your existing application is straightforward. Here are the steps:

Import available translations from the component library:

import enUsLang from '@securityscorecars/design-system/locales/en-US';

If your preferred language is not available, you can create your own translations following the same structure.

Provide the imported or created resources to your i18next configuration under the sscds namespace. Here's a simple example:

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import enUsLang from '@securityscorecars/design-system/locales/en-US';

i18n.use(initReactI18next).init({
  resources: {
    en: {
      sscds: enUsLang,
    },
  },
  lng: 'en',
  fallbackLng: 'en',
  nsSeparator: '|',
  interpolation: {
    escapeValue: false,
  },
});

The Design System localization expects to use | as the namespace separator to prevent accidental clash with the existing keys containing the : character.

By following these steps, your application will be set up to use the localized versions of our components. The components will automatically use the translations provided under the sscds namespace, allowing for seamless integration of multiple languages in your user interface.

Available languages

en-US - The default language
ja-JP - Japanese (日本語)
es-ES - Spanish
pt-BR - Brazilian Portuguese
cs-CZ - Czech

FilesExpand file tree

localization.mdx

Latest commit

History