# General Translation Platform: determineLocale
URL: https://generaltranslation.com/ru/docs/platform/core/reference/gt-class-methods/locales/determine-locale.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Находит наиболее подходящую локаль из списка разрешённых локалей. Справка по API для determineLocale.

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' (likely-region fallback)

// Несколько предпочтений (порядок предпочтения имеет приоритет)
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]

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

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

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

## Sitemap

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