Lightweight React Localization 3.8KB

localize-react

:airplane: Lightweight React Localization Library :us:

Motivation

Creating really simple lightweight library for localization in React applications, which is built on top of new React Context Api

Library has just 3.8KB gzipped size

Installation

npm:

npm install localize-react --save

yarn:

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
defaultLocale
locale
translations

Example:

import React from 'react';
import ReactDOM from 'react-dom';
import { LocalizationConsumer, LocalizationProvider } from 'localize-react';

const TRANSLATIONS = {
  en: {
    name: 'Alex',
  },
};

const App = () => (
  <LocalizationProvider
    defaultLocale="en"
    locale="en"
    translations={TRANSLATIONS}
  >
    <LocalizationConsumer>
      {({ translate }) => translate('name')}
    </LocalizationConsumer>
  </LocalizationProvider>
);

ReactDOM.render(<App />, node); // "Alex" will be rendered

Message

Message component is used to provide translated message by specified descriptor, which should be passed via props. Component has the next props:

• descriptor - translation key (descriptor)

Example:

import React from 'react';
import ReactDOM from 'react-dom';
import { LocalizationConsumer, Message } from 'localize-react';

const TRANSLATIONS = {
  en: {
    name: 'Alex',
  },
};

const App = () => (
  <LocalizationProvider
    defaultLocale="en"
    locale="en"
    translations={TRANSLATIONS}
  >
    <Message descriptor="name" />
  </LocalizationProvider>
);

ReactDOM.render(<App />, 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:

import React from 'react';
import ReactDOM from 'react-dom';
import { useLocalize } from 'localize-react';

const TRANSLATIONS = {
  en: {
    name: 'Alex',
  },
};

function Test() {
  const { translate } = useLocalize();

  return translate('name');
}

const App = () => {

  return (
    <LocalizationProvider
      defaultLocale="en"
      locale="en"
      translations={TRANSLATIONS}
    >
      <Test />
    </LocalizationProvider>
  );
}

ReactDOM.render(<App />, node); // "Alex" will be rendered

contextType

Alternative way of usage inside class components:

class Translation extends React.PureComponent {
  render() {
    return (
      <span>
        {this.context.translate('name')}
      </span>
    )
  }
}

Translation.contextType = LocalizationContext;

const App = () => {
  return (
    <LocalizationProvider
      defaultLocale="en"
      locale="en"
      translations={TRANSLATIONS}
    >
      <Translation />
    </LocalizationProvider>
  );
}

ReactDOM.render(<App />, node); // "Alex" will be rendered

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:

yarn test

License

localize-react is MIT licensed