@locale-tools/localization

Localization and internationalization tools.

Installation

Install a given package with npm or yarn.

npm install @locale-tools/localization

yarn add @locale-tools/localization

Usage

Types

type Locale = {
  ietf: IETF[];
  drivingSide: DrivingSide | DrivingSides;
  measurementSystem: MeasurementSystem | MeasurementSystems;
  hourClock: HourClock | HourClocks;
  timezones: Timezone[] | TZTimezones[];
  dateFormats: {
    [key in IETF]: string;
  };
  weekStartsOn: WeekStartDay | WeekStartDays;
  distanceUnit: DistanceUnit | DistanceUnits;
  temperatureUnit: TemperatureUnit | TemperatureUnit;
};

// distance unit -- both strings and enum valid
enum DistanceUnits {
  KM = "kilometer",
  MI = "mile",
}
type DistanceUnit = `${DistanceUnits}` | DistanceUnits;

// temp unit -- both strings and enum valid
enum TemperatureUnits {
  C = "celsius",
  F = "fahrenheit",
}
type TemperatureUnit = `${TemperatureUnits}` | TemperatureUnits;

// driving side -- both strings and enum valid
enum DrivingSides {
  LEFT = "left",
  RIGHT = "right",
}
type DrivingSide = `${DrivingSides}` | DrivingSides;

// measurement system -- both strings and enum valid
enum MeasurementSystems {
  METRIC = "metric",
  IMPERIAL = "imperial",
}
type MeasurementSystem = `${MeasurementSystems}` | MeasurementSystems;

// supported locales
export type SupportedLocale = {
  code: string;
  name: string;
  translationFile: JsonObject;
};

Methods

buildI18n({ supportedLanguages, namespaces, defaultNamespace, fallbackLanguage, languageStorageKey, errorCallback }): I18nInstance

Builds an instance of i18next to use in an application for translations.

Parameters	Type	Description	Default
supportedLanguages	SupportedLocale[]	An array of supported languages	Required
namespaces	string[]	An array of namespace keys in your translation file	Required
defaultNamespace	string	A default namespace key	common
fallbackLanguage	string	A fallback IETF language code	en-US
languageStorageKey	string	Key for storing user's chosen language (localStorage for web, AsyncStorage for React Native)	language
errorCallback	void	Function to handle any errors	undefined

To use, you will need to install i18next and react-i18next into your application. You'll then need to do some configuration:

i18n.ts - this file can be anywhere in your app

import { buildI18n } from "@locale-tools/localization";
import { IETF } from "@locale-tools/languages";
import enTranslation from "./en.json"; // your local translation file

const supportedLanguages = [
  {
    code: IETF.en_US,
    name: "English (US)",
    translationFile: en,
  },
];

export const i18n = buildI18n({
  supportedLanguages,
  namespaces: ["common", "validation", "a11y"],
});

Ensure that you have JSON translation files stored somewhere in your app for your i18n instance to reference. This file should be keyed with the namespaces you specify.

Then, you'll need to import your i18n instance in your app entry file.

import { i18n } from "./i18n";

.. // rest of the file

For more instructions, see the i18next docs.