# General Translation Platform: determineLocale
URL: https://generaltranslation.com/ja/docs/platform/core/reference/utility-functions/locales/determine-locale.mdx
---

title: determineLocale
description: GT インスタンスなしで最適なロケールを見つけます。determineLocale の API リファレンス。

---

[`determineLocale`](/docs/platform/core/reference/gt-class-methods/locales/determine-locale) は、General Translation のコアライブラリに含まれるスタンドアロンのユーティリティ関数で、ユーザーの設定に基づいて、承認済みロケールの一覧から最適なロケールを見つけます。GT インスタンスを必要とせずにコンテンツネゴシエーションを実現します。

## 概要 [#overview]

`generaltranslation` から `determineLocale` を直接インポートし、ユーザーの優先ロケールと承認済みロケールの一覧を引数に渡して呼び出します。これには API key も [GT](/docs/platform/core/reference/gt-class/constructor) インスタンスも必要ありません。`approvedLocales` のデフォルト値としてインスタンスに設定された locales を使うインスタンスベースの同等機能が必要な場合は、代わりに [`GT`](/docs/platform/core/reference/gt-class/constructor) インスタンスの [`determineLocale`](/docs/platform/core/reference/gt-class-methods/locales/determine-locale) メソッドを使用してください。

```typescript
import { determineLocale } from 'generaltranslation';

const approvedLocales = ['en-US', 'es-ES', 'fr-FR', 'de-DE'];

const best = determineLocale(['fr-CA', 'es-MX'], approvedLocales);
// 戻り値: "fr-FR"
```

シグネチャ:

```typescript
determineLocale(
  locales: string | string[],
  approvedLocales?: string[],
  customMapping?: CustomMapping
): string | undefined
```

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

* **優先順位。** `locales` は、優先順位順に並べた単一のロケールまたは配列です。各候補は、承認済みロケールの一覧に対して順に照合されます。
* **マッチング。** まず完全一致を優先し、一致しない場合は同じ基本言語の別の方言にフォールバックします。たとえば、優先候補が `fr-CA` の場合、次の候補に進む前に承認済みの `fr-FR` に一致します。
* **一致なし。** どの候補も承認済みロケールに一致しない場合は、`undefined` を返します。
* **カスタムマッピング。** ロケールの検証と標準化では、[`customMapping`](/docs/platform/core/reference/types/custom-mapping) が適用されます。

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

| パラメーター                                 | 説明                         | 型                                                                     | 任意  | デフォルト |
| -------------------------------------- | -------------------------- | --------------------------------------------------------------------- | --- | ----- |
| [`locales`](#locales)                  | 単一のロケール、または優先順に並べたロケールの配列。 | `string \| string[]`                                                  | いいえ | —     |
| [`approvedLocales`](#approved-locales) | 承認済みロケール。これも優先順に並べられます。    | `string[]`                                                            | はい  | `[]`  |
| [`customMapping`](#custom-mapping)     | マッチング時に適用するカスタムのロケールマッピング。 | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | はい  | —     |

### `locales` [#locales]

**型** `string | string[]` · **必須**

単一のロケール、または優先度順 (最も優先されるものが先頭) のロケール配列。

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

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

照合に使用する承認済みロケールの一覧で、優先順にも並んでいます。

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

**型** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **任意**

マッチング前にロケールを検証・標準化する際に適用されるカスタムマッピングです。

## 戻り値 [#returns]

**型** `string | undefined`

`approvedLocales` の中で最も適切に一致するロケール。一致するものが見つからない場合は `undefined`。

## 例 [#examples]

```typescript
import { determineLocale } from 'generaltranslation';

const approvedLocales = ['en-US', 'es-ES', 'fr-FR', 'de-DE'];

// 完全一致
console.log(determineLocale('en-US', approvedLocales)); // 'en-US'

// 言語フォールバック (en-GB → en-US)
console.log(determineLocale('en-GB', approvedLocales)); // 'en-US'

// 複数の優先ロケール (fr-CA は es-MX より先に fr-FR に一致する)
console.log(determineLocale(['fr-CA', 'es-MX'], approvedLocales)); // 'fr-FR'

// 一致なし
console.log(determineLocale('it-IT', approvedLocales)); // undefined
```

## メモ [#notes]

* インテリジェントなロケールネゴシエーションを実装しています。まず完全一致を優先し、次に同じ言語の別方言を試します。
* 入力配列の優先順を尊重します。
* 一致するものが見つからない場合は `undefined` を返します。
* Web アプリケーションのロケールネゴシエーションに不可欠です。