@intlayer/docs 6.1.6-canary.0 → 7.0.0-canary.0

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

@@ -37,7 +37,7 @@ We focus on **Next.js 13+ App Router** (with **React Server Components**) and ev
 
 > **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.
 
-> One confusion often made by developers is to think that `next-intl` is the Next.js version of `react-intl`. It's not—`next-intl` is maintained by [Amann](https://github.com/amannn), while `react-intl` is maintained by [FormatJS](https://github.com/formatjs/formatjs).
+> One confusion often made by developers is to think that `next-intl` is the Next.js version of `react-intl`. It's not, `next-intl` is maintained by [Amann](https://github.com/amannn), while `react-intl` is maintained by [FormatJS](https://github.com/formatjs/formatjs).
 
 ---
 
@@ -180,16 +180,16 @@ Here an example of the impact of bundle size optimization using `intlayer` in a
 <Columns>
   <Column>
 
-**next-intl**
+**next-i18next**
 
-- Solid TypeScript support, but **keys aren’t strictly typed by default**; you’ll maintain safety patterns manually.
+- Base typings for hooks. **strict key typing requires extra tooling/config**.
 
   </Column>
   <Column>
 
-**next-i18next**
+**next-intl**
 
-- Base typings for hooks; **strict key typing requires extra tooling/config**.
+- Solid TypeScript support, but **keys aren’t strictly typed by default**. you’ll maintain safety patterns manually.
 
   </Column>
   <Column>
@@ -210,16 +210,16 @@ Here an example of the impact of bundle size optimization using `intlayer` in a
 <Columns>
   <Column>
 
-**next-intl**
+**next-i18next**
 
-- Relies on **runtime fallbacks** (e.g., show the key or default locale). Build doesn’t fail.
+- Relies on **runtime fallbacks**. Build doesn’t fail.
 
   </Column>
   <Column>
 
-**next-i18next**
+**next-intl**
 
-- Relies on **runtime fallbacks** (e.g., show the key or default locale). Build doesn’t fail.
+- Relies on **runtime fallbacks**. Build doesn’t fail.
 
   </Column>
   <Column>
@@ -231,7 +231,7 @@ Here an example of the impact of bundle size optimization using `intlayer` in a
   </Column>
 </Columns>
 
-**Why it matters:** Catching gaps during build prevents “mystery strings” in production and aligns with strict release gates.
+**Why it matters:** Catching gaps during build prevents 'undefined' strings in production.
 
 ---
 
@@ -240,28 +240,30 @@ Here an example of the impact of bundle size optimization using `intlayer` in a
 <Columns>
   <Column>
 
-**next-intl**
+**next-i18next**
 
-- Works with **Next.js localized routing** on the App Router.
+- Allows localized routing. But middleware is not built-in.
 
   </Column>
   <Column>
 
-**next-i18next**
+**next-intl**
 
-- Works with **Next.js localized routing** on the App Router.
+- Allows localized routing.
+- Provides middleware.
 
   </Column>
   <Column>
 
 **intlayer**
 
-- All of the above, plus **i18n middleware** (locale detection via headers/cookies) and **helpers** to generate localized URLs and `<link rel="alternate" hreflang="…">` tags.
+- Allows localized routing.
+- Provides middleware.
 
   </Column>
 </Columns>
 
-**Why it matters:** Fewer custom glue layers; **consistent UX** and **clean SEO** across locales.
+**Why it matters:** Helps for SEO and discovery, as well as user experience.
 
 ---
 
@@ -270,58 +272,33 @@ Here an example of the impact of bundle size optimization using `intlayer` in a
 <Columns>
   <Column>
 
-**next-intl**
-
-- Supports Next.js 13+. Often requires passing t-functions/formatters through component trees in hybrid setups.
-
-  </Column>
-  <Column>
-
 **next-i18next**
 
-- Supports Next.js 13+. Similar constraints with passing translation utilities across boundaries.
-
-  </Column>
-  <Column>
-
-**intlayer**
-
-- Supports Next.js 13+ and smooths the **server/client boundary** with a consistent API and RSC-oriented providers, avoiding shuttling formatters or t-functions.
+- Support page and layout server components.
+- Do not provide synchronous API for children server components.
 
   </Column>
-</Columns>
-
-**Why it matters:** Cleaner mental model and fewer edge cases in hybrid trees.
-
----
-
-## DX, tooling & maintenance
-
-<Columns>
   <Column>
 
 **next-intl**
 
