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

title: requiresTranslation
description: 2 つのロケール間で翻訳が必要かどうかを確認します。requiresTranslation の API リファレンス。

---

[GT](/docs/platform/core/reference/gt-class/constructor) インスタンスで、ソースロケールとターゲットロケールの間で翻訳が必要かどうかを判定します。General Translation はロケールコードを比較し、承認済みロケールの一覧を考慮して、コンテンツを翻訳する必要があるかどうかを判断します。

## 概要 [#overview]

[`GT`](/docs/platform/core/reference/gt-class/constructor) インスタンスに対して `requiresTranslation` を呼び出す際は、必要に応じてソースロケールとターゲットロケールを指定できます。省略した場合は、そのインスタンスの `sourceLocale` と `targetLocale` が使用されます。

```typescript
const gt = new GT({
  sourceLocale: 'en-US',
  targetLocale: 'es-ES',
  locales: ['en-US', 'es-ES', 'fr-FR', 'de-DE'],
});

console.log(gt.requiresTranslation('en-US', 'es-ES')); // true
console.log(gt.requiresTranslation('en', 'en-US')); // false（同じダイアレクト）
```

シグネチャ:

```typescript
requiresTranslation(
  sourceLocale?: string,
  targetLocale?: string,
  approvedLocales?: string[],
  customMapping?: CustomMapping
): boolean
```

*注: `requiresTranslation` はローカルで実行されるため、APIキーは不要です。引数を省略した場合は、インスタンスの `sourceLocale`、`targetLocale`、`locales`、`customMapping` が使用されます。`GT` インスタンスなしでチェックする場合は、スタンドアロンの [`requiresTranslation`](/docs/platform/core/reference/utility-functions/locales/requires-translation) を参照してください。*

## 仕組み [#how-it-works]

このメソッドは、次の順序で判定されます。

1. **有効性。** ソース、ターゲット、または承認済みロケールのいずれかが有効なロケールでない場合は、`false` を返します。
2. **同一方言。** ソースとターゲットが同じ方言である場合 (たとえば `en` と `en-US`) 、`false` を返します。翻訳は不要です。
3. **許可リストなし。** 適用される `approvedLocales` がない場合は、ソースとターゲットが異なるときに `true` を返します。
4. **許可範囲。** それ以外の場合は、ターゲットの言語が、少なくとも 1 つの承認済みロケールの言語と一致するときにのみ `true` を返します。同じ言語でも方言が異なれば翻訳が必要とみなされます (そのため、より近い方言をフォールバックとして使用できます) 。ターゲットの言語が承認済みロケールに含まれていない場合は、`false` を返します。

`sourceLocale` または `targetLocale` を省略した場合は、インスタンスの値が使用されます。ソースロケールが指定されておらず、かつインスタンスに `sourceLocale` がない場合、またはターゲットロケールが指定されておらず、かつインスタンスに `targetLocale` がない場合は、`Error` をスローします。

## パラメーター [#parameters]

| パラメーター                                 | 説明                 | 型                                                                     | 任意 | デフォルト                |
| -------------------------------------- | ------------------ | --------------------------------------------------------------------- | -- | -------------------- |
| [`sourceLocale`](#source-locale)       | ソースロケールのコード。       | `string`                                                              | はい | `this.sourceLocale`  |
| [`targetLocale`](#target-locale)       | ターゲットロケールのコード。     | `string`                                                              | はい | `this.targetLocale`  |
| [`approvedLocales`](#approved-locales) | 承認済みターゲットロケールの配列。  | `string[]`                                                            | はい | `this.locales`       |
| [`customMapping`](#custom-mapping)     | ロケール解決用のカスタムマッピング。 | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | はい | `this.customMapping` |

### `sourceLocale` [#source-locale]

**型** `string` · **任意** · **デフォルト** `this.sourceLocale`

ソースロケールのロケールコード。指定しない場合は、このインスタンスの `sourceLocale` が使用されます。

### `targetLocale` [#target-locale]

**型** `string` · **任意** · **デフォルト** `this.targetLocale`

ターゲットロケールコードです。指定しない場合は、インスタンスの `targetLocale` が使用されます。

### `approvedLocales` [#approved-locales]

**型** `string[]` · **任意** · **デフォルト** `this.locales`

承認済みのターゲットロケールの配列です。指定しない場合は、このインスタンスの `locales` 配列が使用されます。ターゲットロケールがこのリストに含まれていない場合、このメソッドは `false` を返します。

### `customMapping` [#custom-mapping]

**型** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **任意** · **デフォルト** `this.customMapping`

ロケール解決用のカスタムマッピング。

## 戻り値 [#returns]

**型** `boolean`

翻訳が必要な場合は `true`、不要な場合は `false` です。ソースまたはターゲットロケールを解決できない場合は、`Error` をスローします。

## 例 [#examples]

```typescript
const gt = new GT({
  sourceLocale: 'en-US',
  targetLocale: 'es-ES',
  locales: ['en-US', 'es-ES', 'fr-FR', 'de-DE'],
});

// 異なる言語は翻訳が必要
console.log(gt.requiresTranslation('en-US', 'es-ES')); // true
console.log(gt.requiresTranslation('en-US', 'fr-FR')); // true

// 全く同じダイアレクトは翻訳不要
console.log(gt.requiresTranslation('en-US', 'en-US')); // false
console.log(gt.requiresTranslation('es-ES', 'es-ES')); // false
console.log(gt.requiresTranslation('en', 'en-US')); // false (同じダイアレクト)

// 同じ言語の異なるダイアレクトは翻訳が必要
// (より近いダイアレクトをフォールバックとして使用できる)
console.log(gt.requiresTranslation('en-US', 'en-GB')); // true
console.log(gt.requiresTranslation('es-ES', 'es-MX')); // true

// ターゲット言語が承認済みロケールに含まれていない場合
console.log(gt.requiresTranslation('en-US', 'it-IT')); // false (it-IT は承認済みロケールに含まれていない)
```

## メモ [#notes]

* `false` を返すのは、完全に同じ方言、無効なロケール、または対象の言語が承認済みロケールに含まれていない場合に限られます。
* 同じ言語でも異なる方言 (たとえば `en-US` と `en-GB`) では翻訳が必要になるため、より近い方言をフォールバックとして使えます。
* 承認済みロケールの一覧が考慮され、照合は完全に同じ方言ではなく、言語単位で行われます。