Internationalization (i18n)

Documentation for configuring a project to leverage the various internationalization (i18n) / localization (l10n) tools.

At its core, our i18n utilities are driven by the popular i18next javascript library. The hope is through use of our various actors and utilities, configuration is greatly simplified for javascript applications.

Adding languages / cultures

We like typescript at andculture, so we've setup our utilities to benefit from typings. Before we can even initialize the application, we must have some languages/cultures created.

The andculture core package provides various typed version of languages (ie. BaseEnglishUnitedStates, BaseSpanishSpain). Using the LocalizationUtils.cultureFactory you can create an application versions.

First define your translation keys with an interface

// interfaces/CultureResources.ts

interface CultureResources {
    createAnAccount: string;
    signIn: string;
}

export { CultureResources };

Create your application culture files

// cultures/english-united-states.ts

import {
    BaseEnglishUnitedStates,
    Culture,
    LocalizationUtils,
} from "andculturecode-javascript-core";
import CultureResources from "interfaces/culture-resources";

const EnglishUnitedStates: Culture<CultureResources> = LocalizationUtils.cultureFactory(
    BaseEnglishUnitedStates,
    {
        resources: {
            createAnAccount: "Create An Account",
            signIn: "Sign In",
        },
    }
);

export default EnglishUnitedStates;

// cultures/spanish-spain.ts

import {
    BaseEnglishUnitedStates,
    Culture,
    LocalizationUtils,
} from "andculturecode-javascript-core";
import CultureResources from "interfaces/culture-resources";

const SpanishSpain: Culture<CultureResources> = LocalizationUtils.cultureFactory(
    BaseSpanishSpain,
    {
        resources: {
            createAnAccount: "Crea una cuenta",
            signIn: "Registrarse",
        },
    }
);

export default SpanishSpain;

Initialization

During startup of your application, an initialization is required before other code call request translations, change language, or so forth.

With your newly created culture files created, initialize your application.

// app.tsx

import CultureResources from "interfaces/culture-resources";
import { LocalizationUtils } from "andculturecode-javascript-core";
import EnglishUnitedStates from "cultures/english-united-states";
import SpanishSpain from "cultures/spanish-spain";

const module = {}; // ie. in react it would be initReactI18next

LocalizationUtils.initialize<CultureResources>(module, [
    EnglishUnitedStates,
    SpanishSpain,
]);

Detect language

With the application initialized with your cultures, setup your application to detect and initialize the requested culture/language.

// app.tsx

useEffect(() => {

    const cultureCode = LocalizationUtils.detectCultureCode();
    ServiceUtils.configureCultureCode(cultureCode);

});

Translate your application!

Now that your application is fully configured, go ahead and swap out any hard-coded strings with translation functions

// views/my-view.tsx

import { LocalizationUtils } from "andculturecode-javascript-core";

...

<h1>{LocalizationUtils.t("createAnAccount")</h1>