-- Commonly paired with external localization platforms and editorial workflows.
-
-  </Column>
-  <Column>
-
-**next-i18next**
-
-- Commonly paired with external localization platforms and editorial workflows.
+- Support page and layout server components.
+- Do not provide synchronous API for children server components.
 
   </Column>
   <Column>
 
 **intlayer**
 
-- Ships a **free Visual Editor** and **optional CMS** (Git-friendly or externalized), plus a **VSCode extension** and **AI-assisted translations** using your own provider keys.
+- Support page and layout server components.
+- Provide synchronous API for children server components.
 
   </Column>
 </Columns>
 
-**Why it matters:** Lowers ops cost and shortens the loop between developers and content authors.
+**Why it matters:** Server component suport is a key feature of Next.js 13+, helping for performance. Passing props the locale or the `t` function from the parent to the child server components make your components less reusable.
+
+---
 
 ## Integration with localization platforms (TMS)
 
@@ -342,6 +319,8 @@ Large organizations often rely on Translation Management Systems (TMS) like **Cr
 
 > Note: `next-intl` and `i18next` also accepts TypeScript catalogs. If your team stores messages in `.ts` files or decentralizes them by feature, you can face similar TMS friction. However, many `next-intl` setups remain centralized in a `locales/` folder, which is a bit easier to refactor to JSON for TMS.
 
+---
+
 ## Developer Experience
 
 This part makes a deep comparison between the three solutions. Rather than considering simple cases, as described in the 'getting started' documentation for each solution, we will consider a real use case, more similar to a real project.
@@ -1008,20 +987,24 @@ export default ServerComponent;
 
 ```tsx fileName="src/components/ServerComponent.tsx"
 type ServerComponentProps = {
-  formattedCount: string;
-  label: string;
-  increment: string;
+  t: (key: string) => string;
+  locale: string;
+  count: number;
+  formatter: Intl.NumberFormat;
 };
 
 const ServerComponent = ({
-  formattedCount,
-  label,
-  increment,
+  t,
+  locale,
+  count,
+  formatter,
 }: ServerComponentProps) => {
+  const formatted = formatter.format(count);
+
   return (
     <div>
-      <p>{formattedCount}</p>
-      <button aria-label={label}>{increment}</button>
+      <p>{formatted}</p>
+      <button aria-label={t("counter.label")}>{t("counter.increment")}</button>
     </div>
   );
 };
@@ -1105,12 +1088,16 @@ export function abs(locale: string, path: string) {
 import type { Metadata } from "next";
 import { locales, defaultLocale, localizedPath } from "@/i18n.config";
 
-export async function generateMetadata({
+type GenerateMetadataParams = {
+  params: Promise<{
+    locale: string;
+  }>;
+};
+
+export const generateMetadata = async ({
   params,
-}: {
-  params: { locale: string };
-}): Promise<Metadata> {
-  const { locale } = params;
+}: GenerateMetadataParams): Promise<Metadata> => {
+  const { locale } = await params;
 
   // Import the correct JSON bundle from src/locales
   const messages = (await import("@/locales/" + locale + "/about.json"))
@@ -1128,7 +1115,7 @@ export async function generateMetadata({
       languages: { ...languages, "x-default": "/about" },
     },
   };
-}
+};
 
 export default async function AboutPage() {
   return <h1>About</h1>;
@@ -1139,7 +1126,7 @@ export default async function AboutPage() {
 import type { MetadataRoute } from "next";
 import { locales, defaultLocale, abs } from "@/i18n.config";
 
-export default function sitemap(): MetadataRoute.Sitemap {
+export const sitemap = (): MetadataRoute.Sitemap => {
   const languages = Object.fromEntries(
     locales.map((locale) => [locale, abs(locale, "/about")])
   );
@@ -1152,7 +1139,7 @@ export default function sitemap(): MetadataRoute.Sitemap {
       alternates: { languages },
     },
   ];
-}
+};
 ```
 
 ```ts fileName="src/app/robots.ts"
@@ -1168,7 +1155,7 @@ const expandAllLocales = (path: string) => [
     .map((locale) => localizedPath(locale, path)),
 ];
 
-export default function robots(): MetadataRoute.Robots {
+export const robots = (): MetadataRoute.Robots => {
   const disallow = [
     ...expandAllLocales("/dashboard"),
     ...expandAllLocales("/admin"),
@@ -1179,7 +1166,7 @@ export default function robots(): MetadataRoute.Robots {
     host: ORIGIN,
     sitemap: ORIGIN + "/sitemap.xml",
   };
-}
+};
 ```
 
   </TabItem>
