Author:
    Aymeric PINEAU
    Creation:2026-09-19Last update:2026-09-19

    useLocale Hook Documentation

    The useLocale hook from remix-intlayer provides access to the locale of the HTTP request currently being processed, along with the project's configured default and available locales.

    Usage

    In a Remix component (for example a language switcher):

    src/components/LocaleSwitcher.tsx
    import { type FC } from "react";
import { Link } from "@remix-run/react";
import { useLocale } from "remix-intlayer";
import { getLocalizedUrl, getPathWithoutLocale } from "intlayer";

export const LocaleSwitcher: FC = () => {
  const { locale, availableLocales } = useLocale();
  const pathWithoutLocale = getPathWithoutLocale();

  return (
    <nav>
      <ul>
        {availableLocales.map((localeItem) => (
          <li key={localeItem} className="p-1">
            <Link
              href={getLocalizedUrl(pathWithoutLocale, localeItem)}
              aria-current={localeItem === locale ? "page" : undefined}
            >
              {localeItem.toUpperCase()}
            </Link>
          </li>
        ))}
      </ul>
    </nav>
  );
};

    In a route handler:

    src/server.ts
    import { createRouter } from "remix/router";
import { intlayer, useLocale } from "remix-intlayer";

const router = createRouter({
  middleware: [intlayer()],
});

router.get("/api/locale-info", () => {
  const { locale, defaultLocale, availableLocales } = useLocale();

  return Response.json({
    locale,
    defaultLocale,
    availableLocales,
  });
});

    Return Values

    The hook returns an object of type UseLocaleResult:

    PropertyTypeDescription
    localeDeclaredLocalesThe locale resolved for the current request.
    defaultLocaleDeclaredLocalesThe default fallback locale configured in intlayer.config.ts.
    availableLocalesDeclaredLocales[]Array of all available locales configured in intlayer.config.ts.

    Description

    1. Request-Scoped Resolution: In an active request handled by the intlayer() middleware, useLocale reads the resolved locale from the request storage.
    2. Graceful Fallback: If called outside of a request context (such as during initialization scripts or test suites), it defaults to the configured defaultLocale.

    Related Documentation

    useIntlayervite-intlayer