easy-translation

React - Easy Translation

Easily add language translations to your React application.

Table of contents

• Project Name
  • Table of contents
  • Installation
  • Usage
    • LanguageProvider Context
    • Language Files
    • useTranslation Hook
    • translate function
    • t group function
    • Translation Component
  • Built With
  • Authors

Installation

To install the library, run:

$ npm i easy-translation

Usage

LanguageProvider

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

url (Optional)

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

supported (Required)

Type	Description
Array[string]	List of supported languages

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

import { LanguageProvider } from "easy-translation";
function main() {
  return (
    <LanguageProvider
      url="<http path to language directory>"
      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-translation";

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

LanguageFiles

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: Example:

• en.json
• fr.json

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

en.json

{
  "@": {
    "title": "This is an English language file",
    "multiple": "This is a string | That can be indexed", // Split by pipe
    "tokens": "This is an indexed string | With tokens [$0] [$1]" // Matches array index
  },
  "Section1": {
    "title": "This is section one"
  },
  "Section2": {
    "title": "This is section two",
    "subtitle": "This is section two"
  }
}

useTranslation

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

Example:

import { useTranslation } from "easy-translation";

function MyComponent() {
  const {translate} = useTranslation(); // @ section (see options below for passing sections)

  return (
    <div>
      <h2>{translate("@title@")}</h2>
      <p>{translate("@multple@")[0]}</p>
      <p>{translate("@multple@")[1]}</p>
      <p>{translate("@tokens@")[0]}</p>
      <p>{translate("@tokens@", "-", ["token1", "token2"])[1]}</p>
      <p>{translate("@title@", "Section1")[}</p>
    </div>
  );
};
export default MyComponent

useTranslation("section");

Options:

section (Optional)

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

Translate

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

Example:

import { useTranslation } from "easy-translation";

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

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

Options:

@text@ (Required)

Type	Default value	Description
string	""	The translation key that must match the key in the language file

section (Optional)

Type	Default value	Description
string	undefined	Section of the language file this key exists.

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

tokens (Optional)

Type	Default value	Description
Array[Strings]	undefined	Token strings. Language matches tokens on an index. See language file above.

TranslateGroup

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

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

Example:

import { useTranslation } from "easy-translation";

function MyComponent() {
  const { 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

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

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

Built With

• React

Versioning

• 1.2.0

Authors

• Wallace Krumrei - WallaceKrumrei