Can I use Intlayer without a global provider?

    Yes. getIntlayer and getDictionary are plain functions that do not need any provider, and useIntlayer also works outside of one.

    ts
    import { getIntlayer } from "intlayer";

const { title } = getIntlayer("app"); // No locale passed

    Which locale is used?

    When you pass a locale, it always wins. Otherwise, the locale is resolved in this order:

    1. The locale of the current request, on the server, when an Intlayer integration handles it: the middlewares of express-intlayer, fastify-intlayer, hono-intlayer, adonis-intlayer, elysia-intlayer, remix-intlayer and astro-intlayer, or IntlayerProvider in React Server Components.
    2. The locale stored in the browser (cookie, localStorage, sessionStorage), the one your locale switcher persists.
    3. The defaultLocale of your configuration.

    Each request is resolved from its own cookies and headers, and kept in a per-request scope. Concurrent users with different locales never share a locale.

    The same resolution applies to getDictionary, to the calls rewritten by the build optimisation, and to useIntlayer and useDictionaryDynamic rendered outside of a provider.

    build optimisation

    Next.js Server Components

    On Next.js, the request locale is only readable asynchronously, through headers() and cookies(). Use getIntlayerAsync, which awaits it the same way getLocale() from next-intlayer/server does:

    getIntlayerAsync
    tsx
    import { getIntlayerAsync } from "intlayer";

export const generateMetadata = async () => {
  const { title } = await getIntlayerAsync("app"); // Locale of the request

  return { title };
};

    Reading the headers opts the route into dynamic rendering. When IntlayerProvider already provides the locale, the headers are not read and the route stays static.

    Performance: with or without a provider

    The content is the same. The difference is about reactivity and rendering cost.

    With a providerWithout a provider
    Locale switchComponents re-render in place, without a reloadNothing re-renders; the new locale shows on the next call (navigation, reload)
    Cost of a readContext lookup and subscription to the localeA memoised function call, same object for the same key + locale
    Cost of a switchRe-render of every consumerNone
    Server renderingThe server and the browser render the same localeOutside of a request integration, the server renders the defaultLocale and the browser the stored locale: possible hydration mismatch
    BundleThe provider codeAbout 100 bytes (gzipped) to read the stored locale, cached until the locale changes

    Keep the provider for interactive apps that switch locale in place or render on the server. Go without one for backends, scripts, static pages whose locale comes from the URL (pass it explicitly), or code that reads content once.

    See getIntlayer for more details.

    getIntlayer