Development translation guide

Before reading this read the user translation guide, to get familiar with all possible translation options.

Development

All the string visible to the user should be translated using the below explained mechanisms.

useTranslation (hook)

It gets the t function and i18n instance inside your functional components.

Usage

import React from "react";
import { useTranslation } from "react-i18next";

export function MyComponent() {
    const { t, i18n } = useTranslation();
    // or const [t, i18n] = useTranslation();

    return <p>{t("key")}</p>; //returns corresponding translated text from translation files
}

See the useTranslation documentation for more details.

withTranslation (HOC)

The withTranslation is a classic HOC (higher order component) and gets the t function and i18n instance inside your component via props.

Usage

import React from "react";
import { withTranslation } from "react-i18next";

function MyComponent({ t, i18n }) {
    return <p>{t("my translated text")}</p>;
}

export default withTranslation()(MyComponent);

See the withTranslation documentation for more details.

Trans component

While the Trans component gives you a lot of power by letting you interpolate or translate complex react elements - the truth is - in most cases you won't need it.

As long you have no react nodes you like to be integrated into a translated text (text formatting, like strong, i, ...) or adding some link component - you won't need it - most can be done by using the good old t function.

import React from "react";
import { Trans, useTranslation } from "react-i18next";

function MyComponent() {
    const { t } = useTranslation("myNamespace");

    return (
        <Trans t={t} key="keyHelloWorld">
            Hello World
        </Trans>
    );
}

See the withTranslation documentation for more details.

Interesting functions

Interpolation

Use dynamic values in translations.

{
    "key": "{{what}} is {{how}}"
}

Sample

i18next.t("key", { what: "i18next", how: "great" });
// -> "i18next is great"

See the i18next interpolation documentation for further details.

Singular / Plural

i18next features automatic recognition of singular and plural forms.

The variable name must be count!

Keys

{
    "key": "item",
    "key_plural": "items",
    "keyWithCount": "{{count}} item",
    "keyWithCount_plural": "{{count}} items"
}

Example

i18next.t("key", { count: 0 }); // -> "items"
i18next.t("key", { count: 1 }); // -> "item"
i18next.t("key", { count: 5 }); // -> "items"
i18next.t("key", { count: 100 }); // -> "items"
i18next.t("keyWithCount", { count: 0 }); // -> "0 items"
i18next.t("keyWithCount", { count: 1 }); // -> "1 item"
i18next.t("keyWithCount", { count: 5 }); // -> "5 items"
i18next.t("keyWithCount", { count: 100 }); // -> "100 items"

See the i18next singular-plural documentation for more details.

Nesting

Nesting allows you to reference other keys in a translation.

Keys

{
    "nesting1": "1 $t(nesting2)",
    "nesting2": "2 $t(nesting3)",
    "nesting3": "3"
}

Example

i18next.t("nesting1"); // -> "1 2 3"

See the i18next nesting documentation for more details.

Context

By providing a context you can differ translations.

Keys

{
    "friend": "A friend",
    "friend_male": "A boyfriend",
    "friend_female": "A girlfriend"
}

Example

i18next.t("friend"); // -> "A friend"
i18next.t("friend", { context: "male" }); // -> "A boyfriend"
i18next.t("friend", { context: "female" }); // -> "A girlfriend"

See the react-i18next context documentation for more details.

Future work

• Support internationalization of catalog content.