PACKAGES

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

Terminal

bashnpm 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.

rasengan.config.js

jsimport { 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:

src/messages/en.json

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

WarningEvery 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.

src/app/app.layout.tsx

tsximport { 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.

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

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.

rasengan-env.d.ts

ts/// <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.

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

src/components/greeting.tsx

tsximport { 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:

src/messages/en.json

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

And we can use the useTranslation hook like this:

src/components/greeting.tsx

tsximport { 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.

src/components/navbar.tsx

tsximport { 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: