README.md

react-littera

🌐 Modern react library for managing translations.

Features

• ⚡ Lightning fast
• 🧩 Variable translations
• 🗃️ User defined presets
• 👶 Shallow learning curve
• ♻️ Reusable

About

Littera was created to make maintaining and managing translations easier. It allows placing translations right beside your component as well as storing translations globally. Littera's structure was inspired by react-jss.

Here below we have a translations object which is accepted by the core translate function, which then returns the translated string for the correct language. It can be passed to the useLittera hook or withLittera HOC.

{
    welcome: {
        en_US: "Welcome",
        pl_PL: "Witamy",
        de_DE: "Willkommen"
    }
}

Let's say the active language is en_US (English), the output will be:

{
    welcome: "Welcome"
}

Simply explained

Let's assume you want to have a translations system in your React app that updates all the text when the language changes. Bam! All you need to do is: define a simple object that lists all translated strings for each language. Then pass it to a hook and it will return a reduced object with translations only for active language. Display it like any other string. Ready.

Installation

via npm

npm install @assembless/react-littera

via yarn

yarn add @assembless/react-littera

or clone/download the repository.

Usage

First you have to wrap your components with a provider and feed it with a list of available languages.

import React, { useState } from "react";
import ReactDOM from "react-dom";

import { LitteraProvider } from "@assembless/react-littera";

function App() {
    return (
        <div className="App">
            <LitteraProvider locales={[ "en_US", "pl_PL", "de_DE" ]}>
                <YourApp />
            </LitteraProvider>
        </div>
    );
}

const rootElement = document.getElementById("root");
ReactDOM.render(<App />, rootElement);

Now you can make use of Littera by adding translations directly into your component.

Here we have two options:

• Hooks (recommended)
• HOC (deprecated)

Hooks Example

Basic

import React from "react";
import { useLittera } from "@assembless/react-littera";

// Object containing translations for each key...
const translations = {
    example: {
        en_US: "Example",
        pl_PL: "Przykład",
        de_DE: "Beispiel"
    }
};

const ExampleComponent = () => {
    // Obtain our translated object.
    const translated = useLittera(translations);
    // Get access to global littera methods for currect context.
    const methods = useLitteraMethods();

    const handleLocaleChange = () => {
        // Change language to German.
        methods.setLocale("de_DE");
    }

    return <button onClick={handleLocaleChange}>{translated.example}</button>;
};

export default ExampleComponent;

Variable translations

import React from "react";
import { useLittera } from "@assembless/react-littera";

const translations = {
    // Use a function for variable translations.
    hello: (name) => ({
        en_US: `Hello ${name}`,
        pl_PL: `Cześć ${name}`,
        de_DE: `Hallo ${name}`
    })
};

const ExampleComponent = () => {
    // Obtain our translated object.
    const translated = useLittera(translations);

    // Call the method obtained from our translated object with required arguments.
    const varTranslation = translated.hello("Mike");

    return <button onClick={handleLocaleChange}>{varTranslation}</button>;
};

export default ExampleComponent;

Array translations

import React from "react";
import { useLittera } from "@assembless/react-littera";

const translations = {
    greetings: [
        {
            de_DE: "Guten Tag",
            en_US: "Good morning"
        },
        {
            de_DE: "Hallo",
            en_US: "Hello"
        },
    ]
};

const ExampleComponent = () => {
    // Obtain our translated object.
    const translated = useLittera(translations);

    // Get the translated strings from the array.
    const varTranslation = translated[0]; // => Good morning

    return <button onClick={handleLocaleChange}>{varTranslation}</button>;
};

export default ExampleComponent;

HOC Example

import React from "react";
import { withLittera } from "@assembless/react-littera";

// Object containing translations for each key...
const translations = {
    example: {
        en_US: "Example",
        pl_PL: "Przykład",
        de_DE: "Beispiel"
    }
};

class ExampleComponent extends React.Component {

    handleLocaleChange() {
        const { setLocale } = this.props;

        setLocale("de_DE");
    }

    render() {
        const { translated } = this.props;

        return <button onClick={this.handleLocaleChange}>{translated.example}</button>;
    }
}

export default withLittera(translation)(ExampleComponent);

API

LitteraProvider

type: ReactContext<ILitteraProvider>

Component providing the core context. To use withLittera and useLittera properly, you have to wrap your components with this provider.

