Hooks for using Polyglot.js with React

React Polyglot Hooks

Hooks for using Polyglot.js with React.

Installation

React Polyglot Hooks is available as an npm package.

// with npm
npm install react-polyglot-hooks

// with yarn
yarn add react-polyglot-hooks

React is required as a peer dependency.
Please install version 16.8.3 or later (minimum requirement for hooks).

Usage

React Polyglot Hooks offers 1 wrapper component: <I18n>, 2 hooks: useLocale and useT and 1 helper component: <T>.
The hooks and the helper component have to be wrapped with the <I18n> component to work properly.

Here is a quick example to get you started:
First, wrap a parent component with <I18n> and provide locale and phrases.

Parent.jsx

import React from 'react';
import { I18n } from 'react-polyglot-hooks';
import Child from './Child';

// ... or any ways to determine current locale
const locale = window.locale || 'en';

// You can put translations in separate files
const phrases = {
  en: { hello: 'Hello, World!' },
  fr: { hello: 'Bonjour, Monde!' },
};

export default function Parent() {
  return (
    <I18n locale={locale} phrases={phrases[locale]}>
      <Child />
    </I18n>
  );
}

Then, in a child component, call the hooks:

Child.jsx

import React from 'react';
import { T, useLocale } from 'react-polyglot-hooks';

export default function Child() {
  const locale = useLocale(); // Current locale: "en"
  return (
    <React.Fragment>
      <span>{locale}</span>
      <T phrase="hello" />
    </React.Fragment>
  );
}

That's it! For more in-depth examples, check out the examples directory.

Usage with TypeScript

Types are baked in as the project is written in TypeScript.

API

<I18n>

Provides i18n context to the T component and the hooks. Accepts all options supported by Polyglot.js.

Props

Prop	Type	Required	Description
children	Node	✅	Any node(s) accepted by React.
locale	string	✅	Current locale, used for pluralization.
phrases	{ [key: string]: string }	✅	Key-value pair of translated phrases, can be nested.
allowMissing	boolean	❌	Controls whether missing phrase keys in a t call is allowed.
interpolation	{ prefix: string, suffix: string }	❌	Controls the prefix and suffix for an interpolation.
onMissingKey	(key: string, options: InterpolationOptions, locale: string) => string	❌	A function called when allowMissing is true and a missing key is encountered.
pluralRules	{ pluralTypes: PluralTypes, pluralTypeToLanguages: PluralTypeToLanguages }	❌	Custom pluralization rules to be applied to change language(s) behaviour(s).

<T>

Renders a phrase according to the props.

Props

Props	Type	Required	Description
phrase	string	✅	Key of the needed phrase.
count	number	❌	A number to be interpolated with smart_count.
fallback	string	❌	A fallback to be rendered if the phrase is missing.
interpolations	InterpolationOptions	❌	See InterpolationOptions below.

useLocale

Returns the current active locale (string).

useT

Returns a special function (t) which takes in parameters and returns a phrase.

t(phrase, InterpolationOptions)

Param	Type	Required	Description
phrase	string	✅	Key of the needed phrase.
InterpolationOptions	number or { [key: string]: ReactNode }	❌	A number to be interpolated with smart_count, or a key-value pair to interpolate values into the phrase.