React-polyglot-hooks NPM

React Polyglot Hooks

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.