React - Easy Translation

Easily add language translations to your React/Next application.

Prerequisites

This project was built using React (version 19.0.0).

Table of contents

• Easy Peasy Translation
  • Table of contents
  • Installation
  • Usage
    • LanguageProvider Context
    • Language Files
    • useTranslation Hook
    • translate function
    • group function
    • Translation Component
  • Versioning
  • Authors

Installation

To install the library, run:

$ npm i easy-peasy-translation

Usage

LanguageProvider

The LanuageProvider must be added to the top level of your application as it sets up the required Context.

Props:

url (Optional) - Used for remote files

| Type | Description | | ------ | ------------------------------------------------------------------------------------------------------- | | string | The url to language files directory. If not included will look in your server public "locale" directory |

files (Optional) - Used for local files

| Type | Description | | ------------------- | -------------------------------------------------------------------------- | | Array(LanguageFile) | A list of Language File objects ({name: "en", file: en}) see example below |

supported (Required)

| Type | Description | | ------------- | --------------------------- | | Array[string] | List of supported languages |

Example:

For ReactJS. The provider can be added directly to the top level.

Remote URL

import { LanguageProvider } from "easy-peasy-translation";
function main() {
  return (
    <LanguageProvider
      url="<http path to language directory>"
      supported={["en", "fr"]}
    >
      <div>...</div>
    </LanguageProvider>
  );
}
export default main;

Local Files

import { LanguageProvider } from "easy-peasy-translation";

import en from "./features/Languages/en.json";
import fr from "./features/Languages/fr.json";
function main() {
  return (
    <LanguageProvider
      files={[
        { name: "en", file: en },
        { name: "fr", file: fr },
      ]}
      supported={["en", "fr"]}
    >
      <div>...</div>
    </LanguageProvider>
  );
}
export default main;

For NextJS. The provider needs to be added from inside a client component.

function main() {
  return (
    <Lang>
      <div>...</div>
    </Lang>
  );
}
export default main;

"use client";
import React from "react";
import { LanguageProvider } from "easy-peasy-translation";

function Lang({ children }: { children: React.ReactNode }) {
  return (
    <LanguageProvider
      url="<http path to language directory>"
      supported={["en", "fr"]}
    >
      {children}
    </LanguageProvider>
  );
}
export default Lang;

Language Files

Language files are JSON files that are seperated into sections. Language files must be localed in at publicly accessable url. http://someurl.com/locale

If url is not supplied, falls back to '/Public/Locale/'

Language file names must be named based on the supported language:

Files:

• en.json
• fr.json

The first section for each language file MUST have the "@" section. See below for an example.

Usage:

Basic

{
  "@": {
    "key": "This is the text to be translated"
  }
}

Multiple (Pipe split)

{
  "@": {
    "key": "This is the text | to translate to that is indexed"
  }
}

Tokenized

{
  "@": {
    "key": "This is a token [$0] and some more tokens [$1] [$2]"
  }
}

Example:

en.json

{
  "@": {
    "title": "This is an English language file",
    "multiple": "This is a string | That can be indexed",
    "tokens": "This is an indexed string | With tokens [$0] [$1]"
  },
  "section1": {
    "title": "This is section one",
    "tokens": "This is a string with tokens [$0] [$1]"
  },
  "section2": {
    "title": "This is section two",
    "subtitle": "This is section two"
  }
}

useTranslation

This is the most common way to use the translation library.

Usage:

useTranslation("section");

Options:

section (Optional)

| Type | Default value | Description | | ------ | ------------- | ------------------------------------------------------- | | string | undefined | All translations will use a passed "section" as default |

Translate

Usage:

translate("@text@", "section", ["tokens"])[idx];

Options:

@text@ (Required)

| Type | value | Description | | ------ | -------- | ---------------------------------------------------------------- | | string | "@text@" | The translation key that must match the key in the language file |

section (Optional)

