# generaltranslation: General Translation Core SDK: translate
URL: https://generaltranslation.com/zh/docs/core/class/methods/translation/translate.mdx
---
title: translate
description: GT translate 方法的 API 参考文档
---

## 概述

`translate` 方法是 GT 库的主要翻译函数。
它使用 AI 翻译服务，将内容从源区域设置翻译为指定的目标区域设置。

```typescript
const gt = new GT({
  apiKey: 'your-api-key',
  projectId: 'your-project-id'
});

const result = await gt.translate('Hello, world!', 'es');
console.log(result); // "¡Hola, mundo!"
```

该方法支持多种内容类型，包括纯文本、ICU 消息格式以及 i18next 风格的消息，并可选附带元数据，以提高翻译准确性。

<Callout>
  **需要身份验证：**
  `translate` 方法要求在 GT 实例中同时配置 `apiKey` (或 `devApiKey`) 和 `projectId`。
</Callout>

***


## 参考

### 参数

<TypeTable
  type={{
  "source": {
    type: 'TranslateManyEntry',
    description: '要翻译的内容。可以是普通字符串，也可以是包含 source 和元数据的对象。',
    optional: false,
  },
  "options": {
    type: 'string | TranslateOptions',
    description: '目标区域设置字符串（简写），或包含 targetLocale 和其他设置的选项对象。',
    optional: false,
  },
  "timeout?": {
    type: 'number',
    description: '可选的请求超时时间（以毫秒为单位）。',
    optional: true,
  }
}}
/>

### TranslateManyEntry

`source` 参数既可以是普通字符串，也可以是对象：

```typescript
type TranslateManyEntry = string | { source: Content; metadata?: EntryMetadata };
```


### TranslateOptions

`options` 参数可以是区域设置字符串 (即 `targetLocale` 的简写) ，也可以是一个对象：

```typescript
type TranslateOptions = {
  targetLocale: string;
  sourceLocale?: string;
  modelProvider?: string;
};
```


### 参数说明

| 参数        | 说明                                                                                    |
| --------- | ------------------------------------------------------------------------------------- |
| `source`  | 要翻译的内容。可以是普通字符串，也可以是包含 `source` (Content) 和可选 `metadata` (EntryMetadata) 的对象。         |
| `options` | 目标区域设置字符串 (例如 `'es'`) ，或包含 `targetLocale`、可选的 `sourceLocale` 和 `modelProvider` 的选项对象。 |
| `timeout` | 可选的请求超时时间，单位为毫秒。                                                                      |

### 返回值

```typescript
Promise<TranslationResult | TranslationError>
```

* **TranslationResult**：包含翻译后的内容和元数据
* **TranslationError**：如果翻译失败，包含错误信息

***


## 行为

### 内容类型检测

该方法会根据 `source` 参数自动识别内容类型：

* **String**：视为纯文本或 ICU 消息格式
* **JSX Elements**：按 React 风格的 JSX 内容处理
* **Objects**：按结构化消息格式处理

### 区域设置判定

* 会根据 BCP-47 标准验证目标区域设置
* 如果已配置，则会应用自定义区域设置映射
* API 请求会使用标准区域设置代码

### 选项简写

你可以将字符串作为 `options` 参数传入，作为 `{ targetLocale: string }` 的简写：

```typescript
// 以下两种写法等价：
await gt.translate('Hello', 'es');
await gt.translate('Hello', { targetLocale: 'es' });
```

***


## 示例

### 简单字符串翻译

```typescript
const result = await gt.translate('Welcome to our application', 'fr');
```


### 使用选项对象

```typescript
const result = await gt.translate('Welcome to our application', {
  targetLocale: 'fr',
  sourceLocale: 'en',
});
```


### 包含源元数据

```typescript
const result = await gt.translate(
  { source: '{count, plural, other {{count} items}}', metadata: { dataFormat: 'ICU', context: 'Item count display' } },
  { targetLocale: 'es' }
);
```


### 带超时设置

```typescript
const result = await gt.translate('Hello, world!', 'es', 5000);
```

***


## 说明

* 将给定字符串翻译为目标区域设置，并返回一个 Promise
* 底层通过单条目调用 `translateMany`

## 后续步骤

* **[使用 translateMany 翻译多个条目](/docs/core/class/methods/translation/translate-many)**
* **[了解 EntryMetadata 选项](/docs/core/types/entry-metadata)**
* **[查看 TranslationResult 类型](/docs/core/types/translation-result)**