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.59/19/2026

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 Behavior

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