Rasengan I18n

The @rasenganjs/i18n makes it easy to add internationalization (i18n) to your Rasengan.js applications. It lets you manage translations using simple, static JSON files—keeping your localization workflow clear, fast, and scalable.

Installation

npm install @rasenganjs/[email protected]

Usage

Configuration

First thing first, you have to configure the i18n package into the rasengan.config.js file by importing the plugin and passing it to the vite plugins array.

import { defineConfig } from 'rasengan';
import i18n from '@rasenganjs/i18n/plugin';

export default defineConfig(async () => {
  return {
    vite: {
      plugins: [
        i18n({
          defaultLocale: 'fr',
          resources: {
            source: '/src/messages', // The path to the messages directory
          },
        }),
      ],
    },
  };
});

The i18n plugin takes a configuration object with the following properties:

| Name | Type | Description | Optional | Default | | ---------------- | ------ | ----------------------------------- | -------- | -------------- | | defaultLocale | string | The default locale to use. | false | - | | resources.source | string | The path to the messages directory. | true | src/messages |

Messages

The messages directory should contain JSON files for each locale, with the following structure:

{
  "translation": {
    "greeting": "Hello, World!"
  }
}

Every JSON file should have a translation key that contains the translations for that locale.

Register the Provider

You have to register the RasenganI18nProvider component at the root of your application inside the root layout file.

import { LayoutComponent, Outlet } from 'rasengan';
import { RasenganI18nProvider } from '@rasenganjs/i18n';

const RootLayout: LayoutComponent = () => {
  return (
    <RasenganI18nProvider>
      <Outlet />
    </RasenganI18nProvider>
  );
};

RootLayout.path = '/'; // Only work while using a Config-based routing

export default RootLayout;

Don't wrap your application with the RasenganI18nProvider inside the main.tsx file, prefer to wrap it inside the root layout file.

Hooks

The @rasenganjs/i18n package provides a number of hooks to help you manage translations in your application.

| Name | Description | | ---------------- | ------------------------------------------------------------------------- | | useTranslation | Returns a function that returns the current translation based on the key. | | useLocale | Returns the current locale and a function to change it. |

useTranslation

import { useTranslation } from '@rasenganjs/i18n';

const Greeting = () => {
  const t = useTranslation();

  return (
    <div>
      <h1>{t('greeting')}</h1>
    </div>
  );
};

export default Greeting;

The useTranslation hook takes an optional param called namespace that allows you to specify the namespace of the translation you want to use.

Let's suppose we have the following message:

{
  "translation": {
    "home": {
      "header": {
        "greeting": "Hello, World!"
      }
    }
  }
}

And we can use the useTranslation hook like this:

import { useTranslation } from '@rasenganjs/i18n';

const Greeting = () => {
  const t = useTranslation('home');

  return (
    <div>
      <h1>{t('header.greeting')}</h1>
    </div>
  );
};

export default Greeting;

useLocale

From the useLocale hook, you can get the current locale and a function to change it.

import { useLocale } from '@rasenganjs/i18n';

const Navbar = () => {
  const { locale, setLocale } = useLocale();

  return (
    <div>
      <h1>{locale}</h1>
      <button onClick={() => setLocale('en')}>English</button>
      <button onClick={() => setLocale('fr')}>French</button>
    </div>
  );
};

export default Navbar;

Note: The value passed to setLocale must be one of the locales defined into your messages directory.

Community

The Rasengan.js community can be found on GitHub Discussions where you can ask questions, voice ideas, and share your projects with other people.

We also have a Twitter account where you can follow us to get the latest news about Rasengan.js.

License

Rasengan.js is MIT licensed.

Authors

Here is the authors list:

• Dilane Kombou (@dilanekombou)