# General Translation Platform: determineLocale
URL: https://generaltranslation.com/en-US/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 preference order. It returns the best matching approved locale, or `undefined` when 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 minimized forms before using the language's likely region and script.
- **Preference order.** Respects 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 preference order. | `string \| string[]` | No | — |
| [`approvedLocales`](#approved-locales) | Locales eligible for matching. | `string[]` | Yes | `this.locales` |
| [`customMapping`](#custom-mapping) | Custom locale mapping 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 preference order (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.