Hooks for using Polyglot.js with React.
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).
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.
Types are baked in as the project is written in TypeScript.
<I18n>
Provides i18n context to the T component and the hooks. Accepts all options supported by Polyglot.js.
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 | 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. |
For more details, please visit the documentation of Polyglot.js.
The changelog is available here.
This project is developed to ease the use of Polyglot.js within React, and is highly influenced by react-polyglot
.
Author: pmmmwh
The Demo/Documentation: View The Demo/Documentation
Download Link: Download The Source Code
Official Website: https://github.com/pmmmwh/react-polyglot-hooks
License: This project is licensed under the terms of the MIT License.
#react #polyglot #i18n