React Translation

React Translation is an easy-to-use Translation Library for React and React Native! It is thought to be used with shared libraries and without instance conflicts.

/!\ Version 0.7 to 0.8 breaking change

React and React Native components are not seamlessly integrated together. Which means that it is now possible to use in the same way the Translation component for both React and React Native.

Disclaimers

Even if React Translation is quite stable by its simplicity, and you can easily use it on your tools, this is still a work in progress project and potential breaking changes may happen especially in the way that translations are being declared. I'm very glad to get feedbacks from you as it helps to improve this library at its early stage.

Documentation

You can find the documentation here

Installation

npm install --save @psyycker/react-translation

Usage

Initialise the library

In your index file (and in case of the usage of a shared library, in any index file) Import directly the library to initialise the events:

import "@psyycker/react-translation"

Set default config

By default, no locale is set, you can define it by calling the function

import { setTranslationConfig } from "@psyycker/react-translation"
// Always call first before initialising the config
import "@psyycker/react-translation"

// Do not call inside a component
setTranslationConfig({
  defaultLocale: "en-US"
})

Translation Files

First, you'll need to define your translation files. Both JSON and JS objects are supported You can nest properties to make it more readable

{
  "component": {
    "title": "My Value"
  }
}

Register your translation files

Let's say you have 2 files. One for English (US) and one for French

translations
    |-- french.json
    |-- english-us.json

import { registerTranslations } from "@psyycker/react-translation";
import french from "./translations/french.json";
import englishUS from "./translations/english-us.json";

registerTranslations({
  "en-US": englishUS,
  "fr-FR": french
})

You can split your translation files and register them at different places. They will be merged

Translate

With React

Using Hooks

import { useTranslation, changeLocale } from "@psyycker/react-translation"; import {useEffect} from "react";

function MyComponent() {

  const { getTranslation } = useTranslation();

  return (
    <div>{getTranslation({
      translationKey: "component.title",
      defaultValue: "My Default Value"
    })}</div>
  )
}

Using Component

import { Translation, changeLocale } from "@psyycker/react-translation"; import {useEffect} from "react";

function MyComponent() {

  return (
    <div>
          <Translation 
            translationKey="component.title" 
            defaultValue="My default value"
         />
    </div>
  )
}

With React Native

import { useTranslation, changeLocale } from "@psyycker/react-translation"; import {useEffect} from "react";

function MyComponent() {

  const { getTranslation } = useTranslation();

  return (
    <Text>{getTranslation({
      translationKey: "component.title",
      defaultValue: "My Default Value"
    })}</Text>
  )
}

Using Component

import { Translation, changeLocale } from "@psyycker/react-translation"; import {useEffect} from "react";
import { StyleSheet } from "react-native"

const styles = StyleSheet.create({
  textStyle: {
    ...
  }
})

function MyComponent() {

  return (
    <View>
          <Translation 
            // If you want to apply a react native style on Text Component
            style={styles.textStyle}
            translationKey="component.title" 
            defaultValue="My default value"
         />
    </View>
  )
}

API of Translation Component

| Property | Type | Optional | Description | |----------------|--------|----------|------------------------------------------------------------------------------| | translationKey | String | | The key defined in the JSON file | | defaultValue | String | | The default value if the key is not found | | parameters | Object | Yes | An object which contains the values which replace {} in the string | | style | Object | Yes | Can either be a CSS in JS style (React) or a Stylesheet style (React Native) |

Using parameters

You might want to inject parameters in your translations. You can do so by using {<yourVariableName>} format (See below)

{
  "component": {
    "title": "Hello {input}"
  }
}

And then, you can inject it using the parameters property

import { Translation, changeLocale } from "@psyycker/react-translation"; 
import {useEffect} from "react";

function MyComponent() {

  return (
    <>
          <Translation 
            translationKey="component.title" 
            defaultValue="My default value"
            parameters={{
              input: "My custom input"
            }}
         />
    </>
  )
}

You can also do it by calling:

    getTranslation({
      translationKey: "component.title",
      defaultValue: "My Default Value",
      parameters: { input: "My Custom Input" }
})

Change the locale

You can easily change the locale by doing:

import { changeLocale } from "@psyycker/react-translations";

    ...

    function onLocaleChange(newLocale){
      changeLocale(newLocale)
    }

    ... // Probably some ui to change the locale!
    

ROADMAP

See the roadmap here

Development and examples

See development.md to see how to use the examples and participate in the repo

License

MIT