# General Translation Platform: determineLocale
URL: https://generaltranslation.com/zh/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 Core 库提供的一个独立工具函数，可根据用户偏好，从一组已批准的区域设置中找出最匹配的区域设置。它可在无需 GT 实例的情况下实现内容协商。

## 概览 [#overview]

直接从 `generaltranslation` 导入 `determineLocale`，并传入用户的首选 locales 和已批准的区域设置列表来调用它。它既不需要 API 密钥，也不需要 [`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` 可以是单个区域设置，也可以是按偏好顺序排序的 locales 数组。系统会按顺序将每个偏好与允许列表进行匹配。
* **匹配。** 优先进行精确匹配；如果没有，再回退到同一基础语言的其他方言。例如，偏好 `fr-CA` 会先匹配已批准的 `fr-FR`，然后才会继续检查下一个偏好。
* **无匹配。** 如果没有任何偏好能与已批准的区域设置匹配，则返回 `undefined`。
* **自定义映射。** 在验证和规范化 locales 时，会应用任何 [`customMapping`](/docs/platform/core/reference/types/custom-mapping)。

## 参数 [#parameters]

| 参数                                     | 描述                       | 类型                                                                    | 可选 | 默认值  |
| -------------------------------------- | ------------------------ | --------------------------------------------------------------------- | -- | ---- |
| [`locales`](#locales)                  | 单个区域设置，或按优先级顺序排列的 locales 数组。 | `string \| string[]`                                                  | 否  | —    |
| [`approvedLocales`](#approved-locales) | 已批准的区域设置，同样按优先级顺序排列。     | `string[]`                                                            | 是  | `[]` |
| [`customMapping`](#custom-mapping)     | 匹配时应用的自定义区域设置映射。         | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | 是  | —    |

### `locales` [#locales]

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

单个区域设置，或按优先级排序的 locales 数组 (最优先的排在最前面) 。

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

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

用于匹配的已批准的区域设置列表，同样会按优先级排序。

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

**类型** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **可选**

在匹配前用于验证和标准化 locales 的自定义映射。

## 返回值 [#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 应用中的区域设置协商至关重要。