Does it handle SEO: one URL per language and hreflang?

今天不行。访客的语言信息存储在 Cookie 中，且所有语言版本都通过相同的 URL 提供，因此搜索引擎只会对源语言进行索引。您可以在 generateMetadata 方法中使用 tDynamicAll 来翻译页面标题和描述。如果您现在需要按语言生成可被搜索引擎索引的 URL，请使用支持语言环境路由的库，例如 next-intl 或 Paraglide JS。

How do I translate dynamic content from a CMS, an API or users?

该插件仅翻译代码中包含的文本。对于代码无法获取的内容，请在 Next.js 服务器组件中调用 @weglot/translate-react/dynamic 中的 tDynamic、tDynamicAll 或 tDynamicHtml。如果 API 调用耗时超过 500 毫秒，或者首次请求某段文本，这些方法将返回源文本。后续请求时，翻译结果将已准备就绪。如果您自行缓存数据，请确保缓存基于访问者的语言进行存储。

Next.js or Vite: what changes?

Next.js 使用来自 @weglot/translate-react/next 的 withWeglot 以及来自 @weglot/translate-react/react/next 的 WeglotProvider。Vite 使用来自 @weglot/translate-react/vite 的 weglotPlugin 以及来自 @weglot/translate-react/react 的 WeglotProvider。Webpack 使用来自 @weglot/translate-react/webpack 的 weglotPlugin。动态内容函数仅在 Next.js 服务器组件中运行。

Does it work with React Server Components?

是的，可以通过 Next.js App Router 实现。从 @weglot/translate-react/react/next 导入 WeglotProvider，这样切换语言时就能刷新服务器端组件。tDynamic、tDynamicAll 和 tDynamicHtml 都在服务器端运行，位于服务器端组件中。

What happens when I build?

该插件会在 sourceRoot 下的 JSX 中查找文本，并向Weglot API 请求缺失的翻译。Weglot 会使用大型语言模型 (LLM) 生成这些翻译，构建过程会等待最长 translationTimeout 时间（默认值为 300 秒）。随后，它会将翻译写入 public/translations/ .json。如果转换失败，构建将失败，并将其接收到的内容保存在本地缓存中：请重新构建以继续。当 buildMode 设置为 "cache-only" 时，构建过程不会进行任何网络调用。

Where are the translations stored?

在您的Weglot 项目中，您可以在那里审阅和编辑这些内容。每次构建还会将收到的翻译保存在 /weglot/cache/ .json。将该文件夹提交到代码库以进行构建（无需调用 API），或者将其忽略。public/translations/ 文件夹是自动生成的，应将其加入 .gitignore 文件中。

What gets translated, and how do I exclude something?

JSX 中的文本、JSX 表达式内的字符串字面量、从常量读取的字符串，以及 title、alt、placeholder 和 aria-label 等属性。JSX 之外的代码、URL、类名和字符串将保持不变。添加 translate="no" 或 data-weglot-skip 以将元素保留为原始语言。可使用 translatableAttributes 声明自定义文本属性。

@weglot/translate-react

翻译您的
React, Next.js 或 Vite app

无需 t() 封装，也无需 JSON 文件。只需添加一个构建插件和一个Weglot API 密钥：当应用构建时，JSX 中的文本就会被翻译，而您的团队无需触碰代码，即可在Weglot 上编辑翻译内容。

获取您的 API 密钥

复制以下提示： · · · 阅读文档 · 在 npm 上查看

需要 React 19 Next.js 15 / 16.0.4+（App Router）或 Vite Node 20.9+

// how it works

四个步骤。您的组件保持不变。

源语言和目标语言来自您的Weglot 项目，而非您的代码。该插件会在构建时读取您 JSX 中的文本，并获取其翻译内容。

安装该软件包并添加您的 API 密钥

创建一个“Weglot 2.0”项目，然后从项目设置中复制其 API 密钥。该密钥以 pk_. 保留 .env 不在版本控制范围内。
终端 · .env
```
$ npm install @weglot/translate-react

# .env
WEGLOT_API_KEY=pk_your_weglot_api_key
```

添加插件

将您的 Next.js 配置包裹在 withWeglot. 点 sourceRoot 到存放您的页面和组件的文件夹中。

添加 weglotPlugin 到你的 Vite 配置中。使用 Webpack 时，请从 @weglot/translate-react/webpack 而是。

next.config.ts

import type { NextConfig } from "next";
import { withWeglot } from "@weglot/translate-react/next";

const nextConfig: NextConfig = {};

export default async function (): Promise<NextConfig> {
  return await withWeglot(nextConfig, { sourceRoot: "./app" });
}

