olo-locale

olo-locale provides usefull functionality for content negotiation for language specific contents. As well as other utilities around internationalization.

Currently only the main english and german languages and reagions are supported. Support for additional languages as well as the customization of used locales will be added next.

Installation

Navigate to your project folder and enter the following in you terminal:

npm i olo-locale --save

Usage

This package provides three classes that should cover usefull functionality not allready covered by other platforms.

Locale

The Locale class is meant to identify the locale (language & region) of a piece of content, asset, or entity. You can set it up with a language, a country code or a meta-data object:

const english = new Locale('en');
const greatbritain = new Locale('GB');

const swissGerman = new Locale({
  locale: 'de-CH',
  language: 'de', // not needed of locale is defined
  region: 'CH', // not needed of locale is defined
  availableLocales: ['de-DE', 'de-AT'], // Available locales describes other version of the entity that are available with an additional request.
});

Once setup the Locale instace allows you to check if it is the same as another locale, locale code, language or regions and how well it fits a given locale request.

english.isSame(greatbritain); // true, because GB is the default region for english
english.isSame('en'); // true

swissGerman.isSame('DE'); // false, because here the Swiss locale has been explicitly defined;
swissGerman.isSame('de'); // true;

english.isFit(['de-CH', 'de-DE', 'en-GB']), // 3
swissGerman.isFit(['en-GB']), // false

LocaleRequest

LocaleRequest is ordered list of preferred locales, typically used for content negotiation or defining a fallback sequence for localization.

It extends the native Array class and automatically populates itself based on input locales, their mapped fallbacks (via DefaultLocaleLocale), and the global DefaultLocale, ensuring no duplicates and maintaining a preference order.

const swissGerman = new LocaleRequest('de-CH'); // ['de-CH', 'de-DE', 'en-GB']

The isFit() method provides an a number representing how well a given locale fits the request (lower is better).

swissGerman.isFit(new Locale('de-CH')); // 1
swissGerman.isFit(new Locale('en-US')); // false

Localization

The static Localization class provides utility classes and methods around for specific internationalization cases.

You can compile gender inclusive phrasings with the language specific Genderer classes.

const germanGenderer = Localization.getGenderer('de-DE');
germanGenderer.setGenderDividers('*', '/'); // defaults to ':' and '/'

germanGenderer.compileGenderedDeclinationItem('Studentin', 'Student'); // Student*in
germanGenderer.compileGenderedDeclinationItem('Studentinnen', 'Studenten'); // Studentinnen/Studenten

In case you don't use configuration by locale but only by language or region, you can convert them to lacale based configurations.

Localization.expandLanguageToLocaleMap({
  de: { capitalization: 'always', adress: 'Liebe(r) ' }
  en: { capitalization: 'startOfSentence', adress: 'Dear ' }
});

/*
{
  'de-DE': { capitalization: 'always', adress: 'Liebe(r) ' },
  'de-CH': { capitalization: 'always', adress: 'Liebe(r) ' },
  'de-AT': { capitalization: 'always', adress: 'Liebe(r) ' },
  'en-US': { capitalization: 'startOfSentence', adress: 'Dear ' },
  'en-GB': { capitalization: 'startOfSentence', adress: 'Dear ' }
}
*/

Localization.expandRegionToLocaleMap({
  GB: { imprintRequired: false, privacyStatementRequired: true },
  DE: { imprintRequired: true, privacyStatementRequired: true }
});