@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.11

package/blog/en-GB/intlayer_with_react-i18next.md

@@ -72,24 +72,40 @@ This guide explains how to leverage Intlayer as an **adapter for react-i18next**
 
 Install the necessary packages:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.
+
+> This command will detect your environment and install the required packages. For example:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Package descriptions:**

package/blog/en-GB/intlayer_with_react-intl.md

@@ -70,24 +70,40 @@ This guide explains how to leverage Intlayer as an **adapter for react-intl**, a
 
 Install the necessary packages:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.
+
+> This command will detect your environment and install the required packages. For example:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Package descriptions:**

package/blog/en-GB/intlayer_with_vue-i18n.md

@@ -72,24 +72,40 @@ This guide explains how to leverage Intlayer as an **adapter for vue-i18n**, all
 
 Install the necessary packages using your preferred package manager:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.
+
+> This command will detect your environment and install the required packages. For example:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Package explanations:**

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

@@ -282,34 +282,6 @@ Here is an example of the impact of bundle size optimisation using `intlayer` in
 
 ---
 
-## DX, tooling & maintenance
-
-<Columns>
-  <Column>
-
-**next-intl**
-
-- Commonly paired with external localisation platforms and editorial workflows.
-
-  </Column>
-  <Column>
-
-**next-i18next**
-
-- Commonly paired with external localisation platforms and editorial workflows.
-
-  </Column>
-  <Column>
-
-**intlayer**
-
-- Ships a **free Visual Editor** and **optional CMS** (Git-friendly or externalised), plus a **VSCode extension** and **AI-assisted translations** using your own provider keys.
-
-  </Column>
-</Columns>
-
-**Why it matters:** Lowers operational costs and shortens the feedback loop between developers and content authors.
-
 ## Integration with localisation platforms (TMS)
 
 Large organisations often rely on Translation Management Systems (TMS) like **Crowdin**, **Phrase**, **Lokalise**, **Localizely**, or **Localazy**.
@@ -1177,6 +1149,127 @@ export default robots;
 
 ---
 
+### Middleware for locale routing
+
+<Tabs defaultTab="next-intl" group='techno'>
+  <Tab label="next-i18next" value="next-i18next">
+
+Add a middleware to handle locale detection and routing:
+
+```ts fileName="src/middleware.ts"
+import { NextResponse, type NextRequest } from "next/server";
+import { defaultLocale, locales } from "@/i18n.config";
+
+const PUBLIC_FILE = /\.[^/]+$/; // exclude files with extensions
+
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+  if (
+    pathname.startsWith("/_next") ||
+    pathname.startsWith("/api") ||
+    pathname.startsWith("/static") ||
+    PUBLIC_FILE.test(pathname)
+  ) {
+    return;
+  }
+
+  const hasLocale = locales.some(
+    (l) => pathname === "/" + l || pathname.startsWith("/" + l + "/")
+  );
+  if (!hasLocale) {
+    const locale = defaultLocale;
+    const url = request.nextUrl.clone();
+    url.pathname = "/" + locale + (pathname === "/" ? "" : pathname);
+    return NextResponse.redirect(url);
+  }
+}
+
+export const config = {
+  matcher: [
+    // Match all paths except the ones starting with these and files with an extension
+    "/((?!api|_next|static|.*\\..*).*)",
+  ],
+};
+```
+
+  </Tab>
+  <Tab label="next-intl" value="next-intl">
+
+Add a middleware to handle locale detection and routing:
+
+```ts fileName="src/middleware.ts"
+import createMiddleware from "next-intl/middleware";
+import { locales, defaultLocale } from "@/i18n";
+
+export default createMiddleware({
+  locales: [...locales],
+  defaultLocale,
+  localeDetection: true,
+});
+
+export const config = {
+  // Skip API, Next internals and static assets
+  matcher: ["/((?!api|_next|.*\\..*).*)"],
+};
+```
+
+  </Tab>
+  <Tab label="intlayer" value="intlayer">
+
+Intlayer provides built-in middleware handling through the `next-intlayer` package configuration.
+
+```ts fileName="src/middleware.ts"
+import { intlayerProxy } from "next-intlayer/proxy";
+
+export const middleware = intlayerProxy();
+
+// applies this middleware only to files in the app directory
+export const config = {
+  matcher: "/((?!api|_next|static|.*\\..*).*)",
+};
+```
+
+The setup of the middleware is centralised in the `intlayer.config.ts` file.
+
+  </Tab>
+</Tabs>
+
+### Setup checklist and good practices
+
+<Tabs defaultTab="next-intl" group='techno'>
+  <Tab label="next-i18next" value="next-i18next">
+
+- Ensure `lang` and `dir` are set on the root `<html>` in `src/app/[locale]/layout.tsx`.
+- Split translations into namespaces (for example `common.json`, `about.json`) under `src/locales/<locale>/`.
+- Only load required namespaces in client components using `useTranslation('<ns>')` and by scoping `I18nProvider` with the same namespaces.
+- Keep pages static when possible: export `export const dynamic = 'force-static'` on pages; set `dynamicParams = false` and implement `generateStaticParams`.
+- Use sync server components nested under client boundaries by passing already-computed strings or the `t` function and the `locale`.
+- For SEO, set `alternates.languages` in metadata, list localised URLs in `sitemap.ts`, and disallow duplicate localised routes in `robots.ts`.
+- Prefer locale-aware formatters (e.g., `Intl.NumberFormat(locale)`) and memoise them on the client if using React < 19.
+
+  </Tab>
+  <Tab label="next-intl" value="next-intl">
+
+- **Set html `lang` and `dir`**: In `src/app/[locale]/layout.tsx`, compute `dir` via `getLocaleDirection(locale)` and set `<html lang={locale} dir={dir}>`.
+- **Split messages by namespace**: Organise JSON per locale and namespace (e.g., `common.json`, `about.json`).
+- **Minimise client payload**: On pages, send only required namespaces to `NextIntlClientProvider` (e.g., `pick(messages, ['common', 'about'])`).
+- **Prefer static pages**: Export `export const dynamic = 'force-static'` and generate static params for all `locales`.
+- **Synchronous server components**: Keep server components sync by passing precomputed strings (translated labels, formatted numbers) rather than async calls or non-serialisable functions.
+
+  </Tab>
+  <Tab label="intlayer" value="intlayer">
+
+- **Modular content**: Co-locate content dictionaries with components using `.content.{ts|js|json}` files.
+- **Type safety**: Leverage TypeScript integration for compile-time content validation.
+- **Build-time optimisation**: Use Intlayer's build tools for automatic tree-shaking and bundle optimisation.
+- **Integrated tooling**: Take advantage of built-in routing, SEO helpers, and visual editor support.
+
+  </Tab>
+</Tabs>
+
+---
+
 ## And the winner is…
 
 It’s not simple. Each option has trade-offs. Here’s how I see it:

