@intlayer/docs 5.5.9 → 5.5.11

package/docs/en/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 implemented, and is planning to implement.
+keywords:
+  - Roadmap
+  - Intlayer
+  - Internationalization
+  - CMS
+  - Content Management System
+  - Visual Editor
+slugs:
+  - doc
+  - roadmap
+---
+
+# Intlayer: Feature Overview & Roadmap
+
+Intlayer is a content management and internationalization solution designed to streamline how you declare, manage, and update content across your applications. It offers powerful features such as centralized or distributed content declaration, extensive internationalization 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
+
+#### Centralized or Distributed
+
+- **Centralized**: 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/en/dictionary/get_started.md)
+
+### 2. Internationalization
+
+- 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:
+>
+> - [Internationalization](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/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/en/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/en/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 personalized experiences without duplicating content across multiple files.
+
+3. Enumeration & Pluralization
+
+   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 behavior.
+
+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 (like visual editors) due to its standardized format.
+
+  > Resources:
+  >
+  > - [Content Declaration Formats](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_extention_customization.md)
+
+### 7. Purging, bundle optimization and dynamic imports
+
+- Intlayer integrates `Babel` and `SWC` plugins to optimize your bundle and improve performance. It replace imports, to allows importing only the dictionaries that are used into the bundle.
+- By activating the option, Intlayer also allows to import dynamically 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 a 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/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/intlayer_with_vite+react.md)
+
+### 3. Express
+
+- Manage content and internationalize backend services built on Express.
+- Personalize emails, error messages, push notifications, and more with localized text.
+
+> Resources:
+>
+> - [Express](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_express.md)
+
+### 4. React Native
+
+- Integrate Intlayer with React Native to manage content and internationalize your mobile applications.
+- Supports both iOS and Android platforms.
+
+> Resources:
+>
+> - [React Native](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_react_native.md)
+
+### 5. Lynx
+
+- Integrate Intlayer with Lynx to manage content and internationalize your mobile applications.
+- Supports both iOS and Android platforms.
+
+> Resources:
+>
+> - [Lynx](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_lynx.md)
+
+### 6. Vue
+
+- Integrate Intlayer with Vue to manage content and internationalize your Vite / Vue.js applications.
+
+> Resources:
+>
+> - [Vue](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_vue.md)
+
+### 7. Nuxt
+
+- Integrate Intlayer with Nuxt to manage content and internationalize 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/intlayer_with_nuxt.md)
+
+### 8. Preact
+
+- Integrate Intlayer with Preact to manage content and internationalize your Preact applications.
+
+> Resources:
+>
+> - [Preact](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_preact.md)
+
+---
+
+## Visual Editors and CMS
+
+### 1. Local Visual Editor
+
+- A **free, local visual editor** that lets you edit your application content by directly selecting elements on the page.
+- Integrates AI features to help:
+  - Generate or fix translations
+  - Check syntax and spelling
+  - Suggest improvements
+- Can be hosted locally or deployed on a remote server.
+
+> Resources:
+>
+> - [Visual Editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)
+
+### 2. Intlayer CMS (Remote)
+
+- A **hosted CMS** solution that allows you to manage application content online, without touching your codebase.
+- Provides AI-assisted features for declaring content, managing translations, and fixing 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/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/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/intlayer_CMS.md)
+
+---
+
+## Upcoming Features
+
+### 1. A/B Testing & Personalization
+
+- **Multivariate Testing**: Test different versions of a given piece of content to see which performs best (e.g., higher click rate).
+- **Data-Driven Personalization**: Display different content based on user demographics (gender, age, location, etc.), or other behavior 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 **analyze 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 internationalization. It focuses on flexibility (centralized 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 centralize and optimize 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/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 localized content and manage your dictionaries efficiently.
+keywords:
+  - VS Code Extension
+  - Intlayer
+  - Localization
+  - 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 improve the developer experience when working with localized 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 localized 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 `npm` package manager for compatibility with `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)
+
+## License
+
+Intlayer is released under the **MIT License**.
+
+## Doc History
+
+- 5.5.10 - 2025-06-29: Init history

package/docs/en-GB/CI_CD.md

@@ -0,0 +1,172 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: CI/CD Integration
+description: Learn how to integrate Intlayer into your CI/CD pipeline for automated content management and deployment.
+keywords:
+  - CI/CD
+  - Continuous Integration
+  - Continuous Deployment
+  - Automation
+  - Internationalization
+  - Documentation
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - ci-cd
+---
+
+# Auto-Generate Translations in a CI/CD Pipeline
+
+Intlayer allows the automatic generation of translations for your content declaration files. There are multiple ways to achieve this depending on your workflow.
+
+## Using the CMS
+
+With Intlayer, you can adopt a workflow where only a single locale is declared locally, while all translations are managed remotely through the CMS. This allows content and translations to be completely detached from the codebase, offering more flexibility for content editors and enabling hot content reloading (no need to rebuild the application to apply changes).
+
+### Example Configuration
+
+```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], // Optional locales will be managed remotely
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    dictionaryPriorityStrategy: "distant_first", // Remote content takes priority
+
+    applicationURL: process.env.APPLICATION_URL, // Application URL used by the CMS
+
+    clientId: process.env.INTLAYER_CLIENT_ID, // CMS credentials
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+  ai: {
+    applicationContext: "This is a test application", // Helps ensure consistent translation generation
+  },
+};
+
+export default config;
+```
+
+To learn more about the CMS, refer to the [official documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md).
+
+## Using Husky
+
+You can integrate translation generation into your local Git workflow using [Husky](https://typicode.github.io/husky/).
+
+### Example Configuration
+
+```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], // Optional locales are handled remotely
+    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, // Use your own API key
+
+    applicationContext: "This is a test application", // Helps ensure consistent translation generation
+  },
+};
+
+export default config;
+```
+
+```bash fileName=".husky/pre-push"
+npx intlayer build                          # To ensure dictionaries are up to date
+npx intlayer fill --unpushed --mode fill    # Only fill missing content, does not update existing ones
+```
+
+> For more information about Intlayer CLI commands and their usage, refer to the [CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_cli.md).
+
+> If you have multiple apps in your repo using separate intlayer instances, you can use the `--base-dir` argument like this:
+
+```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
+```
+
+## Using GitHub Actions
+
+Intlayer provides a CLI command to autofill and review dictionary content. This can be integrated into your CI/CD workflow using GitHub Actions.
+
+```yaml fileName=".github/workflows/intlayer-translate.yml"
+name: Intlayer Auto-Fill
+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: ⬇️ Checkout repository
+        uses: actions/checkout@v3
+        with:
+          persist-credentials: true
+
+      - name: 🟢 Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20
+
+      - name: 📦 Install dependencies
+        run: npm ci
+
+      - name: ⚙️ Build Intlayer project
+        run: npx intlayer build
+
+      - name: 🤖 Auto-fill missing translations
+        run: npx intlayer fill --git-diff --mode fill
+
+      - name: 📤 Create or update translation PR
+        uses: peter-evans/create-pull-request@v4
+        with:
+          commit-message: chore: auto-fill missing translations [skip ci]
+          branch: auto-translations
+          title: chore: update missing translations
+          labels: translation, automated
+```
+
+> Same as for Husky, in the case of a monorepo, you can use the `--base-dir` argument to sequentially treat each app.
+
+> By default, the `--git-diff` argument filters dictionaries that include changes from base (default `origin/main`) to current branch (default: `HEAD`).
+
+> For more information about Intlayer CLI commands and their usage, refer to the [CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_cli.md).
+
+## Doc History
+
+- 5.5.10 - 2025-06-29: Init history