@vtex/i18n-iso

<p align="center"> <img alt="i18n-iso logo" src="assets/vtex-logo.svg" height="200" /> <h3 align="center">@vtex/i18n-iso</h3> <p align="center">Flexible, future proof and easy to use localization library based on the ISO language set standards</p> <

Usage no npm install needed!

<script type="module">
  import vtexI18nIso from 'https://cdn.skypack.dev/@vtex/i18n-iso';
</script>

README

i18n-iso logo

@vtex/i18n-iso

Flexible, future proof and easy to use localization library based on the ISO language set standards

Installation

yarn add @vtex/i18n-iso

npm i @vtex/i18n-iso

Compliance

ISO standard Support
ISO 639-1 ✔️
ISO 639-2 ✔️
ISO 3166-1 Alpha 2 ✔️
ISO 3166-1 Alpha 3 ✔️
IETF BCP 47 language tag ✔️

Language support

Language Support
English (U.S.A., G.B.) ✔️
Chinese (Standard) ✔️
Hindi ✔️
Spanish (Mexico, Colombia, Spain, Argentina) ✔️
French (France) ✔️
Arabic (Egypt, Standard, U.A.E.) ✔️
Bengali ✔️
Russian ✔️
Portuguese (Brazil, Portugal) ✔️
Indonesian ✔️
Urdu ✔️
German (Germany, Austria) ✔️
Dutch (Netherlands, Belgium) ✔️
Swedish (Sweden) ✔️
Finnish (Finland) ✔️
Czech (Czech Republic) ✔️
Norwegian (Norway) ✔️
Japanese ✔️
Korean (South Korea) ✔️
Thai ✔️
Romanian (Romania) ✔️
Italian ✔️
Catalan (Andorra) ✔️
Assamese (India) ✔️
Afar (Djibouti) ✔️
Zulu (South Africa) ✔️
Xhosa (South Africa) ✔️
Afrikaans (South Africa) ✔️
Pedi (South Africa) ✔️
Tswana (South Africa) ✔️
Southern Sotho (South Africa) ✔️
Tsonga (South Africa) ✔️
Swazi (South Africa) ✔️
Venda (South Africa) ✔️
Southern Ndebele (South Africa) ✔️
Albanian (Albania) ✔️
Aragonese (Spain) ✔️
Armenian (Armenia) ✔️
Azerbaijani (Azerbaijan) ✔️
Basque (Spain) ✔️
Belarusian (Belarus) ✔️
Bislama (Vanuatu) ✔️
Bosnian (Bosnia and Herzegovina) ✔️
Breton (France) ✔️
Bulgarian (Bulgaria) ✔️
Burmese (Myanmar) ✔️
Abkhaz (Abkhazia) ✔️

Usage

You can play with this package on it's playground

Summary

Note on the getters

Every getter has an options, optional parameter of type Options, which you can use to control some of the getter's behavior:

interface Options {
  tryFallback?: boolean;
}
  • tryFallback
    • If this option is set to true, it will fallback to the default locale in case it doesn't find a locale or any of the locales you're looking for. The default locale is en-US, but you can override this with the configure method.

Every getter has the following type signature:

Parameter Type Description Defaults to
language string or string[] Key used to find the locale or locales you need -
options (optional) Options Gives you the ability to control some behavior { tryFallback: false }

In case you give a non existent language input, or a language input that is not present on the locales subset (if that was set), you will not be able to get it's locale. In case you give an array of languages as input and some of them either doesn't exist or are not on the locales subset, you will still receive an array of the locales found as output.

getLocaleByIETFLanguageTag

Get a single or multiple locale objects by IETF language tag.

Example usage

import { getLocaleByIETFLanguageTag } from `@vtex/i18n-iso`;

const locale = getLocaleByIETFLanguageTag("pt-BR");

const locales = getLocaleByIETFLanguageTag(["pt-BR", "pt-PT", "en-US"]);

getLocalesByOfficialLanguage

Get locales object by official language.

import { getLocalesByOfficialLanguage } from `@vtex/i18n-iso`;

const locales = getLocalesByOfficialLanguage("Portuguese");

const moreLocales = getLocalesByOfficialLanguage(["English", "Spanish"]);

getLocaleByRegion

Get a single or multiple locale objects by region.

import { getlocaleByRegion } from `@vtex/i18n-iso`;

const locale = getlocaleByRegion("Austria");

const locales = getLocaleByRegion(["Austria", "South Korea"]);

getLocaleByISO31661Alpha2

Get a single or multiple locale objects by its ISO 3166-1 alpha-2 code.

import { getLocaleByISO31661Alpha2 } from `@vtex/i18n-iso`;

const locale = getLocaleByISO31661Alpha2("IT");

const locales = getLocaleByISO31661Alpha2(["IT", "EG", "RO"]);

getLocaleByISO6391

Get a single or multiple locale objects by ISO 639-1 codes.

