Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/yankouskia/localize-react
✈️ Lightweight React Localization Library 🇺🇸
https://github.com/yankouskia/localize-react
l10n lightweight localization react
Last synced: about 1 month ago
JSON representation
✈️ Lightweight React Localization Library 🇺🇸
- Host: GitHub
- URL: https://github.com/yankouskia/localize-react
- Owner: yankouskia
- License: mit
- Created: 2019-07-24T17:34:56.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-06T02:02:52.000Z (almost 2 years ago)
- Last Synced: 2024-11-08T11:42:16.805Z (about 2 months ago)
- Topics: l10n, lightweight, localization, react
- Language: JavaScript
- Homepage:
- Size: 1.22 MB
- Stars: 53
- Watchers: 2
- Forks: 4
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://circleci.com/gh/yankouskia/localize-react) [](https://codecov.io/gh/yankouskia/localize-react/) [](https://github.com/yankouskia/localize-react/pulls) [](https://github.com/yankouskia/localize-react/blob/master/LICENSE) 
[](https://www.npmjs.com/package/localize-react)
# localize-react
✈️ Lightweight React Localization Library 🇺🇸
## Motivation
Creating really simple lightweight library for localization in React applications without any dependencies, which is built on top of new [React Context Api](https://reactjs.org/docs/context.html)
Library has just **737 Bytes** gzipped size
## Installation
npm:
```sh
npm install localize-react --save
```
yarn:
```sh
yarn add localize-react
```
## API
### Provider & Consumer
`LocalizationProvider` is used to provide data for translations into React context. The root application component should be wrapped into `LocalizationProvider`. Component has the next props:
- `children` - children to render
- `locale` - [OPTIONAL] locale to be used for translations. If locale is not specified regular translations object will be used as map of `{ key: translations }`
- `translations` - object with translations
- `disableCache` - boolean variable to disable cache on runtime (`false` by default). Setting this to `true` could affect runtime performance, but could be useful for development.
Example:
```js
import React from 'react';
import ReactDOM from 'react-dom';
import { LocalizationConsumer, LocalizationProvider } from 'localize-react';
const TRANSLATIONS = {
en: {
name: 'Alex',
},
};
const App = () => (
{({ translate }) => translate('name')}
);
ReactDOM.render(, node); // "Alex" will be rendered
```
### Message
`Message` component is used to provide translated message by specified key, which should be passed via props. Component has the next props:
- `descriptor` - translation key (descriptor)
- `defaultMessage` - message to be used in case translation is not provided (values object are applied to default message as well)
- `values` - possible values to use with template string (Template should be passed in next format: `Hello {{name}}`)
Example:
```js
import React from 'react';
import ReactDOM from 'react-dom';
import { LocalizationProvider, Message } from 'localize-react';
const TRANSLATIONS = {
en: {
name: 'Alex',
},
};
const App = () => (
);
ReactDOM.render(, node); // "Alex" will be rendered
```
To use with templates:
```js
import React from 'react';
import ReactDOM from 'react-dom';
import { LocalizationProvider, Message } from 'localize-react';
const TRANSLATIONS = {
en: {
name: 'Hello, {{name}}!',
},
};
const App = () => (
);
ReactDOM.render(, node); // "Alex" will be rendered
```
To use with default message:
```js
import React from 'react';
import ReactDOM from 'react-dom';
import { LocalizationProvider, Message } from 'localize-react';
const TRANSLATIONS = {
en: {},
};
const App = () => (
);
ReactDOM.render(, node); // "Alex" will be rendered
```
### useLocalize
`useLocalize` hook is used to provide localization context, which can be used for translation.
**NOTE**
Keep in mind, that hooks are not supported in class components!
Example:
```js
import React from 'react';
import ReactDOM from 'react-dom';
import { LocalizationProvider, useLocalize } from 'localize-react';
const TRANSLATIONS = {
en: {
name: 'Alex',
},
};
function Test() {
const { translate } = useLocalize();
return translate('name');
}
const App = () => {
return (
);
}
ReactDOM.render(, node); // "Alex" will be rendered
```
### Templates
It's possible to use templates inside translation strings with highlighting templates using double curly braces. To pass correpospondent values:
```js
const translation = translate('My name is {{name}}. I am {{age}}', { name: 'Alex', age: 25 });
```
Or with React component:
```js
```
### contextType
Alternative way of usage inside class components:
```js
import React from 'react';
import { LocalizationContext, LocalizationProvider } from 'localize-react';
const TRANSLATIONS = {
en: {
name: 'Alex',
},
};
class Translation extends React.PureComponent {
render() {
return (
{this.context.translate('name')}
)
}
}
Translation.contextType = LocalizationContext;
const App = () => {
return (
);
}
ReactDOM.render(, node); // "Alex" will be rendered
```
### locale
Locale could be passed in short or long option.
Valid examples:
```
en-us
EN_US
en
eN-uS
```
### translations
Translations could be passed in any object form (plain or with deep properties)
Valid examples:
```js
const translations = {
n: {
a: {
m: {
e: 'Alex',
},
},
},
},
```
You could use key with dot delimiter to access that property:
```js
// will print "Alex"
```
If there is no exact match in translations, then the value of locale will be sanitized and formatted to **lower_case_separate_by_underscore**. Make sure you provide translations object with keys in this format. If translations for long locale will not be found, and translations will be found for shorten alternative - that version will be used
## Restriction
At least `React 16.8.0` is required to use this library, because new React Context API & React Hooks
## Contributing
`localize-react` is open-source library, opened for contributions
### Tests
**Current test coverage is 100%**
`jest` is used for tests. To run tests:
```sh
yarn test
```
### License
localize-react is [MIT licensed](https://github.com/yankouskia/localize-react/blob/master/LICENSE)