@intlayer/docs 5.7.8 → 5.8.0

package/blog/en/intlayer_with_next-intl.md

@@ -23,7 +23,6 @@ Both next-intl and Intlayer are open-source internationalization (i18n) framewor
 They share three principal notions:
 
 1. **Dictionary**: The method for defining the translatable content of your application.
-
    - Named `content declaration file` in Intlayer, which can be a JSON, JS, or TS file exporting the structured data. See [Intlayer documentation](https://intlayer.org/fr/doc/concept/content) for more information.
    - Named `messages` or `locale messages` in next-intl, usually in JSON files. See [next-intl documentation](https://github.com/amannn/next-intl) for more information.
 
@@ -170,8 +169,8 @@ const content = {
   content: {
     helloWorld: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
   },
 } satisfies Dictionary;
@@ -188,8 +187,8 @@ const content = {
   content: {
     helloWorld: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
   },
 };
@@ -205,8 +204,8 @@ module.exports = {
   content: {
     helloWorld: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
   },
 };

package/blog/en/intlayer_with_react-i18next.md

@@ -247,8 +247,8 @@ const content = {
     // Each "t" call is a separate translation node
     heading: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     description: t({
       en: "My i18n description text...",

package/blog/en/intlayer_with_react-intl.md

@@ -118,8 +118,8 @@ const content = {
     // Each call to t() declares a translatable field
     helloWorld: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     description: t({
       en: "This is a description",

package/blog/en/next-i18next_vs_next-intl_vs_intlayer.md

@@ -1,6 +1,6 @@
 ---
-createdAt: 2024-08-11
-updatedAt: 2025-06-29
+createdAt: 2025-08-23
+updatedAt: 2025-08-23
 title: next-i18next vs next-intl vs Intlayer
 description: Compare next-i18next with next-intl and Intlayer for the internationalization (i18n) of a Next.js app
 keywords:
@@ -17,277 +17,146 @@ slugs:
   - next-i18next-vs-next-intl-vs-intlayer
 ---
 
-# next-i18next VS next-intl VS Intlayer | Next.js Internationalization (i18n)
+# next-i18next VS next-intl VS intlayer | Next.js Internationalization (i18n)
 
-Below is a concise comparison of **three popular libraries** for internationalizing (i18n) a Next.js application: **next-intl**, **next-i18next**, and **Intlayer**.
+This guide compares three widely used i18n options for **Next.js**: **next-intl**, **next-i18next**, and **Intlayer**.
+We focus on **Next.js 13+ App Router** (with **React Server Components**) and evaluate:
 
-This document highlights key criteria:
+1. **Architecture & content organization**
+2. **TypeScript & safety**
+3. **Missing translation handling**
+4. **Routing & middleware**
+5. **Performance & loading behavior**
+6. **Developer experience (DX), tooling & maintenance**
+7. **SEO & large-project scalability**
 
-1. **Architecture** (keeping translations close to their components)
-2. **TypeScript support**
-3. **Management of missing translations**
-4. **Server Components support**
-5. **Enhanced routing & middleware** for Next.js
-6. **Simplicity of setup**
-
-The guide also provides an **in-depth look at Intlayer**, showing why it can be a strong choice especially for Next.js 13+, including **App Router** and **Server Components**.
+> **tl;dr**: All three can localize a Next.js app. If you want **component-scoped content**, **strict TypeScript types**, **build-time missing-key checks**, **tree-shaken dictionaries**, and **first-class App Router + SEO helpers**, **Intlayer** is the most complete, modern choice.
 
 ---
 
-## Overview of Each Library
-
-### 1. next-intl
+## High-level positioning
 
-**Main Focus**: Quick and easy setup with a lightweight approach to localization.
+- **next-intl** - Lightweight, straightforward message formatting with solid Next.js support. Centralized catalogs are common; DX is simple, but safety and large-scale maintenance remain mostly your responsibility.
+- **next-i18next** - i18next in Next.js clothing. Mature ecosystem and features via plugins (e.g., ICU), but configuration can be verbose and catalogs tend to centralize as projects grow.
+- **Intlayer** - Component-centric content model for Next.js, **strict TS typing**, **build-time checks**, **tree-shaking**, **built-in middleware & SEO helpers**, optional **Visual Editor/CMS**, and **AI-assisted translations**.
 
-- **Architecture**: Encourages co-locating translations in a single folder (e.g., `locales/`) but also allows multiple strategies. Does not strictly enforce “translation per component” architecture.
-- **TypeScript Support**: Basic TypeScript integration. Some type definitions exist, but they are not heavily centered on auto-generating TypeScript definitions from your translation files.
-- **Missing Translations**: Basic fallback mechanism. By default, falls back to a key or a default locale string. No robust out-of-the-box tooling for advanced missing translations checks.
-- **Server Components Support**: Works with Next.js 13+ in general, but the pattern is less specialized for deep server-side usage (e.g., server components with complex dynamic routing).
-- **Routing & Middleware**: Middleware support is possible but limited. Typically relies on Next.js `Middleware` for locale detection, or manual configuration for rewriting locale paths.
-- **Setup Simplicity**: Very straightforward. Minimal boilerplate is needed.
+---
 
-**Use when**: You want a simpler approach or are comfortable managing your translations in more conventional ways (like one folder with locale JSON files).
+## Side-by-Side Feature Comparison (Next.js focused)
+
+| Feature                                       | `next-intlayer` (Intlayer)                                                                                                          | `next-intl`                                                                                              | `next-i18next`                                                                                           |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| **Translations Near Components**              | ✅ Yes, content collocated with each component                                                                                      | ❌ No                                                                                                    | ❌ No                                                                                                    |
+| **TypeScript Integration**                    | ✅ Advanced, auto-generated strict types                                                                                            | ✅ Good                                                                                                  | ⚠️ Basic                                                                                                 |
+| **Missing Translation Detection**             | ✅ TypeScript error hightlight and build-time error/warning                                                                         | ⚠️ Runtime fallback                                                                                      | ⚠️ Runtime fallback                                                                                      |
+| **Rich Content (JSX/Markdown/components)**    | ✅ Direct support                                                                                                                   | ❌ Not designed for rich nodes                                                                           | ⚠️ Limited                                                                                               |
+| **AI-powered Translation**                    | ✅ Yes, supports multiple AI providers. Usable using your own API keys. Considers the context of your application and content scope | ❌ No                                                                                                    | ❌ No                                                                                                    |
+| **Visual Editor**                             | ✅ Yes, local Visual Editor + optional CMS; can externalize codebase content; embeddable                                            | ❌ No / available via external localization platforms                                                    | ❌ No / available via external localization platforms                                                    |
+| **Localized Routing**                         | ✅ Yes, supports localized paths out of the box (works with Next.js & Vite)                                                         | ✅ Built-in, App Router supports `[locale]` segment                                                      | ✅ Built-in                                                                                              |
+| **Dynamic Route Generation**                  | ✅ Yes                                                                                                                              | ✅ Yes                                                                                                   | ✅ Yes                                                                                                   |
+| **Pluralization**                             | ✅ Enumeration-based patterns                                                                                                       | ✅ Good                                                                                                  | ✅ Good                                                                                                  |
+| **Formatting (dates, numbers, currencies)**   | ✅ Optimized formatters (Intl under the hood)                                                                                       | ✅ Good (Intl helpers)                                                                                   | ✅ Good (Intl helpers)                                                                                   |
+| **Content Format**                            | ✅ .tsx, .ts, .js, .json, .md, .txt, (.yaml WIP)                                                                                    | ✅ .json, .js, .ts                                                                                       | ⚠️ .json                                                                                                 |
+| **ICU support**                               | ⚠️ WIP                                                                                                                              | ✅ Yes                                                                                                   | ⚠️ Via plugin (`i18next-icu`)                                                                            |
+| **SEO Helpers (hreflang, sitemap)**           | ✅ Built-in tools: helpers for sitemap, robots.txt, metadata                                                                        | ✅ Good                                                                                                  | ✅ Good                                                                                                  |
+| **Ecosystem / Community**                     | ⚠️ Smaller but growing fast and reactive                                                                                            | ✅ Good                                                                                                  | ✅ Good                                                                                                  |
+| **Server-side Rendering & Server Components** | ✅ Yes, streamlined for SSR / React Server Components                                                                               | ⚠️ Supported at page level but need to pass t-functions on component tree for children server components | ⚠️ Supported at page level but need to pass t-functions on component tree for children server components |
+| **Tree-shaking (load only used content)**     | ✅ Yes, per-component at build time via Babel/SWC plugins                                                                           | ⚠️ Partial                                                                                               | ⚠️ Partial                                                                                               |
+| **Lazy loading**                              | ✅ Yes, per-locale / per-dictionary                                                                                                 | ✅ Yes (per-route/per-locale), need mamespace management                                                 | ✅ Yes (per-route/per-locale), need mamespace management                                                 |
+| **Purge unused content**                      | ✅ Yes, per-dictionary at build time                                                                                                | ❌ No, can be managed manually with namespace management                                                 | ❌ No, can be managed manually with namespace management                                                 |
+| **Management of Large Projects**              | ✅ Encourages modular, suited for design-system                                                                                     | ✅ Modular with setup                                                                                    | ✅ Modular with setup                                                                                    |
 
 ---
 
-### 2. next-i18next
+## Deep-dive comparison
 
-**Main Focus**: Time-tested solution using `i18next` under the hood, widely adopted for Next.js projects.
+### 1) Architecture & scalability
 
-- **Architecture**: Often organizes translations in the `public/locales` folder. Not specifically designed to keep translations “close” to each component, though you can manually adopt a different structure.
-- **TypeScript Support**: Reasonable TypeScript coverage but requires custom configuration for typed translations and typed hooks.
-- **Missing Translations**: i18next offers interpolation/fallbacks. However, missing translation detection typically needs extra setup or third-party plugins.
-- **Server Components Support**: Basic usage with Next.js 13 is documented, but advanced usage (e.g., deep integration with server components, dynamic route generation) can be cumbersome.
-- **Routing & Middleware**: Relies heavily on Next.js `Middleware` and rewrites for locale subpaths. For more complex setups, you might need to dive into advanced i18next configuration.
-- **Setup Simplicity**: Familiar approach for those used to i18next. However, it can get more boilerplate-heavy when advanced i18n features are needed (namespaces, multiple fallback locales, etc.).
+- **next-intl / next-i18next**: Default to **centralized catalogs** per locale (plus **namespaces** in i18next). Works fine early on, but often becomes a big shared surface area with rising coupling and key churn.
+- **Intlayer**: Encourages **per-component** (or per-feature) dictionaries **co-located** with the code they serve. This lowers cognitive load, eases duplication/migration of UI pieces, and reduces cross-team conflicts. Unused content is naturally easier to spot and purge.
 
-**Use when**: You’re already committed to the `i18next` ecosystem or have existing i18next-based translations.
+**Why it matters:** In large codebases or design-system setups, **modular content** scales better than monolithic catalogs.
 
 ---
 
-### 3. Intlayer
-
-**Main Focus**: A modern, open-source i18n library specifically tailored for Next.js **App Router** (12, 13, 14, and 15) with built-in support for **Server Components** and **Turbopack**.
-
-#### Key Advantages
+### 2) TypeScript & safety
 
-1. **Architecture**
+- **next-intl**: Solid TypeScript support, but **keys aren’t strictly typed by default**; you’ll maintain safety patterns manually.
+- **next-i18next**: Base typings for hooks; **strict key typing requires extra tooling/config**.
+- **Intlayer**: **Generates strict types** from your content. **IDE autocompletion** and **compile-time errors** catch typos and missing keys before deploy.
 
-   - Encourages placing **translations right next to their components**. Each page or component can have its own `.content.ts` (or JSON) file no more rummaging through a giant translation folder.
-   - This makes your code more **modular and maintainable**, especially in large codebases.
+**Why it matters:** Strong typing shifts failures **left** (CI/build) instead of **right** (runtime).
 
-2. **TypeScript Support**
-
-   - **Auto-generated type definitions**: The moment you define your content, Intlayer generates types that power autocomplete and catch translation errors.
-   - Minimizes runtime errors like missing keys and offers advanced **autocomplete** directly in your IDE.
-
-3. **Management of Missing Translations**
+---
 
-   - During build, Intlayer can **detect missing translation keys** and throw warnings or errors.
-   - This ensures you never accidentally ship with missing text across your languages.
+### 3) Missing translation handling
 
-4. **Optimized for Server Components**
+- **next-intl / next-i18next**: Rely on **runtime fallbacks** (e.g., show the key or default locale). Build doesn’t fail.
+- **Intlayer**: **Build-time detection** with **warnings/errors** for missing locales or keys.
 
-   - Fully compatible with the Next.js **App Router** and the new **Server Components** paradigm.
-   - Provides specialized providers (`IntlayerServerProvider`, `IntlayerClientProvider`) to **isolate server context** (vital when dealing with Next.js 13+).
+**Why it matters:** Catching gaps during build prevents “mystery strings” in production and aligns with strict release gates.
 
-5. **Enhanced Routing & Middleware**
+---
 
-   - Includes a dedicated [**`intlayerMiddleware`**](#) for **automatic locale detection** (via cookies or browser headers) and advanced route generation.
-   - Dynamically handles localized paths (e.g., `/en-US/about` vs. `/fr/about`) with minimal configuration.
-   - Offers helper methods like `getMultilingualUrls` for generating alternate language links (great for **SEO**).
+### 4) Routing, middleware & URL strategy
 
-6. **Simplified Setup**
-   - A single config file (`intlayer.config.ts`) to define your locales, default locale, and integration preferences.
-   - A wrapper plugin `withIntlayer(nextConfig)` that **injects** all environment variables and watchers for your content.
-   - **No large fallback configurations** the system is built to “just work” with minimal friction.
+- All three work with **Next.js localized routing** on the App Router.
+- **Intlayer** goes further with **i18n middleware** (locale detection via headers/cookies) and **helpers** to generate localized URLs and `<link rel="alternate" hreflang="…">` tags.
 
-> **Bottom line**: Intlayer is a modern solution that wants to **push best practices**: from **keeping translations close** to each React component, to offering **robust TS support** and **easy server-side** usage, while **drastically reducing boilerplate**.
+**Why it matters:** Fewer custom glue layers; **consistent UX** and **clean SEO** across locales.
 
 ---
 
-## Side-by-Side Feature Comparison
+### 5) Server Components (RSC) alignment
 
-| **Feature**                           | **next-intl**                            | **next-i18next**                               | **Intlayer**                                   |
-| ------------------------------------- | ---------------------------------------- | ---------------------------------------------- | ---------------------------------------------- |
-| **Keep translations near components** | Partial – typically one locales folder   | Not default – often `public/locales`           | **Yes – recommended & easy**                   |
-| **TypeScript Autogenerated**          | Basic TS definitions                     | Basic TS support                               | **Yes – advanced out-of-the-box**              |
-| **Missing translations detection**    | Mostly fallback strings                  | Mostly fallback strings                        | **Yes – build-time checks**                    |
-| **Server Components Support**         | Works but not specialized                | Supported but can be verbose                   | **Full support with specialized providers**    |
-| **Routing & Middleware**              | Manually integrated with Next middleware | Provided via rewriting config                  | **Dedicated i18n middleware + advanced hooks** |
-| **Setup Complexity**                  | Simple, minimal configuration            | Traditional, can be verbose for advanced usage | **One config file & plugin**                   |
+- **All** support Next.js 13+.
+- **Intlayer** smooths the **server/client boundary** with a consistent API and providers designed for RSC, so you don’t shuttle formatters or t-functions through component trees.
+
+**Why it matters:** Cleaner mental model and fewer edge cases in hybrid trees.
 
 ---
 
-## Why Intlayer?
+### 6) Performance & loading behavior
 
-For teams migrating to or building on top of **Next.js App Router** (versions 13, 14, or 15) with **Server Components**, Intlayer provides:
+- **next-intl / next-i18next**: Partial control via **namespaces** and **route-level splits**; risk of bundling unused strings if discipline slips.
+- **Intlayer**: **Tree-shakes** at build and **lazy-loads per dictionary/locale**. Unused content doesn’t ship.
 
-1. **A Streamlined Architecture**
+**Why it matters:** Smaller bundles and faster startup, especially on multi-locale sites.
 
-   - Each route or component holds its own translations. This fosters clarity and maintainability.
+---
 
-2. **Powerful TypeScript Integration**
+### 7) DX, tooling & maintenance
 
-   - You gain compiler-level safety, avoiding “typo-laden” or missing translation keys.
+- **next-intl / next-i18next**: You’ll typically wire up external platforms for translations and editorial workflows.
+- **Intlayer**: Ships a **free Visual Editor** and **optional CMS** (Git-friendly or externalized). Plus **VSCode extension** for content authoring and **AI-assisted translations** using your own provider keys.
 
-3. **Real Missing Translation Alerts**
+**Why it matters:** Lowers ops cost and shortens the loop between developers and content authors.
 
-   - If you forget a key or language translation, you’ll be warned at build time (rather than shipping an incomplete UI).
+---
 
-4. **Built-In Advanced Routing**
+## When to choose which?
 
-   - Automatic locale detection, dynamic route generation, and easy localized URL management are included.
-   - A standard `intlayerMiddleware` does not require deep custom rewrites.
+- **Choose next-intl** if you want a **minimal** solution, you’re comfortable with centralized catalogs, and your app is **small to mid-size**.
+- **Choose next-i18next** if you need **i18next’s plugin ecosystem** (e.g., advanced ICU rules via plugins) and your team already knows i18next, accepting **more configuration** for flexibility.
+- **Choose Intlayer** if you value **component-scoped content**, **strict TypeScript**, **build-time guarantees**, **tree-shaking**, and **batteries-included** routing/SEO/editor tooling - especially for **Next.js App Router**, design-systems and **large, modular codebases**.
 
-5. **One-Stop Setup**
+---
 
-   - Minimal boilerplate: simply define your `intlayer.config.ts`, wrap `next.config` with `withIntlayer`, and add the official middleware.
-   - Clear, straightforward usage for both **server** and **client** components via `IntlayerServerProvider` and `IntlayerClientProvider`.
+## Interoperability with `next-intl` and `next-i18next`
 
-6. **SEO-Friendly**
-   - Built-in helpers (`getMultilingualUrls`, `hrefLang` attributes, etc.) make it easy to produce SEO-compliant pages and sitemaps.
+`intlayer` can also help to manage your `next-intl` and `next-i18next` namespaces.
 
----
+Using `intlayer`, you can declare your content in the format of your favorite i18n library, and intlayer will generate your namespaces in the location of your choice (example: `/messages/{{locale}}/{{namespace}}.json`).
 
-## Example: Intlayer in Action
-
-Below is a _very_ condensed snippet illustrating how to harness Intlayer in a Next.js 15 project. For the full details and code examples, [check out the full Intlayer guide](#).
-
-<details>
-<summary>Step-by-step example</summary>
-
-1. **Install & Configure**
-
-   ```bash
-   npm install intlayer next-intlayer
-   ```
-
-   ```ts
-   // intlayer.config.ts
-   import { Locales, type IntlayerConfig } from "intlayer";
-
-   const config: IntlayerConfig = {
-     internationalization: {
-       locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-       defaultLocale: Locales.ENGLISH,
-     },
-   };
-   export default config;
-   ```
-
-2. **Use the Plugin**
-
-   ```ts
-   // next.config.mjs
-   import { withIntlayer } from "next-intlayer/server";
-
-   /** @type {import('next').NextConfig} */
-   const nextConfig = {};
-
-   export default withIntlayer(nextConfig);
-   ```
-
-3. **Add Middleware**
-
-   ```ts
-   // src/middleware.ts
-   export { intlayerMiddleware as middleware } from "next-intlayer/middleware";
-
-   export const config = {
-     matcher:
-       "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
-   };
-   ```
-
-4. **Create a Localized Layout**
-
-   ```tsx
-   // src/app/[locale]/layout.tsx
-   import { getHTMLTextDir } from "intlayer";
-   import { NextLayoutIntlayer } from "next-intlayer";
-
-   const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
-     const { locale } = params;
-     return (
-       <html lang={locale} dir={getHTMLTextDir(locale)}>
-         <body>{children}</body>
-       </html>
-     );
-   };
-
-   export { generateStaticParams } from "next-intlayer";
-   export default LocaleLayout;
-   ```
-
-5. **Declare & Use Content**
-
-   ```tsx
-   // src/app/[locale]/page.content.ts
-   import { t } from "intlayer";
-
-   export default {
-     key: "page",
-     content: {
-       getStarted: {
-         main: t({
-           en: "Get started by editing",
-           fr: "Commencez par éditer",
-           es: "Comience por editar",
-         }),
-         pageLink: "src/app/page.tsx",
-       },
-     },
-   };
-   ```
-
-   ```tsx
-   // src/app/[locale]/page.tsx
-   import { IntlayerServerProvider } from "next-intlayer/server";
-   import { IntlayerClientProvider, useIntlayer } from "next-intlayer";
-
-   const PageContent = () => {
-     const { content } = useIntlayer("page");
-     return (
-       <>
-         <p>{content.getStarted.main}</p>
-         <code>{content.getStarted.pageLink}</code>
-       </>
-     );
-   };
-
-   export default function Page({ params }) {
-     return (
-       <IntlayerServerProvider locale={params.locale}>
-         <IntlayerClientProvider locale={params.locale}>
-           <PageContent />
-         </IntlayerClientProvider>
-       </IntlayerServerProvider>
-     );
-   }
-   ```
-
-   </details>
+Refer to [`dictionaryOutput` and `i18nextResourcesDir` options](https://intlayer.org/doc/concept/configuration#content-configuration) for more details.
 
 ---
 
 ## Conclusion
 
-Each solution **next-intl**, **next-i18next**, and **Intlayer** has proven effective for multilingual Next.js projects. However, **Intlayer** goes further by:
-
-- **Strongly encouraging a component-level translation architecture**
-- Integrating seamlessly with **Next.js 13+ and Server Components**
-- Offering **powerful TypeScript** auto-generation for safer code
-- Handling **missing translations** at build time
-- Providing a **simplified, single configuration** approach with advanced routing & middleware
-
-If you want **modern** i18n features tailored to Next.js App Router and are looking for a **fully typed** experience without manually rigging fallback logic, route rewrites, or complex build steps, **Intlayer** is a compelling choice. It not only shortens your setup time but also ensures a more maintainable, scalable approach to translations for your team.
-
-### Further Reading
+All three libraries succeed at core localization. The difference is **how much work you must do** to achieve a robust, scalable setup in **modern Next.js**:
 
-- [Intlayer + Next.js 15 Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nextjs_15.md)
-- [next-intl Documentation](https://formatjs.io/docs/react-intl/)
-- [next-i18next Documentation](https://next.i18next.com/)
+- With **Intlayer**, **modular content**, **strict TS**, **build-time safety**, **tree-shaken bundles**, and **first-class App Router + SEO tooling** are **defaults**, not chores.
+- If your team prizes **maintainability and speed** in a multi-locale, component-driven app, Intlayer offers the **most complete** experience today.
 
-Feel free to mix and match approaches to suit your requirements there is no “one-size-fits-all” solution, and each library continues to evolve to address new use cases in the React ecosystem.
+Refer to ['Why Intlayer?' doc](https://intlayer.org/doc/why) for more details.