https://github.com/pmmmwh/react-polyglot-hooks
Hooks for using Polyglot.js with React.
https://github.com/pmmmwh/react-polyglot-hooks
i18n polyglot react react-hooks translation
Last synced: about 1 year ago
JSON representation
Hooks for using Polyglot.js with React.
- Host: GitHub
- URL: https://github.com/pmmmwh/react-polyglot-hooks
- Owner: pmmmwh
- License: mit
- Created: 2019-08-26T17:28:52.000Z (almost 7 years ago)
- Default Branch: main
- Last Pushed: 2025-03-15T19:18:38.000Z (about 1 year ago)
- Last Synced: 2025-03-16T07:41:34.518Z (about 1 year ago)
- Topics: i18n, polyglot, react, react-hooks, translation
- Language: TypeScript
- Homepage:
- Size: 9.3 MB
- Stars: 26
- Watchers: 2
- Forks: 3
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# React Polyglot Hooks
Hooks for using [Polyglot.js](https://airbnb.io/polyglot.js) with [React](https://reactjs.org/).
[](https://www.npmjs.com/package/react-polyglot-hooks)
[](https://bundlephobia.com/result?p=react-polyglot-hooks@latest)
[](https://bundlephobia.com/result?p=react-polyglot-hooks@latest)
[](https://app.circleci.com/pipelines/github/pmmmwh/react-polyglot-hooks?branch=main)
[](https://codecov.io/gh/pmmmwh/react-polyglot-hooks/branch/main)
[](https://conventionalcommits.org)
[](https://dependabot.com)
[](https://david-dm.org/pmmmwh/react-polyglot-hooks/main)
[](https://david-dm.org/pmmmwh/react-polyglot-hooks/main?type=peer)
[](https://david-dm.org/pmmmwh/react-polyglot-hooks/main?type=dev)
## Installation
React Polyglot Hooks is available as an [npm package](https://www.npmjs.com/package/react-polyglot-hooks).
```sh
// 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: ``, 2 hooks: `useLocale` and `useT` and 1 helper component: ``.
The hooks and the helper component have to be wrapped with the `` component to work properly.
Here is a quick example to get you started:
First, wrap a parent component with `` and provide `locale` and `phrases`.
`Parent.jsx`
```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 (
);
}
```
Then, in a child component, call the hooks:
`Child.jsx`
```jsx
import React from 'react';
import { T, useLocale } from 'react-polyglot-hooks';
export default function Child() {
const locale = useLocale(); // Current locale: "en"
return (
{locale}
);
}
```
That's it! For more in-depth examples, check out the [examples](/examples) directory.
### Usage with TypeScript
Types are baked in as the project is written in [TypeScript](https://www.typescriptlang.org/).
## API
### ``
Provides i18n context to the T component and the hooks. Accepts all options supported by [Polyglot.js](https://airbnb.io/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). |
### ``
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. |
For more details, please visit the [documentation](https://airbnb.io/polyglot.js) of Polyglot.js.
## Changelog
The changelog is available [here](/CHANGELOG.md).
## License
This project is licensed under the terms of the
[MIT License](/LICENSE).
## Acknowledgements
This project is developed to ease the use of [Polyglot.js](https://airbnb.io/polyglot.js) within [React](https://reactjs.org/), and is highly influenced by [`react-polyglot`](https://github.com/nayaabkhan/react-polyglot).