# General Translation Platform: determineLocale
URL: https://generaltranslation.com/zh/docs/platform/core/reference/utility-functions/locales/determine-locale.mdx
Docs index: https://generaltranslation.com/llms.txt
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 数组。系统会按顺序将每个偏好与允许列表进行匹配。
* **匹配。** 先检查完全一致的区域设置，然后依次检查派生出的 language-区域、language-书写系统 以及最小化代码。如果都不匹配，则检查该语言最可能的区域 和 书写系统。例如，`fr-CA` 可以匹配 `fr-FR`，而 `en-AU` 则无法匹配仅包含 `en-GB` 的已批准列表。
* **无匹配。** 如果没有任何偏好能与已批准的区域设置匹配，则返回 `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 应用中的区域设置协商至关重要。

## Sitemap

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