@@ -1190,16 +1177,20 @@ import type { Metadata } from "next";
 import { locales, defaultLocale } from "@/i18n";
 import { getTranslations } from "next-intl/server";
 
-function localizedPath(locale: string, path: string) {
+const localizedPath = (locale: string, path: string) => {
   return locale === defaultLocale ? path : "/" + locale + path;
-}
+};
 
-export async function generateMetadata({
+type GenerateMetadataParams = {
+  params: Promise<{
+    locale: string;
+  }>;
+};
+
+export const generateMetadata = async ({
   params,
-}: {
-  params: { locale: string };
-}): Promise<Metadata> {
-  const { locale } = params;
+}: GenerateMetadataParams): Promise<Metadata> => {
+  const { locale } = await params;
   const t = await getTranslations({ locale, namespace: "about" });
 
   const url = "/about";
@@ -1215,7 +1206,7 @@ export async function generateMetadata({
       languages: { ...languages, "x-default": url },
     },
   };
-}
+};
 
 // ... Rest of the page code
 ```
@@ -1229,7 +1220,7 @@ const origin = "https://example.com";
 const formatterLocalizedPath = (locale: string, path: string) =>
   locale === defaultLocale ? origin + path : origin + "/" + locale + path;
 
-export default function sitemap(): MetadataRoute.Sitemap {
+export const sitemap = (): MetadataRoute.Sitemap => {
   const aboutLanguages = Object.fromEntries(
     locales.map((l) => [l, formatterLocalizedPath(l, "/about")])
   );
@@ -1243,7 +1234,7 @@ export default function sitemap(): MetadataRoute.Sitemap {
       alternates: { languages: aboutLanguages },
     },
   ];
-}
+};
 ```
 
 ```tsx fileName="src/app/robots.ts"
@@ -1258,7 +1249,7 @@ const withAllLocales = (path: string) => [
     .map((locale) => "/" + locale + path),
 ];
 
-export default function robots(): MetadataRoute.Robots {
+export const robots = (): MetadataRoute.Robots => {
   const disallow = [
     ...withAllLocales("/dashboard"),
     ...withAllLocales("/admin"),
@@ -1269,7 +1260,7 @@ export default function robots(): MetadataRoute.Robots {
     host: origin,
     sitemap: origin + "/sitemap.xml",
   };
-}
+};
 ```
 
   </TabItem>
@@ -1410,6 +1401,20 @@ export const config = {
 
 Intlayer provides built-in middleware handling through the `next-intlayer` package configuration.
 
+```ts fileName="src/middleware.ts"
+import { intlayerMiddleware } from 'next-intlayer/middleware';
+
+export const middleware = intlayerMiddleware()
+
+// applies this middleware only to files in the app directory
+export const config = {
+  matcher:
+    "/((?!api|_next|static|.*\\..*).*)",
+};
+```
+
+The set up of the middleware centralized in the `intlayer.config.ts` file.
+
   </TabItem>
 </Tab>
 

package/dist/cjs/_virtual/rolldown_runtime.cjs

@@ -0,0 +1,25 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+
+exports.__toESM = __toESM;

package/dist/cjs/blog.cjs

@@ -1,46 +1,21 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var blog_exports = {};
-__export(blog_exports, {
-  getBlog: () => getBlog,
-  getBlogBySlug: () => getBlogBySlug,
-  getBlogMetadata: () => getBlogMetadata,
-  getBlogMetadataBySlug: () => getBlogMetadataBySlug,
-  getBlogMetadataRecord: () => getBlogMetadataRecord,
-  getBlogs: () => getBlogs
-});
-module.exports = __toCommonJS(blog_exports);
-var import_common = require('./common.cjs');
-var import_blog = require('./generated/blog.entry.cjs');
-const getBlogs = async (locale = import_common.defaultLocale) => await (0, import_common.getFiles)(import_blog.blogEntry, locale);
-const getBlog = async (docName, locale = import_common.defaultLocale) => await (0, import_common.getFile)(import_blog.blogEntry, docName, locale);
-const getBlogMetadataRecord = async (locale = import_common.defaultLocale) => await (0, import_common.getFileMetadataRecord)(import_blog.blogEntry, locale);
-const getBlogMetadata = async (docName, locale = import_common.defaultLocale) => await (0, import_common.getFileMetadata)(import_blog.blogEntry, docName, locale);
-const getBlogMetadataBySlug = async (slugs, locale = import_common.defaultLocale, strict = false) => await (0, import_common.getFileMetadataBySlug)(import_blog.blogEntry, slugs, locale, strict);
-const getBlogBySlug = async (slugs, locale = import_common.defaultLocale, strict = false) => await (0, import_common.getFileBySlug)(import_blog.blogEntry, slugs, locale, strict);
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  getBlog,
-  getBlogBySlug,
-  getBlogMetadata,
-  getBlogMetadataBySlug,
-  getBlogMetadataRecord,
-  getBlogs
-});
+const require_common = require('./common.cjs');
+const require_generated_blog_entry = require('./generated/blog.entry.cjs');
+
+//#region src/blog.ts
+const getBlogsKeys = () => require_common.getKeys(require_generated_blog_entry.blogEntry);
+const getBlogs = async (locale = require_common.defaultLocale) => await require_common.getFiles(require_generated_blog_entry.blogEntry, locale);
+const getBlog = async (docName, locale = require_common.defaultLocale) => await require_common.getFile(require_generated_blog_entry.blogEntry, docName, locale);
+const getBlogMetadataRecord = async (locale = require_common.defaultLocale) => await require_common.getFileMetadataRecord(require_generated_blog_entry.blogEntry, locale);
+const getBlogMetadata = async (docName, locale = require_common.defaultLocale) => await require_common.getFileMetadata(require_generated_blog_entry.blogEntry, docName, locale);
+const getBlogMetadataBySlug = async (slugs, locale = require_common.defaultLocale, strict = false) => await require_common.getFileMetadataBySlug(require_generated_blog_entry.blogEntry, slugs, locale, strict);
+const getBlogBySlug = async (slugs, locale = require_common.defaultLocale, strict = false) => await require_common.getFileBySlug(require_generated_blog_entry.blogEntry, slugs, locale, strict);
+
+//#endregion
+exports.getBlog = getBlog;
+exports.getBlogBySlug = getBlogBySlug;
+exports.getBlogMetadata = getBlogMetadata;
+exports.getBlogMetadataBySlug = getBlogMetadataBySlug;
+exports.getBlogMetadataRecord = getBlogMetadataRecord;
+exports.getBlogs = getBlogs;
+exports.getBlogsKeys = getBlogsKeys;
 //# sourceMappingURL=blog.cjs.map

