Frontend i18n Architecture in Practice: next-intl, react-i18next, and Multilingual SEO

前端开发

i18n Is More Than Translating Text

i18n involves translation, typography, date/number formatting, currency, plurals, RTL, SEO—far more complex than simply "switching a language pack."

Dimension Example
Translation "Hello" → "你好" → "こんにちは"
Date Format 2026/06/02 vs 02/06/2026 vs 06.02.2026
Number Format 1,234.56 vs 1.234,56 vs 1 234,56
Currency ¥1,234 vs $1,234 vs €1.234
Plurals 1 item vs 2 items (Chinese has no plural inflection)
Text Direction LTR (Chinese/English) vs RTL (Arabic)
URL Strategy /en/about vs /about?lang=en

1. Translation File Organization

Namespace-Based Splitting

messages/
├── zh-CN/
│   ├── common.json       # General: buttons, navigation, errors
│   ├── home.json         # Homepage
│   ├── auth.json         # Login/Register
│   ├── dashboard.json    # Dashboard
│   └── errors.json       # Error messages
├── en/
│   ├── common.json
│   ├── home.json
│   └── ...
└── ja/
    ├── common.json
    └── ...

JSON Structure

{
  "common": {
    "button": {
      "submit": "Submit",
      "cancel": "Cancel",
      "confirm": "Confirm"
    },
    "nav": {
      "home": "Home",
      "about": "About",
      "contact": "Contact Us"
    }
  },
  "home": {
    "title": "Free Online Toolkit",
    "subtitle": "200+ tools, browser-side processing, private and secure",
    "cta": "Get Started"
  }
}

Flattening Nested Keys

// Nested style
{ "home": { "hero": { "title": "Toolkit" } } }

// Equivalent flat style
{ "home.hero.title": "Toolkit" }

2. next-intl in Practice

Configuration

// src/i18n/routing.ts
import { defineRouting } from 'next-intl/routing';

export const routing = defineRouting({
  locales: ['zh-CN', 'zh-TW', 'en', 'ja'],
  defaultLocale: 'zh-CN',
  localePrefix: 'always', // /zh-CN/about
});

Server-Side Usage

// src/app/[locale]/page.tsx
import { useTranslations } from 'next-intl';

export default function HomePage() {
  const t = useTranslations('home');
  return (
    <div>
      <h1>{t('title')}</h1>
      <p>{t('subtitle')}</p>
    </div>
  );
}

Client-Side Usage

'use client';
import { useTranslations } from 'next-intl';

function LanguageSwitcher() {
  const router = useRouter();
  const pathname = usePathname();
  const locale = useLocale();

  function switchLocale(newLocale: string) {
    router.replace(pathname.replace(`/${locale}`, `/${newLocale}`));
  }

  return (
    <select value={locale} onChange={(e) => switchLocale(e.target.value)}>
      <option value="zh-CN">简体中文</option>
      <option value="zh-TW">繁體中文</option>
      <option value="en">English</option>
      <option value="ja">日本語</option>
    </select>
  );
}

3. ICU Message Format

Variable Interpolation

{
  "greeting": "Hello, {name}!",
  "fileCount": "{count} files uploaded"
}

t('greeting', { name: 'John' })       // Hello, John!
t('fileCount', { count: 5 })          // 5 files uploaded

Plural Handling

{
  "items": "{count, plural, =0 {No items} =1 {1 item} other {# items}}"
}
count English
0 No items
1 1 item
5 5 items

Select Format (Gender, etc.)

{
  "invitation": "{gender, select, male {Invite him} female {Invite her} other {Invite them}}"
}

Rich Text

{
  "terms": "Click <link>this link</link> to view terms"
}

<p>{t.rich('terms', {
  link: (children) => <a href="/terms">{children}</a>
})}</p>

4. Date and Number Formatting

Date Format

import { useFormatter } from 'next-intl';

function DateFormatter({ date }: { date: Date }) {
  const format = useFormatter();

  return (
    <div>
      {/* Chinese: 2026年6月2日 */}
      <p>{format.dateTime(date, { dateStyle: 'long' })}</p>

      {/* English: June 2, 2026 */}
      {/* Japanese: 2026年6月2日 */}

      {/* Custom format */}
      <p>{format.dateTime(date, {
        year: 'numeric',
        month: '2-digit',
        day: '2-digit',
      })}</p>
      {/* zh-CN: 2026/06/02 */}
      {/* en: 06/02/2026 */}
      {/* ja: 2026/06/02 */}
    </div>
  );
}

Number and Currency Format

