Getting Started Internationalising (i18n) with Intlayer and Lynx and React

What is Intlayer?

Intlayer is an innovative, open-source internationalisation (i18n) library that simplifies multilingual support in modern applications. It works in many JavaScript/TypeScript environments, including Lynx (via the react-intlayer package).

With Intlayer, you can:

• Easily manage translations using declarative dictionaries at the component level.
• Ensure TypeScript support with autogenerated types.
• Dynamically localise content, including UI strings (and in React for web, it can also localise HTML metadata, etc.).
• Benefit from advanced features, like dynamic locale detection and switching.

Step 1: Install Dependencies

From your Lynx project, install the following packages:

npm install intlayer react-intlayer lynx-intlayer

Packages

• intlayer
  The core i18n toolkit for configuration, dictionary content, types generation, and CLI commands.

• react-intlayer
  React integration that provides the context providers and React hooks you’ll use in Lynx for obtaining and switching locales.

• lynx-intlayer
  Lynx integration that provides the plugin for integrating Intlayer with the Lynx bundler.

Step 2: Create an Intlayer Config

In your project root (or anywhere convenient), create an Intlayer config file. It might look like this:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalisation: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // ... Add any other locales you need    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

Within this config, you can:

• Configure your list of supported locales.
• Set a default locale.
• Later, you may add more advanced options (e.g., logs, custom content directories, etc.).
• See the Intlayer configuration docs for more.

Step 3: Add the Intlayer plugin to the Lynx bundler

To use Intlayer with Lynx, you need to add the plugin to your lynx.config.ts file:

import { defineConfig } from "@lynx-js/rspeedy";import { pluginIntlayerLynx } from "lynx-intlayer/plugin";export default defineConfig({  plugins: [    // ... other plugins    pluginIntlayerLynx(),  ],});

Step 4: Add the Intlayer provider

To keep synchronised the user language across your application, you need to wrap your root component with the IntlayerProvider component from react-intlayer.

Also, you need to add the intlayerPolyfill function file to ensure that Intlayer can work properly.

import { root } from "@lynx-js/react";import { App } from "./App.js";import { IntlayerProvider } from "react-intlayer";import { intlayerPolyfill } from "lynx-intlayer";intlayerPolyfill();root.render(  <IntlayerProvider>    <App />  </IntlayerProvider>);if (import.meta.webpackHot) {  import.meta.webpackHot.accept();}

Step 5: Declare Your Content

Create content declaration files anywhere in your project (commonly within src/), using any of the extension formats that Intlayer supports:

• .content.ts
• .content.mjs
• .content.cjs
• .content.json
• etc.

Example (TypeScript with TSX nodes for Lynx):

import { t, type Dictionary } from "intlayer";const appContent = {  key: "app",  content: {    title: "React",    subtitle: t({      "en-GB": "on Lynx",      en: "on Lynx",      fr: "sur Lynx",      es: "en Lynx",    }),    description: t({      "en-GB": "Tap the logo and have fun!",      en: "Tap the logo and have fun!",      fr: "Appuyez sur le logo et amusez-vous!",      es: "¡Toca el logo y diviértete!",    }),    hint: [      t({        "en-GB": "Edit",        en: "Edit",        fr: "Modifier",        es: "Editar",      }),      " src/App.tsx ",      t({        "en-GB": "to see updates!",        en: "to see updates!",        fr: "pour voir les mises à jour!",        es: "para ver actualizaciones!",      }),    ],  },} satisfies Dictionary;export default appContent;

For details on content declarations, see Intlayer’s content docs.

Step 4: Use Intlayer in Your Components

Use the useIntlayer hook in child components to get localised content.

import { useCallback, useState } from "@lynx-js/react";import { useIntlayer } from "react-intlayer";import "./App.css";import arrow from "./assets/arrow.png";import lynxLogo from "./assets/lynx-logo.png";import reactLynxLogo from "./assets/react-logo.png";import { LocaleSwitcher } from "./components/LocaleSwitcher.jsx";export const App = () => {  const [alterLogo, setAlterLogo] = useState(false);  const { title, subtitle, description, hint } = useIntlayer("app");  const onTap = useCallback(() => {    "background only";    setAlterLogo(!alterLogo);  }, [alterLogo]);  return (    <view>      <view className="Background" />      <view className="App">        <view className="Banner">          <view className="Logo" bindtap={onTap}>            {alterLogo ? (              <image src={reactLynxLogo} className="Logo--react" />            ) : (              <image src={lynxLogo} className="Logo--lynx" />            )}          </view>          <text className="Title">{title}</text>          <text className="Subtitle">{subtitle}</text>        </view>        <view className="Content">          <image src={arrow} className="Arrow" />          <text className="Description">{description}</text>          <text className="Hint">            {hint[0]}            <text style={{ fontStyle: "italic" }}>{hint[1]}</text>            {hint[2]}          </text>        </view>        <LocaleSwitcher />        <view style={{ flex: 1 }}></view>      </view>    </view>  );};

When using content.someKey in string-based props (e.g., a button’s title or a Text component’s children), call content.someKey.value to get the actual string.

(Optional) Step 5: Change the App Locale

To switch locales from within your components, you can use the useLocale hook’s setLocale method:

import { type FC } from "react";import { getLocaleName } from "intlayer";import { useLocale } from "react-intlayer";export const LocaleSwitcher: FC = () => {  const { setLocale, availableLocales, locale } = useLocale();  return (    <view      style={{        display: "flex",        flexDirection: "row",        justifyContent: "centre",        alignItems: "centre",        gap: 10,      }}    >      {availableLocales.map((localeEl) => (        <text          key={localeEl}          style={{            colour: localeEl === locale ? "#fff" : "#888",            fontSize: "12px",          }}          bindtap={() => setLocale(localeEl)}        >          {getLocaleName(localeEl)}        </text>      ))}    </view>  );};

This triggers a re-render of all components that use Intlayer content, now showing translations for the new locale.

See useLocale docs for more details.

Configure TypeScript (if you use TypeScript)

Intlayer generates type definitions in a hidden folder (by default .intlayer) to improve autocompletion and catch translation errors:

// tsconfig.json{  // ... your existing TS config  "include": [    "src", // your source code    ".intlayer", // <-- ensure the auto-generated types are included    // ... anything else you already include  ],}

This is what enables features like:

• Autocompletion for your dictionary keys.
• Type checking that warns if you access a non-existent key or mismatch the type.

Git Configuration

To avoid committing auto-generated files by Intlayer, add the following to your .gitignore:

# Ignore the files generated by Intlayer.intlayer

Go Further

• Visual Editor: Use the Intlayer Visual Editor to manage translations visually.
• CMS Integration: You can also externalise and fetch your dictionary content from a CMS.
• CLI Commands: Explore the Intlayer CLI for tasks like extracting translations or checking missing keys.