# gt-next: General Translation Next.js SDK: 动态内容
URL: https://generaltranslation.com/zh/docs/next/guides/dynamic-content.mdx
---
title: 动态内容
description: 如何使用服务器端翻译 API 翻译运行时内容
---

动态内容翻译用于处理那些在构建时无法获取的文本，例如用户生成的内容、API 响应或数据库记录。对于 JSX 内容，请使用 [`<Tx>`](/docs/next/api/components/tx)；对于纯字符串，请使用 [`tx`](/docs/next/api/strings/tx)。出于安全考虑，这两者都只能在服务器端使用。

<Callout type="warn">
  **谨慎使用：** 动态翻译会消耗 API 配额并增加延迟。请尽可能优先使用 [`<T>` 组件](/docs/next/guides/t)和[变量组件](/docs/next/guides/variables)。
</Callout>

## 何时使用动态翻译

动态翻译适用于那些在构建时确实无法确定的内容：

### 适用场景

* **用户生成内容**：聊天消息、评论、社交媒体帖子
* **外部 API 响应**：第三方数据、RSS 源、外部服务
* **数据库记录**：动态 CMS 内容、来自 API 的用户资料
* **实时数据**：实时通知、状态信息

### 以下情况请勿使用

* 用户名、账号 → 使用 [`<Var>`](/docs/next/api/components/var)
* 条件消息 → 使用 [分支组件](/docs/next/guides/branches)
* 表单验证 → 使用 [字符串翻译](/docs/next/guides/strings)
* 静态配置 → 使用 [共享字符串](/docs/next/guides/shared-strings)

## 快速开始

### 使用 Tx 的 JSX 内容

```jsx
import { Tx } from 'gt-next';

async function UserPost({ postContent }) {
  return (
    <article>
      <Tx>{postContent}</Tx>
    </article>
  );
}
```


### 使用 tx 处理纯字符串

```jsx
import { tx } from 'gt-next/server';

async function NotificationBanner({ message }) {
  const translatedMessage = await tx(message);
  
  return (
    <div className="banner">
      {translatedMessage}
    </div>
  );
}
```


## 仅限服务器端

出于安全原因，[`<Tx>`](/docs/next/api/components/tx) 和 [`tx`](/docs/next/api/strings/tx) 只能在服务器端使用：

```jsx
// ✅ 服务器组件
async function ServerComponent() {
  const translated = await tx(dynamicContent);
  return <div>{translated}</div>;
}

// ❌ 客户端组件 - 不可用
'use client';
function ClientComponent() {
  const translated = await tx(dynamicContent); // 错误！
  return <div>{translated}</div>;
}
```

## 示例

### 用户生成内容

```jsx
import { Tx } from 'gt-next';

async function ChatMessage({ message }) {
  return (
    <div className="chat-message">
      <div className="author">{message.author}</div>
      <Tx>{message.content}</Tx>
    </div>
  );
}
```


### 外部 API 数据

```jsx
import { tx } from 'gt-next/server';

async function NewsArticle({ article }) {
  const translatedTitle = await tx(article.title);
  
  return (
    <article>
      <h1>{translatedTitle}</h1>
      <p>{article.publishedAt}</p>
    </article>
  );
}
```


### 混合内容

```jsx
import { T, Tx, Var } from 'gt-next';

async function ProductReview({ review }) {
  return (
    <div>
      {/* 带变量的静态内容 */}
      <T>
        <p><Var>{review.author}</Var> rated this <Var>{review.rating}</Var> stars</p>
      </T>
      
      {/* 动态用户内容 */}
      <Tx>{review.content}</Tx>
    </div>
  );
}
```


## API 路由用法

[`tx`](/docs/next/api/strings/tx) 可用于 Next.js API 路由处理函数中，而不仅限于服务端组件：

```tsx
// app/api/translate/route.ts
import { tx } from 'gt-next/server';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const { text, locale } = await request.json();
  const translated = await tx(text, { locale });
  return NextResponse.json({ translated });
}
```

当你需要通过 API 端点对外提供翻译能力时，这会很有用——例如，为客户端组件或外部服务提供翻译。


## 客户端翻译模式

由于 [`tx`](/docs/next/api/strings/tx) 仅限服务端使用，因此客户端组件可以通过调用 API 路由作为代理来翻译动态内容：

```tsx
'use client';

async function translateText(text: string) {
  const res = await fetch('/api/translate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text, locale: 'fr' }),
  });
  const { translated } = await res.json();
  return translated;
}
```

这需要与[上面的 API 路由](#api-route-usage)配合使用，才能让客户端组件访问动态翻译。


## 翻译多个条目

使用 `Promise.all` 并行翻译内容数组：

```tsx
import { tx } from 'gt-next/server';

const translatedPosts = await Promise.all(
  posts.map(async (post) => ({
    ...post,
    title: await tx(post.title),
  }))
);
```

这对于翻译数据库记录列表、API 响应或任何动态生成的字符串集合都很有用。


## 常见问题

### 避免滥用

对于可以使用标准组件的内容，不要使用动态翻译：

```jsx
// ❌ 不必要
const content = `Hello, ${userName}!`;
return <Tx>{content}</Tx>;

// ✅ 改用变量组件
return (
  <T>
    <p>Hello, <Var>{userName}</Var>!</p>
  </T>
);
```


### API 配额影响

动态翻译会在每次请求时消耗 API 配额。请在生产环境中使用缓存和错误处理机制。

## 后续步骤

<Callout>
  **查看实际效果：** 查看[动态内容示例应用](https://github.com/gt-examples/dynamic-content-tx)，了解 `tx()` 和 `<Tx>` 的实际运行效果 — [在线预览](https://dynamic-content-tx.generaltranslation.dev)。
</Callout>

* [本地翻译指南](/docs/next/guides/local-tx) - 无需调用 API 即可处理翻译
* [中间件指南](/docs/next/guides/middleware) - 语言检测与路由
* API 参考：
  * [`<Tx>` 组件](/docs/next/api/components/tx)