π Type-safe React i18n toolkit with intelligent automation and Server Components support
Features β’ Quick Start β’ Documentation β’ API Reference
English | νκ΅μ΄
i18nexus is a comprehensive React internationalization toolkit that automates the entire i18n workflow with full type safety. With TypeScript config support, automatic string wrapping, and seamless Google Sheets integration, i18nexus eliminates tedious manual work while providing IDE autocomplete for language codes.
- π Accept-Language Auto-Detection - Automatically detects user's browser language
- π¨ Variable Interpolation -
{{variable}}syntax with styled variables - π― Type-Safe Languages - TypeScript config with IDE autocomplete
- π₯οΈ Server Components - Full Next.js App Router support with zero hydration
- π οΈ Developer Tools - React Query-style devtools for visual debugging
- π€ Zero Manual Work - Automatically detect and wrap hardcoded strings
- πͺ Smart Persistence - Cookie-based language management with SSR support
npm install i18nexus
npm install -D i18nexus-tools # Recommended for CLI toolsnpx i18n-sheets initCreates i18nexus.config.json:
{
"languages": ["en", "ko", "ja"],
"defaultLanguage": "en",
"localesDir": "./locales",
"sourcePattern": "app/**/*.{ts,tsx}",
"translationImportSource": "i18nexus"
}Note: i18nexus.config.json is the recommended configuration format. TypeScript config (.ts) is legacy and not recommended for new projects.
// app/layout.tsx
import { createServerI18n } from "i18nexus/server";
import { I18nProvider } from "i18nexus";
export default async function RootLayout({ children }) {
const { language } = await createServerI18n({
availableLanguages: ["en", "ko", "ja"],
defaultLanguage: "en",
});
return (
<html lang={language}>
<body>
<I18nProvider initialLanguage={language}>{children}</I18nProvider>
</body>
</html>
);
}Server Component:
import { createServerI18n } from "i18nexus/server";
export default async function Page() {
const { t, language } = await createServerI18n({
availableLanguages: ["en", "ko", "ja"],
defaultLanguage: "en",
});
return (
<div>
<h1>{t("Welcome {{name}}", { name: "User" })}</h1>
<p>Current: {language}</p>
</div>
);
}Client Component:
"use client";
import { useTranslation } from "i18nexus";
export default function ClientComponent() {
const { t } = useTranslation();
return (
<div>
<h1>{t("Welcome")}</h1>
<p>{t("You have {{count}} messages", { count: 5 })}</p>
</div>
);
}- Documentation Hub - Central documentation portal
- π Accept-Language Detection - Browser language auto-detection
- π¨ Variable Interpolation - Dynamic values in translations
- π― Type-Safe Configuration - TypeScript config setup
- π οΈ Developer Tools - Visual debugging tools
- Server-Side API -
createServerI18n,getServerLanguage, etc. - Client-Side API -
useTranslation,useLanguageSwitcher, etc. - TypeScript Types - Complete type definitions
- v2.7.0 - Accept-Language auto-detection (Latest)
- v2.6.0 - Variable interpolation & CI/CD
- v2.5.2 - Developer tools
- v2.1.0 - Server Components support
- Full Changelog
Automatically detects user's browser language from Accept-Language header:
const { t, language } = await createServerI18n({
availableLanguages: ["en", "ko", "ja", "zh"],
defaultLanguage: "en",
});
// Detects from:
// 1. Cookie (user preference)
// 2. Accept-Language header (browser setting)
// 3. Default language (fallback)Insert dynamic values with {{variable}} syntax:
// Basic
t("Hello {{name}}", { name: "World" });
// Multiple variables
t("{{count}} of {{total}} done", { count: 7, total: 10 });
// With styles (Client Component)
t(
"Price: {{amount}}",
{ amount: 100 },
{ amount: { color: "red", fontWeight: "bold" } }
);// Define your language type
type AppLanguages = "en" | "ko" | "ja";
const { changeLanguage } = useLanguageSwitcher<AppLanguages>();
changeLanguage("en"); // β
Autocomplete!
changeLanguage("fr"); // β Compile error!import { I18NexusDevtools } from "i18nexus";
<I18nProvider>
<App />
<I18NexusDevtools /> {/* Dev mode only */}
</I18nProvider>;Get compile-time key validation with TypeScript:
1. Define your translation keys:
// locales/types.ts
import type { translations } from "./index";
export type AppTranslationKey = keyof typeof translations.ko & string;2. Create a custom hook:
// hooks/useAppTranslation.ts
import { useTranslation } from "i18nexus";
import type { AppTranslationKey } from "../locales/types";
export function useAppTranslation() {
return useTranslation<AppTranslationKey>();
}3. Use everywhere:
import { useAppTranslation } from "./hooks/useAppTranslation";
export function MyComponent() {
const { t } = useAppTranslation();
t("greeting"); // β
Type-checked
t("invalid.key"); // β TypeScript Error!
return <div>{t("greeting")}</div>;
}For complete setup instructions and patterns, see TYPE_SAFE_SETUP.md
- Name: i18nexus
- Version: 2.11.0
- License: MIT
- TypeScript: β Full support with type-safe keys
- Bundle Size: ~15KB (gzipped)
We welcome contributions! Please see our contribution guidelines:
Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated!
MIT License - see LICENSE for details.
- π¦ npm Package
- π GitHub Repository
- π Documentation
- π Issue Tracker
- π¬ Discussions
Made with β€οΈ for the React community