---

每日一句正能量

最好的感情是初见时的心动，是相知时的欣赏，是熟识后的接纳，是平淡后的相守。
最好的感情不是没有瑕疵，而是一个动态演进、不断深化的过程。

前言

Codex 官网在 2026 年初启动了多语言化改造，目标是在不牺牲性能的前提下支持简体中文、英语、阿拉伯语和日语四种语言。这个项目的核心挑战并非翻译本身，而是如何在 Next.js App Router 架构下实现路由隔离、消息按需加载、RTL 布局翻转以及 SEO 的 hreflang 标注。本文将完整复盘这套国际化工程方案的设计决策与落地细节。

一、路由策略：为什么我们选择 URL 路径前缀

在启动 i18n 工程之前，团队首先面临一个架构级决策：使用 URL 路径前缀（/en/docs）、子域名（en.codex.dev）还是 Cookie/会话偏好？

子域名方案的优势在于域名级别的隔离，适合需要独立部署或不同法律主体运营的场景。但它的代价同样明显：每个子域名需要独立的 SSL 证书和 DNS 配置，更重要的是，搜索引擎会将子域名视为独立站点，导致域名权重被分散。对于 Codex 这样以内容为核心的文档平台，SEO 权重的集中远比域名的物理隔离重要。

Cookie 方案看似简洁——URL 保持干净，通过 Accept-Language 头或用户偏好 Cookie 决定返回语言。但这种方案的致命缺陷在于 SEO：搜索引擎爬虫不会携带用户的 Cookie，也无法通过不同 URL 索引多语言版本。当用户分享一个链接时，接收方看到的语言取决于自己的浏览器设置，而非发送方的意图。

Codex 最终采用了 URL 路径前缀策略，在 Next.js App Router 中通过 [locale] 动态路由段实现：

app/
├── [locale]/
│   ├── layout.tsx      # 根布局，注入 locale 和消息
│   ├── page.tsx        # 首页
│   └── docs/
│       └── page.tsx    # 文档页
└── middleware.ts       # 语言检测与重定向

这一策略将多语言版本集中在一个域名下，所有外链权重汇聚到主域；同时每个语言版本拥有独立的可分享 URL，配合 hreflang 标签向搜索引擎明确声明页面间的等价关系。

二、next-intl 的选型与配置

在 Next.js 生态中，i18n 库的选择主要落在 next-intl 与 react-i18next 之间。Codex 选择了 next-intl，核心原因在于它对 App Router 的原生支持：无需客户端 Provider 包裹整个应用，消息文件可以在服务器组件中直接读取，显著减少了客户端 JavaScript 体积。

消息文件按命名空间组织在 messages/ 目录下：

// messages/zh.json
{
  "metadata": {
    "title": "Codex 文档平台",
    "description": "为开发者打造的下一代文档体验"
  },
  "navigation": {
    "docs": "文档",
    "blog": "博客",
    "pricing": "定价"
  },
  "hero": {
    "title": "构建下一代文档",
    "cta": "开始使用",
    "subtitle": "{count, number} 位开发者已加入"
  }
}

命名空间分割是关键优化。如果一次性将所有翻译注入客户端，首屏 JavaScript 会增加 80–120KB。next-intl 支持按页面按需加载——在 page.tsx 中仅 pick 当前页面所需的命名空间：

import { pick } from 'next-intl';

export default async function HomePage({ params }: { params: { locale: string } }) {
  const messages = (await import(`@/messages/${params.locale}.json`)).default;
  const pageMessages = pick(messages, ['hero', 'navigation']);

  return (
    <NextIntlClientProvider messages={pageMessages} locale={params.locale}>
      <HeroSection />
    </NextIntlClientProvider>
  );
}

中间件负责语言检测与路由守卫：

// middleware.ts
import createMiddleware from 'next-intl/middleware';

export default createMiddleware({
  locales: ['en', 'zh', 'ar', 'ja'],
  defaultLocale: 'zh',
  localeDetection: true, // 读取 Accept-Language 头
});

export const config = {
  matcher: ['/((?!api|_next|.*\\..*).*)'],
};

