React Polyglot Hooks

Hooks for using Polyglot.js with React.

View Documentation View Github

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.