import { getLocalesByISO6391 } from `@vtex/i18n-iso`;

const locales = getLocalesByISO6391("pt"); // returns both Brazilian Portuguese and Portuguese.
const moreLocales = getLocalesByISO6391(["fr", "en", "pt"]);

configure

You should use this method if you're willing to override some default behavior, specifically the locales made available and the default locale to be used as a fallback if any of the methods don't find the locales being queried.

By default, every locale on this library is made available by the getLocales method, and the default language set as fallback is English.

🛑 IMPORTANT: You must import the configure method on the file that's first read.

Parameters

Parameter Type Description Defaults to
localesSubset (optional) { lookupKey: LocaleKey, locales: string[] } An object containing a lookup key and a list containing the strings of the subset you want to be used. The search will run against the strings by the lookup key. You can use this to limit the locales objects that should be exposed. Every locale object present on this package
defaultLocale (optional) { lookupKey: LocaleKey, locale: string } An object containing a lookup key and a single string representing the default locale to be used when the tryFallback parameter is passed to any other method. The search will run against the string by the lookup key. You can use this to tell i18n-iso-languages: hey, if you don't find this locale for any reason, return X one instead. This is useful if you're interacting with third party services that might not always give you as input a valid ISO or language for your project. The English (U.S.A.) locale

Note: When you don't define a locales subset, every locale defined on this lib is used.

The LocaleKey type is a union type of the following keywords:

  • ISO6391 (ISO 639-1)
  • ISO6392 (ISO 639-2)
  • ISO31661Alpha2 (ISO 3166-1 alpha-2)
  • ISO31661Alpha3 (ISO 3166-1 alpha-3)
  • IETFLanguageTag (IETF language tag)
  • officialLanguage
  • nativeOfficialLanguage
  • region
  • nativeRegion

Example usage

Configuring a locale fallback in case any of the methods find a given locale on it's locales set or subset

import { configure } from "@vtex/i18n-iso";

configure({
  defaultLocale: {
    lookupKey: "ISO31661Alpha2",
    locales: "RU",
  },
});

// On other files...
import { getLocaleByISO3166Alpha3 } from "@vtex/i18n-iso";

// This returns undefined, as there is no such
// NON-EXSITENT-CODE under the ISO 3166-1 alpha-3 standard,
// and the tryFallback option is set to false by default.
const maybeNonExistentCode = getLocaleByISO3166Alpha3("NON-EXISTENT-CODE");

// This returns the russian locale.
const fallback = getLocaleByISO3166Alpha3("NON-EXISTENT-CODE", {
  tryFallback: true,
});

Configuring a subset of locales by the IETF language tag pattern

import { configure } from "@vtex/i18n-iso";

configure({
  localesSubset: {
    lookupKey: "IETFLanguageTag",
    locales: ["en-US", "pt-BR", "it-IT", "es-AR"],
  },
});

// On other files...
import { getLocales, getLocaleByISO3166Alpha2 } from "@vtex/i18n-iso";

const locales = getLocales();
// There are 4 locale objects on the array above.

// This is undefined because japanese locales are not included on the locales subset.
const japaneseLocales = getLocaleByISO3166Alpha2("JP");

// This returns the english (U.S.A.) locales as the
// japanese locales are not included on the locales subset
// BUT tryFallback is set to true.
const maybeJapaneseLocales = getLocaleByISO3166Alpha2("JP", {
  tryFallback: true,
});

Configuring a subset of locales by the ISO 3166-1 alpha-3 standard

import { configure } from "@vtex/i18n-iso";

configure({
  localesSubset: {
    lookupKey: "ISO31661Alpha3",
    locales: ["MEX", "BRA", "CHN"],
  },
});

// On other files...
import { getLocales } from "@vtex/i18n-iso";
const locales = getLocales();
// There are 3 locale objects on the array above.

Configuring a subset of locales by the ISO 639-2 standard

import { configure } from "@vtex/i18n-iso";

configure({
  localesSubset: {
    lookupKey: "ISO6392",
    locales: ["spa", "arb"],
  },
});

// On other files...
import { getLocales } from "@vtex/i18n-iso";
const locales = getLocales();
// Every spanish and arabic locale objects are included on the array above.

Configuring a subset of locales by the ISO 639-2 standard

import { configure } from "@vtex/i18n-iso";

configure({
  localesSubset: {
    lookupKey: "officialLanguage",
    locales: ["Portuguese", "English", "Chinese"],
  },
});

// On other files...
import { getLocales } from "@vtex/i18n-iso";
const locales = getLocales();
// Every portuguese, english and chinese locale objects are included on the array above.

import { configure } from "@vtex/i18n-iso";

configure({
  localesSubset: {
    lookupKey: "officialLanguage",
    locales: ["Portuguese", "English", "Chinese"],
  },
});

// On other files...
import { getLocales } from "@vtex/i18n-iso";
const locales = getLocales();
// Every portuguese, english and chinese locale objects are included on the array above.