# General Translation Platform: translate
URL: https://generaltranslation.com/ja/docs/platform/core/reference/gt-class-methods/translation/translate.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: General Translation を使用して、1 つの string または構造化コンテンツのエントリをターゲットロケールに翻訳します。translate の API リファレンスです。

`translate` は、[GT](/docs/platform/core/reference/gt-class/constructor) インスタンスの主要な翻訳メソッドであり、1 回に 1 つの string または構造化コンテンツのエントリを翻訳します。

## 概要 [#overview]

設定済みの [`GT`](/docs/platform/core/reference/gt-class/constructor) インスタンスで `translate` を呼び出すと、1 つのエントリを翻訳できます。翻訳する内容と、ターゲットロケールのロケール文字列 (省略形) または options object のいずれかを渡します。戻り値は [`TranslationResult`](/docs/platform/core/reference/types/translation-result) に解決される Promise です。

```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` メタデータに基づいて、plain text、ICU メッセージ、i18next スタイルのメッセージ、または構造化された JSX content として判別されます。
* **ドキュメント全体。** [`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]

| パラメーター                | 説明                                                       | 型                                                                                | 任意  | デフォルト |
| --------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------- | --- | ----- |
| [`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)) と、コンテキスト、`dataFormat`、その他の翻訳ヒントを追加する任意の `metadata` ([`EntryMetadata`](/docs/platform/core/reference/types/entry-metadata)) を含むオブジェクトを渡します。

### `options` [#options]

**型** `string | TranslateOptions` · **必須**

`'es'` のようなターゲットロケールを表す文字列、またはオプションオブジェクト:

```typescript
type TranslateOptions = {
  targetLocale: string; // 翻訳先のロケール
  sourceLocale?: string; // インスタンスのsourceLocaleを上書きする
  modelProvider?: string; // モデルプロバイダーのヒント（省略可）
};
```

### `timeout` [#timeout]

**Type** `number` · **任意**

リクエストのタイムアウト時間 (ミリ秒) 。省略した場合は、インスタンスのデフォルト値が使用されます。

## 戻り値 [#returns]

**型** `Promise<TranslationResult>`

[`TranslationResult`](/docs/platform/core/reference/types/translation-result) を返します。これは、成功時の結果 (`translation` と `locale` を含む) またはエラー時の結果 (`error` と `code` を含む) を表す判別可能な union です。翻訳を参照する前に、必ず `success` で絞り込んでください。

## 例 [#examples]

```typescript
// シンプルなstring翻訳（ロケールのshorthand）
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.