react-simple-i18n

React i18n solution with context API

Usage no npm install needed!

<script type="module">
  import reactSimpleI18n from 'https://cdn.skypack.dev/react-simple-i18n';
</script>

README

React Simple I18n

  • React i18n solution with context API, support React 16.3.0+ (16.8.0+ if use hooks)
  • Lightweight, simple usage, easy to configure
  • 100% test coverage, reliable

Usage

Define languages data first

const langData = {
  enUS: {
    projects: 'Projects',
    cars: 'This car is %s%, that car is %s%',
    nav: {
      home: 'Home',
    },
  },
  zhCN: {
    projects: '项目',
    cars: '这辆车是%s%,那辆车是%s%',
    nav: {
      home: '首页',
    },
  },
}

Choice A: Use React hook

import React, { Component } from 'react'
import { createI18n, I18nProvider, useI18n } from 'react-simple-i18n'

const Demo = () => {
  const { t, i18n } = useI18n()

  return (
    <div>
      <p>{t('projects')}</p>
      <p>{t('cars', 'BMW', 'TOYOTA')}</p>
      <p>{t('nav.home')}</p>
      <button onClick={() => i18n.setLang('enUS')}>English</button>
      <button onClick={() => i18n.setLang('zhCN')}>中文</button>
    </div>
  )
}

const App = () => (
  <I18nProvider i18n={createI18n(langData, { lang: 'enUS' })}>
    <Demo />
  </I18nProvider>
)

Choice B: Use traditional HOC

import React, { Component } from 'react'
import { createI18n, I18nProvider, withI18n } from 'react-simple-i18n'

class Demo extends Component {
  handleSetEnglish = () => {
    this.props.i18n.setLang('enUS')
  }

  handleSetChinese = () => {
    this.props.i18n.setLang('zhCN')
  }

  render() {
    const { t } = this.props
    return (
      <div>
        <p>{t('projects')}</p>
        <p>{t('cars', 'BMW', 'TOYOTA')}</p>
        <p>{t('nav.home')}</p>
        <button onClick={this.handleSetEnglish}>English</button>
        <button onClick={this.handleSetChinese}>中文</button>
      </div>
    )
  }
}

const DemoWithI18n = withI18n(Demo)

const App = () => (
  <I18nProvider i18n={createI18n(langData, { lang: 'enUS' })}>
    <DemoWithI18n />
  </I18nProvider>
)

Top Level API

createI18n(data, options)

Creates an i18n object for I18nProvider

Arguments

  • data Language data object, see usage above
  • options
    • lang Initial language to use

Return

  • i18n
    • t(key, ...args) Get translation by language name
      • @param key {string} key of a translation field
      • @param args {[string]} strings to replace %s% in the field
    • getLang() Get current language
      • @return {string} current language name, such as enUS
    • setLang(lang) Set language by language name
      • @param lang {string} language name, such as enUS
    • addLangData(langData) Async add language data, allow adding multiple languages once
      • @param langData {object} Language object { enUS: { key: 'value' } }
    • listen(handler) Add listener to language change
      • @param handler {func()} function which will be called when language change
    • unlisten(handler) Unbind a listener of language change
      • @param handler {func()} function which will be called when language change

<I18nProvider i18n>

Makes i18n available to withI18n HOC and useI18n hook

Props

  • i18n I18n object created by createI18n

withI18n(Component)

Connects a React component to i18n object. Adds t and i18n to props of wrapped component.

useI18n()

A React hook that returns an object with t and i18n.

License

MIT