package/dist/cjs/blog.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/blog.ts"],"sourcesContent":["import { LocalesValues } from '@intlayer/config';\nimport {\n  defaultLocale,\n  FileMetadata,\n  getFile,\n  getFileBySlug,\n  getFileMetadata,\n  getFileMetadataBySlug,\n  getFileMetadataRecord,\n  getFiles,\n} from './common';\nimport { blogEntry } from './generated/blog.entry';\n\nexport type BlogKey = keyof typeof blogEntry;\nexport type Blogs = Record<BlogKey, Record<LocalesValues, Promise<string>>>;\nexport type BlogMetadata = FileMetadata;\n\nexport const getBlogs = async <L extends LocalesValues>(\n  locale: L = defaultLocale as L\n): Promise<Record<BlogKey, string>> => await getFiles(blogEntry, locale);\n\nexport const getBlog = async <L extends LocalesValues>(\n  docName: BlogKey,\n  locale: L = defaultLocale as L\n): Promise<string> => await getFile(blogEntry, docName, locale);\n\nexport const getBlogMetadataRecord = async <L extends LocalesValues>(\n  locale: L = defaultLocale as L\n): Promise<Record<BlogKey, FileMetadata>> =>\n  await getFileMetadataRecord(blogEntry, locale);\n\nexport const getBlogMetadata = async <\n  D extends BlogKey,\n  L extends LocalesValues,\n>(\n  docName: D,\n  locale: L = defaultLocale as L\n): Promise<FileMetadata> => await getFileMetadata(blogEntry, docName, locale);\n\nexport const getBlogMetadataBySlug = async <L extends LocalesValues>(\n  slugs: string | string[],\n  locale: L = defaultLocale as L,\n  strict = false\n): Promise<FileMetadata[]> =>\n  await getFileMetadataBySlug(blogEntry, slugs, locale, strict);\n\nexport const getBlogBySlug = async <L extends LocalesValues>(\n  slugs: string | string[],\n  locale: L = defaultLocale as L,\n  strict = false\n): Promise<string[]> => await getFileBySlug(blogEntry, slugs, locale, strict);\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AACA,oBASO;AACP,kBAA0B;AAMnB,MAAM,WAAW,OACtB,SAAY,gCACyB,UAAM,wBAAS,uBAAW,MAAM;AAEhE,MAAM,UAAU,OACrB,SACA,SAAY,gCACQ,UAAM,uBAAQ,uBAAW,SAAS,MAAM;AAEvD,MAAM,wBAAwB,OACnC,SAAY,gCAEZ,UAAM,qCAAsB,uBAAW,MAAM;AAExC,MAAM,kBAAkB,OAI7B,SACA,SAAY,gCACc,UAAM,+BAAgB,uBAAW,SAAS,MAAM;AAErE,MAAM,wBAAwB,OACnC,OACA,SAAY,6BACZ,SAAS,UAET,UAAM,qCAAsB,uBAAW,OAAO,QAAQ,MAAM;AAEvD,MAAM,gBAAgB,OAC3B,OACA,SAAY,6BACZ,SAAS,UACa,UAAM,6BAAc,uBAAW,OAAO,QAAQ,MAAM;","names":[]}
+{"version":3,"file":"blog.cjs","names":["getKeys","blogEntry","defaultLocale","getFiles","getFile","getFileMetadataRecord","getFileMetadata","getFileMetadataBySlug","getFileBySlug"],"sources":["../../src/blog.ts"],"sourcesContent":["import type { DeclaredLocales, LocalesValues } from '@intlayer/types';\nimport {\n  defaultLocale,\n  type FileMetadata,\n  getFile,\n  getFileBySlug,\n  getFileMetadata,\n  getFileMetadataBySlug,\n  getFileMetadataRecord,\n  getFiles,\n  getKeys,\n} from './common';\nimport { blogEntry } from './generated/blog.entry';\n\nexport type BlogKey = keyof typeof blogEntry;\nexport type Blogs = Record<BlogKey, Record<LocalesValues, Promise<string>>>;\nexport type BlogMetadata = FileMetadata;\n\nexport const getBlogsKeys = (): (keyof typeof blogEntry)[] =>\n  getKeys(blogEntry);\n\nexport const getBlogs = async <L extends LocalesValues = DeclaredLocales>(\n  locale: L = defaultLocale as L\n): Promise<Record<BlogKey, string>> => await getFiles(blogEntry, locale);\n\nexport const getBlog = async <L extends LocalesValues = DeclaredLocales>(\n  docName: BlogKey,\n  locale: L = defaultLocale as L\n): Promise<string> => await getFile(blogEntry, docName, locale);\n\nexport const getBlogMetadataRecord = async <\n  L extends LocalesValues = DeclaredLocales,\n>(\n  locale: L = defaultLocale as L\n): Promise<Record<BlogKey, FileMetadata>> =>\n  await getFileMetadataRecord(blogEntry, locale);\n\nexport const getBlogMetadata = async <\n  D extends BlogKey,\n  L extends LocalesValues = DeclaredLocales,\n>(\n  docName: D,\n  locale: L = defaultLocale as L\n): Promise<FileMetadata> => await getFileMetadata(blogEntry, docName, locale);\n\nexport const getBlogMetadataBySlug = async <\n  L extends LocalesValues = DeclaredLocales,\n>(\n  slugs: string | string[],\n  locale: L = defaultLocale as L,\n  strict = false\n): Promise<FileMetadata[]> =>\n  await getFileMetadataBySlug(blogEntry, slugs, locale, strict);\n\nexport const getBlogBySlug = async <L extends LocalesValues = DeclaredLocales>(\n  slugs: string | string[],\n  locale: L = defaultLocale as L,\n  strict = false\n): Promise<string[]> => await getFileBySlug(blogEntry, slugs, locale, strict);\n"],"mappings":";;;;AAkBA,MAAa,qBACXA,uBAAQC,uCAAU;AAEpB,MAAa,WAAW,OACtB,SAAYC,iCACyB,MAAMC,wBAASF,wCAAW,OAAO;AAExE,MAAa,UAAU,OACrB,SACA,SAAYC,iCACQ,MAAME,uBAAQH,wCAAW,SAAS,OAAO;AAE/D,MAAa,wBAAwB,OAGnC,SAAYC,iCAEZ,MAAMG,qCAAsBJ,wCAAW,OAAO;AAEhD,MAAa,kBAAkB,OAI7B,SACA,SAAYC,iCACc,MAAMI,+BAAgBL,wCAAW,SAAS,OAAO;AAE7E,MAAa,wBAAwB,OAGnC,OACA,SAAYC,8BACZ,SAAS,UAET,MAAMK,qCAAsBN,wCAAW,OAAO,QAAQ,OAAO;AAE/D,MAAa,gBAAgB,OAC3B,OACA,SAAYC,8BACZ,SAAS,UACa,MAAMM,6BAAcP,wCAAW,OAAO,QAAQ,OAAO"}