function NumberFormatter() {
  const format = useFormatter();

  return (
    <div>
      {/* Numbers */}
      {format.number(1234.56)}          {/* zh-CN: 1,234.56 | de: 1.234,56 */}

      {/* Currency */}
      {format.number(1234, { style: 'currency', currency: 'CNY' })}
      {/* zh-CN: ¥1,234.00 | en-US: CN¥1,234.00 */}

      {/* Percentage */}
      {format.number(0.856, { style: 'percent' })}
      {/* zh-CN: 86% | en: 86% */}

      {/* Units */}
      {format.number(1024, { style: 'unit', unit: 'megabyte' })}
      {/* zh-CN: 1,024 MB | en: 1,024 MB */}
    </div>
  );
}

5. RTL Support

Detection and Setup

import { useLocale } from 'next-intl';

const RTL_LOCALES = ['ar', 'he', 'fa', 'ur'];

function AppLayout({ children }) {
  const locale = useLocale();
  const dir = RTL_LOCALES.includes(locale) ? 'rtl' : 'ltr';

  return (
    <html dir={dir} lang={locale}>
      <body>{children}</body>
    </html>
  );
}

CSS Logical Properties

/* Use logical properties for automatic RTL adaptation */
.card {
  margin-inline-start: 1rem;    /* LTR: margin-left | RTL: margin-right */
  padding-inline-end: 0.5rem;   /* LTR: padding-right | RTL: padding-left */
  border-inline-start: 2px solid blue;
  text-align: start;            /* LTR: left | RTL: right */
}

6. Multilingual SEO

hreflang Tags

<link rel="alternate" hreflang="zh-CN" href="https://example.com/zh-CN/about" />
<link rel="alternate" hreflang="zh-TW" href="https://example.com/zh-TW/about" />
<link rel="alternate" hreflang="en" href="https://example.com/en/about" />
<link rel="alternate" hreflang="ja" href="https://example.com/ja/about" />
<link rel="alternate" hreflang="x-default" href="https://example.com/en/about" />

Next.js Metadata Generation

// src/app/[locale]/about/layout.tsx
export async function generateMetadata({ params: { locale } }) {
  const t = await getTranslations({ locale, namespace: 'about' });

  return {
    title: t('metaTitle'),
    description: t('metaDescription'),
    alternates: {
      canonical: `https://example.com/${locale}/about`,
      languages: {
        'zh-CN': 'https://example.com/zh-CN/about',
        'zh-TW': 'https://example.com/zh-TW/about',
        'en': 'https://example.com/en/about',
        'ja': 'https://example.com/ja/about',
        'x-default': 'https://example.com/en/about',
      },
    },
  };
}

Sitemap for Multilingual

// src/app/sitemap.ts
export default function sitemap() {
  const locales = ['zh-CN', 'zh-TW', 'en', 'ja'];
  const pages = ['/', '/about', '/tools', '/blog'];

  return locales.flatMap(locale =>
    pages.map(page => ({
      url: `https://example.com/${locale}${page}`,
      lastModified: new Date(),
      changeFrequency: 'weekly',
      priority: page === '/' ? 1 : 0.8,
    }))
  );
}

7. URL Strategy Comparison

Strategy Example SEO Technical Complexity
Sub-path /zh-CN/about Good Low
Sub-domain cn.example.com/about Good Medium
Query Parameter /about?lang=zh-CN Poor Low
Separate Domain example.cn/about Good High

Recommendation: Sub-path strategy—SEO-friendly and easy to implement.

8. Translation Quality Assurance

i18n Validation Script

// scripts/i18n-check.js
const fs = require('fs');
const path = require('path');

const locales = ['zh-CN', 'en', 'ja'];
const baseLocale = 'zh-CN';

function flattenKeys(obj, prefix = '') {
  return Object.entries(obj).flatMap(([key, value]) =>
    typeof value === 'object'
      ? flattenKeys(value, prefix ? `${prefix}.${key}` : key)
      : [prefix ? `${prefix}.${key}` : key]
  );
}

const baseKeys = flattenKeys(JSON.parse(fs.readFileSync(`messages/${baseLocale}/common.json`, 'utf-8')));

for (const locale of locales.filter(l => l !== baseLocale)) {
  const localeKeys = flattenKeys(JSON.parse(fs.readFileSync(`messages/${locale}/common.json`, 'utf-8')));
  const missing = baseKeys.filter(k => !localeKeys.includes(k));
  const extra = localeKeys.filter(k => !baseKeys.includes(k));

  if (missing.length) console.log(`[${locale}] Missing keys:`, missing);
  if (extra.length) console.log(`[${locale}] Extra keys:`, extra);
}

CI Integration

- name: i18n check
  run: node scripts/i18n-check.js

Translation Workflow

  1. Developers only modify zh-CN files
  2. CI validates key completeness for other languages
  3. New keys are automatically marked as pending translation
  4. Translation platform (Crowdin/Transifex) syncs
  5. Auto PR after translation is complete

Try these browser-local tools — no sign-up required →

#i18n#国际化#next-intl#react-i18next#SEO#多语言