Author:

Creation:2026-09-19Last update:2026-09-19

Reference this doc to your favorite AI assistantChatGPT Claude DeepSeek Google AI mode Gemini Perplexity Mistral Grok

Ask your question and get a summary of the document by referencing this page and the AI provider of your choice

Version History

"Init doc"
v9.5.519/09/2026

The content of this page was translated using an AI.

See the last version of the original content in English

Edit this doc

If you have an idea for improving this documentation, please feel free to contribute by submitting a pull request on GitHub.

GitHub link to the documentation

Copy

Copy doc Markdown to clipboard

useLocale Hook Documentation

Name: Intlayer
Rating: 4.92 (64 reviews)
Author: Intlayer

The useLocale hook from astro-intlayer provides access to the current request locale, the configured default locale, and all available locales in Astro applications.

It behaves consistently across server-rendered .astro frontmatter and client-side <script> blocks.

Usage

In Component Frontmatter (Server-Rendered)

src/layouts/Layout.astro

Copy code

Copy the code to the clipboard

---
import { useLocale } from "astro-intlayer";
import { getLocalizedUrl, getPathWithoutLocale } from "intlayer";

const { locale, defaultLocale, availableLocales } = useLocale();
const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
---

<!DOCTYPE html>
<html lang={locale}>
  <head>
    <meta charset="utf-8" />
    <title>Astro + Intlayer</title>
  </head>
  <body>
    <header>
      <span>Current: {locale}</span>
      <span>Default: {defaultLocale}</span>
      <nav>
        <ul>
          {availableLocales.map((localeItem) => (
            <li key={localeItem} className="p-1">
              <a
                href={getLocalizedUrl(pathWithoutLocale, localeItem)}
                aria-current={localeItem === locale ? "page" : undefined}
              >
                {localeItem.toUpperCase()}
              </a>
            </li>
          ))}
        </ul>
      </nav>
    </header>
    <slot />
  </body>
</html>

In Client `<script>` (Interactive)

src/components/LocaleSwitcher.astro

Copy code

Copy the code to the clipboard

---
import { useLocale } from "astro-intlayer";

const { locale, availableLocales } = useLocale();
---

<select id="locale-select">
  {availableLocales.map((loc) => (
    <option value={loc} selected={loc === locale}>
      {loc.toUpperCase()}
    </option>
  ))}
</select>

<script>
  import { useLocale, setLocaleInStorage } from "astro-intlayer";

  const { setLocale } = useLocale();

  document.getElementById("locale-select")?.addEventListener("change", (e) => {
    const target = e.target as HTMLSelectElement;
    setLocale(target.value);
  });
</script>

Return Values

The hook returns an object of type UseLocaleResult:

Show all table content

Open the table in a modal to view all data content clearly

Property	Type	Description
`locale`	`DeclaredLocales`	The active locale.
`defaultLocale`	`DeclaredLocales`	The default fallback locale configured in `intlayer.config.ts`.
`availableLocales`	`DeclaredLocales[]`	Array of all supported locales configured for the project.
`setLocale`	`(locale: LocalesValues) => void`	Function to update the locale. (Interactive in client `<script>`, warns during SSR).
`subscribe`	`(callback: () => void) => () => void`	Subscribes to client-side locale changes.

Server vs Client Behaviour

During SSR / Server Rendering: A request is rendered once with fixed parameters. Calling setLocale() during a server render has no effect and emits a warning; locale switching should be performed on the client or by navigating to the target locale URL.
In Client Scripts: setLocale updates the client store and updates persisted cookies or local storage according to your Intlayer configuration.

useIntlayer remix-intlayer