| Type | value | Description | | ------ | --------- | --------------------------------------------- | | string | "section" | Section of the language file this key exists. |

if "-" is passed in the section field. Looks in the current section.

tokens (Optional)

| Type | value | Description | | -------------- | -------------------- | ---------------------------------------------------------------------------- | | Array[strings] | ["token1", "token2"] | Token strings. Language matches tokens on an index. See language file above. |

Basic

translate("@title@");

Multiple (Pipe split)

translate("@multiple@")[0];
translate("@multiple@")[1];

Tokenized

translate("@tokens@", "section1", ["token1", "token2"]);

Example:

import { useTranslation } from "easy-peasy-translation";

function MyComponent() {
  const { translate: t } = useTranslation("section1"); // Switch default to Section1

  return (
    <div>
      <p>{t("@title@")}</p>
      <p>{t("@title@", "@")}</p>
      <p>{t("@multple@", "@")[1]}</p>
      <p>{t("@tokens@", "@", ["token1", "token2"])[1]}</p>
      <p>{t("@title@", "section2")}</p>
    </div>
  );
}
export default MyComponent;

Translate Group

This function can be used to translate an Array of Translation Objects

Usage:

group([{ text: "@text@", section: "section", tokens: ["tokens"] }]);

Options:

object (Required)

| Type | value | Description | | --------- | ----------------- | ------------------------------------ | | Array[{}] | [{text:"@text@"}] | Pass an array of Translation Objects |

Basic

import { useTranslation } from "easy-peasy-translation";

function MyComponent() {
  const { group: t } = useTranslation();
  const translations = t([{ text: "@title@" }, { text: "@subtitle@" }]);

  return (
    <div>
      <p>{translations.title}</p>
      <p>{translations.subtitle}</p>
    </div>
  );
}
export default MyComponent;

Multiple (Pipe split)

import { useTranslation } from "easy-peasy-translation";

function MyComponent() {
  const { group: t } = useTranslation();
  const translations = t([{ text: "@multiple@" }]);

  return (
    <div>
      <p>{translations.multiple[0]}</p>
      <p>{translations.multiple[1]}</p>
    </div>
  );
}
export default MyComponent;

Tokenized

import { useTranslation } from "easy-peasy-translation";

function MyComponent() {
  const { group: t } = useTranslation("section1");
  const translations = t([
    { text: "@tokens@", "-", ["token1", "token2"] }
  ]);

  return (
    <div>
      <p>{translations.tokens}</p>
    </div>
  );
}
export default MyComponent;

Example:

import { useTranslation } from "easy-peasy-translation";

function MyComponent() {
  const { group: t } = useTranslation("Section2");
  const translations = t([
    { text: "@title@" },
    { text: "@subtitle@" },
    { text: "@tokens@", category: "@", tokens: ["token1", "token2"] },
  ]);

  return (
    <div>
      <p>{translations.title}</p>
      <p>{translations.subtitle}</p>
      <p>{translations.tokens[0]}</p>
      <p>{translations.tokens[1]}</p>
    </div>
  );
}
export default MyComponent;

Translation

The Translation Component can also be used. This component translates @text@ tokens by passing JSX.

Options:

category (Required)

| Type | Default value | Description | | ------ | ------------- | ---------------------------------------------------------------- | | string | undefined | The translation key that must match the key in the language file |

@text@ (Required)

| Type | Default value | Description | | ------ | ------------- | ------------------------------------------------------- | | string | "" | All translations will use a passed "section" as default |

Example:

"use client";
import { Translation } from "easy-peasy-translation";

function MyComponent() {
  return (
    <div>
      <Translation category={"Section2"}>
        <h3>@title@</h3>
        <p>@subtitle@</p>
      </Translation>
    </div>
  );
}
export default MyComponent;

Versioning

• 1.0.4
• 1.0.2
• 1.0.1
• 1.0.0

Authors

• Wallace Krumrei - WallaceKrumrei