package/blog/en-GB/react-i18next_vs_react-intl_vs_intlayer.md

@@ -139,6 +139,20 @@ We evaluate:
 
 ---
 
+## Interoperability with `react-intl` and `react-i18next`
+
+`intlayer` can also help to manage your `react-intl` and `react-i18next` namespaces.
+
+Using `intlayer`, you can declare your content in the format of your favourite i18n library, and intlayer will generate your namespaces in the location of your choice (example: `/messages/{{locale}}/{{namespace}}.json`).
+
+---
+
+## GitHub STARs
+
+GitHub stars are a strong indicator of a project's popularity, community trust, and long-term relevance. While not a direct measure of technical quality, they reflect how many developers find the project useful, follow its progress, and are likely to adopt it. For estimating the value of a project, stars help compare traction across alternatives and provide insights into ecosystem growth.
+
+[![Star History Chart](https://api.star-history.com/chart?repos=formatjs/formatjs%2Ci18next/react-i18next%2Caymericzip/intlayer&type=date&legend=top-left)](https://www.star-history.com/#formatjs/formatjs&i18next/react-i18next&aymericzip/intlayer)
+
 ## Conclusion
 
 All three libraries localise React effectively. The differentiator is how much **infrastructure** you must build to reach a **safe, scalable** setup:

package/blog/en-GB/vue-i18n_vs_intlayer.md

@@ -251,6 +251,22 @@ This approach:
 
 ---
 
+## Interoperability with vue-i18n
+
+`intlayer` can also help to manage your `vue-i18n` namespaces.
+
+Using `intlayer`, you can declare your content in the format of your favourite i18n library, and intlayer will generate your namespaces in the location of your choice (example: `/messages/{{locale}}/{{namespace}}.json`).
+
+---
+
+## GitHub STARs
+
+GitHub stars are a strong indicator of a project's popularity, community trust, and long-term relevance. While not a direct measure of technical quality, they reflect how many developers find the project useful, follow its progress, and are likely to adopt it. For estimating the value of a project, stars help compare traction across alternatives and provide insights into ecosystem growth.
+
+[![Star History Chart](https://api.star-history.com/svg?repos=intlify/vue-i18n&repos=aymericzip/intlayer&type=Date)](https://www.star-history.com/#intlify/vue-i18n&aymericzip/intlayer)
+
+---
+
 ## Conclusion
 
 Both **vue-i18n** and **Intlayer** localise Vue apps well. The difference is **how much you must build yourself** to achieve a robust, scalable setup:

package/blog/es/intlayer_with_i18next.md

@@ -34,6 +34,10 @@ author: aymericzip
 
 <iframe title="Cómo automatizar tus traducciones JSON de i18next usando Intlayer" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/MpGMxniDHNg?autoplay=0&amp;origin=https://intlayer.org&amp;controls=0&amp;rel=1"/>
 
+## Tabla de contenidos
+
+<TOC/>
+
 ## ¿Qué es Intlayer?
 
 **Intlayer** es una biblioteca innovadora y de código abierto para la internacionalización, diseñada para abordar las limitaciones de las soluciones i18n tradicionales. Ofrece un enfoque moderno para la gestión de contenido en aplicaciones JavaScript.
@@ -65,24 +69,40 @@ Esta guía te muestra cómo aprovechar el sistema superior de declaración de co
 
 Instala los paquetes necesarios:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> la bandera `--interactive` es opcional. Usa `intlayer-cli init` si eres un agente de IA.
+
+> Este comando detectará su entorno e instalará los paquetes necesarios. Por ejemplo:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Descripción de los paquetes:**

package/blog/es/intlayer_with_next-i18next.md

@@ -34,17 +34,6 @@ author: aymericzip
 
 <TOC/>
 
-## ¿Qué es next-i18next?
-
-**next-i18next** es uno de los frameworks de internacionalización (i18n) más populares para aplicaciones Next.js. Construido sobre el poderoso ecosistema de **i18next**, proporciona una solución integral para gestionar traducciones, localización y cambio de idioma en proyectos Next.js.
-
-Sin embargo, next-i18next presenta algunos desafíos:
-
-- **Configuración compleja**: Configurar next-i18next requiere múltiples archivos de configuración y una configuración cuidadosa de las instancias i18n tanto del lado del servidor como del cliente.
-- **Traducciones dispersas**: Los archivos de traducción suelen almacenarse en directorios separados de los componentes, lo que dificulta mantener la consistencia.
-- **Gestión manual de namespaces**: Los desarrolladores deben gestionar manualmente los namespaces y asegurar la correcta carga de los recursos de traducción.
-- **Seguridad de tipos limitada**: El soporte para TypeScript requiere configuración adicional y no proporciona generación automática de tipos para las traducciones.
-
 ## ¿Qué es Intlayer?
 
 **Intlayer** es una biblioteca innovadora y de código abierto para internacionalización, diseñada para abordar las deficiencias de las soluciones i18n tradicionales. Ofrece un enfoque moderno para la gestión de contenido en aplicaciones Next.js.
@@ -73,24 +62,40 @@ Esta guía te muestra cómo aprovechar el superior sistema de declaración de co
 
 Instala los paquetes necesarios usando tu gestor de paquetes preferido:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> la bandera `--interactive` es opcional. Usa `intlayer-cli init` si eres un agente de IA.
+
+> Este comando detectará su entorno e instalará los paquetes necesarios. Por ejemplo:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Explicaciones de los paquetes:**

package/blog/es/intlayer_with_next-intl.md

@@ -29,6 +29,10 @@ author: aymericzip
 
 <iframe title="Cómo automatizar tus traducciones JSON de next-intl usando Intlayer" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/MpGMxniDHNg?autoplay=0&amp;origin=https://intlayer.org&amp;controls=0&amp;rel=1"/>
 
+# Tabla de contenidos
+
+<TOC/>
+
 ## ¿Qué es Intlayer?
 
 **Intlayer** es una biblioteca innovadora y de código abierto para la internacionalización, diseñada para abordar las limitaciones de las soluciones tradicionales de i18n. Ofrece un enfoque moderno para la gestión de contenido en aplicaciones Next.js.
@@ -59,24 +63,40 @@ Esta guía te muestra cómo aprovechar el sistema superior de declaración de co
 
 Instala los paquetes necesarios:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> la bandera `--interactive` es opcional. Usa `intlayer-cli init` si eres un agente de IA.
+
+> Este comando detectará su entorno e instalará los paquetes necesarios. Por ejemplo:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Descripción de los paquetes:**

package/blog/es/intlayer_with_react-i18next.md

@@ -63,24 +63,40 @@ Esta guía te muestra cómo aprovechar el sistema superior de declaración de co
 
 Instala los paquetes necesarios:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> la bandera `--interactive` es opcional. Usa `intlayer-cli init` si eres un agente de IA.
+
+> Este comando detectará su entorno e instalará los paquetes necesarios. Por ejemplo:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Descripción de los paquetes:**

package/blog/es/intlayer_with_react-intl.md

@@ -61,24 +61,40 @@ Esta guía te muestra cómo aprovechar el sistema superior de declaración de co
 
 Instala los paquetes necesarios:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> la bandera `--interactive` es opcional. Usa `intlayer-cli init` si eres un agente de IA.
+
+> Este comando detectará su entorno e instalará los paquetes necesarios. Por ejemplo:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Descripción de los paquetes:**

package/blog/es/intlayer_with_vue-i18n.md

@@ -63,24 +63,40 @@ Esta guía te muestra cómo aprovechar el sistema superior de declaración de co
 
 Instala los paquetes necesarios usando tu gestor de paquetes preferido:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> la bandera `--interactive` es opcional. Usa `intlayer-cli init` si eres un agente de IA.
+
+> Este comando detectará su entorno e instalará los paquetes necesarios. Por ejemplo:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Explicación de los paquetes:**