!GitHub stars


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

Library has just 737 Bytes gzipped size

Installation

npm:

``sh
npm install localize-react --save
`

yarn:

`sh
yarn add localize-react
`

API

$3

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 = () => (
disableCache
locale="en"
translations={TRANSLATIONS}
>

{({ translate }) => translate('name')}


);

ReactDOM.render(, node); // "Alex" will be rendered
`

$3

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 = () => (
locale="en"
translations={TRANSLATIONS}
>


);

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 = () => (
locale="en"
translations={TRANSLATIONS}
>


);

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 = () => (
locale="en"
translations={TRANSLATIONS}
>
descriptor="name"
defaultMessage="Hello, {{name}}!"
values={{ name: 'Alex' }}
/>

);

ReactDOM.render(, node); // "Alex" will be rendered
`

$3

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 (
locale="en"
translations={TRANSLATIONS}
>


);
}

ReactDOM.render(, node); // "Alex" will be rendered
`

$3

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

`

$3

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 (
locale="en"
translations={TRANSLATIONS}
>


);
}

ReactDOM.render(, node); // "Alex" will be rendered
`

$3

`
en-us
EN_US
en
eN-uS
`

$3

`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

$3

Current test coverage is 100%

jest is used for tests. To run tests:

`sh
yarn test
``

$3

localize-react is MIT licensed