Lingui.js 在 React Server Components 中的实践指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00048/article/details/148507558

Lingui.js 在 React Server Components 中的实践指南

js-lingui 🌍 📖 A readable, automated, and optimized (3 kb) internationalization for JavaScript 项目地址: https://gitcode.com/gh_mirrors/js/js-lingui

前言

在现代前端开发中，国际化(i18n)已成为构建全球化应用的重要环节。Lingui.js 作为一个强大的国际化解决方案，从 4.10.0 版本开始正式支持 React Server Components (RSC)。本文将深入探讨如何在使用 Next.js App Router 的项目中集成 Lingui.js 实现国际化功能。

基础准备

在开始之前，需要确保项目已经完成以下准备工作：

根据项目使用的转译器(SWC 或 Babel)完成 Lingui.js 的安装和基础配置
正确配置 TypeScript 以理解 @lingui/react 包的导出类型
确保 Next.js 项目已升级到支持 App Router 的版本

Next.js 国际化基础配置

路由与中间件配置

Next.js 应用需要具备处理多语言路由和内容渲染的能力。这主要通过中间件实现：

创建中间件文件处理语言检测和重定向逻辑
将页面和路由文件从 app 目录移动到 app/[lang] 目录下
确保 lang 参数能够传递到每个布局和页面组件

这种结构使得 Next.js 路由器能够动态处理不同语言的路由。

SWC 插件配置

为了在项目中使用 Lingui 宏功能，需要在 next.config.js 中添加 SWC 插件配置：

module.exports = {
  experimental: {
    swcPlugins: [["@lingui/swc-plugin", {}]],
  },
};

服务端组件集成方案

核心实现原理

Lingui.js 在服务端组件和客户端组件中提供了相同的国际化体验，Trans 和 useLingui 可以在两种环境中以相同方式使用。其内部实现机制有所不同：

客户端组件：通过 React 上下文传递 I18n 实例
服务端组件：使用 React 的 cache 机制为每个请求维护独立的 I18n 实例

实现步骤

第一步：服务端 I18n 实例管理

在根布局组件中，我们需要根据语言参数创建并缓存 I18n 实例：

import { setI18n } from "@lingui/react/server";
import { getI18nInstance } from "./appRouterI18n";

export default function RootLayout({ params: { lang }, children }) {
  const i18n = getI18nInstance(lang);
  setI18n(i18n); // 为当前请求设置服务端 I18n 实例
  
  return (
    <html lang={lang}>
      <body>
        {/* 客户端组件提供者 */}
        {children}
      </body>
    </html>
  );
}

第二步：客户端 I18n 提供者

创建一个客户端组件作为 I18n 提供者：

"use client";

import { I18nProvider } from "@lingui/react";
import { setupI18n } from "@lingui/core";
import { useState } from "react";

export function LinguiClientProvider({ initialLocale, initialMessages, children }) {
  const [i18n] = useState(() => {
    return setupI18n({
      locale: initialLocale,
      messages: { [initialLocale]: initialMessages },
    });
  });
  
  return <I18nProvider i18n={i18n}>{children}</I18nProvider>;
}

第三步：I18n 实例工厂

实现一个服务端专用的 I18n 实例管理模块，为每个语言维护独立的实例：

import { I18n } from "@lingui/core";

const instances = new Map<string, I18n>();

export function getI18nInstance(locale: string): I18n {
  if (!instances.has(locale)) {
    const i18n = new I18n({ locale });
    // 加载对应语言的消息资源
    instances.set(locale, i18n);
  }
  return instances.get(locale)!;
}

组件国际化实践

通用组件实现

以下组件既可以在服务端渲染，也可以在客户端运行：

import { Trans, useLingui } from "@lingui/react/macro";

export function SomeComponent() {
  const { t } = useLingui();
  return (
    <div>
      <p><Trans>通用文本</Trans></p>
      <p>{t`动态文本`}</p>
    </div>
  );
}

在服务端组件中，useLingui 实际上是一个从 React cache 读取数据的普通函数调用，而非真正的 Hook。

布局与页面的特殊处理

由于 Next.js App Router 的设计特点，setI18n 调用不仅需要在布局中执行，也需要在每个页面中执行。建议将这一逻辑抽象为公共函数或高阶组件：

export function withLinguiInit(Component) {
  return function WrappedComponent({ params: { lang }, ...props }) {
    const i18n = getI18nInstance(lang);
    setI18n(i18n);
    return <Component {...props} />;
  };
}

语言切换策略

静态生成注意事项

使用 Next.js 静态生成功能时，需要注意：

实现 generateStaticParams 为所有支持的语言生成静态页面
避免在模块顶层创建语言相关的内容，这可能导致内容只针对一种语言生成
确保构建时正确初始化语言环境

错误示例：

// ❌ 构建时确定的语言内容
const staticText = t`不会变化的文本`;

正确做法：

// ✅ 组件内根据当前语言动态渲染
export default function Page() {
  return <Trans>动态文本</Trans>;
}

性能优化建议

合理使用动态导入按需加载语言资源
考虑使用 Lingui.js 的延迟加载功能优化初始加载性能
对于静态内容，优先使用编译时提取的消息

总结

Lingui.js 为 React Server Components 提供了完整的国际化解决方案，开发者可以：

在服务端和客户端使用相同的 API 实现国际化
充分利用 Next.js 的静态生成和服务器渲染能力
构建高性能的多语言应用

通过本文介绍的方法，开发者可以轻松将 Lingui.js 集成到基于 RSC 的 Next.js 应用中，实现优雅的国际化解决方案。

js-lingui 🌍 📖 A readable, automated, and optimized (3 kb) internationalization for JavaScript 项目地址: https://gitcode.com/gh_mirrors/js/js-lingui

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Lingui.js 在 React Server Components 中的实践指南