@intlayer/docs 6.1.5 → 6.1.6-canary.0

package/docs/en-GB/component_i18n.md

@@ -0,0 +1,186 @@
+---
+createdAt: 2024-03-07
+updatedAt: 2025-09-30
+title: Make a component multilingual (i18n library) in React and Next.js
+description: Learn how to declare and retrieve localised content to build a multilingual React or Next.js component with Intlayer.
+keywords:
+  - i18n
+  - component
+  - react
+  - multilingual
+  - next.js
+  - intlayer
+slugs:
+  - doc
+  - component
+  - i18n
+applicationTemplate: https://github.com/aymericzip/intlayer-vite-react-template
+youtubeVideo: https://www.youtube.com/watch?v=dS9L7uJeak4
+---
+
+# How to make a component multilingual (i18n) with Intlayer
+
+This guide shows the minimal steps to make a UI component multilingual in two common setups:
+
+- React (Vite/SPA)
+- Next.js (App Router)
+
+You will first declare your content, then retrieve it in your component.
+
+## 1) Declare your content (shared for React and Next.js)
+
+Create a content declaration file near your component. This keeps translations close to where they are used and enables type safety.
+
+```ts fileName="component.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+const componentContent = {
+  key: "component-example",
+  content: {
+    title: t({
+      en: "Hello",
+      fr: "Bonjour",
+      es: "Hola",
+    }),
+    description: t({
+      en: "A multilingual React component",
+      fr: "Un composant React multilingue",
+      es: "Un componente React multilingüe",
+    }),
+  },
+} satisfies Dictionary;
+
+export default componentContent;
+```
+
+JSON is also supported if you prefer configuration files.
+
+```json fileName="component.content.json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "component-example",
+  "content": {
+    "title": {
+      "nodeType": "translation",
+      "translation": { "en": "Hello", "fr": "Bonjour", "es": "Hola" }
+    },
+    "description": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "A multilingual React component",
+        "fr": "Un composant React multilingue",
+        "es": "Un componente React multilingüe"
+      }
+    }
+  }
+}
+```
+
+## 2) Retrieve your content
+
+### Case A — React app (Vite/SPA)
+
+Default approach: use `useIntlayer` to retrieve by key. This keeps components lean and typed.
+
+```tsx fileName="ComponentExample.tsx"
+import { useIntlayer } from "react-intlayer";
+
+export function ComponentExample() {
+  const content = useIntlayer("component-example");
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+}
+```
+
+Server-side rendering or outside provider: use `react-intlayer/server` and pass an explicit `locale` when required.
+
+```tsx fileName="ServerRenderedExample.tsx"
+import { useIntlayer } from "react-intlayer/server";
+
+export function ServerRenderedExample({ locale }: { locale: string }) {
+  const content = useIntlayer("component-example", locale);
+  return (
+    <>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </>
+  );
+}
+```
+
+Alternative: `useDictionary` can read an entire declared object if you prefer collocating structure at the call site.
+
+```tsx fileName="ComponentWithDictionary.tsx"
+import { useDictionary } from "react-intlayer";
+import componentContent from "./component.content";
+
+export function ComponentWithDictionary() {
+  const { title, description } = useDictionary(componentContent);
+  return (
+    <div>
+      <h1>{title}</h1>
+      <p>{description}</p>
+    </div>
+  );
+}
+```
+
+### Case B — Next.js (App Router)
+
+Prefer server components for data safety and performance. Use `useIntlayer` from `next-intlayer/server` in server files, and `useIntlayer` from `next-intlayer` in client components.
+
+```tsx fileName="app/[locale]/example/ServerComponent.tsx"
+import { useIntlayer } from "next-intlayer/server";
+
+export default function ServerComponent() {
+  const content = useIntlayer("component-example");
+  return (
+    <>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </>
+  );
+}
+```
+
+```tsx fileName="app/[locale]/example/ClientComponent.tsx"
+"use client";
+
+import { useIntlayer } from "next-intlayer";
+
+export function ClientComponent() {
+  const content = useIntlayer("component-example");
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+}
+```
+
+Tip: For page metadata and SEO, you can also fetch content using `getIntlayer` and generate multilingual URLs via `getMultilingualUrls`.
+
+## Why Intlayer’s component approach is best
+
+- **Collocation**: Content declarations live near components, reducing drift and improving reuse across design systems.
+- **Type safety**: Keys and structures are strongly typed; missing translations surface at build-time rather than at runtime.
+- **Server-first**: Works natively in server components for better security and performance; client hooks remain ergonomic.
+- **Tree-shaking**: Only content used by the component is bundled, keeping payloads small in large applications.
+- **DX & tooling**: Built-in middleware, SEO helpers, and optional Visual Editor/AI translations streamline everyday work.
+
+See the comparisons and patterns in the Next.js-focused roundup: https://intlayer.org/blog/next-i18next-vs-next-intl-vs-intlayer
+
+## Related guides and references
+
+- React setup (Vite): https://intlayer.org/doc/environment/vite-and-react
+- React Router v7: https://intlayer.org/doc/environment/vite-and-react/react-router-v7
+- TanStack Start: https://intlayer.org/doc/environment/vite-and-react/tanstack-start
+- Next.js setup: https://intlayer.org/doc/environment/nextjs
+- Why Intlayer vs. next-intl vs. next-i18next: https://intlayer.org/blog/next-i18next-vs-next-intl-vs-intlayer
+
+These pages include end-to-end setup, providers, routing, and SEO helpers.

