Skip to content

Translate your React app without any hassle and with no setup!

License

Notifications You must be signed in to change notification settings

federico-moretti/react-translate

Repository files navigation

react-translate

Translate your React app without any hassle and with no setup!

Features

  • Translate function
  • Translate component
  • Allow nested translations
  • Singular, plural and zero based on count
  • Lightweight (~3KB)
  • Built with TypeScript
  • ~99% code coverage

Installing

npm install @federico.moretti/react-translate
# or
yarn add @federico.moretti/react-translate

Example

Basic usage:

import React from 'react';
import ReactDOM from 'react-dom';
import {
  TranslateProvider,
  useTranslate,
} from '@federico.moretti/react-translate';

const translations = {
  pear: {
    it: 'Pera',
    en: 'Pear',
  },
  apple: {
    it: ['Mela', 'Mele'],
    en: ['Apple', 'Apples'],
  },
  sub: {
    strawberry: {
      en: ['1 strawberry', '%n strawberries', '0 strawberries'],
      it: ['1 ciliegia', '%n ciliegie', '0 ciliegie'],
    },
  },
};

function App() {
  const { t, setLanguage, withPrefix, language } = useTranslate();
  const sub = withPrefix('sub');

  return (
    <div>
      <p>Selected language: {language}</p>
      <p>{t('pear')}</p>
      <p>{t('apple', { count: 2 })}</p>
      <p>{t('sub.strawberry')}</p>
      <p>{sub('strawberry')}</p>
      <div>
        <button onClick={() => setLanguage('it')}>Change to it</button>
        <button onClick={() => setLanguage('en')}>Change to en</button>
      </div>
    </div>
  );
}

ReactDOM.render(
  <TranslateProvider defaultLanguage="en" translations={translations}>
    <App />
  </TranslateProvider>,
  document.getElementById('root')
);

CodeSandbox

API

t(id: string, params?: TranslateParams): string

It returns the translation as a string.

  • id
    • use dot notation to get nested translations
  • params:
    • count?: number
      • select singular, plural or zero
      • if plural %n in a string will be replaced with the count
    • prefix?: string
      • allows to always get nested translations
    • returnIdIfMissing: boolean
      • defaults to true
      • allows to hide the translation id if missing

setLanguage(language: string): void

It changes the language in the provider.

withPrefix(prefix: string): function

It returns t() with the prefix already added.

This is useful if you have to use a lot of translations with the same prefix, for example in a page.

const t = withPrefix('dashboard');
const dashboardTitle = t('title'); // 'dashboard.title'

<T />

Creates a text node (or another element) with the translation.

  • id: string
  • type: keyof React.ReactHTML
    • if type equals p it will return <p>your translation</p>
  • prefix: string
  • count: number
  • returnIdIfMissing: boolean

<TranslateProvider />

Wrap the app with the provider.

  • defaultLanguage: string
    • it defaults to browser language if undefined
    • example: it-IT
  • translations: Translations
    • the translations object
    • required
  • fallbackLanguage: string
    • if a translation is missing this language will be used
    • example: en-GB
  • suppressWarnings: boolean
    • hides the warnings in the console
  • showIds: boolean
    • show translation ids

Translation object

const translations = {
  // basic
  pear: {
    it: 'Pera',
    en: 'Pear',
  },
  apple: {
    // [1, 2+]
    it: ['Mela', 'Mele'],
    en: ['Apple', 'Apples'],
  },
  // nested
  sub: {
    strawberry: {
      // [1, 2+, 0]
      en: ['1 strawberry', '%n strawberries', '0 strawberries'],
      it: ['1 ciliegia', '%n ciliegie', '0 ciliegie'],
    },
  },
};

translate(object): TranslateFunctionParams

Same logic of t() but exported to be used outside of the React context, for example in e2e tests.

  • object:
    • id: string
      • required
    • language: string
      • required
    • translations: Translations
      • the translations object
      • required
    • params: TranslateParams
      • count?: number
        • select singular, plural or zero
        • if plural %n in a string will be replaced with the count
      • prefix?: string
        • allows to always get nested translations
      • returnIdIfMissing: boolean
        • defaults to true
        • allows to hide the translation id if missing
    • fallbackLanguage: string
      • if a translation is missing this language will be used
      • example: en-GB
    • suppressWarnings: boolean
      • hides the warnings in the console
    • showIds: boolean
      • show translation ids

mergeTranslations(array): Translations

A function to merge different language files.

  • array: { language: string; translations: TranslationsWithoutLanguage }[]
    • it will merge the translation using the language
const translationsEn = {
  pear: 'Pear',
  banana: ['Banana', 'Bananas'],
};

const translationsIt = {
  pear: 'Pera',
  banana: ['Banana', 'Banane'],
};

const merged = mergeTranslations([
  { language: 'it', translations: translationsIt },
  { language: 'en', translations: translationsEn },
]);

/* this is how the result will be
{
  pear: { it: 'Pera', en: 'Pear' },
  banana: {
    it: ['Banana', 'Banane'],
    en: ['Banana', 'Bananas'],
  },
};
*/

Coverage

File % Stmts % Branch % Funcs % Lines
All files 99 91 100 99

Licence

MIT © Federico Moretti

About

Translate your React app without any hassle and with no setup!

Resources

License

Stars

Watchers

Forks

Packages

No packages published