# General Translation Platform: translate
URL: https://generaltranslation.com/ja/docs/platform/core/reference/gt-class-methods/translation/translate.mdx
---

title: translate
description: General Translation を使用して、1 つの string または構造化コンテンツのエントリをターゲットロケールに翻訳します。translate の API リファレンスです。

---

単一の string または構造化コンテンツのエントリを、ソースロケールからターゲットロケールに翻訳します。これは、[GT](/docs/platform/core/reference/gt-class/constructor) インスタンスの主要な翻訳メソッドです。

## 概要 [#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 として判別されます。
* **ロケールの解決。** ターゲットロケール は 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
// options objectと明示的なソースロケールを指定する場合
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' }
);
```