@intlayer/docs 5.5.9 → 5.5.11

package/docs/en-GB/introduction.md

@@ -0,0 +1,207 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-06-29
+title: Introduction
+description: Discover how Intlayer works. See the steps used by Intlayer in your application. See what the different packages do.
+keywords:
+  - Introduction
+  - Get started
+  - Intlayer
+  - Application
+  - Packages
+slugs:
+  - doc
+  - get-started
+---
+
+# Intlayer Documentation
+
+Welcome to the official Intlayer documentation! Here, you'll find everything you need to integrate, configure, and master Intlayer for all your internationalisation (i18n) needs, whether you’re working with Next.js, React, Vite, Express, or another JavaScript environment.
+
+## Introduction
+
+### What is Intlayer?
+
+**Intlayer** is an internationalisation library designed specifically for JavaScript developers. It allows the declaration of your content everywhere in your code. It converts declarations of multilingual content into structured dictionaries to integrate easily into your code. Using TypeScript, **Intlayer** makes your development stronger and more efficient.
+
+Intlayer also provides an optional visual editor that allows you to easily edit and manage your content. This editor is particularly useful for developers who prefer a visual interface for content management, or for teams generating content without having to worry about code.
+
+### Example of usage
+
+```bash
+.
+└── Components
+    └── MyComponent
+        ├── index.content.cjs
+        └── index.mjs
+```
+
+```tsx fileName="src/components/MyComponent/index.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const componentContent = {
+  key: "component-key",
+  content: {
+    myTranslatedContent: t({
+      "en-GB": "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+  },
+} satisfies Dictionary;
+
+export default componentContent;
+```
+
+```javascript fileName="src/components/MyComponent/index.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const componentContent = {
+  key: "component-key",
+  content: {
+    myTranslatedContent: t({
+      "en-GB": "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+  },
+};
+
+export default componentContent;
+```
+
+```javascript fileName="src/components/MyComponent/index.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const componentContent = {
+  key: "component-key",
+  content: {
+    myTranslatedContent: t({
+      "en-GB": "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+  },
+};
+
+module.exports = componentContent;
+```
+
+```json fileName="src/components/MyComponent/index.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "component-key",
+  "content": {
+    "myTranslatedContent": {
+      "nodeType": "translation",
+      "translation": {
+        "en-GB": "Hello World",
+        "fr": "Bonjour le monde",
+        "es": "Hola Mundo"
+      }
+    }
+  }
+}
+```
+
+```tsx fileName="src/components/MyComponent/index.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+export const MyComponent: FC = () => {
+  const { myTranslatedContent } = useIntlayer("component-key");
+
+  return <span>{myTranslatedContent}</span>;
+};
+```
+
+```jsx fileName="src/components/MyComponent/index.mjx" codeFormat="esm"
+import { useIntlayer } from "react-intlayer";
+
+const MyComponent = () => {
+  const { myTranslatedContent } = useIntlayer("component-key");
+
+  return <span>{myTranslatedContent}</span>;
+};
+```
+
+```jsx fileName="src/components/MyComponent/index.csx" codeFormat="commonjs"
+const { useIntlayer } = require("react-intlayer");
+
+const MyComponent = () => {
+  const { myTranslatedContent } = useIntlayer("component-key");
+
+  return <span>{myTranslatedContent}</span>;
+};
+```
+
+## Main Features
+
+Intlayer offers a variety of features tailored to meet the needs of modern web development. Below are the key features, with links to detailed documentation for each:
+
+- **Internationalisation Support**: Enhance your application's global reach with built-in support for internationalisation.
+- **Visual Editor**: Improve your development workflow with editor plugins designed for Intlayer. Check out the [Visual Editor Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md).
+- **Configuration Flexibility**: Customise your setup with extensive configuration options detailed in the [Configuration Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md).
+- **Advanced CLI Tools**: Manage your projects efficiently using Intlayer's command line interface. Explore the capabilities in the [CLI Tools Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_cli.md).
+
+## Core Concepts
+
+### Dictionary
+
+Organise your multilingual content close to your code to keep everything consistent and maintainable.
+
+- **[Get Started](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/get_started.md)**  
+  Learn the basics of declaring your content in Intlayer.
+
+- **[Translation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/translation.md)**  
+  Understand how translations are generated, stored, and utilised in your application.
+
+- **[Enumeration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/enumeration.md)**  
+  Easily manage repeated or fixed sets of data across various languages.
+
+- **[Condition](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/conditional.md)**  
+  Learn how to use conditional logic in Intlayer to create dynamic content.
+
+- **[Insertion](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/insertion.md)**
+  Discover how to insert values in a string using insertion placeholders.
+
+- **[Function Fetching](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/function_fetching.md)**  
+  See how to dynamically fetch content with custom logic to match your project’s workflow.
+
+- **[Markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/markdown.md)**  
+  Learn how to use Markdown in Intlayer to create rich content.
+
+- **[File embeddings](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/file_embeddings.md)**  
+  Discover how to embed external files in Intlayer to use them in the content editor.
+
+- **[Nesting](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/nesting.md)**  
+  Understand how to nest content in Intlayer to create complex structures.
+
+### Environments & Integrations
+
+We’ve built Intlayer with flexibility in mind, offering seamless integration across popular frameworks and build tools:
+
+- **[Intlayer with Next.js 15](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_nextjs_15.md)**
+- **[Intlayer with Next.js 14 (App Router)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_nextjs_14.md)**
+- **[Intlayer with Next.js Page Router](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_nextjs_page_router.md)**
+- **[Intlayer with React CRA](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_create_react_app.md)**
+- **[Intlayer with Vite + React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_vite+react.md)**
+- **[Intlayer with React Native and Expo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_react_native+expo.md)**
+- **[Intlayer with Lynx and React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_lynx+react.md)**
+- **[Intlayer with Express](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_express.md)**
+
+Each integration guide includes best practices for using Intlayer’s features, such as **server-side rendering**, **dynamic routing**, or **client-side rendering**, enabling you to maintain a fast, SEO-friendly, and highly scalable application.
+
+## Contributing & Feedback
+
+We value the power of open-source and community-driven development. If you’d like to propose improvements, add a new guide, or correct any issues in our docs, feel free to submit a Pull Request or open an issue on our [GitHub repository](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB).
+
+**Ready to translate your application faster and more efficiently?** Dive into our docs to start using Intlayer today. Experience a robust, streamlined approach to internationalisation that keeps your content organised and your team more productive.
+
+---
+
+## Doc History
+
+- 5.5.10 - 2025-06-29: Init history

