# General Translation Platform: determineLocale
URL: https://generaltranslation.com/en-GB/docs/platform/core/reference/utility-functions/locales/determine-locale.mdx
---

title: determineLocale
description: Find the best matching locale without a GT instance. API reference for determineLocale.

---

[`determineLocale`](/docs/platform/core/reference/gt-class-methods/locales/determine-locale) is a standalone utility function from General Translation's Core library that finds the best matching locale from a list of approved locales, based on a user's preferences. It powers content negotiation without requiring a GT instance.

## Overview [#overview]

Import `determineLocale` directly from `generaltranslation` and call it with the user's preferred locale(s) and the list of approved locales. It does not require an API key or a [GT](/docs/platform/core/reference/gt-class/constructor) instance. For the instance-based equivalent that defaults `approvedLocales` to the instance's configured locales, use the [`determineLocale`](/docs/platform/core/reference/gt-class-methods/locales/determine-locale) method on a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance instead.

```typescript
import { determineLocale } from 'generaltranslation';

const approvedLocales = ['en-US', 'es-ES', 'fr-FR', 'de-DE'];

const best = determineLocale(['fr-CA', 'es-MX'], approvedLocales);
// Returns: "fr-FR"
```

Signature:

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

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

* **Preference order.** `locales` is a single locale or an array sorted in preference order. Each preference is checked in turn against the approved list.
* **Matching.** Prioritises exact matches, then falls back to another dialect of the same base language. For example, a preference of `fr-CA` matches the approved `fr-FR` before moving on to the next preference.
* **No match.** Returns `undefined` when no preference can be matched against the approved locales.
* **Custom mapping.** Any [`customMapping`](/docs/platform/core/reference/types/custom-mapping) is applied when validating and standardising locales.

## Parameters [#parameters]

| Parameter                              | Description                                                        | Type                                                                  | Optional | Default |
| -------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------- | -------- | ------- |
| [`locales`](#locales)                  | A single locale or an array of locales sorted in preference order. | `string \| string[]`                                                  | No       | —       |
| [`approvedLocales`](#approved-locales) | Approved locales, also sorted by preference.                       | `string[]`                                                            | Yes      | `[]`    |
| [`customMapping`](#custom-mapping)     | Custom locale mapping to apply during matching.                    | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | Yes      | —       |

### `locales` [#locales]

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

A single locale or an array of locales, sorted by preference (most preferred first).

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

**Type** `string[]` · **Optional** · **Default** `[]`

The list of approved locales to match against, also sorted by preference.

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

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

A custom mapping applied when validating and standardising locales before matching.

## Returns [#returns]

**Type** `string | undefined`

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

## Examples [#examples]

```typescript
import { determineLocale } from 'generaltranslation';

const approvedLocales = ['en-US', 'es-ES', 'fr-FR', 'de-DE'];

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

// Language fallback (en-GB → en-US)
console.log(determineLocale('en-GB', approvedLocales)); // 'en-US'

// Multiple preferences (fr-CA matches fr-FR before es-MX is considered)
console.log(determineLocale(['fr-CA', 'es-MX'], approvedLocales)); // 'fr-FR'

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

## Notes [#notes]

* Implements intelligent locale negotiation: exact matches first, then same-language dialects.
* Honours the preference order of the input array.
* Returns `undefined` when no match is found.
* Essential for locale negotiation in web applications.