intlayer-next-js · diff
git:20260226.28174a9 to git:20260923.e86be10
21 added, 38 removed. Audit A to A.
---
name: intlayer-next-js
description: Integrates Intlayer internationalization with Next.js App Router and Pages Router. Use when the user asks to "setup Next.js i18n", use "useIntlayer" in Server Components, or handle client-side translations in Next.js.
metadata:
author: Intlayer
url: https://intlayer.org
license: Apache-2.0
mcp-server: "@intlayer/mcp"
category: productivity
tags: [i18n, nextjs]
documentation: https://intlayer.org/doc
support: contact@intlayer.org
---
# Intlayer Next.js Usage
## Core Philosophy
Intlayer promotes **Component-Level Content Declaration**. Instead of a massive global translation file, content is declared in `*.content.ts` files adjacent to the Next.js components that use them.
## Workflow
To create a translated component, you need two files:
1. **Declaration:** A content file (e.g., `myComponent.content.ts`) defining the dictionary.
2. **Implementation:** A Next.js component (Server or Client) using the `useIntlayer` hook.
### 1. Declare Content
Create a content file using `t()` for translations.
**File:** `src/components/MyComponent/myComponent.content.ts`
```typescript
import { t, type Dictionary } from "intlayer";
const content = {
// The 'key' must be unique and matches what you pass to useIntlayer()
key: "my-component",
content: {
text: t({
en: "Welcome",
fr: "Bienvenue",
es: "Hola",
}),
},
} satisfies Dictionary;
export default content;
```
## Setup
- [Next.js](references/environment_nextjs.md)
- [Next.js 14](references/environment_nextjs_14.md)
- [Next.js 15](references/environment_nextjs_15.md)
- - [No Locale Path](references/environment_nextjs_no-locale-path.md)
- [Page Router](references/environment_nextjs_next-with-page-router.md)
- ## Server Components
-
- To use Intlayer in Server Components, use `IntlayerServerProvider` to provide the locale and `useIntlayer` from `next-intlayer/server`.
-
- ```tsx
- import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";
-
- const MyServerComponent = () => {
- const content = useIntlayer("my-component");
- return (
- <div>
- <h1>{content.text}</h1>
- </div>
- );
- };
-
- const Page = async ({ params }) => {
- const { locale } = await params;
- return (
- <IntlayerServerProvider locale={locale}>
- <MyServerComponent />
- </IntlayerServerProvider>
- );
- };
+ ## Provider
- export default Page;
- ```
+ Mount one `IntlayerProvider` (from `next-intlayer/server`) in the `[locale]` layout. It serves both server and client components, so pages don't wrap themselves (see the [Next.js guide](references/environment_nextjs.md)).
- ## Client Components
+ ## useIntlayer Hook
- For Client Components, add the `"use client"` directive and use `useIntlayer` from `next-intlayer`. Ensure the component is wrapped in an `IntlayerClientProvider`.
+ `next-intlayer` is isomorphic: the same `useIntlayer` import works in Server Components and in `"use client"` components.
```tsx
- "use client";
-
import { useIntlayer } from "next-intlayer";
- export const MyClientComponent = () => {
+ export const MyComponent = () => {
const content = useIntlayer("my-component");
- return (
- <div>
- <h1>{content.text}</h1>
- </div>
- );
+ return <h1>{content.text}</h1>;
};
```
[Next.js package Documentation](references/packages_next-intlayer_exports.md)
+ ## Compiler
+
+ The [Intlayer Compiler](references/compiler.md) can extract all your content keys from your components, using one CLI command (`npx intlayer extract`) or automatically at app build.
+
## References
- [Website](https://intlayer.org)
- [Doc](https://intlayer.org/doc)
### Environments
- [Next.js](references/environment_nextjs.md)
- [Next.js 14](references/environment_nextjs_14.md)
- [Next.js 15](references/environment_nextjs_15.md)
- - [Next.js No Locale Path](references/environment_nextjs_no-locale-path.md)
- [Next.js with Page Router](references/environment_nextjs_next-with-page-router.md)
+ - [Intlayer with next-intl](references/next-intl.md)
+ - [Intlayer with next-i18next](references/next-i18next.md)
+ ### Concepts
+
+ - [Variants](references/concept_variants.md)
+ - [Collections](references/concept_collections.md)
+ - [Compiler](references/compiler.md)
+ - [Formatters (number, currency, date, …)](references/formatters.md)
+
### Packages
- [Intlayer Exports](references/packages_intlayer_exports.md)
- [Next Intlayer Exports](references/packages_next-intlayer_exports.md)
- [Next Intlayer Middleware](references/packages_next-intlayer_intlayerMiddleware.md)
- [Next Intlayer T](references/packages_next-intlayer_t.md)
- [Next Intlayer useDictionary](references/packages_next-intlayer_useDictionary.md)
- [Next Intlayer useIntlayer](references/packages_next-intlayer_useIntlayer.md)
- [Next Intlayer useLocale](references/packages_next-intlayer_useLocale.md)
+ - [next-intlayer usePathname](references/packages_next-intlayer_usePathname.md)
+ - [next-intlayer useRewriteURL](references/packages_next-intlayer_useRewriteURL.md)