@marcelovicentegc/i18n-iso-languages v0.13.0

Installation

yarn add @marcelovicentegc/i18n-iso-languages

npm i @marcelovicentegc/i18n-iso-languages

Compliance

Language support

Usage

You can play with this package on it's playground

Summary

• getters
  • getLocaleByIETFLanguageTag
  • getLocalesByOfficialLanguage
  • getLocaleByRegion
  • getLocaleByISO31661Alpha2
• configuration
  • configure

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:

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 `@marcelovicentegc/i18n-iso-languages`;

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

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

getLocalesByOfficialLanguage

Get locales object by official language.

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

const locales = getLocalesByOfficialLanguage("Portuguese");

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

getLocaleByRegion

Get a single or multiple locale objects by region.

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

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 `@marcelovicentegc/i18n-iso-languages`;

const locale = getLocaleByISO31661Alpha2("IT");

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

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

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 "@marcelovicentegc/i18n-iso-languages";

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

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

// 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 "@marcelovicentegc/i18n-iso-languages";

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

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

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 "@marcelovicentegc/i18n-iso-languages";

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

// On other files...
import { getLocales } from "@marcelovicentegc/i18n-iso-languages";
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 "@marcelovicentegc/i18n-iso-languages";

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

// On other files...
import { getLocales } from "@marcelovicentegc/i18n-iso-languages";
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 "@marcelovicentegc/i18n-iso-languages";

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

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

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

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

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