npm package: @marcelovicentegc/i18n-iso-languages
Description: <p align="center">   <img alt="i18n-iso-languages logo" src="assets/globe.png" height="300" />   <h3 align="center">@marcelovicentegc/i18n-iso-languages</h3>   <p align="center">Flexible, future proof and easy to use localization library based on the ISO 
Author: Marcelo Cardoso
Latest version: 0.13.0
Deprecated: This package moved to @vtex/i18n-iso

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

---

[![npm version](https://badge.fury.io/js/%40marcelovicentegc%2Fi18n-iso-languages.svg)](https://badge.fury.io/js/%40marcelovicentegc%2Fi18n-iso-languages) [![Playground](https://img.shields.io/badge/-Play%20with%20it%20%20on%20it's%20playground!-success)](https://marcelovicentegc.github.io/i18n-iso-languages)

## Installation

> yarn add @marcelovicentegc/i18n-iso-languages

> npm i @marcelovicentegc/i18n-iso-languages

## 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

<img src="https://upload.wikimedia.org/wikipedia/en/thumb/a/a4/Flag_of_the_United_States.svg/1200px-Flag_of_the_United_States.svg.png" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/en/thumb/a/ae/Flag_of_the_United_Kingdom.svg/1200px-Flag_of_the_United_Kingdom.svg.png" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/f/fa/Flag_of_the_People%27s_Republic_of_China.svg/1200px-Flag_of_the_People%27s_Republic_of_China.svg.png" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/en/thumb/4/41/Flag_of_India.svg/1200px-Flag_of_India.svg.png" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/1/17/Flag_of_Mexico.png/1200px-Flag_of_Mexico.png" width="20" /> <img src="https://cdn.countryflags.com/thumbs/colombia/flag-400.png" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/en/thumb/9/9a/Flag_of_Spain.svg/1200px-Flag_of_Spain.svg.png" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/3/35/Flag_of_Argentina_%283-2%29.svg/750px-Flag_of_Argentina_%283-2%29.svg.png" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/en/c/c3/Flag_of_France.svg" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/f/fe/Flag_of_Egypt.svg" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/b/bb/Arabic-Language-Flag.svg" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/c/cb/Flag_of_the_United_Arab_Emirates.svg/1280px-Flag_of_the_United_Arab_Emirates.svg.png" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/f/f9/Flag_of_Bangladesh.svg" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/en/f/f3/Flag_of_Russia.svg" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/en/thumb/0/05/Flag_of_Brazil.svg/1200px-Flag_of_Brazil.svg.png" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/5/5c/Flag_of_Portugal.svg/255px-Flag_of_Portugal.svg.png" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/9/9f/Flag_of_Indonesia.svg" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/3/32/Flag_of_Pakistan.svg" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/en/thumb/b/ba/Flag_of_Germany.svg/1200px-Flag_of_Germany.svg.png" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/4/41/Flag_of_Austria.svg/255px-Flag_of_Austria.svg.png" width="20"/> <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/2/20/Flag_of_the_Netherlands.svg/1200px-Flag_of_the_Netherlands.svg.png" width="20"/> <img src="https://upload.wikimedia.org/wikipedia/commons/6/65/Flag_of_Belgium.svg" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/en/thumb/4/4c/Flag_of_Sweden.svg/1200px-Flag_of_Sweden.svg.png" width="20" /> <img src="https://cdn.webshopapp.com/shops/94414/files/52382996/flag-of-finland.jpg" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/en/thumb/9/9e/Flag_of_Japan.svg/1200px-Flag_of_Japan.svg.png" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/0/09/Flag_of_South_Korea.svg/640px-Flag_of_South_Korea.svg.png" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/a/a9/Flag_of_Thailand.svg/1200px-Flag_of_Thailand.svg.png" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/7/73/Flag_of_Romania.svg/1200px-Flag_of_Romania.svg.png" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/en/0/03/Flag_of_Italy.svg" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/c/ce/Flag_of_Catalonia.svg" width="20"/> <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/c/cb/Flag_of_the_Czech_Republic.svg/1200px-Flag_of_the_Czech_Republic.svg.png" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/d/d9/Flag_of_Norway.svg" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/7/7a/Flag_of_the_Republic_of_Abkhazia.svg" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/e/e8/Bandera_de_Arag%C3%B3n.svg" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/3/36/Flag_of_Albania.svg" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/a/af/Flag_of_South_Africa.svg" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/2/2f/Flag_of_Armenia.svg" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/d/dd/Flag_of_Azerbaijan.svg" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/2/2d/Flag_of_the_Basque_Country.svg" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/6/6e/Flag_of_Vanuatu_%28official%29.svg" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/b/bf/Flag_of_Bosnia_and_Herzegovina.svg" width="20" /> <img src="https://upload.wikimedia.org/wikipedia/commons/9/9a/Flag_of_Bulgaria.svg" width="20" />

| 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](https://marcelovicentegc.github.io/i18n-iso-languages/)

> ### Summary
>
> - getters
>   - [getLocaleByIETFLanguageTag](https://github.com/marcelovicentegc/i18n-iso-languages#getlocalebyietflanguagetag)
>   - [getLocalesByOfficialLanguage](https://github.com/marcelovicentegc/i18n-iso-languages#getlocalesbyofficiallanguage)
>   - [getLocaleByRegion](https://github.com/marcelovicentegc/i18n-iso-languages#getlocalebyregion)
>   - [getLocaleByISO31661Alpha2](https://github.com/marcelovicentegc/i18n-iso-languages#getlocalebyiso31661alpha2)
> - configuration
>   - [configure](https://github.com/marcelovicentegc/i18n-iso-languages#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:

```ts
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](https://github.com/marcelovicentegc/i18n-iso-languages#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](https://github.com/marcelovicentegc/i18n-iso-languages#configure) (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](https://marcelovicentegc.github.io/i18n-iso-languages/#getLocaleByIETFLanguageTag)

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

#### Example usage

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

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

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

### [getLocalesByOfficialLanguage](https://marcelovicentegc.github.io/i18n-iso-languages/#getLocalesByOfficialLanguage)

Get locales object by official language.

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

const locales = getLocalesByOfficialLanguage("Portuguese");

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

### [getLocaleByRegion](https://marcelovicentegc.github.io/i18n-iso-languages/#getLocaleByRegion)

Get a single or multiple locale objects by region.

```tsx
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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code.

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

const locale = getLocaleByISO31661Alpha2("IT");

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

### [configure](https://marcelovicentegc.github.io/i18n-iso-languages/#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](https://github.com/marcelovicentegc/i18n-iso-languages#language-support) |
| `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**

```tsx
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**

```tsx
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,
});
```

</details>

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

```tsx
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**

```tsx
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**

```tsx
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.
```

```tsx
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.
```