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

title: determineLocale
description: Находит наиболее подходящую локаль из списка разрешённых локалей. Справка по API для determineLocale.

---

Определяет наиболее подходящую локаль из списка разрешённых локалей на основе пользовательских предпочтений в экземпляре [GT](/docs/platform/core/reference/gt-class/constructor). General Translation использует согласование локали, чтобы находить наиболее подходящую локаль, когда точное совпадение недоступно.

## Обзор [#overview]

Вызовите `determineLocale` у экземпляра [`GT`](/docs/platform/core/reference/gt-class/constructor), передав одну или несколько предпочтительных локалей в порядке приоритета. Метод вернёт наиболее подходящую разрешённую локаль или `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' (closest English variant)

// Несколько предпочтений (порядок определяет приоритет)
console.log(gt.determineLocale(['fr-CA', 'es-MX', 'en-US'])); // 'fr-FR' (closest to first preference)

// Нет совпадений
console.log(gt.determineLocale('it-IT')); // undefined
```

Сигнатура:

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

*Примечание: `determineLocale` выполняется локально и не требует API-ключа. Если `approvedLocales` и `customMapping` не указаны, используются `locales` и `customMapping` экземпляра. О сопоставлении без экземпляра `GT` см. в описании автономной функции [`determineLocale`](/docs/platform/core/reference/utility-functions/locales/determine-locale).*

## Как это работает [#how-it-works]

* **Сначала точное совпадение.** Возвращает первое точное совпадение из списка разрешённых локалей.
* **Резервный вариант по языку.** Если точное совпадение по региону недоступно, используется совпадение по языку.
* **Порядок предпочтения.** Учитывает порядок элементов во входном массиве: совпадение для более предпочтительного языка будет выбрано вместо менее предпочтительного точного совпадения.
* **Нет совпадений.** Возвращает `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 браузера
const userPreferences = ['fr-CA', 'en-GB', 'en'];
const bestMatch = gt.determineLocale(userPreferences);
console.log(bestMatch); // 'fr-FR' на основе порядка предпочтений
```

## Заметки [#notes]

* Возвращает первое точное совпадение среди разрешённых локалей.
* Если точное совпадение по региону недоступно, использует совпадение по языку.
* Учитывает порядок предпочтений во входном массиве.
* Возвращает `undefined`, если подходящее совпадение не найдено.
* Необходимо для реализации согласования локали в веб-приложениях.