vite.config.ts

import { defineConfig } from "vite";
import { weglotPlugin } from "@weglot/translate-react/vite";

export default defineConfig({
  plugins: [weglotPlugin({ sourceRoot: "src" })],
});

添加提供商

将根布局用以下代码包裹起来： WeglotProvider 从 Next.js 的入口点开始，这样切换语言时，服务器组件就会自动刷新。

使用以下方式封装您的应用程序： WeglotProvider，尽早。

app/layout.tsx

import { WeglotProvider } from "@weglot/translate-react/react/next";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <WeglotProvider>{children}</WeglotProvider>
      </body>
    </html>
  );
}

src/main.tsx

import { WeglotProvider } from "@weglot/translate-react/react";

root.render(
  <WeglotProvider>
    <App />
  </WeglotProvider>,
);

使用项目中的每种语言进行构建和发布

每次构建都会从Weglot 获取缺失的翻译，并写入 public/translations/<locale>.json. 忽略该文件夹。使用以下代码添加一个语言切换器： LocaleSwitcher 或 useWeglotContext.
.gitignore
```
public/translations/
```

// compare

为什么不使用经典的 i18n 库呢？

i18n 库要求你将每个字符串替换为一个键，并为每种语言维护一个文件。Weglot 则会读取你已经编写的字符串。以下是这些选项的对比。

基于各项目的公开文档（Weglot 、next-intl、Paraglide JS、Contentful、Sanity、Strapi），2026年11月。
标准	Weglot `@weglot/translate-react`	next-intl / i18next	Paraglide JS	CMS 本地化
将字符串封装在 t() 或消息函数中	否在构建时检测到了 JSX 中的文本。	是的`t("key")` 对于每个字符串。	是的`m.key()` 消息功能。	仅内容代码中的字符串仍然需要一个库。
各语言的翻译文件	无需维护在构建时生成，已被添加到 Git 忽略列表中。	是通常每个语言环境对应一个 JSON 文件。	是每个语言环境对应一个消息文件。	否存储在CMS中。
多语言路由与搜索引擎优化（按语言生成的URL、hreflang）	尚未语言信息存储在Cookie中。所有语言使用相同的URL，源语言已建立索引。	next-intl：是内置了区域设置路由功能。i18next：通过您的框架配置实现。	是内置本地化 URL：包含语言前缀、已翻译的路径或域名。请自行添加 hreflang 标签。	前端无头内容管理系统（CMS）按语言环境存储内容。URL 和 hreflang 来自您的前端。
为您生成的翻译	是Weglot 在构建过程中通过大型语言模型（LLM）进行翻译。	否请自带翻译内容或使用翻译管理系统（TMS）。	借助工具inlang CLI 机器翻译，或您的编码代理。	付费插件付费套餐中的 AI 翻译功能：Contentful AI Actions、Sanity AI Assist、Strapi AI Translations。
无需开发人员即可编辑翻译	是在Weglot 仪表盘中进行审阅和编辑。	否编辑 JSON 文件，或添加一个单独的 TMS。	使用 Finkinlang 的网页编辑器，需拥有 GitHub 账户。	是在CMS编辑器中。
由一位编程代理在一条提示中完成设置	是一次安装，两次配置修改。下方提供可复制的提示。	耗时较长的任务该代理将每个字符串重写为键和文件。	耗时较长的任务`init` 如果不提示选择代理就运行，那么每个字符串都会变成一个 `m.key()` 消息。	不适用已在内容管理系统（CMS）中配置。

// built for coding agents

专为人工智能编程代理而设计

如果您使用 Claude Code、Cursor 或 Codex 进行构建，您的代理可以自动添加Weglot 。由于无需重写任何字符串，因此该更改幅度较小且易于审查。

01 · 设置

代理会进行安装和配置

一 npm install，一个插件，一个提供商，一行代码 .gitignore. 该代理仅需您提供 API 密钥。

02 · 文档

大型语言模型（LLM）能够读取的文档

该文档中有一个 llms.txt 索引，且每页都有一个 Markdown 版本：添加 .md 添加到其网址中。

03 · 提示

一个可直接复制的提示语

提示中的每个步骤都与入门指南相对应，并包含实际的导入路径。请将其复制到下方。

将代码粘贴到克劳德代码中

粘贴到光标位置（代理模式）

粘贴到Codex中

在您的应用中运行

$ npm install @weglot/translate-react

// for your team

无需触碰代码即可进行编辑和审阅

每项翻译都会显示在您的Weglot 项目中。产品团队、市场团队和译员可以在该项目中直接审阅和编辑译文，无需提交拉取请求。