package/docs/en-GB/mcp_server.md

@@ -0,0 +1,174 @@
+---
+createdAt: 2025-06-07
+updatedAt: 2025-06-07
+title: MCP Server Documentation
+description: Explore the features and setup of the MCP Server to optimise your server management and operations.
+keywords:
+  - MCP Server
+  - Server Management
+  - Optimisation
+  - Intlayer
+  - Documentation
+  - Setup
+  - Features
+slugs:
+  - doc
+  - mcp-server
+---
+
+# Intlayer MCP Server
+
+The **Intlayer MCP (Model Context Protocol) Server** provides AI-powered IDE assistance tailored for the Intlayer ecosystem. Designed for modern developer environments such as **Cursor**, **GitHub Copilot workspace**, and any IDE supporting the MCP protocol, this server offers you contextual, real-time support based on your project's setup.
+
+## Why Use the Intlayer MCP Server?
+
+By enabling the Intlayer MCP Server in your IDE, you unlock:
+
+- **Smart CLI Integration**  
+  Access and run Intlayer CLI commands directly from your IDE interface. View the full list of commands and options in the [Intlayer CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_cli.md).
+
+- **Context-Aware Documentation**  
+  The MCP server loads and exposes the documentation that corresponds to the version of Intlayer you're using in your project. This ensures that code suggestions, command options, and explanations are always up to date and relevant.
+
+- **AI-Assisted Development**  
+  With project-aware suggestions and autocomplete, the AI assistant can explain your code, recommend CLI usage, or suggest how to use specific features of Intlayer based on your current files.
+
+- **Lightweight & Instant Setup**  
+  No server maintenance or heavy installation required. Just configure your `.cursor/mcp.json` or equivalent MCP config and you're ready to go.
+
+---
+
+## Setup Cursor
+
+In your project root, add the following `.cursor/mcp.json` configuration file:
+
+```json
+{
+  "mcpServers": {
+    "intlayer": {
+      "command": "npx",
+      "args": ["-y", "@intlayer/mcp"]
+    }
+  }
+}
+```
+
+This instructs your IDE to launch the Intlayer MCP server using `npx`, ensuring it always uses the latest available version unless you choose to pin it.
+
+---
+
+## Setup VS Code
+
+To use the Intlayer MCP Server with VS Code, you need to configure it in your workspace or user settings.
+
+### Workspace Configuration
+
+Create a `.vscode/mcp.json` file in your project root:
+
+```json
+{
+  "servers": {
+    "intlayer": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@intlayer/mcp"]
+    }
+  }
+}
+```
+
+### Using the MCP Server in VS Code
+
+1. **Enable Agent Mode**: Open the Chat view (⌃⌘I on Mac, Ctrl+Alt+I on Windows/Linux) and select **Agent** mode from the dropdown.
+
+2. **Access Tools**: Click the **Tools** button to view available Intlayer tools. You can select or deselect specific tools as required.
+
+3. **Direct Tool Reference**: Refer to tools directly in your prompts by typing `#` followed by the tool name.
+
+4. **Tool Confirmation**: By default, VS Code will request confirmation before running tools. Use the **Continue** button options to automatically confirm tools for the current session, workspace, or all future invocations.
+
+### Managing the Server
+
+- Run **MCP: List Servers** from the Command Palette to view configured servers
+- Start, stop, or restart the Intlayer MCP server as needed
+- View server logs for troubleshooting by selecting the server and choosing **Show Output**
+
+For more detailed information about VS Code MCP integration, see the [official VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
+
+---
+
+## Using the MCP Server via CLI
+
+You can also run the Intlayer MCP server directly from the command line for testing, debugging, or integration with other tools.
+
+### Install the MCP Server
+
+First, install the MCP server package globally or use it via npx:
+
+```bash
+# Install globally
+npm install -g @intlayer/mcp
+
+# Or use directly with npx (recommended)
+npx @intlayer/mcp
+```
+
+### Start the Server
+
+To start the MCP server with the inspector for debugging and testing:
+
+```bash
+# Using the built-in start command
+npm run start
+
+# Or directly with npx
+npx @modelcontextprotocol/inspector npx @intlayer/mcp
+```
+
+This will launch the MCP server with an inspector interface that allows you to:
+
+- Test MCP protocol communications
+- Debug server responses
+- Validate tool and resource implementations
+- Monitor server performance
+
+### Development Usage
+
+For development and testing purposes, you can run the server in various modes:
+
+```bash
+# Build and start in development mode
+npm run dev
+
+# Run with custom configuration
+node dist/cjs/index.cjs
+
+# Test the server functionality
+npm test
+```
+
+The server will expose Intlayer-specific tools and resources that can be consumed by any MCP-compatible client, not just Cursor or other IDEs.
+
+---
+
+## Features Overview
+
+| Feature        | Description                                                                  |
+| -------------- | ---------------------------------------------------------------------------- |
+| CLI Support    | Run `intlayer` commands, get usage hints and arguments inline                |
+| Versioned Docs | Auto-detect and load documentation matching your current version of Intlayer |
+| Autocompletion | Intelligent command and config suggestions as you type                       |
+| Plugin-Ready   | Compatible with IDEs and tools that support the MCP standard                 |
+
+---
+
+## Useful Links
+
+- [Intlayer CLI Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_cli.md)
+- [Intlayer GitHub Repository](https://github.com/aymericzip/intlayer)
+
+---
+
+## Doc History
+
+- 5.5.10 - 2025-06-29: Init history

package/docs/en-GB/packages/@intlayer/api/index.md

@@ -0,0 +1,56 @@
+---
+createdAt: 2025-02-07
+updatedAt: 2025-06-29
+title: @intlayer/api - SDK for Intlayer API Integration
+description: NPM package providing Software Development Kit (SDK) to interact with Intlayer API for content auditing, organisations, projects, and user management.
+keywords:
+  - intlayer
+  - API
+  - SDK
+  - integration
+  - content audit
+  - organisations
+  - projects
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - api
+---
+
+# @intlayer/api: NPM Package to interact with Intlayer API
+
+**Intlayer** is a suite of packages designed specifically for JavaScript developers. It is compatible with frameworks like React, React, and Express.js.
+
+The **`@intlayer/api`** package is an SDK (Software Development Kit) to interact with the Intlayer API. It provides a set of functions to audit content declaration, interact with organisations, projects, and users, etc.
+
+## Usage
+
+```ts
+import { intlayerAPI } from "@intlayer/api";
+
+intlayerAPI.user.getUser({
+  ids: ["user-id-1", "user-id-2"],
+});
+```
+
+## Installation
+
+Install the necessary package using your preferred package manager:
+
+```bash packageManager="npm"
+npm install @intlayer/api
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/api
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/api
+```
+
+## Doc History
+
+- 5.5.10 - 2025-06-29: Init history

package/docs/en-GB/packages/@intlayer/chokidar/index.md

@@ -0,0 +1,55 @@
+---
+createdAt: 2025-02-07
+updatedAt: 2025-06-29
+title: @intlayer/chokidar - File Watching for Intlayer i18n
+description: NPM package providing file watching capabilities for Intlayer, enabling automatic updates and hot reloading for internationalisation content.
+keywords:
+  - intlayer
+  - chokidar
+  - file watching
+  - hot reload
+  - i18n
+  - JavaScript
+  - NPM
+  - development
+slugs:
+  - doc
+  - package
+  - @intlayer_chokidar
+---
+
+# @intlayer/chokidar: NPM Package to Scan and Build Intlayer Declaration Files into Dictionaries
+
+**Intlayer** is a suite of packages designed specifically for JavaScript developers. It is compatible with frameworks such as React and Express.js.
+
+The **`@intlayer/chokidar`** package is used to scan and build Intlayer declaration files into dictionaries using [chokidar](https://github.com/paulmillr/chokidar) and in accordance with the [Intlayer configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md).
+
+## Usage
+
+```ts
+import { watch, prepareIntlayer } from "@intlayer/chokidar";
+
+await prepareIntlayer(); // Build Intlayer dictionaries
+
+watch({ persistent: true }); // Watch for changes in the configuration files
+```
+
+## Installation
+
+Install the necessary package using your preferred package manager:
+
+```bash packageManager="npm"
+npm install @intlayer/chokidar
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/chokidar
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/chokidar
+```
+
+## Doc History
+
+- 5.5.10 - 2025-06-29: Initial history

package/docs/en-GB/packages/@intlayer/cli/index.md

@@ -0,0 +1,45 @@
+---
+createdAt: 2025-02-07
+updatedAt: 2025-06-29
+title: @intlayer/cli - Command Line Interface Package for Intlayer
+description: NPM package providing scripts for Intlayer CLI commands, ensuring uniformity across all command line interfaces for internationalisation management.
+keywords:
+  - intlayer
+  - CLI
+  - command line
+  - scripts
+  - i18n
+  - JavaScript
+  - NPM
+  - tools
+slugs:
+  - doc
+  - package
+  - @intlayer_cli
+---
+
+# @intlayer/cli: NPM Package to use the scripts provided by the intlayer CLI
+
+**Intlayer** is a suite of packages designed specifically for JavaScript developers. It is compatible with frameworks such as React, React, and Express.js.
+
+The **`@intlayer/cli`** package is an NPM package used to declare the scripts related to the Intlayer command line interfaces. It ensures the uniformity of all Intlayer CLI commands. This package is notably consumed by the [intlayer-cli](https://github.com/aymericzip/intlayer/tree/main/docs/docs/en-GB/packages/intlayer-cli/index.md), and the [intlayer](https://github.com/aymericzip/intlayer/tree/main/docs/docs/en-GB/packages/intlayer/index.md) packages.
+
+## Installation
+
+Install the necessary package using your preferred package manager:
+
+```bash packageManager="npm"
+npm install @intlayer/cli
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/cli
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/cli
+```
+
+## Doc History
+
+- 5.5.10 - 2025-06-29: Initial history

package/docs/en-GB/packages/@intlayer/config/index.md

@@ -0,0 +1,140 @@
+---
+createdAt: 2025-02-07
+updatedAt: 2025-06-29
+title: @intlayer/config - Configuration Management for Intlayer
+description: NPM package to retrieve Intlayer configuration and define environment variables for internationalisation settings across different environments.
+keywords:
+  - intlayer
+  - configuration
+  - environment
+  - settings
+  - i18n
+  - JavaScript
+  - NPM
+  - variables
+slugs:
+  - doc
+  - package
+  - @intlayer_config
+---
+
+# @intlayer/config: NPM Package to retrieve Intlayer configuration
+
+**Intlayer** is a suite of packages designed specifically for JavaScript developers. It is compatible with frameworks such as React, React, and Express.js.
+
+The **`@intlayer/config`** package is an NPM package that allows you to retrieve the configuration of Intlayer and define the environment variables related to the current environment.
+
+## Installation
+
+Install the necessary package using your preferred package manager:
+
+```bash packageManager="npm"
+npm install @intlayer/config
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/config
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/config
+```
+
+## Usage
+
+### Read the configuration of Intlayer using the file system
+
+Example:
+
+```ts
+import { getConfiguration, type IntlayerConfig } from "@intlayer/config";
+
+const config: IntlayerConfig = getConfiguration();
+
+console.log(config);
+// Output:
+// {
+//   internationalisation: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+> This function uses the `fs` package and will only work on the server side.
+
+### Read the configuration of Intlayer using environment variables
+
+Example:
+
+```ts
+import { getConfiguration, type IntlayerConfig } from "@intlayer/config/client";
+
+const config: IntlayerConfig = getConfiguration({
+  env: "production",
+});
+
+console.log(config);
+// Output:
+// {
+//   internationalisation: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+> This function will not return anything if the environment variables are not defined.
+
+### Define the environment variables
+
+1. Create a configuration file.
+
+```ts fileName="intlayer.config.ts"
+import { type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalisation: {
+    /* ... */
+  },
+  middleware: {
+    /* ... */
+  },
+  content: {
+    /* ... */
+  },
+  editor: {
+    /* ... */
+  },
+};
+
+export default config;
+```
+
+> See [Intlayer configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md) for more details.
+
+2. Define the environment variables.
+
+```ts
+import { getConfiguration } from "@intlayer/config";
+
+const intlayerConfig = getConfiguration();
+
+// Format all configuration values as environment variables
+const env = formatEnvVariable();
+
+// Set each formatted environment variable in process.env
+Object.assign(process.env, env);
+```
+
+3. Import the configuration file.
+
+```ts
+import { getConfiguration } from "@intlayer/config/client";
+
+const intlayerConfig = getConfiguration();
+```
+
+## Doc History
+
+- 5.5.10 - 2025-06-29: Initial history