# generaltranslation: General Translation Core SDK: translateMany
URL: https://generaltranslation.com/zh/docs/core/class/methods/translation/translate-many.mdx
---
title: translateMany
description: GT translateMany 方法的 API 参考文档，用于批量翻译
---

## 概述

`translateMany` 方法可通过一次 API 请求高效翻译多个内容项。
该方法针对批量处理进行了优化，性能优于多次单独调用 `translate`。

```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'
);
```

***


## 参考

### 重载 1：条目数组

```typescript
translateMany(
  sources: TranslateManyEntry[],
  options: string | TranslateOptions,
  timeout?: number
): Promise<TranslateManyResult>
```

返回一个 `TranslateManyResult` (由 `TranslationResult` 对象组成的数组) ，其顺序与输入相同。


### 重载 2：Record 形式的条目

```typescript
translateMany(
  sources: Record<string, TranslateManyEntry>,
  options: string | TranslateOptions,
  timeout?: number
): Promise<Record<string, TranslationResult>>
```

给定一个以哈希值为键的记录时，返回一个以相同哈希值为键的记录。


### 参数

<TypeTable
  type={{
  "sources": {
    type: 'TranslateManyEntry[] | Record<string, TranslateManyEntry>',
    description: '要翻译的条目数组或记录对象。',
    optional: false,
  },
  "options": {
    type: 'string | TranslateOptions',
    description: '目标区域设置字符串（简写）或选项对象。',
    optional: false,
  },
  "timeout?": {
    type: 'number',
    description: '可选的请求超时时间（毫秒）。',
    optional: true,
  }
}}
/>

### TranslateManyEntry

每个条目都可以是普通字符串，也可以是包含源内容和可选元数据的对象：

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


### TranslateOptions

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


### 参数说明

| 参数        | 说明                                                                                    |
| --------- | ------------------------------------------------------------------------------------- |
| `sources` | 由 `TranslateManyEntry` 项组成的数组或记录对象。每一项都可以是普通字符串，也可以是包含 `source` 和可选 `metadata` 的对象。   |
| `options` | 目标区域设置字符串 (例如 `'es'`) ，或包含 `targetLocale`、可选的 `sourceLocale` 和 `modelProvider` 的选项对象。 |
| `timeout` | 可选的请求超时时间，单位为毫秒。                                                                      |

### 返回值

* **数组输入** → `Promise<TranslateManyResult>` (`TranslationResult[]`)，顺序与输入一致
* **记录输入** → `Promise<Record<string, TranslationResult>>`，键与相同的哈希对应

***

## 行为

### Array 与 Record

* **Array**：条目会在内部进行哈希处理；结果按输入顺序返回。
* **Record**：键会被当作哈希值处理；响应会返回一个具有相同键的记录。

### 错误处理策略

* 单个翻译失败不会中断整个批处理
* 每个结果都会独立标明成功或失败
* 完全支持部分成功的情况

### 选项简写

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

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

***


## 示例

### 字符串数组

```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' }
);
```


### Record (以哈希为键) 

```typescript
const results = await gt.translateMany(
  {
    'greeting-hash': 'Hello, world!',
    'farewell-hash': 'Goodbye, world!'
  },
  'es'
);

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

***


## 注意事项

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

## 后续步骤

* 了解单个翻译，请参阅 [translate](/docs/core/class/methods/translation/translate)
* 查看 [TranslateManyEntry 类型](/docs/core/types/Entry)
* 了解 [TranslateManyResult 结构](/docs/core/types/translate-many-result)