"use i18n";

"use i18n" 指令 允许在不重构现有代码的情况下，对 React 组件进行逐个文件的本地化处理。就像 "use client" 或 "use server" 一样，只需将其添加到文件顶部，即可自动本地化该组件中所有可翻译的内容。

这种方法非常适合在大型代码库中逐步添加多语言支持，风险最小且灵活性最大。

工作原理

当您在 React 文件顶部添加 "use i18n" 时，Lingo.dev 编译器 会自动：

  1. 扫描整个文件 以查找可翻译内容
  2. 提取 JSX 文本 和可翻译属性
  3. 使用您配置的 AI 模型生成翻译
  4. 在构建时注入本地化版本
  5. 保持热模块替换 (Hot Module Replacement)，以实现无缝开发

该指令在文件级别工作，处理该组件边界内的所有内容，同时保持应用程序的其他部分不变。

启用指令

要使用 "use i18n" 指令，请在编译器配置中启用它：

{
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  useDirective: true, // 启用 "use i18n" 指令
  models: {
    "*:*": "groq:mistral-saba-24b",
  }
}

注意： 当 useDirective 设置为 false（默认值）时，Lingo.dev 编译器 会将所有文件视为在顶部包含 "use i18n"。设置 useDirective: true 可让您对文件的本地化进行精细控制。

基本用法

在任何 React 组件文件的顶部添加指令：

"use i18n";

import React from "react";

export function WelcomeCard() {
  return (
    <div className="card">
      <h2>欢迎使用我们的应用！</h2>
      <p>
        开始探索我们的功能，发现让我们平台与众不同的地方。
      </p>
      <button>开始使用</button>
    </div>
  );
}

就是这样！该组件现在将自动以用户选择的语言呈现，无需任何代码更改。

兼容现有指令

"use i18n" 指令可以自然地与您可能已经使用的其他 React 指令一起工作：

"use client";
"use i18n";

export function InteractiveComponent() {
  const [count, setCount] = useState(0);

  return (
    <div>
      <h1>点击计数器</h1>
      <p>您已点击 {count} 次</p>
      <button onClick={() => setCount(count + 1)}>点击我！</button>
    </div>
  );
}

"use server";
"use i18n";

export async function ServerComponent() {
  const data = await fetchData();

  return (
    <div>
      <h1>服务器渲染内容</h1>
      <p>此内容在服务器上渲染，并在构建时进行本地化</p>
    </div>
  );
}

编译器会智能地处理所有指令，保持组件的预期行为，同时添加本地化功能。

开发工作流程

1. 渐进式迁移

从为单个组件添加指令开始：

// 之前：仅支持英文的组件
export function Header() {
  return <h1>我的应用程序</h1>;
}

// 之后：通过一行代码实现多语言支持的组件
("use i18n");

export function Header() {
  return <h1>我的应用程序</h1>;
}

2. 热模块替换

该指令与 HMR 无缝集成。当您修改带有 "use i18n" 的组件中的文本时，翻译会立即在浏览器中更新：

"use i18n";

export function StatusMessage() {
  return (
    <div>
      {/* 修改此文本，立即在所有语言中更新 */}
      <p>您的更改已成功保存！</p>
    </div>
  );
}

3. 按文件逐步实现

非常适合需要逐步本地化的大型代码库：

src/
├── components/
│   ├── Header.tsx          // ✅ "use i18n" - 已本地化
│   ├── Navigation.tsx      // ✅ "use i18n" - 已本地化
│   ├── ProductCard.tsx     // ✅ "use i18n" - 已本地化
│   ├── Footer.tsx          // ⏳ 尚未本地化
│   └── Sidebar.tsx         // ⏳ 尚未本地化

优势

"use i18n" 指令使本地化变得像在 React 组件中添加一行代码一样简单，专为需要逐步本地化的成熟项目设计。

下一步