# General Translation Platform: translateMany
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/translation/translate-many.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 在一次请求中翻译多个字符串或结构化内容条目。translateMany 的 API 参考。

在一次 General Translation API 请求中翻译多个内容条目。适用于批量翻译——比多次单独调用 [`translate`](/docs/platform/core/reference/gt-class-methods/translation/translate) 更高效。

## 概览 [#overview]

在已配置的 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上调用 `translateMany`，传入一组条目，以及目标区域设置字符串 (简写) 或选项对象。它既支持以数组形式传入条目，也支持传入以哈希为键的记录，并会以相同的结构返回结果。

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

const results = await gt.translateMany(
  ['Hello, world!', 'Welcome to our app', 'Click here to continue'],
  'es'
);
```

签名：

```typescript
// 重载 1：entries 的 array
translateMany(
  sources: TranslateManyEntry[],
  options: string | TranslateOptions,
  timeout?: number
): Promise<TranslateManyResult>

// 重载 2：以 hash 为键的 entries record
translateMany(
  sources: Record<string, TranslateManyEntry>,
  options: string | TranslateOptions,
  timeout?: number
): Promise<Record<string, TranslationResult>>
```

*注意：`translateMany` 需要在 GT 实例中提供 `apiKey` (或 `devApiKey`) 和 `projectId`。*

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

* **数组与 记录。** 使用数组时，条目会在内部计算哈希，结果会按输入顺序返回。使用 记录 时，各个键会被视为哈希值，返回的也是一个具有相同键的 记录。
* **独立结果。** 单个翻译失败不会中止批量操作——每个结果都会分别报告成功或失败，因此完全支持部分成功。
* **选项简写。** 给 `options` 传入一个 string 时，就是 `{ targetLocale: string }` 的简写形式，因此 `gt.translateMany(['Hello'], 'es')` 和 `gt.translateMany(['Hello'], { targetLocale: 'es' })` 是等价的。
* **完整文档。** 将 [`metadata.fileFormat`](/docs/platform/core/reference/types/entry-metadata#file-format) 设置为 `'MD'` 或 `'MDX'`，即可在保留结构的前提下解析并翻译一整篇文档。该文档必须是 string，且 `dataFormat: 'STRING'` (这是默认值) ，并且不能使用 `maxChars`。当某个分块失败或翻译后的文档无效时，文档条目会直接失败，而不会返回部分输出。

## 参数 [#parameters]

| 参数                    | 描述                          | 类型                                                                                                                       | 可选 | 默认值 |
| --------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -- | --- |
| [`sources`](#sources) | 要翻译的条目数组或 Record。           | [`TranslateManyEntry[] \| Record<string, TranslateManyEntry>`](/docs/platform/core/reference/types/translate-many-entry) | 否  | —   |
| [`options`](#options) | 目标区域设置字符串，或 选项对象。 | `string \| TranslateOptions`                                                                                             | 否  | —   |
| [`timeout`](#timeout) | 请求超时时间 (毫秒) 。               | `number`                                                                                                                 | 是  | —   |

### `sources` [#sources]

**类型** [`TranslateManyEntry[] \| Record<string, TranslateManyEntry>`](/docs/platform/core/reference/types/translate-many-entry) · **必填**

待翻译的条目。每个 [`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)) 的对象：

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

传入数组时，结果会按输入顺序返回；传入以哈希为键的记录时，结果则会按相同的键返回。

### `options` [#options]

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

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

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

### `timeout` [#timeout]

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

请求超时时间，单位为毫秒。未指定时，使用实例默认值。

## 返回值 [#returns]

**类型** `Promise<TranslateManyResult> | Promise<Record<string, TranslationResult>>`

* **数组输入** 会解析为 [`TranslateManyResult`](/docs/platform/core/reference/types/translate-many-result) (即由 [`TranslationResult`](/docs/platform/core/reference/types/translation-result) 对象组成的数组) ，顺序与输入保持一致。
* **记录 输入** 会解析为 `Record<string, TranslationResult>`，其键与输入中的哈希值相同。

读取结果中的译文前，请先根据 `success` 缩小每个结果的类型范围。

## 示例 [#examples]

```typescript
// 字符串数组
const results = await gt.translateMany(['Home', 'About', 'Products', 'Contact'], 'fr');

results.forEach((result, index) => {
  if (result.success) {
    console.log(`Item ${index}: ${result.translation}`);
  } else {
    console.error(`Item ${index} failed: ${result.error}`);
  }
});
```

```typescript
// 包含每条条目元数据的数组
const results = await gt.translateMany(
  [
    { source: 'Hello, world!', metadata: { dataFormat: 'ICU' } },
    { source: 'Goodbye, world!' },
  ],
  { targetLocale: 'es' }
);
```

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

```typescript
// 以哈希为键的 记录 — 结果通过相同的键返回
const results = await gt.translateMany(
  {
    'greeting-hash': 'Hello, world!',
    'farewell-hash': 'Goodbye, world!',
  },
  'es'
);

console.log(results['greeting-hash'].translation);
```

## 说明 [#notes]

* 在一次 API 请求中翻译多个条目。
* 某个条目失败不会影响其他条目。
* 结果会保持与输入数组一致的顺序，或保留与输入记录相同的键。

## Sitemap

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