# General Translation Platform: translate
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/translation/translate.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 使用 General Translation 将单个 字符串 或结构化内容条目翻译为目标区域设置。translate 的 API 参考。

`translate` 是 [GT](/docs/platform/core/reference/gt-class/constructor) 实例上的主要翻译方法，用于一次翻译单个 字符串 或结构化内容条目。

## 概览 [#overview]

在已配置的 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上调用 `translate`，即可翻译单个条目。传入要翻译的内容，以及目标区域设置字符串 (简写) 或选项对象。该方法会返回一个 promise，最终解析为 [`TranslationResult`](/docs/platform/core/reference/types/translation-result)。

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

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

签名：

```typescript
translate(
  source: TranslateManyEntry,
  options: string | TranslateOptions,
  timeout?: number
): Promise<TranslationResult>
```

*注意：`translate` 要求 GT 实例中提供 `apiKey` (或 `devApiKey`) 和 `projectId`。它底层实际上是用单个条目调用 [`translateMany`](/docs/platform/core/reference/gt-class-methods/translation/translate-many)。*

## 工作原理 [#how-it-works]

* **内容检测。** `source` 会根据其形式以及你提供的 `dataFormat` 元数据，被识别为纯文本、ICU 消息、i18next 风格消息或结构化 JSX 内容。
* **完整文档。** 将 [`metadata.fileFormat`](/docs/platform/core/reference/types/entry-metadata#file-format) 设为 `'MD'` 或 `'MDX'`，即可在保留结构的前提下解析并翻译一整篇文档。该文档必须是字符串，且 `dataFormat: 'STRING'` (默认值) ，并且不能使用 `maxChars`。当某个分块失败或翻译后的文档无效时，文档条目会直接失败，而不会返回部分输出。
* **区域设置解析。** 目标区域设置会根据 BCP 47 进行验证。实例上的任何 [`customMapping`](/docs/platform/core/reference/types/custom-mapping) 都会生效，并将规范的区域设置代码发送到 API。
* **选项简写。** 为 `options` 传入字符串是 `{ targetLocale: string }` 的简写，因此 `gt.translate('Hello', 'es')` 与 `gt.translate('Hello', { targetLocale: 'es' })` 是等价的。

## 参数 [#parameters]

| 参数                    | 描述                                             | Type                                                                             | Optional | Default |
| --------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------- | -------- | ------- |
| [`source`](#source)   | 待翻译内容：一个字符串，或一个包含 `source` 和可选 `metadata` 的对象。 | [`TranslateManyEntry`](/docs/platform/core/reference/types/translate-many-entry) | 否        | —       |
| [`options`](#options) | 目标区域设置字符串，或一个选项对象。                             | `string \| TranslateOptions`                                                     | 否        | —       |
| [`timeout`](#timeout) | 请求超时时间 (以毫秒为单位) 。                              | `number`                                                                         | 是        | —       |

### `source` [#source]

**类型** [`TranslateManyEntry`](/docs/platform/core/reference/types/translate-many-entry) · **必填**

要翻译的内容。可传入普通字符串，或传入一个对象，其中包含 `source` ([`Content`](/docs/platform/core/reference/types/content)) 以及可选的 `metadata` ([`EntryMetadata`](/docs/platform/core/reference/types/entry-metadata)，用于提供上下文、`dataFormat` 和其他翻译提示) 。

### `options` [#options]

**类型** `string | TranslateOptions` · **必填**

目标区域设置字符串，例如 `'es'`，或选项对象：

```typescript
type TranslateOptions = {
  targetLocale: string; // 要翻译成的区域设置
  sourceLocale?: string; // 覆盖实例的 sourceLocale
  modelProvider?: string; // 可选的模型提供商提示
};
```

### `timeout` [#timeout]

**类型** `number` · **可选**

请求超时时间 (毫秒) 。省略时，使用实例的默认值。

## 返回 [#returns]

**类型** `Promise<TranslationResult>`

会解析为 [`TranslationResult`](/docs/platform/core/reference/types/translation-result)——这是一种可辨别联合类型，包含成功结果 (带有 `translation` 和 `区域设置`) 以及错误结果 (带有 `error` 和 `code`) 。读取翻译结果前，务必先根据 `success` 进行类型收窄。

## 示例 [#examples]

```typescript
// 简单字符串翻译（区域设置简写）
const result = await gt.translate('Welcome to our application', 'fr');

if (result.success) {
  console.log(result.translation); // "Bienvenue dans notre application"
} else {
  console.error(`Translation failed: ${result.error}`);
}
```

```typescript
// 使用选项对象并显式指定源区域设置
const result = await gt.translate('Welcome to our application', {
  targetLocale: 'fr',
  sourceLocale: 'en',
});
```

```typescript
// 带有源元数据（ICU 复数 + 上下文）
const result = await gt.translate(
  {
    source: '{count, plural, other {{count} items}}',
    metadata: { dataFormat: 'ICU', context: 'Item count display' },
  },
  { targetLocale: 'es' }
);
```

```typescript
// 翻译完整的 Markdown 文档。
const result = await gt.translate(
  {
    source: '# Welcome\n\nRead the [guide](/guide).',
    metadata: { fileFormat: 'MD' },
  },
  { sourceLocale: 'en', targetLocale: 'es' }
);
```

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.