Auteur:
    Aymeric PINEAU
    Création:2026-09-19Dernière mise à jour:2026-09-19

    Documentation du hook useLocale

    Le hook useLocale de astro-intlayer fournit un accès à la locale de requête actuelle, à la locale par défaut configurée et à toutes les locales disponibles dans les applications Astro.

    Il se comporte de manière cohérente dans le frontmatter .astro rendu côté serveur et dans les blocs <script> côté client.

    Utilisation

    Dans le frontmatter de composant (Rendu côté serveur)

    src/layouts/Layout.astro
    ---
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>Actuelle : {locale}</span>
      <span>Par défaut : {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>

    Dans un <script> client (Interactif)

    src/components/LocaleSwitcher.astro
    ---
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>

    Valeurs de retour

    Le hook retourne un objet de type UseLocaleResult :

    PropriétéTypeDescription
    localeDeclaredLocalesLa locale active.
    defaultLocaleDeclaredLocalesLa locale de repli par défaut configurée dans intlayer.config.ts.
    availableLocalesDeclaredLocales[]Tableau de toutes les locales supportées configurées pour le projet.
    setLocale(locale: LocalesValues) => voidFonction pour mettre à jour la locale. (Interactive dans <script>, avertit lors du SSR).
    subscribe(callback: () => void) => () => voidS'abonne aux changements de locale côté client.

    Comportement Serveur vs Client

    • Pendant le SSR / Rendu Serveur : Une requête est rendue une seule fois avec des paramètres fixes. Appeler setLocale() pendant un rendu serveur n'a aucun effet et émet un avertissement ; le changement de locale doit être effectué côté client ou en naviguant vers l'URL de la locale cible.
    • Dans les scripts client : setLocale met à jour le store client et met à jour les cookies persistants ou le stockage local selon votre configuration Intlayer.

    Documentation associée

    useIntlayerremix-intlayer