# General Translation Platform: determineLocale
URL: https://generaltranslation.com/en-GB/docs/platform/core/reference/gt-class-methods/locales/determine-locale.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Find the best-matching locale from a list of approved locales. API reference for determineLocale.

General Translation implements locale negotiation to find the most suitable locale when an exact match is not available.

## Overview [#overview]

Call `determineLocale` on a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance with one or more preferred locales, in order of preference. It returns the best matching approved locale, or `undefined` if none matches.

```typescript
const gt = new GT({
  sourceLocale: 'en-US',
  locales: ['en-US', 'es-ES', 'fr-FR', 'de-DE'],
});

// Exact match
console.log(gt.determineLocale('en-US')); // 'en-US'

// Language fallback
console.log(gt.determineLocale('en-GB')); // 'en-US' (likely-region fallback)

// Multiple preferences (preference order wins)
console.log(gt.determineLocale(['fr-CA', 'es-MX', 'en-US'])); // 'fr-FR' (closest to first preference)

// No match
console.log(gt.determineLocale('it-IT')); // undefined
```

Signature:

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

*Note: `determineLocale` runs locally and does not require an API key. When `approvedLocales` and `customMapping` are omitted, it uses the instance's `locales` and `customMapping`. For matching without a `GT` instance, see the standalone [`determineLocale`](/docs/platform/core/reference/utility-functions/locales/determine-locale).*

## How it works [#how-it-works]

* **Exact match first.** Returns an exact approved-locale match for the current user preference.
* **Derived locale matching.** Checks language-region, language-script, and minimised forms before using the language's likely region and script.
* **Preference order.** Honours the order of the input array, so a higher-preference language match is chosen over a lower-preference exact match.
* **Approved locales.** Treats `approvedLocales` as the set of eligible results. Its array order does not choose between same-language candidates.
* **No match.** Returns `undefined` when no suitable match is found.

## Parameters [#parameters]

| Parameter                              | Description                                                 | Type                                                                  | Optional | Default              |
| -------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------- | -------- | -------------------- |
| [`locales`](#locales)                  | A single locale or array of locales in order of preference. | `string \| string[]`                                                  | No       | —                    |
| [`approvedLocales`](#approved-locales) | Locales eligible for matching.                              | `string[]`                                                            | Yes      | `this.locales`       |
| [`customMapping`](#custom-mapping)     | Custom locale mapping used for resolution.                  | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | Yes      | `this.customMapping` |

### `locales` [#locales]

**Type** `string | string[]` · **Required**

A single locale or an array of locales in order of preference (for example, a browser `Accept-Language` list).

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

**Type** `string[]` · **Optional** · **Default** `this.locales`

Locales eligible for matching. When omitted, the instance's `locales` are used. Array order does not determine which same-language locale wins.

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

**Type** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **Optional** · **Default** `this.customMapping`

Custom locale mapping used during resolution. When omitted, the instance's `customMapping` is used.

## Returns [#returns]

**Type** `string | undefined`

The best matching locale, or `undefined` if no match is found.

## Examples [#examples]

```typescript
// User locale negotiation
const gt = new GT({
  sourceLocale: 'en-US',
  locales: ['en-US', 'en-GB', 'es-ES', 'fr-FR'],
});

// Simulate a browser Accept-Language header
const userPreferences = ['fr-CA', 'en-GB', 'en'];
const bestMatch = gt.determineLocale(userPreferences);
console.log(bestMatch); // 'fr-FR' based on preference order
```

## Notes [#notes]

* Checks exact and derived locale codes for each user preference.
* Uses likely-region and likely-script fallbacks, not arbitrary same-language dialect matching.
* Respects preference order in the input array.
* Does not use approved-locale array order as a tie-breaker.
* Returns `undefined` when no suitable match is found.
* Essential for implementing locale negotiation in web applications.

## Sitemap

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