package/docs/en-GB/vs_code_extension.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-17
-updatedAt: 2025-09-22
+updatedAt: 2025-09-30
 title: Official VS Code Extension
 description: Learn how to use the Intlayer extension in VS Code to enhance your development workflow. Quickly navigate between localised content and manage your dictionaries efficiently.
 keywords:
@@ -23,92 +23,36 @@ slugs:
 
 [**Intlayer**](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension) is the official Visual Studio Code extension for **Intlayer**, designed to improve the developer experience when working with localised content in your projects.
 
-![Intlayer VS Code Extension](https://github.com/aymericzip/intlayer/blob/main/docs/assets/vs_code_extension_demo.gif)
+![Intlayer VS Code Extension](https://github.com/aymericzip/intlayer/blob/main/docs/assets/vs_code_extension_demo.gif?raw=true)
 
 Extension link: [https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension)
 
 ## Features
 
-### Instant Navigation
+![Fill dictionaries](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_fill_active_dictionary.gif?raw=true)
 
-**Go to Definition Support** – Use `⌘ + Click` (Mac) or `Ctrl + Click` (Windows/Linux) on a `useIntlayer` key to open the corresponding content file instantly.  
-**Seamless Integration** – Works effortlessly with **react-intlayer** and **next-intlayer** projects.  
-**Multi-language Support** – Supports localised content across different languages.  
-**VS Code Integration** – Smoothly integrates with VS Code’s navigation and command palette.
-
-### Dictionary Management Commands
-
-Manage your content dictionaries directly from VS Code:
-
-- **Build Dictionaries** – Generate content files based on your project structure.
-- **Push Dictionaries** – Upload the latest dictionary content to your repository.
-- **Pull Dictionaries** – Synchronise the latest dictionary content from your repository to your local environment.
+- **Instant Navigation** – Quickly jump to the correct content file when clicking on a `useIntlayer` key.
 - **Fill Dictionaries** – Populate dictionaries with content from your project.
-- **Test Dictionaries** – Identify missing or incomplete translations.
-
-### Content Declaration Generator
-
-Easily generate structured dictionary files in different formats:
 
-If you are currently working on a component, it will generate the `.content.{ts,tsx,js,jsx,mjs,cjs,json}` file for you.
+![List commands](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_list_commands.gif?raw=true)
 
-Example of component:
+- **Easy access to Intlayer Commands** – Build, push, pull, fill, test content dictionaries with ease.
 
-```tsx fileName="src/components/MyComponent/index.tsx"
-const MyComponent = () => {
-  const { myTranslatedContent } = useIntlayer("my-component");
+![Create content file](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_create_content_file.gif?raw=true)
 
-  return <span>{myTranslatedContent}</span>;
-};
-```
-
-Generated file in TypeScript format:
+- **Content Declaration Generator** – Create dictionary content files in various formats (`.ts`, `.esm`, `.cjs`, `.json`).
 
-```tsx fileName="src/components/MyComponent/index.content.ts"
-import { t, type Dictionary } from "intlayer";
+![Test dictionaties](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_test_missing_dictionary.gif?raw=true)
 
-const componentContent = {
-  key: "my-component",
-  content: {
-    myTranslatedContent: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-  },
-};
+- **Test Dictionaries** – Test dictionaries for missing translations.
 
-export default componentContent;
-```
+![Rebuild dictionary](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_rebuild_dictionary.gif?raw=true)
 
-Available formats:
+- **Keep your dictionaries up to date** – Keep your dictionaries up to date with the latest content from your project.
 
-- **TypeScript (`.ts`)**
-- **ES Module (`.esm`)**
-- **CommonJS (`.cjs`)**
-- **JSON (`.json`)**
-
-### Intlayer Tab (Activity Bar)
+![Intlayer Tab (Activity Bar)](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_search_dictionary.gif?raw=true)
 
-Open the Intlayer tab by clicking the Intlayer icon in the VS Code Activity Bar. It contains two views:
-
-- **Search**: A live search bar to quickly filter dictionaries and their content. Typing updates the results instantly.
-- **Dictionaries**: A tree view of your environments/projects, dictionary keys, and the files contributing entries. You can:
-  - Click a file to open it in the editor.
-  - Use the toolbar to run actions: Build, Pull, Push, Fill, Refresh, Test, and Create Dictionary File.
-  - Use the context menu for item‑specific actions:
-    - On a dictionary: Pull or Push
-    - On a file: Fill Dictionary
-  - When you switch editors, the tree will reveal the matching file if it belongs to a dictionary.
-
-## Installation
-
-You can install **Intlayer** directly from the VS Code Marketplace:
-
-1. Open **VS Code**.
-2. Go to the **Extensions Marketplace**.
-3. Search for **"Intlayer"**.
-4. Click **Install**.
+- **Intlayer Tab (Activity Bar)** – Browse and search dictionaries from a dedicated side tab with toolbar and context actions (Build, Pull, Push, Fill, Refresh, Test, Create File).
 
 ## Usage
 
@@ -124,60 +68,55 @@ You can install **Intlayer** directly from the VS Code Marketplace:
 3. **Command-click** (`⌘+Click` on macOS) or **Ctrl+Click** (on Windows/Linux) on the key (e.g., `"app"`).
 4. VS Code will automatically open the corresponding dictionary file, e.g., `src/app.content.ts`.
 
-### Managing Content Dictionaries
-
 ### Intlayer Tab (Activity Bar)
 
 Use the side tab to browse and manage dictionaries:
 
 - Open the Intlayer icon in the Activity Bar.
 - In **Search**, type to filter dictionaries and entries in real time.
-- In **Dictionaries**, browse environments, dictionaries, and files. Use the toolbar for Build, Pull, Push, Fill, Refresh, Test, and Create Dictionary File. Right‑click for context actions (Pull/Push on dictionaries, Fill on files). The current editor file auto‑reveals in the tree when applicable.
+- In **Dictionaries**, browse environments, dictionaries, and files. Use the toolbar for Build, Pull, Push, Fill, Refresh, Test, and Create Dictionary File. Right-click for context actions (Pull/Push on dictionaries, Fill on files). The current editor file auto-reveals in the tree when applicable.
 
-#### Building Dictionaries
+### Accessing the commands
 
-Generate all dictionary content files with:
+You can access the commands from the **Command Palette**.
 
 ```sh
 Cmd + Shift + P (macOS) / Ctrl + Shift + P (Windows/Linux)
 ```
 
-Search for **Build Dictionaries** and execute the command.
-
-#### Pushing Dictionaries
-
-Upload the latest dictionary content:
-
-1. Open the **Command Palette**.
-2. Search for **Push Dictionaries**.
-3. Select the dictionaries to push and confirm.
-
-#### Pulling Dictionaries
+- **Build Dictionaries**
+- **Push Dictionaries**
+- **Pull Dictionaries**
+- **Fill Dictionaries**
+- **Test Dictionaries**
+- **Create Dictionary File**
 
-Sync the latest dictionary content:
+### Loading Environment Variables
 
-1. Open the **Command Palette**.
-2. Search for **Pull Dictionaries**.
-3. Choose the dictionaries to pull.
+Intlayer recommends storing your AI API keys, as well as the Intlayer client ID and secret, in environment variables.
 
-#### Filling Dictionaries
+The extension can load environment variables from your workspace to run Intlayer commands with the correct context.
 
-Fill dictionaries with content from your project:
+- **Load order (by priority)**: `.env.<env>.local` → `.env.<env>` → `.env.local` → `.env`
+- **Non-destructive**: existing `process.env` values are not overridden.
+- **Scope**: files are resolved from the configured base directory (defaults to the workspace root).
 
-1. Open the **Command Palette**.
-2. Search for **Fill Dictionaries**.
-3. Run the command to populate dictionaries.
+#### Selecting the active environment
 
-#### Testing Dictionaries
+- **Command Palette**: open the palette and run `Intlayer: Select Environment`, then choose the environment (e.g., `development`, `staging`, `production`). The extension will attempt to load the first available file in the priority list above and show a notification like “Loaded env from .env.<env>.local”.
+- **Settings**: go to `Settings → Extensions → Intlayer`, and set:
+  - **Environment**: the environment name used to resolve `.env.<env>*` files.
+  - (Optional) **Env File**: an explicit path to a `.env` file. When provided, it takes precedence over the inferred list.
 
-Validate dictionaries and find missing translations:
+#### Monorepos and custom directories
 
-1. Open the **Command Palette**.
-2. Search for **Test Dictionaries**.
-3. Review the reported issues and fix as needed.
+If your `.env` files reside outside the workspace root, set the **Base Directory** in `Settings → Extensions → Intlayer`. The loader will search for `.env` files relative to that directory.
 
 ## Doc History
 
-| Version | Date       | Changes      |
-| ------- | ---------- | ------------ |
-| 5.5.10  | 2025-06-29 | Init history |
+| Version | Date       | Changes                             |
+| ------- | ---------- | ----------------------------------- |
+| 6.1.5   | 2025-09-30 | Added demo gif                      |
+| 6.1.0   | 2025-09-24 | Added environment selection section |
+| 6.0.0   | 2025-09-22 | Intlayer Tab / Fill & Test commands |
+| 5.5.10  | 2025-06-29 | Initial history                     |

package/docs/es/component_i18n.md

@@ -0,0 +1,182 @@
+---
+createdAt: 2024-03-07
+updatedAt: 2025-09-30
+title: Hacer un componente multilingüe (biblioteca i18n) en React y Next.js
+description: Aprende a declarar y recuperar contenido localizado para construir un componente multilingüe de React o Next.js con Intlayer.
+keywords:
+  - i18n
+  - componente
+  - react
+  - multilingüe
+  - next.js
+  - intlayer
+slugs:
+  - doc
+  - component
+  - i18n
+applicationTemplate: https://github.com/aymericzip/intlayer-vite-react-template
+youtubeVideo: https://www.youtube.com/watch?v=dS9L7uJeak4
+---
+
+# Cómo hacer un componente multilingüe (i18n) con Intlayer
+
+Esta guía muestra los pasos mínimos para hacer que un componente de interfaz sea multilingüe en dos configuraciones comunes:
+
+- React (Vite/SPA)
+- Next.js (App Router)
+
+Primero declararás tu contenido y luego lo recuperarás en tu componente.
+
+## 1) Declara tu contenido (compartido para React y Next.js)
+
+Crea un archivo de declaración de contenido cerca de tu componente. Esto mantiene las traducciones cerca del lugar donde se usan y habilita la seguridad de tipos.
+
+```ts fileName="component.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+const componentContent = {
+  key: "component-example",
+  content: {
+    title: t({
+      en: "Hello",
+      fr: "Bonjour",
+      es: "Hola",
+    }),
+    description: t({
+      en: "A multilingual React component",
+      fr: "Un composant React multilingue",
+      es: "Un componente React multilingüe",
+    }),
+  },
+} satisfies Dictionary;
+
+export default componentContent;
+```
+
+También se admite JSON si prefieres archivos de configuración.
+
+```json fileName="component.content.json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "component-example",
+  "content": {
+    "title": {
+      "nodeType": "translation",
+      "translation": { "en": "Hello", "fr": "Bonjour", "es": "Hola" }
+    },
+    "description": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "A multilingual React component",
+        "fr": "Un composant React multilingue",
+        "es": "Un componente React multilingüe"
+      }
+    }
+  }
+}
+```
+
+## 2) Recupera tu contenido
+
+### Caso A — Aplicación React (Vite/SPA)
+
+Enfoque por defecto: usa `useIntlayer` para recuperar por clave. Esto mantiene los componentes ligeros y tipados.
+
+```tsx fileName="ComponentExample.tsx"
+import { useIntlayer } from "react-intlayer";
+
+export function ComponentExample() {
+  const content = useIntlayer("component-example");
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+}
+```
+
+Renderizado en servidor o fuera del provider: usa `react-intlayer/server` y pasa un `locale` explícito cuando sea necesario.
+
+```tsx fileName="ServerRenderedExample.tsx"
+import { useIntlayer } from "react-intlayer/server";
+
+export function ServerRenderedExample({ locale }: { locale: string }) {
+  const content = useIntlayer("component-example", locale);
+  return (
+    <>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </>
+  );
+}
+```
+
+Alternativa: `useDictionary` puede leer un objeto declarado completo si prefieres colocar la estructura en el punto de uso.
+
+```tsx fileName="ComponentWithDictionary.tsx"
+import { useDictionary } from "react-intlayer";
+import componentContent from "./component.content";
+
+export function ComponentWithDictionary() {
+  const { title, description } = useDictionary(componentContent);
+  return (
+    <div>
+      <h1>{title}</h1>
+      <p>{description}</p>
+    </div>
+  );
+}
+```
+
+### Caso B — Next.js (App Router)
+
+Prefiere componentes de servidor por seguridad y rendimiento. Usa `useIntlayer` de `next-intlayer/server` en archivos de servidor, y `useIntlayer` de `next-intlayer` en componentes cliente.
+
+```tsx fileName="app/[locale]/example/ServerComponent.tsx"
+import { useIntlayer } from "next-intlayer/server";
+
+export default function ServerComponent() {
+  const content = useIntlayer("component-example");
+  return (
+    <>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </>
+  );
+}
+```
+
+```tsx fileName="app/[locale]/example/ClientComponent.tsx"
+"use client";
+
+import { useIntlayer } from "next-intlayer";
+
+export function ClientComponent() {
+  const content = useIntlayer("component-example");
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+}
+```
+
+Consejo: Para metadatos de página y SEO, también puedes obtener contenido con `getIntlayer` y generar URLs multilingües con `getMultilingualUrls`.
+
+## Por qué el enfoque de componentes de Intlayer es el mejor
+
+- Colocación: Las declaraciones de contenido viven cerca de los componentes, reduciendo la deriva y mejorando la reutilización en los sistemas de diseño.
+- Seguridad de tipos: Las claves y estructuras están fuertemente tipadas; las traducciones faltantes aparecen en tiempo de build en lugar de en tiempo de ejecución.
+- Server-first: Funciona de forma nativa en componentes de servidor para mejor seguridad y rendimiento; los hooks de cliente siguen siendo ergonómicos.
+- Tree-shaking: Solo se incluye el contenido usado por el componente, manteniendo cargas pequeñas en aplicaciones grandes.
+- DX y herramientas: Middleware incorporado, asistentes de SEO y traducciones opcionales mediante Editor Visual/IA agilizan el trabajo diario.
+
+## Guías y referencias relacionadas
+
+- Configuración React (Vite): https://intlayer.org/doc/environment/vite-and-react
+- React Router v7: https://intlayer.org/doc/environment/vite-and-react/react-router-v7
+- TanStack Start: https://intlayer.org/doc/environment/vite-and-react/tanstack-start
+- Configuración Next.js: https://intlayer.org/doc/environment/nextjs
+- Por qué Intlayer vs. next-intl vs. next-i18next: https://intlayer.org/blog/next-i18next-vs-next-intl-vs-intlayer