Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sealninja/react-i18nify
Simple i18n translation and localization components and helpers for React.
https://github.com/sealninja/react-i18nify
flux i18n javascript localization react redux translation
Last synced: 4 days ago
JSON representation
Simple i18n translation and localization components and helpers for React.
- Host: GitHub
- URL: https://github.com/sealninja/react-i18nify
- Owner: sealninja
- License: mit
- Created: 2016-03-08T15:31:10.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2024-12-07T18:12:51.000Z (17 days ago)
- Last Synced: 2024-12-13T23:07:35.021Z (11 days ago)
- Topics: flux, i18n, javascript, localization, react, redux, translation
- Language: JavaScript
- Homepage:
- Size: 4.78 MB
- Stars: 154
- Watchers: 5
- Forks: 31
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# React I18nify
Simple i18n translation and localization components and helpers for React.
[](https://npmjs.org/package/react-i18nify)
[](https://npmjs.org/package/react-i18nify)
A working example of this package can be found [here at RunKit](https://runkit.com/npm/react-i18nify).
## Migration guide
### Upgrading to v6
`react-i18nify` v6 uses `dayjs` for date localization instead of `date-fns`, to make `react-i18nify` smaller and simpler to use. Migrating to this version requires the following changes to your project:
- Replace locale imports. E.g., `import nl from 'date-fns/locale/nl';` needs to be replaced with `import 'dayjs/locale/nl';`
- Remove calls to `addLocale` and `addLocales`, these are not needed anymore.
- Update date formatting strings. For example, `MM-dd-yyyy` is now `MM-DD-YYYY`. See for more information the [day.js documentation](https://day.js.org/docs/en/display/format).
The v5 documentation can still be found [here](https://github.com/sealninja/react-i18nify/blob/v5/README.md).
## Installation
Install by using npm:
```
npm i react-i18nify
```
## Getting started
Start by setting the translations and locale to be used:
```javascript
import { setTranslations, setLocale } from 'react-i18nify';
setTranslations({
en: {
application: {
title: 'Awesome app with i18n!',
hello: 'Hello, %{name}!'
},
date: {
long: 'MMMM do, yyyy'
},
export: 'Export %{count} items',
export_0: 'Nothing to export',
export_1: 'Export %{count} item',
two_lines:
Line 1
Line 2
},
nl: {
application: {
title: 'Toffe app met i18n!',
hello: 'Hallo, %{name}!'
},
date: {
long: 'd MMMM yyyy'
},
export: 'Exporteer %{count} dingen',
export_0: 'Niks te exporteren',
export_1: 'Exporteer %{count} ding',
two_lines: Regel 1
Regel 2
}
});
setLocale('nl');
```
Now you're all set up to unleash the power of `react-i18nify`!
## Components
The easiest way to translate or localize in your React application is by using the `Translate` and `Localize` components:
```javascript
import { Translate, Localize } from 'react-i18nify';
// => Toffe app met i18n!
// => Hallo, Aad!
// => Exporteer 1 ding
// => Exporteer 2 dingen
// =>
Regel 1
Regel 2
// => 7 april 2016
// => 3 september 2015
// => 7 jaar geleden
// => € 3,33
```
## Helpers
If for some reason, you cannot use the components, you can use the `translate` and `localize` helpers instead:
```javascript
import { translate, localize } from 'react-i18nify';
translate('application.title');
// => Toffe app met i18n!
translate('application.hello', { name: 'Aad' });
// => Hallo, Aad!'
translate('export', { count: 0 });
// => Niks te exporteren
translate('application.unknown_translation');
// => unknown_translation
translate('application', { name: 'Aad' });
// => {hello: 'Hallo, Aad!', title: 'Toffe app met i18n!'}
localize(1385856000000, { dateFormat: 'date.long' });
// => 1 december 2013
localize(Math.PI, { maximumFractionDigits: 2 });
// => 3,14
localize('huh', { dateFormat: 'date.long' });
// => null
```
If you want these helpers to be re-rendered automatically when the locale or translations change, you have to wrap them in a `` component using its `render` prop:
```javascript
import { I18n, translate } from 'react-i18nify';
} />;
```
## Date localization
`react-i18nify` uses [day.js](https://github.com/iamkun/dayjs/) internally to handle date localization. To reduce the base bundle size, `day.js` localizations are not loaded by default. If you need date localization, you can manually import them. For a list of available locales, refer to the [day.js list of locales](https://github.com/iamkun/dayjs/tree/dev/src/locale).
```javascript
import 'dayjs/locale/en';
import 'dayjs/locale/nl';
import 'dayjs/locale/it';
```
## API Reference
### ``
React translate component, with the following props:
- `value` (string)
The translation key to translate.
- Other props
All other provided props will be used as replacements for the translation.
### ``
React localize component, with the following props:
- `value` (number|string|object)
The number or date to localize.
- `dateFormat` (string)
The translation key for providing the format string. Only needed for localizing dates.
For the full list of formatting tokens which can be used in the format string, see the [day.js documentation](https://day.js.org/docs/en/display/format).
- `parseFormat` (string)
An optional formatting string for parsing the value when localizing dates.
For the full list of formatting tokens which can be used in the parsing string, see the [day.js documentation](https://day.js.org/docs/en/parse/string-format).
- `options` (object)
When localizing numbers, the localize component supports all options as provided by the Javascript built-in `Intl.NumberFormat` object.
For the full list of options, see https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat.
### ``
React I18n wrapper component, with the following prop:
- `render` (func)
The return value of the provide function will be rendered and automatically re-render when the locale or translations change.
### `setLocale(locale, rerenderComponents = true)`
The used locale can be set with this function. By default, changing the locale will re-render all components.
This behavior can be prevented by providing `false` as a second argument.
### `getLocale()`
Get the currently used locale.
### `setTranslations(translations, rerenderComponents = true)`
The used translations can be set with this function. By default, changing the translations will re-render all components.
This behavior can be prevented by providing `false` as a second argument.
### `getTranslations()`
Get the currently used translations.
### `setLocaleGetter(fn)`
Alternatively to using `setLocale`, you can provide a callback to return the locale with `setLocaleGetter`:
```javascript
import { setLocaleGetter } from 'react-i18nify';
const localeFunction = () => 'nl';
setLocaleGetter(localeFunction);
```
### `setTranslationsGetter(fn)`
Alternatively to using `setTranslations`, you can provide a callback to return the translations with `setTranslationsGetter`:
```javascript
import { setTranslationsGetter } from 'react-i18nify';
const translationsFunction = () => ({
en: { ... },
nl: { ... }
});
setTranslationsGetter(translationsFunction);
```
### `setHandleMissingTranslation(fn)`
By default, when a translation is missing, the translation key will be returned in a slightly formatted way,
as can be seen in the `translate('application.unknown_translation');` example above.
You can however overwrite this behavior by setting a function to handle missing translations.
```javascript
import { setHandleMissingTranslation, translate } from 'react-i18nify';
setHandleMissingTranslation((key, replacements, options, err) => `Missing translation: ${key}`);
translate('application.unknown_translation');
// => Missing translation: application.unknown_translation
```
### `setHandleFailedLocalization(fn)`
By default, when a localization failed, `null` will be returned,
as can be seen in the `localize('huh', { dateFormat: 'date.long' });` example above.
You can however overwrite this behavior by setting a function to handle failed localizations.
```javascript
import { setHandleFailedLocalization, localize } from 'react-i18nify';
setHandleFailedLocalization((value, options, err) => `Failed localization: ${value}`);
localize('huh', { dateFormat: 'date.long' });
// => Failed localization: huh
```
### `translate(key, replacements = {})`
Helper function to translate a `key`, given an optional set of `replacements`. See the above Helpers section for examples.
### `localize(value, options)`
Helper function to localize a `value`, given a set of `options`. See the above Helpers section for examples.
For localizing dates, the `day.js` library is used.
A `dateFormat` option can be used for providing a translation key with the format string.
For the full list of formatting tokens which can be used in the format string, see the [day.js documentation](https://day.js.org/docs/en/display/format).
Moreover, `parseFormat` option can be used for providing a formatting string for parsing the value.
For the full list of formatting tokens which can be used in the parsing string, see the [day.js documentation](https://day.js.org/docs/en/parse/string-format).
For number formatting, the localize helper supports all options as provided by the Javascript built-in `Intl.NumberFormat` object.
For the full list of options, see https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat.
### `t(key, replacements = {})`
Alias for `translate`.
### `l(value, options)`
Alias for `localize`.
### `forceComponentsUpdate()`
This function can be called to force a re-render of all I18n components.
## Example application with SSR
An example application with server-side rendering using features of `react-i18nify` can be found at https://github.com/sealninja/react-ssr-example.
## License
MIT