当用户访问 /docs 而无语言前缀时，中间件会根据 Accept-Language 头自动重定向到 /zh/docs 或 /en/docs。这一逻辑必须在中间件中完成，而非 React 上下文中——否则搜索引擎爬虫收到的初始 HTML 将缺失语言信号，导致索引混乱。

三、日期、数字与列表的本地化

翻译文本只是本地化的冰山一角。日期格式、数字千分位分隔符、货币符号、列表连接词在不同语言中存在显著差异。Codex 全面采用原生 Intl API 家族，而非依赖第三方格式化库。

// 日期本地化
function formatDate(date: Date, locale: string) {
  return new Intl.DateTimeFormat(locale, {
    year: 'numeric',
    month: 'long',
    day: 'numeric',
  }).format(date);
}

// zh: 2026年8月26日
// en: August 26, 2026
// ar: ٢٦ أغسطس ٢٠٢٦

// 数字与货币
function formatCurrency(value: number, locale: string, currency: string) {
  return new Intl.NumberFormat(locale, {
    style: 'currency',
    currency,
  }).format(value);
}

// 列表连接词
function formatList(items: string[], locale: string) {
  return new Intl.ListFormat(locale, { type: 'conjunction' }).format(items);
}

// zh: "React、Vue 和 Angular"
// en: "React, Vue, and Angular"
// ar: "React و Vue و Angular"

Intl.RelativeTimeFormat 用于动态时间表达：

const rtf = new Intl.RelativeTimeFormat('zh', { numeric: 'auto' });
rtf.format(-3, 'day'); // "3 天前"

这些 API 由浏览器原生实现，无需额外依赖，且在服务端渲染时可直接调用，保证了首屏 HTML 中即包含正确格式化的内容。

四、RTL 布局翻转：从物理属性到逻辑属性

阿拉伯语（ar）和希伯来语等 RTL（Right-to-Left）语言对布局提出了根本性的挑战：不仅文本流向从右向左，整个页面的视觉层次——导航栏的 Logo 位置、侧边栏的相对位置、按钮的图标与文字顺序——都需要镜像翻转。

2026 年的标准方案已不再是写两套 CSS 或使用 transform: scaleX(-1) 的 hack，而是全面采用 CSS Logical Properties。这些属性以内容流向为基准，而非物理方位：

物理属性（LTR 专用）	逻辑属性（LTR/RTL 自适应）
margin-left	margin-inline-start
margin-right	margin-inline-end
padding-left	padding-inline-start
text-align: left	text-align: start
left: 0	inset-inline-start: 0
border-radius: 8px 0 0 8px	border-start-start-radius: 8px

Tailwind CSS v4 原生支持逻辑属性工具类：ms-4（margin-inline-start）、me-4（margin-inline-end）、ps-4（padding-inline-start）、text-start、rounded-s-* 等。将旧代码库从 ml-* / mr-* 迁移到 ms-* / me-* 通常是一个下午的机械替换工作，但能一次性解决 80% 的 RTL 布局问题。

在 Next.js 根布局中，根据 locale 动态设置 dir 和 lang：

// app/[locale]/layout.tsx
const rtlLocales = ['ar', 'he'];

