@intlayer/docs 5.5.9 → 5.5.11

package/docs/en-GB/roadmap.md

@@ -0,0 +1,337 @@
+---
+createdAt: 2025-03-01
+updatedAt: 2025-06-29
+title: Roadmap
+description: Discover the roadmap of Intlayer. See all the features that Intlayer has implemented, and is planning to implement.
+keywords:
+  - Roadmap
+  - Intlayer
+  - Internationalisation
+  - CMS
+  - Content Management System
+  - Visual Editor
+slugs:
+  - doc
+  - roadmap
+---
+
+# Intlayer: Feature Overview & Roadmap
+
+Intlayer is a content management and internationalisation solution designed to streamline how you declare, manage, and update content across your applications. It offers powerful features such as centralised or distributed content declaration, extensive internationalisation options, Markdown support, conditional rendering, TypeScript/JavaScript/JSON integration, and more. Below is a comprehensive overview of what Intlayer currently provides, followed by upcoming roadmap features.
+
+---
+
+## Current Features
+
+### 1. Content Declaration
+
+#### Centralised or Distributed
+
+- **Centralised**: Declare all your content in a single, large file at the base of your application, similar to i18next, so you can manage everything in one place.
+- **Distributed**: Alternatively, split your content into separate files at the component or feature level for better maintainability. This keeps your content close to the relevant code (components, tests, Storybook, etc.). Removing a component ensures any associated content is also removed, preventing leftover data from cluttering your codebase.
+
+> Resources:
+>
+> - [Content Declaration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/{{locale}}/dictionary/get_started.md)
+
+### 2. Internationalisation
+
+- Support for **230 languages and locales** (including regional variants like French (France), English (Canada), English (UK), Portuguese (Portugal), etc.).
+- Easily manage translations for all these locales from one place.
+
+> Resources:
+>
+> - [Internationalisation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/{{locale}}/dictionary/translation.md)
+
+### 3. Markdown Support
+
+- Declare content using **Markdown**, allowing you to automatically format text with paragraphs, headings, links, and more.
+- Ideal for blog posts, articles, documentation pages, or any scenario where rich text formatting is needed.
+
+> Resources:
+>
+> - [Markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/{{locale}}/dictionary/markdown.md)
+
+### 4. External file support
+
+- Import content from external files as text format, such as TXT, HTML, JSON, YAML, or CSV.
+- Use the `file` function in Intlayer to embed external file content into a dictionary, ensuring seamless integration with the Intlayer Visual Editor and CMS.
+- Supports dynamic content updates, meaning that when the source file is modified, the content updates automatically within Intlayer.
+- Enables multilingual content management by linking language-specific Markdown files dynamically.
+
+> Resources:
+>
+> - [File Content Embedding](https://github.com/aymericzip/intlayer/blob/main/docs/docs/{{locale}}/dictionary/file.md)
+
+### 5. Dynamic Content & Function Fetching
+
+Intlayer provides various methods to insert and manage dynamic content, ensuring flexibility and adaptability in content delivery. This includes functions for dynamic content insertion, conditional rendering, enumeration, nesting, and function fetching.
+
+1. Dynamic Content Insertion
+
+   Use the insert function to define content with placeholders ({{name}}, {{age}}, etc.).
+
+   Enables template-like content that adapts based on user input, API responses, or other dynamic data sources.
+
+   Works seamlessly with TypeScript, ESM, CommonJS, and JSON configurations.
+
+   Easily integrates with React Intlayer and Next Intlayer using useIntlayer.
+
+2. Conditional Rendering
+
+   Define content that adapts based on user-specific conditions, such as language or authentication status.
+
+   Tailor personalised experiences without duplicating content across multiple files.
+
+3. Enumeration & Pluralisation
+
+   Use the enu function to define content variations based on numeric values, ranges, or custom keys.
+
+   Ensures automatic selection of the correct phrase based on a given value.
+
+   Supports ordering rules, ensuring predictable behaviour.
+
+4. Nesting & Sub-Content Referencing
+
+   Use the nest function to reference and reuse content from another dictionary, reducing duplication.
+
+   Supports structured and hierarchical content management for better maintainability.
+
+5. Function Fetching
+
+   Intlayer allows content to be declared as functions, enabling both synchronous and asynchronous content retrieval.
+
+   Synchronous Functions: Content is generated dynamically at build time.
+
+   Asynchronous Functions: Fetch data from external sources (e.g., APIs, databases) dynamically.
+
+   Integration: Works with TypeScript, ESM, and CommonJS but is not supported in JSON or remote content files.
+
+### 6. Content Declaration Formats
+
+Intlayer supports **TypeScript** (also JavaScript) and **JSON** for declaring content.
+
+- **TypeScript**:
+
+  - Ensures your content structure is correct and that no translations are missing.
+  - Offers strict or more flexible validation modes.
+  - Allows dynamic data fetching from variables, functions, or external APIs.
+
+- **JSON**:
+
+  - Makes it easy to integrate with external tools (such as visual editors) due to its standardised format.
+
+  > Resources:
+  >
+  > - [Content Declaration Formats](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_extention_customization.md)
+
+### 7. Purging, bundle optimisation and dynamic imports
+
+- Intlayer integrates `Babel` and `SWC` plugins to optimise your bundle and improve performance. It replaces imports, allowing only the dictionaries that are used to be imported into the bundle.
+- By activating the option, Intlayer also allows dynamic importing of the dictionary content for the current locale only.
+
+> Resources:
+>
+> - [Build Configuration](https://intlayer.org/doc/concept/configuration#build-configuration)
+
+---
+
+## Integration with Frameworks & Environments
+
+### 1. Next.js
+
+#### a. Server and Client Components
+
+- Provides a **unified content management approach** for both server and client components.
+- Offers a built-in context for server components, simplifying implementation compared to other solutions.
+
+#### b. Metadata, Sitemaps, and robots.txt
+
+- Fetch and inject content dynamically to generate metadata, sitemaps, or `robots.txt` files.
+
+#### c. Middleware
+
+- Add middleware to **redirect users** to content based on their preferred language.
+
+#### d. Turbopack and Webpack Compatibility
+
+- Fully compatible with the new Next.js Turbopack as well as traditional Webpack.
+
+> Resources:
+>
+> - [Next.js](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_nextjs_15.md)
+
+### 2. Vite
+
+- Similar to Next.js, you can integrate Intlayer with Vite and use a **middleware** to redirect users to content based on their preferred language.
+
+> Resources:
+>
+> - [Vite](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_vite+react.md)
+
+### 3. Express
+
+- Manage content and internationalise backend services built on Express.
+- Personalise emails, error messages, push notifications, and more with localised text.
+
+> Resources:
+>
+> - [Express](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_express.md)
+
+### 4. React Native
+
+- Integrate Intlayer with React Native to manage content and internationalise your mobile applications.
+- Supports both iOS and Android platforms.
+
+> Resources:
+>
+> - [React Native](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_react_native.md)
+
+### 5. Lynx
+
+- Integrate Intlayer with Lynx to manage content and internationalise your mobile applications.
+- Supports both iOS and Android platforms.
+
+> Resources:
+>
+> - [Lynx](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_lynx.md)
+
+### 6. Vue
+
+- Integrate Intlayer with Vue to manage content and internationalise your Vite / Vue.js applications.
+
+> Resources:
+>
+> - [Vue](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_vue.md)
+
+### 7. Nuxt
+
+- Integrate Intlayer with Nuxt to manage content and internationalise your Nuxt / Vue.js applications.
+- Supports both server and client components.
+- Integrates routing and middleware to redirect users to content based on their preferred language.
+
+> Resources:
+>
+> - [Nuxt](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_nuxt.md)
+
+### 8. Preact
+
+- Integrate Intlayer with Preact to manage content and internationalise your Preact applications.
+
+> Resources:
+>
+> - [Preact](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_preact.md)
+
+---
+
+## Visual Editors and CMS
+
+### 1. Local Visual Editor
+
+- A **free, local visual editor** that allows you to edit your application content by directly selecting elements on the page.
+- Integrates AI features to assist with:
+  - Generating or correcting translations
+  - Checking syntax and spelling
+  - Suggesting improvements
+- Can be hosted locally or deployed on a remote server.
+
+> Resources:
+>
+> - [Visual Editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_visual_editor.md)
+
+### 2. Intlayer CMS (Remote)
+
+- A **hosted CMS** solution that enables you to manage application content online, without modifying your codebase.
+- Provides AI-assisted features for declaring content, managing translations, and correcting syntax or spelling errors.
+- Interact with your content via your live application interface.
+
+> Resources:
+>
+> - [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md)
+
+---
+
+## IDE Extensions
+
+- Extensions for major IDEs to provide a **graphical interface** for managing local and remote translations.
+- Features could include auto-generating content declaration files for components, direct integration with the Intlayer CMS, and real-time validation.
+
+---
+
+## MCP Server
+
+- A **MCP server** that allows you to manage your content and translations using an integrated tool in your IDE.
+
+---
+
+## Intlayer CLI
+
+- **Translation and file generation**: Run audits on your content files to generate missing translations and review inconsistencies.
+- **Remote Interaction**: Push your local content to the remote CMS or pull remote content to integrate into your local application.
+- **Doc translation and review**: Translate and review your documentation / files etc.
+
+> Resources:
+>
+> - [CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_cli.md)
+
+---
+
+## Environments
+
+- Use **environment variables** to configure Intlayer differently across production, testing, and local environments.
+- Define which visual editor or remote CMS project to target depending on your environment.
+
+---
+
+## Hot Content Updates
+
+- When using remote dictionaries and the Intlayer CMS, you can **update your application’s content on the fly**, without needing to redeploy.
+
+> Resources:
+>
+> - [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md)
+
+---
+
+## Upcoming Features
+
+### 1. A/B Testing & Personalisation
+
+- **Multivariate Testing**: Test different versions of a given piece of content to see which performs best (e.g., higher click rate).
+- **Data-Driven Personalisation**: Display different content based on user demographics (gender, age, location, etc.), or other behaviour patterns.
+- **Automated Iteration**: Allow AI to automatically test multiple versions and either pick the top performer or recommend options for admin approval.
+
+### 2. Versioning
+
+- Restore previous versions of your content with **content versioning**.
+- Track changes over time and revert to earlier states if needed.
+
+### 3. Automatic Translation
+
+- For remote CMS users, **one-click translation generation** for any supported language.
+- The system would generate translations in the background and then prompt you for validation or edits.
+
+### 4. SEO Enhancements
+
+- Tools to **analyse keywords**, user search intent, and emerging trends.
+- Suggest improved content for better rankings, and track long-term performance.
+
+### 5. Compatibility with More Frameworks
+
+- Efforts are underway to support **Solid, Svelte, Angular**, and more.
+- Aim to make Intlayer compatible with **any JavaScript-powered application**.
+
+---
+
+## Conclusion
+
+Intlayer aims to be a one-stop solution for content management and internationalisation. It focuses on flexibility (centralised or distributed files), broad language support, easy integration with modern frameworks and bundlers, and powerful AI-driven features. As new capabilities, such as A/B testing, versioning, and automated translations, become available, Intlayer will continue to simplify content workflows and elevate user experiences across different platforms.
+
+Stay tuned for upcoming releases, and feel free to explore the existing features to see how Intlayer can help centralise and optimise your content management processes today!
+
+---
+
+## Doc History
+
+- 5.5.10 - 2025-06-30: Add Preact and Nuxt support, MCP Server, update CLI
+- 5.5.10 - 2025-06-29: Init history

package/docs/en-GB/vs_code_extension.md

@@ -0,0 +1,152 @@
+---
+createdAt: 2025-03-17
+updatedAt: 2025-06-29
+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:
+  - VS Code Extension
+  - Intlayer
+  - Localisation
+  - Development Tools
+  - React
+  - Next.js
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - vs-code-extension
+---
+
+# Official VS Code Extension
+
+## Overview
+
+[**Intlayer**](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension) is the official Visual Studio Code extension for **Intlayer**, designed to enhance 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)
+
+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
+
+**Go to Definition Support** – Use `Cmd+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** (`extension.buildDictionaries`) – Generate content files based on your project structure.
+- **Push Dictionaries** (`extension.pushDictionaries`) – Upload the latest dictionary content to your repository.
+- **Pull Dictionaries** (`extension.pullDictionaries`) – Sync the latest dictionary content from your repository to your local environment.
+
+### Content Declaration Generator
+
+Easily generate structured dictionary files in different formats:
+
+- **TypeScript (`.ts`)** – `extension.createDictionaryFile.ts`
+- **ES Module (`.esm`)** – `extension.createDictionaryFile.esm`
+- **CommonJS (`.cjs`)** – `extension.createDictionaryFile.cjs`
+- **JSON (`.json`)** – `extension.createDictionaryFile.json`
+
+## 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**.
+
+Alternatively, install it via the command line:
+
+```sh
+code --install-extension intlayer
+```
+
+## Usage
+
+### Quick Navigation
+
+1. Open a project using **react-intlayer**.
+2. Locate a call to `useIntlayer()`, such as:
+
+   ```tsx
+   const content = useIntlayer("app");
+   ```
+
+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
+
+#### Building Dictionaries
+
+Generate all dictionary content files with:
+
+```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
+
+Sync the latest dictionary content:
+
+1. Open the **Command Palette**.
+2. Search for **Pull Dictionaries**.
+3. Choose the dictionaries to pull.
+
+## Development & Contribution
+
+Want to contribute? We welcome community contributions!
+
+Repo URL: https://github.com/aymericzip/intlayer-vs-code-extension
+
+### Getting Started
+
+Clone the repository and install dependencies:
+
+```sh
+git clone https://github.com/aymericzip/intlayer-vs-code-extension.git
+cd intlayer-vs-code-extension
+npm install
+```
+
+> Use the `npm` package manager for compatibility with the `vsce` package to build and publish the extension.
+
+### Run in Development Mode
+
+1. Open the project in **VS Code**.
+2. Press `F5` to launch a new **Extension Development Host** window.
+
+### Submit a Pull Request
+
+If you improve the extension, submit a PR on [GitHub](https://github.com/aymericzip/intlayer-vs-code-extension).
+
+## Feedback & Issues
+
+Found a bug or have a feature request? Open an issue on our **GitHub repository**:
+
+[GitHub Issues](https://github.com/aymericzip/intlayer-vs-code-extension/issues)
+
+## Licence
+
+Intlayer is released under the **MIT Licence**.
+
+## Doc History
+
+- 5.5.10 - 2025-06-29: Init history

package/docs/es/CI_CD.md

@@ -0,0 +1,172 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Integración CI/CD
+description: Aprende cómo integrar Intlayer en tu pipeline de CI/CD para la gestión y despliegue automatizado de contenido.
+keywords:
+  - CI/CD
+  - Integración Continua
+  - Despliegue Continuo
+  - Automatización
+  - Internacionalización
+  - Documentación
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - ci-cd
+---
+
+# Generación Automática de Traducciones en un Pipeline CI/CD
+
+Intlayer permite la generación automática de traducciones para tus archivos de declaración de contenido. Existen varias formas de lograr esto dependiendo de tu flujo de trabajo.
+
+## Uso del CMS
+
+Con Intlayer, puedes adoptar un flujo de trabajo donde solo se declara un único locale localmente, mientras que todas las traducciones se gestionan de forma remota a través del CMS. Esto permite que el contenido y las traducciones estén completamente desacoplados de la base de código, ofreciendo mayor flexibilidad para los editores de contenido y habilitando la recarga dinámica del contenido (sin necesidad de reconstruir la aplicación para aplicar cambios).
+
+### Configuración de ejemplo
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
+    requiredLocales: [Locales.ENGLISH], // Los locales opcionales se gestionarán de forma remota
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    dictionaryPriorityStrategy: "distant_first", // El contenido remoto tiene prioridad
+
+    applicationURL: process.env.APPLICATION_URL, // URL de la aplicación usada por el CMS
+
+    clientId: process.env.INTLAYER_CLIENT_ID, // Credenciales del CMS
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+  ai: {
+    applicationContext: "This is a test application", // Ayuda a asegurar la generación consistente de traducciones
+  },
+};
+
+export default config;
+```
+
+Para aprender más sobre el CMS, consulta la [documentación oficial](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_CMS.md).
+
+## Uso de Husky
+
+Puedes integrar la generación de traducciones en tu flujo de trabajo local de Git usando [Husky](https://typicode.github.io/husky/).
+
+### Configuración de ejemplo
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
+    requiredLocales: [Locales.ENGLISH], // Los locales opcionales se gestionan de forma remota
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+  ai: {
+    provider: "openai",
+    apiKey: process.env.OPENAI_API_KEY, // Usa tu propia clave API
+
+    applicationContext: "This is a test application", // Ayuda a asegurar la generación consistente de traducciones
+  },
+};
+
+export default config;
+```
+
+```bash fileName=".husky/pre-push"
+npx intlayer build                          # Para asegurar que los diccionarios estén actualizados
+npx intlayer fill --unpushed --mode fill    # Solo rellena el contenido faltante, no actualiza los existentes
+```
+
+> Para más información sobre los comandos CLI de Intlayer y su uso, consulta la [documentación CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_cli.md).
+
+> Si tienes múltiples aplicaciones en tu repositorio usando instancias separadas de Intlayer, puedes usar el argumento `--base-dir` así:
+
+```bash fileName=".husky/pre-push"
+# App 1
+npx intlayer build --base-dir ./app1
+npx intlayer fill --base-dir ./app1 --unpushed --mode fill
+
+# App 2
+npx intlayer build --base-dir ./app2
+npx intlayer fill --base-dir ./app2 --unpushed --mode fill
+```
+
+## Uso de GitHub Actions
+
+Intlayer proporciona un comando CLI para auto-rellenar y revisar el contenido del diccionario. Esto puede integrarse en tu flujo de trabajo CI/CD usando GitHub Actions.
+
+```yaml fileName=".github/workflows/intlayer-translate.yml"
+name: Auto-Relleno Intlayer
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'src/**'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - 'src/**'
+  workflow_dispatch: {}
+
+concurrency:
+  group: 'autofill-${{ github.ref }}'
+  cancel-in-progress: true
+
+jobs:
+  autofill:
+    runs-on: ubuntu-latest
+    env:
+      INTLAYER_CLIENT_ID: ${{ secrets.INTLAYER_CLIENT_ID }}
+      INTLAYER_CLIENT_SECRET: ${{ secrets.INTLAYER_CLIENT_SECRET }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+
+    steps:
+      - name: ⬇️ Clonar repositorio
+        uses: actions/checkout@v3
+        with:
+          persist-credentials: true
+
+      - name: 🟢 Configurar Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20
+
+      - name: 📦 Instalar dependencias
+        run: npm ci
+
+      - name: ⚙️ Construir proyecto Intlayer
+        run: npx intlayer build
+
+      - name: 🤖 Auto-rellenar traducciones faltantes
+        run: npx intlayer fill --git-diff --mode fill
+
+      - name: 📤 Crear o actualizar PR de traducción
+        uses: peter-evans/create-pull-request@v4
+        with:
+          commit-message: chore: auto-rellenar traducciones faltantes [skip ci]
+          branch: auto-translations
+          title: chore: actualizar traducciones faltantes
+          labels: translation, automated
+```
+
+> Igual que con Husky, en el caso de un monorepo, puedes usar el argumento `--base-dir` para tratar secuencialmente cada aplicación.
+
+> Por defecto, el argumento `--git-diff` filtra los diccionarios que incluyen cambios desde la base (por defecto `origin/main`) hasta la rama actual (por defecto: `HEAD`).
+
+> Para más información sobre los comandos de la CLI de Intlayer y su uso, consulta la [documentación de la CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_cli.md).
+
+## Historial del documento
+
+- 5.5.10 - 2025-06-29: Historial inicial