# General Translation Platform: determineLocale
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/locales/determine-locale.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 从已批准区域设置列表中找出最佳匹配的区域设置。determineLocale 的 API 参考。

General Translation 实现了区域设置协商，以便在没有精确匹配时找出最合适的区域设置。

## 概览 [#overview]

在 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上调用 `determineLocale`，并按偏好顺序传入一个或多个首选区域设置。它会返回最匹配的已批准区域设置；如果都不匹配，则返回 `undefined`。

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

// 精确匹配
console.log(gt.determineLocale('en-US')); // 'en-US'

// 语言后备内容
console.log(gt.determineLocale('en-GB')); // 'en-US'（可能区域后备内容）

// 多个偏好（按偏好顺序匹配）
console.log(gt.determineLocale(['fr-CA', 'es-MX', 'en-US'])); // 'fr-FR'（与第一偏好最接近）

// 无匹配项
console.log(gt.determineLocale('it-IT')); // undefined
```

签名：

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

*注意：`determineLocale` 在本地运行，无需 API Key。省略 `approvedLocales` 和 `customMapping` 时，它会使用该实例的 `locales` 和 `customMapping`。如果要在不使用 `GT` 实例的情况下进行匹配，请参阅独立版的 [`determineLocale`](/docs/platform/core/reference/utility-functions/locales/determine-locale)。*

## 工作原理 [#how-it-works]

* **优先精确匹配。** 针对当前用户偏好返回精确的已批准区域设置匹配项。
* **派生区域设置匹配。** 在使用该语言的可能 region 和 script 之前，会先检查 language-region、language-script 以及最小化形式。
* **偏好顺序。** 遵循输入数组的顺序，因此会优先选择偏好更高的语言匹配，而不是偏好更低的精确匹配。
* **已批准的区域设置。** 将 `approvedLocales` 视为符合条件的结果集合。其数组顺序不会在同语言候选项之间进行选择。
* **无匹配。** 如果找不到合适的匹配项，则返回 `undefined`。

## 参数 [#parameters]

| 参数                                     | 描述                      | 类型                                                                    | 可选 | 默认值                  |
| -------------------------------------- | ----------------------- | --------------------------------------------------------------------- | -- | -------------------- |
| [`locales`](#locales)                  | 单个区域设置，或按偏好顺序排列的多个区域设置。 | `string \| string[]`                                                  | 否  | —                    |
| [`approvedLocales`](#approved-locales) | 可参与匹配的区域设置。             | `string[]`                                                            | 是  | `this.locales`       |
| [`customMapping`](#custom-mapping)     | 用于解析的自定义区域设置映射。         | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | 是  | `this.customMapping` |

### `locales` [#locales]

**类型** `string | string[]` · **必填**

单个区域设置，或按偏好顺序排列的区域设置数组 (例如浏览器的 `Accept-Language` 列表) 。

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

**类型** `string[]` · **可选** · **默认值** `this.locales`

可参与匹配的区域设置。省略时，使用该实例的 `locales`。数组顺序并不决定同一语言的多个区域设置中哪一个胜出。

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

**类型** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **可选** · **默认值** `this.customMapping`

解析时使用的自定义区域设置映射。省略时，将使用该实例的 `customMapping`。

## 返回值 [#returns]

**类型** `string | undefined`

最匹配的区域设置；如果未找到匹配结果，则为 `undefined`。

## 示例 [#examples]

```typescript
// 用户区域设置协商
const gt = new GT({
  sourceLocale: 'en-US',
  locales: ['en-US', 'en-GB', 'es-ES', 'fr-FR'],
});

// 模拟浏览器 Accept-Language header
const userPreferences = ['fr-CA', 'en-GB', 'en'];
const bestMatch = gt.determineLocale(userPreferences);
console.log(bestMatch); // 根据偏好顺序返回 'fr-FR'
```

## 说明 [#notes]

* 针对每个用户偏好检查精确的及派生的区域设置代码。
* 使用可能的地区和可能的书写系统作为后备内容，而不是任意的同语言方言匹配。
* 遵循输入数组中的偏好顺序。
* 不会将已批准区域设置数组的顺序作为决胜依据。
* 如果找不到合适的匹配项，则返回 `undefined`。
* 这对于在 Web 应用程序中实现区域设置协商至关重要。

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.