Key	Description	Type	Default
initialLocale	Initial language.	string
locales	List of available languages.	Array<string>	[ "en_US" ]
setLocale	Callback called when active language changes.	(locale: string) => void
preset	Preset of translations.	{ [key: string]: { [locale: string]: string } }	{}
pattern	Locale pattern. Default format is xx_XX.	RegExp	/[a-z]{2}_[A-Z]{2}/gi
detectLocale	Tries to detect the browser language. Overriding initialLocale if detected. Not available yet for React Native!	boolean	false

withLittera - HOC

type: (translations: ITranslations) => (Component: React.FunctionComponent) => JSX.Element

A HOC, you feed it with translations(ITranslations) and a component which then gets the translated object passed via prop (e.g. withLittera(translations)(Component)).

Key	Description	Type	Default
translated	Translated object	ITranslated
setLocale	Changes active language	(locale: string) => void
preset	Preset of translations	{ [key: string]: { [locale: string]: string } }	{}
locale	Active language	string	en_US

useLittera - Hook

type: (translations: ITranslations) => ITranslated

A Hook, you feed it with translations(ITranslations) and it returns translated(ITranslated).

useLitteraMethods - Hook

type: () => { see methods below }

This hook exposes following methods:

Key	Description	Type
locale	Active language	string
locales	List of all locales	string[]
setLocale	Changes active language	(locale: string) => void
validateLocale	Validates locale with pattern	(locale: string, pattern?: RegExp) => boolean
preset	Preset object previously passed to the provider	ITranslations
translate	Core translate method	(translations: T, locale: string) => ITranslated
translateSingle	Core method for translating a single key	<T>(translation: T, locale: string) => ISingleTranslated<T>

Types

ITranslation

{ [locale: string]: string }

{
    de_DE: "Einfach",
    en_US: "Simple"
}

ITranslationVarFn

(...args: (string | number)[]) => ITranslation

(name) => ({
    de_DE: `Hallo ${name}`,
    en_US: `Hello ${name}`
})

ITranslationsArr

ITranslation[]

[
    {
        de_DE: "Beispiel",
        en_US: "Example"
    },
]

ITranslations

{ [key: string]: ITranslation | ITranslationVarFn }

{
    simple: {
        de_DE: "Einfach",
        en_US: "Simple"
    },
    hello: (name) => ({
        de_DE: `Hallo ${name}`,
        en_US: `Hello ${name}`
    }),
    greetings: [
        {
            de_DE: "Guten Tag",
            en_US: "Good morning"
        },
        {
            de_DE: "Hallo",
            en_US: "Hello"
        },
    ]
}

ITranslated

{ [key: string]: string | ((...args: (string | number)[]) => string) | string[] }

{
    simple: "Simple",
    hello: (name) => "Hello Mike", // Run this function to get variable translation.
    greetings: [ "Good morning", "Hello" ]
}

Build instructions

After cloning the repo, install all dependencies using npm install.

Build: npm run build

Test the library: npm test

Migration 1.X => 2.X

The migration process is straightforward. You have to rename some properties and change the way you use useLittera.

Changed naming

• language => locale
• setLanguage => setLocale

Mainly pay attention to LitteraProvider and withLittera props naming.

LitteraProvider changes

The provider accepts 2 new props locales: string[] and initialLocale?: string. You don't need to use your own state from now, the provider will handle it by itself. That makes the locale and setLocale props not required.

// v1.X
import LitteraProvider from "react-littera";

const App = () => {
    const [language, setLanguage] = useState("en_US");

    return <LitteraProvider language={language} setLanguage={setLanguage}>
       ...
    </LitteraProvider>
}

// v2.X
import { LitteraProvider } from "@assembless/react-littera";

const App = () => {

    return <LitteraProvider locales={["en_US", "de_DE", "pl_PL"]}>
       ...
    </LitteraProvider>
}

useLittera changes

The hook returns only the translated object now. Use useLitteraMethods to get/set locale, set pattern etc.

// The translations object remains the same.
const translations = {
    example: {
        "en_US": "Example",
        "de_DE": "Beispiel",
        "pl_PL": "Przykład"
    }
}

// v1.X
const [translated, locale, setLanguage] = useLittera(translations)

// v2.X
const translated = useLittera(translations);
const { locale, setLocale, pattern, setPattern, validateLocale } = useLitteraMethods();

FAQ

Will I need to type all the translations by myself?

Yes, we have not implemented a translator to keep this package simple and lightweight also providing the translations manually guarantees a better user experience.

Does react-littera work with React Native?

React Native compatibility has not been tested but the community reported 100% usability.

You can easily transfer translations with a component.

Just define the translations object in your components file or directory. It will travel with your component, just remember to add @assembless/react-littera as a dependency!

License

MIT License