请检查 Weglot 为您的应用生成的翻译内容。
在Weglot 仪表盘中编辑任何翻译。
排除代码中的任何内容，包括 translate="no" 或 data-weglot-skip.

// fit

何时应使用Weglot ，何时不应使用

该软件包目前处于预览阶段。以下是它当前的适用场景。

如果需要，请访问 @weglot/translate-react

您的应用在 Next.js（App Router）或 Vite 上运行 React 19。
你不想把字符串用 t() 包裹起来，也不想为每种语言维护一个文件。
您的编码代理编写了大部分代码，而您希望翻译能跟上它的进度。
不具备编程能力的人也需要审核和修改翻译内容。
您的 UI 文本存储在代码中，而 CMS 内容则可在服务器端进行翻译。

如果……，请使用其他方法

您需要为每种语言设置一个 URL，并确保翻译后的页面能被搜索引擎收录。请使用 next-intl 或 Paraglide JS。
您希望将翻译内容以文件形式存放在代码库中，并通过拉取请求进行审核。请将 inlang 与 Paraglide JS 或 i18next 配合使用。
您的应用基于 React 18、Next.js Pages Router 或 Next.js 14 及更早版本。
您的网站是使用内容管理系统（CMS）或网站构建工具搭建的，而非 React。请使用Weglot 提供的 CMS 集成功能。

常见问题

它是否支持SEO：每种语言一个URL以及hreflang？

今天不行。访客的语言信息存储在 Cookie 中，且所有语言版本都通过相同的 URL 提供，因此搜索引擎只会收录源语言版本。

您可以使用以下方式翻译页面标题和描述： tDynamicAll 在 generateMetadata. 如果您现在需要按语言生成的索引 URL，请使用支持区域设置路由的库，例如 next-intl 或 Paraglide JS。

如何翻译来自内容管理系统（CMS）、API 或用户的动态内容？

该插件仅翻译代码中包含的文本。对于代码无法访问的内容，请调用 tDynamic, tDynamicAll 或 tDynamicHtml 来自 @weglot/translate-react/dynamic 在 Next.js 服务器组件中。

如果 API 响应时间超过 500 毫秒，或者首次请求某段文本，则返回源文本。后续请求时即可获得翻译结果。如果您自行缓存数据，请根据访问者的语言设置缓存规则。

Next.js 还是 Vite：有什么变化？

Next.js 使用 withWeglot 来自 @weglot/translate-react/next 以及 WeglotProvider 来自 @weglot/translate-react/react/next. Vite 使用 weglotPlugin 来自 @weglot/translate-react/vite 以及 WeglotProvider 来自 @weglot/translate-react/react. Webpack 使用 weglotPlugin 来自 @weglot/translate-react/webpack.

动态内容功能仅在 Next.js 服务器组件中运行。

它支持 React 服务器组件吗？

是的，使用 Next.js 应用路由器。导入 WeglotProvider 来自 @weglot/translate-react/react/next 这样，更改语言后，服务器组件就会自动刷新。 tDynamic, tDynamicAll 以及 tDynamicHtml 在服务器端运行，位于服务器组件中。

编译时会发生什么？

该插件会在 JSX 中查找位于 sourceRoot 并向Weglot API 请求其缺失的翻译。Weglot 会通过大型语言模型（LLM）生成这些翻译，而构建过程最多会等待 translationTimeout （默认值为 300 秒）。随后它会写入 public/translations/<locale>.json.

如果翻译失败，构建将失败，并将其接收的内容保存在本地缓存中：请重新构建以继续。使用 buildMode: "cache-only"，该构建版本不会进行任何网络调用。

翻译文件存储在哪里？

在您的Weglot 项目中，您可以在那里审阅和编辑这些内容。每次构建还会将收到的翻译保存在 <sourceRoot>/weglot/cache/<locale>.json. 将该文件夹提交以进行构建（无需调用 API），或者将其忽略。 public/translations/ 被生成并放入 .gitignore.

哪些内容会被翻译，我该如何排除某些内容？

JSX 中的文本、JSX 表达式中的字符串字面量、从常量中读取的字符串，以及诸如 title, alt, placeholder 以及 aria-label. JSX 之外的代码、URL、类名和字符串保持不变。添加 translate="no" 或 data-weglot-skip 要保留元素的原始语言。使用以下方式声明自定义文本属性： translatableAttributes.

无需重写代码，即可让您的 React 应用支持多语言

安装该软件包，添加您的 API 密钥，然后进行构建。

终端

$ npm install @weglot/translate-react