Overview

The getLocale function retrieves the user’s current locale during server-side rendering. The returned locale is formatted as a string, e.g. 'en-US'.

For client-side usage, see useLocale.

Reference

Returns

A promise that resolves to a string representing the user’s current locale, e.g. ‘en-US’.

Fallback behaviour

When an unsupported locale is requested, a fallback locale will be selected.

For example, if an unsupported locale is requested, and (1) the user has configured multiple preferred locales in their browser settings, and (2) one of these locales is supported by your application, then the locale will fall back to the best match.

Additionally, if no direct fallback locales are available, but two locales share the same language (e.g., en-US and en-GB), then the locale will fall back to the supported locale that shares the same language.

If neither condition can be met, the default locale will be used.

See the gt.config.json docs for information on configuring supported locales.

Examples

Basic usage

Retrieve the user's locale during server-side rendering.

import { getLocale } from 'gt-next/server';

export default async function GetUserLocale() {
    const locale = await getLocale(); 
    return <p>User locale: {locale}</p>;
}

Notes

• The getLocale function is asynchronous and must be awaited to retrieve the locale.
• It is specifically designed for server-side use. See useLocale for client-side components.
• The returned locale follows the locale strings format.

Next steps

• Learn how to configure supported locales with withGTConfig().