Internationalization Patterns

Overview

This project supports internationalization (i18n) with separate patterns for server and client components.

Supported Locales

Routes use the [locale] parameter to support:

• en - English
• zh - Chinese

Routing

URL Structure

All routes include the locale parameter:

/en/about
/zh/about

Generating Localized URLs

Use getLocalePath() to create locale-aware URLs:

import { getLocalePath } from "@/utils/locale";

// Current locale: "en"
const aboutPath = getLocalePath("/about"); // Returns "/en/about"

// Switching locale
const zhAboutPath = getLocalePath("/about", "zh"); // Returns "/zh/about"

Translation File Structure

Server Component Translations

Location: translations.json files in component and route folders

src/
  components/
    Header/
      translations.json
  app/
    [locale]/
      about/
        translations.json

Example translations.json:

{
  "en": {
    "title": "About Us",
    "description": "Learn more about our company"
  },
  "zh": {
    "title": "关于我们",
    "description": "了解更多关于我们公司的信息"
  }
}

Client Component Translations

Location: [ComponentName].translations.json (component-specific for tree shaking)

src/
  components/
    Button/
      Button.tsx
      Button.translations.json

Example Button.translations.json:

{
  "en": {
    "submit": "Submit",
    "cancel": "Cancel"
  },
  "zh": {
    "submit": "提交",
    "cancel": "取消"
  }
}

Component-specific translation files enable tree shaking.

Server Components

Server components use the getTranslations utility to obtain translated texts.

import { getTranslations } from "@/utils/translations";

async function ServerComponent({ params }) {
  const t = await getTranslations(params.locale);

  return (
    <div>
      <h1>{t.title}</h1>
      <p>{t.description}</p>
    </div>
  );
}

Use getTranslations(locale) - async function that returns translation object.

Client Components

Client components use the useTranslations() hook which reads translations from context.

"use client";
import { useTranslations } from "@/hooks/useTranslations";

function ClientComponent() {
  const t = useTranslations();

  return <button>{t.submit}</button>;
}

Providing Translations to Client Components

A server component parent must render <TranslationContextProvider /> with the translation content.

// Server component (parent)
import { TranslationContextProvider } from "@/contexts/TranslationContext";
import buttonTranslations from "@/components/Button/Button.translations.json";
import ClientComponent from "./ClientComponent";

async function ServerParent({ params }) {
  const locale = params.locale;

  return (
    <TranslationContextProvider translations={buttonTranslations[locale]}>
      <ClientComponent />
    </TranslationContextProvider>
  );
}

Server component parent must provide <TranslationContextProvider /> with component-specific translations imported from JSON.

Complete Example

Scenario: Button component with translations

1. Translation file (Button.translations.json):

{
  "en": {
    "submit": "Submit",
    "cancel": "Cancel",
    "loading": "Loading..."
  },
  "zh": {
    "submit": "提交",
    "cancel": "取消",
    "loading": "加载中..."
  }
}

2. Client component (Button.tsx):

"use client";
import { useTranslations } from "@/hooks/useTranslations";

export function Button({ isLoading, onSubmit, onCancel }) {
  const t = useTranslations();

  return (
    <div>
      <button onClick={onSubmit} disabled={isLoading}>
        {isLoading ? t.loading : t.submit}
      </button>
      <button onClick={onCancel}>{t.cancel}</button>
    </div>
  );
}

3. Server component parent (Form.tsx):

import { TranslationContextProvider } from "@/contexts/TranslationContext";
import buttonTranslations from "@/components/Button/Button.translations.json";
import { Button } from "@/components/Button/Button";

export async function Form({ params }) {
  const locale = params.locale;

  return (
    <TranslationContextProvider translations={buttonTranslations[locale]}>
      <Button onSubmit={...} onCancel={...} />
    </TranslationContextProvider>
  );
}

Pattern Summary

Server Components

Server Component → getTranslations(locale) → translations.json → Rendered text

Client Components

Server Parent → Import translations.json → TranslationContextProvider
    ↓
Client Component → useTranslations() hook → Rendered text

Best Practices

1. File naming: translations.json for server components, [ComponentName].translations.json for client components
2. Context provider: Always wrap client components with TranslationContextProvider
3. Locale parameter: Pass params.locale from route params

Common Patterns

Locale Switching Link

import { getLocalePath } from "@/utils/locale";

<a href={getLocalePath("/current-route", "zh")}>Switch to Chinese</a>;

Conditional Translation

const t = useTranslations();

<div>{user.isPremium ? t.premiumMessage : t.freeMessage}</div>;

Translation with Variables

// In translations.json
{
  "en": {
    "greeting": "Hello, {name}!"
  }
}

// In component
const message = t.greeting.replace("{name}", userName);

Common Mistakes

❌ Using getTranslations() in client components (use useTranslations() hook) ❌ Missing TranslationContextProvider wrapper for client components ❌ Hardcoding locale strings (use params.locale) ❌ Creating monolithic translation files (split by component)