Author:
    Aymeric PINEAU
    Creation:2026-01-21Last update:2026-08-22

    next-intlayer Package

    The next-intlayer package provides the necessary tools to integrate Intlayer into Next.js applications. It supports both the App Router and the Page Router, including middleware for locale-based routing.

    Installation

    bash
    npm install next-intlayer

    Exports

    Middleware

    Import:

    tsx
    import "next-intlayer/middleware";
    FunctionDescriptionRelated Doc
    intlayerMiddlewareNext.js middleware to handle locale-based routing and redirects. Detects locale from headers/cookies and redirects to appropriate locale path.intlayerMiddleware

    Configuration Helpers

    Import:

    tsx
    import "next-intlayer/server";
    FunctionDescriptionRelated Doc
    withIntlayerAsynchronous helper to wrap Next.js configuration, ensuring Intlayer dictionaries are prepared before build. Prepares content files and sets up webpack/SWC plugins.-
    withIntlayerSyncSynchronous helper to wrap Next.js configuration, ideal for configurations where async is not possible/desired. Does not prepare dictionaries on server start.-

    Providers

    Import:

    tsx
    import "next-intlayer";

    or

    tsx
    import "next-intlayer/server";
    ComponentDescriptionRelated Doc
    IntlayerProviderUnified provider for the Next.js App Router. Mounted once in the locale layout, it seeds the request-scoped server context and mounts the client provider. (Intlayer >= 9.4)-
    IntlayerClientProviderDeprecated — use IntlayerProvider from next-intlayer/server. Provider for client-side components in Next.js App Router. Wraps IntlayerProvider from react-intlayer.-
    IntlayerServerProviderDeprecated — use IntlayerProvider from next-intlayer/server. Provides locale context on the server. (Intlayer < 9.4)-
    IntlayerServerServer-side wrapper for Intlayer content in App Router. Ensures proper locale handling in Server Components.-
    HTMLProviderProvider for HTML-related internationalization settings. Allows component overrides for HTML tags.-
    HTMLRendererRenders HTML content with custom components.-
    MarkdownProviderProvider for markdown rendering context. Allows custom component overrides for markdown elements.-
    MarkdownRendererRenders markdown content with custom components.-

    Hooks (Client-side)

    Import:

    tsx
    import "next-intlayer";

    Re-exports most hooks from react-intlayer.

    HookDescriptionRelated Doc
    useIntlayerClient-side hook that picks one dictionary by its key and returns its content. Uses the locale from context if not provided.useIntlayer
    useDictionaryHook that transforms a dictionary object and returns the content for the current locale. Processes t() translations, enumerations, etc.useDictionary
    useDictionaryAsyncHook that handles asynchronous dictionaries. Accepts a promise-based dictionary map and resolves it for the current locale.-
    useDictionaryDynamicHook that handles dynamic dictionaries loaded by key. Uses React Suspense internally for loading states.-
    useLocaleClient-side hook to get the current locale and a function to set it. Enhanced for Next.js App Router with navigation support.useLocale
    usePathnameHook that returns the current Next.js pathname with the locale segment removed. Wraps next/navigation usePathname and strips locale.usePathname
    useRewriteURLClient-side hook to manage URL rewrites. Automatically updates the URL if a prettier localized rewrite rule exists.useRewriteURL
    useLocalePageRouterNext.js Page Router specific hook for locale management. Handles redirections and page reloads upon locale changes.-
    useI18nHook that provides a translation function t() for accessing nested content by key. Mimics i18next/next-intl pattern.useI18n
    useIntlHook that provides a locale-bound Intl object. Automatically injects the current locale and uses optimized caching.-
    useLoadDynamicHook to load dynamic dictionaries using React Suspense. Accepts a key and promise, caches results.-
    useHTMLRendererHook to get a pre-configured HTML renderer function.-
    useMarkdownRendererHook to get a pre-configured Markdown renderer function.-

    Functions (Server-side)

    Import:

    tsx
    import "next-intlayer/server";
    FunctionDescriptionRelated Doc
    tServer-side version of the translation function for Next.js App Router. Returns the translation of multilang content for the server locale.translation
    getLocaleHelper function to extract the current locale from Next.js headers and cookies. Designed for Server Components, Server Actions, or Route Handlers.-
    generateStaticParamsGenerates static parameters for Next.js's dynamic routes based on configured locales. Returns array of locale objects for pre-rendering.-
    localeFunction to get or set the locale in the server context (App Router). Provides locale management in Server Components.-

    Types

    Import:

    tsx
    import "next-intlayer";
    TypeDescription
    NextPageIntlayerType for Next.js pages with Intlayer support. Generic type that includes locale parameter.
    Next14PageIntlayerType for Next.js 14 pages with Intlayer support.
    Next15PageIntlayerType for Next.js 15 pages with Intlayer support.
    NextLayoutIntlayerType for Next.js layouts with Intlayer support. Generic type that includes locale parameter.
    Next14LayoutIntlayerType for Next.js 14 layouts with Intlayer support.
    Next15LayoutIntlayerType for Next.js 15 layouts with Intlayer support.
    LocalParamsType for Next.js route parameters with locale. Object with locale property.
    LocalPromiseParamsType for Next.js route parameters with locale (async version). Promise that resolves to object with locale property.
    useRewriteURLintlayerMiddleware