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/i18n@1.0.0-beta.3

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:

Messages

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

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

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';
import i18n from 'virtual:rasengan/i18n';
 
const RootLayout: LayoutComponent = () => {
  return (
    <RasenganI18nProvider i18n={i18n}>
      <Outlet />
    </RasenganI18nProvider>
  );
}
 
RootLayout.path = '/:locale?'; // Only work while using a Config-based routing
 
export default RootLayout;

If you prefere using the file-based routing feature, you have to put your RootLayout inside the src/app/_routes/[_locale]/layout.tsx file.

This is recommended because the @rasenganjs/i18n package will automatically detect the current locale from the url.

If you are using TypeScript, you have to configure types into the rasengan-env.d.ts file. This will add the types support for the virtual modules virtual:rasengan/i18n.

/// <reference types="rasengan/types/client" />
/// <reference types="@rasenganjs/i18n/types/client" />

Hooks

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

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

Join the Rasengan.js community to get support, ask questions, and share your projects:

• GitHub Discussions – Ask questions and share ideas.

• X (Twitter) – Stay updated with the latest news.
• Linkedin – Follow the company page.

Let's build something amazing with Rasengan.js! 🚀

License

This package is MIT licensed.