# General Translation Platform: determineLocale
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/locales/determine-locale.mdx
---

title: determineLocale
description: 从已批准区域设置列表中找出最佳匹配的区域设置。determineLocale 的 API 参考。

---

在 [GT](/docs/platform/core/reference/gt-class/constructor) 实例中，根据用户偏好从已批准区域设置列表里确定最佳匹配的区域设置。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 不可用时，会回退到语言匹配。
* **偏好顺序。** 遵循输入数组的顺序，因此会优先选择偏好更高的语言匹配，而不是偏好更低的精确匹配。
* **无匹配。** 如果找不到合适的匹配项，则返回 `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 应用程序中实现区域设置协商至关重要。