react-polyglot-hooks

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.0 or later (minimum requirement for hooks).

Usage

React Polyglot Hooks offers 1 wrapper component: <I18n> and 2 hooks: useLocale and useTranslate. The hooks 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 { useLocale, useTranslate } from 'react-polyglot-hooks';

export default function Child() {
  const locale = useLocale(); // Current locale: "en"
  const t = useTranslate(); // Translate function, takes a phrase key

  return (
    <React.Fragment>
      <span>{locale}</span>
      <span>{t('hello')}</span>
    </React.Fragment>
  );
}

That's it!

Usage with TypeScript

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

API

<I18n>

Provides i18n context to 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 keys in a t call is allowed.
onMissingKey	(key: string, options: InterpolationOptions, locale: string) => string	❌	A function called when allowMissing is true and a missing key is encountered.
interpolation	{ prefix: string, suffix: string }	❌	Controls the prefix and suffix for an interpolation.

useLocale

Returns the current active locale (string).

useTranslate

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]: string }	❌	A number to be interpolated with smart_count, or a key-value pair to interpolate values into the phrase.

For more details, please visit the documentation of Polyglot.js.

Changelog

The changelog is available here.

License

This project is licensed under the terms of the MIT License.

Acknowledgements

This project is a wrapper to ease the use of Polyglot.js within React, and is highly influenced by react-polyglot.

Changelog

0.1.1 (2019-08-26)

Bug Fixes

• deps-dev: fix lock file mismatch (80da34d)
• polyglot: make key in NoOp required (37d68d3)
• publish: properly distribute with the dist folder (0b58f6f)