export default async function LocaleLayout({
  children,
  params: { locale },
}: {
  children: React.ReactNode;
  params: { locale: string };
}) {
  const dir = rtlLocales.includes(locale) ? 'rtl' : 'ltr';
  const messages = await getMessages(locale);

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

当 dir="rtl" 被设置在 <html> 上时，所有使用逻辑属性的 CSS 会自动适配：Flexbox 的 justify-start 会将内容对齐到右侧，ms-4 会渲染为 margin-right: 1rem，text-start 会变为右对齐。这种"声明一次，全局生效"的机制，避免了为 RTL 单独维护一套样式表。

对于必须显式区分方向的场景（如特定语言的图标翻转），Tailwind 提供了 rtl: 和 ltr: 变体前缀：

<!-- 在 RTL 中翻转箭头图标 -->
<svg class="ms-2 rtl:rotate-180">
  <path d="M9 5l7 7-7 7" />
</svg>

五、语言切换器的无刷新实现

语言切换器是用户感知国际化最直接的触点。Codex 的实现需要满足三个条件：无刷新切换、保留当前页面路径、不丢失滚动位置与表单状态。

在 Next.js App Router 中，借助 next-intl 提供的 Link 包装器和 usePathname 钩子，可以构建一个智能切换器：

// components/LocaleSwitcher.tsx
'use client';

import { useLocale, usePathname } from 'next-intl';
import { locales } from '@/i18n/config';

const localeLabels = {
  en: 'English',
  zh: '简体中文',
  ar: 'العربية',
  ja: '日本語',
};

export function LocaleSwitcher() {
  const currentLocale = useLocale();
  const pathname = usePathname();

  return (
    <div className="relative">
      <select
        value={currentLocale}
        onChange={(e) => {
          const newLocale = e.target.value;
          const newPath = pathname.replace(`/${currentLocale}`, `/${newLocale}`);
          window.location.href = newPath;
        }}
        className="appearance-none bg-transparent border border-gray-300 rounded-lg px-4 py-2 pe-8 text-sm focus:outline-none focus:ring-2 focus:ring-blue-500"
        aria-label="切换语言"
      >
        {locales.map((locale) => (
          <option key={locale} value={locale}>
            {localeLabels[locale]}
          </option>
        ))}
      </select>
    </div>
  );
}

更优雅的方案是使用 next-intl 的 useRouter 包装器：

import { useRouter, usePathname } from 'next-intl';

const router = useRouter();
const pathname = usePathname();

// 无刷新切换，保留历史记录
router.replace(pathname, { locale: newLocale });

这种方案下，页面通过客户端导航切换，不会触发整页刷新，用户的滚动位置和组件状态得以保留。切换完成后，<html> 的 lang 和 dir 属性由新的 layout 自动更新，CSS 逻辑属性即时响应布局翻转。

六、SEO 与 hreflang 的完整闭环

多语言站点的 SEO 成败取决于 hreflang 标签的正确实施。Codex 在 layout.tsx 中通过 Metadata API 自动生成 alternates：

import { Metadata } from 'next';

export async function generateMetadata({ params }: { params: { locale: string } }): Promise<Metadata> {
  const pathname = '/docs/getting-started';
  const alternates: Record<string, string> = {};

  ['en', 'zh', 'ar', 'ja'].forEach((loc) => {
    alternates[loc] = `https://codex.dev/${loc}${pathname}`;
  });

  return {
    alternates: {
      canonical: `https://codex.dev/${params.locale}${pathname}`,
      languages: alternates,
    },
  };
}

这会在 <head> 中生成：

<link rel="canonical" href="https://codex.dev/zh/docs/getting-started" />
<link rel="alternate" hreflang="en" href="https://codex.dev/en/docs/getting-started" />
<link rel="alternate" hreflang="zh" href="https://codex.dev/zh/docs/getting-started" />
<link rel="alternate" hreflang="ar" href="https://codex.dev/ar/docs/getting-started" />
<link rel="alternate" hreflang="ja" href="https://codex.dev/ja/docs/getting-started" />
<link rel="alternate" hreflang="x-default" href="https://codex.dev/en/docs/getting-started" />

三个关键规则必须遵守：第一，每个页面的 hreflang 集合必须相互引用，缺失任何一条都会导致 Google 忽略整个集合；第二，x-default 必须指向一个语言选择器页面或主要语言的备用版本；第三，URL 必须完全一致——尾部斜杠的差异（/docs vs /docs/）会被视为不同页面，引发信号冲突。

结语

国际化不是上线前批量替换文本的收尾工作，而是需要从路由架构、组件设计到样式系统全盘考虑的工程课题。Codex 官网通过 URL 路径前缀的路由策略、next-intl 的按需消息加载、CSS Logical Properties 的 RTL 自适应 以及 hreflang 的 SEO 闭环，在四周内完成了从单语言到四语言的平滑迁移，首屏 JavaScript 体积仅增加 12KB，LCP 指标无退化。在下一篇文章中，我们将探讨微前端架构下的模块联邦与独立部署策略。

---

转载自：https://blog.csdn.net/sghtgjfhv/article/details/164078979
欢迎 👍点赞✍评论⭐收藏，欢迎指正