rph

react-polyglot-hooks

Hooks for using Polyglot.js with React.

Showing:

Popularity

Downloads/wk

711

GitHub Stars

23

Maintenance

Last Commit

2d ago

Contributors

2

Package

Dependencies

2

Size (min+gzip)

9.2KB

License

MIT

Type Definitions

Built-In

Tree-Shakeable

No?

Categories

Readme

React Polyglot Hooks

Hooks for using Polyglot.js with React.

npm Package Minified Size Min-zipped Size

CircleCI Coverage Status Code Style Conventional Commits Dependabot Status Dependencies PeerDependencies DevDependencies

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

PropTypeRequiredDescription
childrenNodeAny node(s) accepted by React.
localestringCurrent locale, used for pluralization.
phrases{ [key: string]: string }Key-value pair of translated phrases, can be nested.
allowMissingbooleanControls 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) => stringA 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

PropsTypeRequiredDescription
phrasestringKey of the needed phrase.
countnumberA number to be interpolated with smart_count.
fallbackstringA fallback to be rendered if the phrase is missing.
interpolationsInterpolationOptionsSee 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)

ParamTypeRequiredDescription
phrasestringKey of the needed phrase.
InterpolationOptionsnumber or { [key: string]: ReactNode }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 developed to ease the use of Polyglot.js within React, and is highly influenced by react-polyglot.

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100