rt4lang

React i18n library with built-in per-language font loading and fallback support.

Install

npm install rt4lang

Peer dependencies: react >=17, react-dom >=17.

Quick Start

1. Create a config file

// rt4lang.config.ts
import { createRt4Lang } from "rt4lang";

export default createRt4Lang({
  defaultLanguage: "en",
  languages: {
    en: {
      label: "English",
      messages: {
        greeting: "Hello {{name}}",
        cart: {
          empty: "Your cart is empty",
          itemCount: "{{count}} item in cart | {{count}} items in cart",
        },
      },
      font: {
        family: "Inter",
        fallback: ["Arial", "sans-serif"],
        source: "google",
        weights: [400, 500, 700],
      },
    },
    bn: {
      label: "বাংলা",
      messages: {
        greeting: "হ্যালো {{name}}",
        cart: {
          empty: "আপনার কার্ট খালি",
          itemCount: "কার্টে {{count}}টি পণ্য",
        },
      },
      font: {
        family: "Hind Siliguri",
        fallback: ["SolaimanLipi", "sans-serif"],
        source: "google",
        weights: [400, 600],
      },
    },
  },
});

2. Wrap your app with <LanguageProvider>

import { LanguageProvider } from "rt4lang";
import rt4Config from "./rt4lang.config";

function App() {
  return (
    <LanguageProvider config={rt4Config}>
      <YourApp />
    </LanguageProvider>
  );
}

3. Use the hooks

import { useTranslation, useLanguage } from "rt4lang";

function Header() {
  const { t, language } = useTranslation();
  const { languages, setLanguage } = useLanguage();

  return (
    <header>
      <h1>{t("greeting", { name: "Rafid" })}</h1>
      <select value={language} onChange={(e) => setLanguage(e.target.value)}>
        {languages.map((l) => (
          <option key={l.code} value={l.code}>
            {l.label}
          </option>
        ))}
      </select>
    </header>
  );
}

Font Configuration

Each language can declare its own font. The library automatically loads and applies it when the language is active.

Google Fonts

font: {
  family: "Hind Siliguri",
  fallback: ["sans-serif"],
  source: "google",
  weights: [400, 600],
}

The library builds the Google Fonts CSS2 URL and injects a <link> tag. Font is cached — switching back doesn't re-inject.

Custom URL

font: {
  family: "MyBrandFont",
  source: "url",
  files: [
    { url: "/fonts/brand-regular.woff2", weight: 400 },
    { url: "/fonts/brand-bold.woff2", weight: 700 },
  ],
}

Injects a <style> block with @font-face rules.

Local / Self-hosted

font: {
  family: "MyLocalFont",
  source: "local",
}

No injection — assumes the font is already available via your own CSS. The library only sets the CSS variable.

CSS Variable

The library sets --rt4lang-font-family on document.documentElement (by default). Use it in your global CSS:

body {
  font-family: var(--rt4lang-font-family);
}

Or let the provider inject a scoped style by passing applyFontTo="provider".

API Reference

createRt4Lang(config)

Returns a config object with sensible defaults. No side effects.

Option	Type	Default	Description
defaultLanguage	string	required	Language code used on first visit
fallbackLanguage	string	defaultLanguage	Language to fall back to for missing keys
persist	boolean	true	Save language choice to localStorage
storageKey	string	"rt4lang-language"	localStorage key
applyFontTo	"root" | "provider" | "none"	"root"	Where to set the CSS font variable
languages	Record<string, LanguageDefinition>	required	Language definitions

<LanguageProvider config={...}>

Prop	Type	Description
config	Rt4LangConfig	Output of createRt4Lang()
children	ReactNode	Your app tree

useTranslation()

Returns { t, language }.

• t(key: string, vars?: Record<string, string | number>) — looks up a translation key, applies interpolation and pluralization.
• language — current language code.

useLanguage()

Returns { language, languages, setLanguage, isFontLoading }.

• language — current language code.
• languages — array of { code, label } for all configured languages.
• setLanguage(code) — switch language (loads font, persists choice).
• isFontLoading — true while the new language's font is loading.

Pluralization

Use the "singular | plural" pattern with a count variable:

messages: {
  itemCount: "{{count}} item | {{count}} items",
}

t("itemCount", { count: 1 });  // "1 item"
t("itemCount", { count: 5 });  // "5 items"

Interpolation

Use {{variableName}} in messages:

t("greeting", { name: "Rafid" });  // "Hello Rafid"

Missing Keys

Missing keys return the key itself and log a warning to the console:

t("missing.key");  // "missing.key" + console.warn

SSR / Next.js

The library is SSR-safe — no window/document access happens during render. All DOM work (font loading, CSS variable injection) happens inside useEffect in the provider.

For Next.js App Router, wrap your root layout:

"use client";
import { LanguageProvider } from "rt4lang";
import rt4Config from "./rt4lang.config";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <LanguageProvider config={rt4Config}>
          {children}
        </LanguageProvider>
      </body>
    </html>
  );
}

License

MIT