Twitch Intl

A typescript client library for localizing values in a JS application. (formerly TwilightIntl)

See helper library twitch-intl-cli for tools to extract messages from code and managing those messages in Smartling.

See tachyon-intl for an SSR compatible wrapper of this package.

Installation

yarn add twitch-intl

Basic Usage

import { Locale, TwitchIntl } from 'twitch-intl';

// Generate a list of the locales your application supports
export function getLocales(): Locale[] {
  /***/
}

// return the value of the request's Accept-Language header on the server or
// window.navigator.languages on the client
export function getUserLanguages(): string[] {
  /***/
}

// Create an instance of Twitch Intl and tell it to choose a locale based on the user's language preferences
const intl = new TwitchIntl(getLocales());
intl.loadLocale(getUserLanguages());

// Now you can use format functions for strings, numbers, etc
const label = intl.formatMessage('String to internationalize', '<UniqueID>');

Intl Formatting Functions

Rich type info will be available in your editor for detailed usage of each of the formatting function TwitchIntl supports:

• formatMessage - The bread and butter string formatting
• formatDate
• formatTime
• formatNumber
• formatNumberShort - Abbreviated numbers (1k, 1.5m, etc)
• formatRelativeDate - "2 days from now" or "5 minutes ago"
• formatPastRelativeDate - Same as above, but clamped to never display dates in the future (because otherwise a client's clock might be out of sync and their new post just happened "in 2 minutes")

Defining Locales

Default Locales

A default locale will be used in the event that none of the user languages that are provided to intl.loadLocale or intl.loadLocaleSync are found in the list of Locale objects that are provided to TwitchIntl. When this happens, the first Locale with the optional field default: true will be used. In the event that a default is not explicitly specified, the first Locale in the supported list will be used.

The default locale should correspond to the language that strings are originally written in (and can be assumed to always have a string available).

Static vs Dynamic Locales

The application data for each supported locale can be provided directly to TwitchIntl within each Locale object or loading can be deferred until the point in which a locale is selected for use. The latter approach must be utilized on the client to avoid unnecessarily loading strings for all locales and bloating the size of your application.

Example:

import { DynamicLocale, Locale, StaticLocale, TwitchIntl } from 'twitch-intl';

export function getLocales(): Locale[] {
  const defaultLocale: StaticLocale = {
    name: 'English',
    languageCode: 'en',
    locale: 'en-US',
    // Empty because the default locale strings are already present in the code so
    // no extra loading is required
    data: {},
    default: true,
  };

  const dynamicLocales: DynamicLocale[] = [
    {
      name: 'Deutsch',
      languageCode: 'de',
      locale: 'de-DE',
      loader: () => import('messages/de.json'),
    },
    // ...
  ];

  return [defaultLocale, ...dynamicLocales];
}

const intl = new TwitchIntl(getLocales());

Loading A Locale

After initializing TwitchIntl, you must call either loadLocale or loadLocaleSync exactly once in order to prompt it to select and load a locale for utilization. For convenience, both functions will return a LocaleData object so that you can determine which locale was chosen.

Synchronous Loading via loadLocaleSync

Use loadLocaleSync to avoid unnecessary asynchrony if all of your locales are of type StaticLocale.

import { StaticLocale, TwitchIntl } from 'twitch-intl';

const allLocales: StaticLocale[] = getLocales();
const intl = new TwitchIntl(allLocales);
const selectedLocaleData = intl.loadLocaleSync(['de', 'pt', 'en']);

Note: If you use loadLocaleSync and a locale of type DynamicLocale is selected, a run-time exception will be thrown.

Asynchronous Loading via loadLocale

Use loadLocale if any of the locales you have defined are of type DynamicLocale. This method also supports loading StaticLocale objects.

import { Locale, TwitchIntl } from 'twitch-intl';

const allLocales: Locale[] = getLocales();
const intl = new TwitchIntl(allLocales);
const selectedLocale = await intl.loadLocale(['de', 'pt', 'en']);