←Back to Home

Getting Started

Complete step-by-step guide to setting up i18nexus in your project

1

Installation

npm install i18nexus

Installs both React components and CLI tools

2

Initialize Project

npx i18n-sheets init

Creates the following:

  • •i18nexus.config.json- Project configuration file
  • •locales/- Translation files directory (ko.json, en.json)
3

I18nProvider Setup

For Next.js App Router: Add to root layout.tsx

// app/layout.tsx
import { headers } from "next/headers";
import { I18nProvider } from "i18nexus";
import { getServerLanguage } from "i18nexus/server";
import { translations } from "@/lib/i18n";

export default async function RootLayout({ children }) {
  const headersList = await headers();
  const language = getServerLanguage(headersList);

  return (
    <html lang={language}>
      <body>
        <I18nProvider 
          initialLanguage={language} 
          translations={translations}
        >
          {children}
        </I18nProvider>
      </body>
    </html>
  );
}

Translation Files: Create lib/i18n.ts

// lib/i18n.ts
import en from "../locales/en.json";
import ko from "../locales/ko.json";

export const translations = {
  en,
  ko,
};
4

Wrap Korean Text

npx i18n-wrapper

Automatically wraps all Korean text with t()

⚠️Important: Check Server Components

After running i18n-wrapper, some files may have errors:

  1. 1. Server Components:
    If the file is a Server Component (no use client), you must use server utilities instead of hooks
  2. 2. Manually fix:
    Check errors and decide whether to add use client or use createServerTranslation()

✓For Client Components

"use client";
import { useTranslation } from "i18nexus";

export default function Page() {
  const { t } = useTranslation();
  return <div>{t("안녕하세요")}</div>;
}

✓For Server Components

import { headers } from "next/headers";
import { getServerLanguage, 
  createServerTranslation } from "i18nexus/server";

export default async function Page() {
  const lang = getServerLanguage(await headers());
  const t = createServerTranslation(lang, translations);
  return <div>{t("안녕하세요")}</div>;
}
5

Extract translation keys

npx i18n-extractor

Scan code to generate/update translation files

💡App Directory Notes

If using Next.js App Router, use the -p flag to specify the correct directory:

npx i18n-extractor -p "app/**/*.tsx"

Output File:

  • →locales/ko.json- Korean Translation (Auto-filled)
  • →locales/en.json- English Translation (Manual translation required)
6

Add English Translation

Open locales/en.json and add English translations

Before (Auto-generated):

{
  "안녕하세요": "안녕하세요",
  "환영합니다": "환영합니다"
}

After (Translated):

{
  "안녕하세요": "Hello",
  "환영합니다": "Welcome"
}
📊

Optional: Google Sheets Integration

Can sync with Google Sheets for team collaboration

Upload Translations:

npx i18n-sheets upload -s YOUR_SPREADSHEET_ID

Download Translations:

npx i18n-sheets download -s YOUR_SPREADSHEET_ID
✓

Done!

Your app is now fully internationalized and ready to deploy

Learn More About I18nProvider →Explore CLI Tools →