# General Translation Platform: determineLocale
URL: https://generaltranslation.com/en-US/docs/platform/core/reference/utility-functions/locales/determine-locale.mdx
Docs index: https://generaltranslation.com/llms.txt
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.** Checks the exact locale, then derived language-region, language-script, and minimized codes. If none match, it checks the language's likely region and script. For example, `fr-CA` can match `fr-FR`, while `en-AU` does not match an approved list containing only `en-GB`.
- **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 standardizing 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) | Locales eligible for matching. | `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 locales eligible for matching. Array order does not determine which same-language locale wins; matching uses the derived region and script for each user preference.

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

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

A custom mapping applied when validating and standardizing the 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]

- Matches exact and derived locale codes, including likely-region and likely-script fallbacks.
- Respects the preference order of the input array.
- Does not use approved-locale array order as a tie-breaker.
- Returns `undefined` when no match is found.
- Essential for web application locale negotiation.

## Sitemap

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