@intlayer/docs 5.5.8

package/en/t.md

@@ -0,0 +1,163 @@
+# 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/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/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/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/en/dictionary/file.md)
+
+### 5. Dynamic Content & Logic-Based Rendering
+
+This section combines Enumeration, Nesting, Conditional Rendering, and Insertion functions, along with Function Fetching, into a single structured overview.
+
+#### Enumeration & Pluralization
+
+- Use the `enu` function to define content variations based on numeric values, ranges, or custom keys.
+- Enables automatic selection of the correct phrase based on the given value, ensuring content adapts dynamically.
+- Supports ordering rules, where the first valid condition is chosen, ensuring predictable behavior.
+- Compatible with TypeScript, ESM, CommonJS, and JSON configurations for seamless integration.
+- Works with React Intlayer and Next Intlayer via `useIntlayer`, allowing flexible UI content adjustments.
+- Supports custom fallback values when no specific conditions match, preventing undefined responses.
+
+#### Nesting & Sub-Content Referencing
+
+- Use the `nest` function to reference and reuse content from another dictionary, reducing duplication.
+- Allows referencing an entire dictionary or a specific nested value within it.
+- Ensures dynamic content updates when the referenced dictionary changes.
+- Compatible with TypeScript, ESM, CommonJS, and JSON configurations for flexible integration.
+- Works seamlessly with React Intlayer and Next Intlayer using `useIntlayer` to retrieve nested content dynamically.
+- Supports structured and hierarchical content management, improving maintainability and scalability.
+
+#### Conditional Rendering
+
+- Define content that adapts based on specific conditions, such as user language, user login status, or any other context-related variable.
+- Helps tailor personalized experiences without duplicating content across multiple files.
+
+#### Dynamic Content Insertion
+
+- Utilize the `insert` function to define content with placeholders (`{{name}}`, `{{age}}`, etc.), allowing dynamic substitution at runtime.
+- 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, ensuring broad compatibility.
+- Easily integrates with React Intlayer and Next Intlayer using `useIntlayer`, allowing flexible content rendering in UI components.
+- Supports reusable and customizable messages by passing different data objects to the insertion function.
+
+#### Function Fetching
+
+Intlayer allows you to declare content functions in your content modules, which can be either synchronous or asynchronous. When the application builds, Intlayer executes these functions to obtain the function's result. The return value must be a JSON object or a simple value like a string or number.
+
+> Warning: Function fetching is currently not available in JSON content declaration and distant content declaration files.
+
+##### Function Declarations
+
+Example of a simple synchronous function fetching content:
+
+```typescript
+import type { Dictionary } from "intlayer";
+
+const functionContent = {
+  key: "function_content",
+  content: {
+    text: () => "This is the content rendered by a function",
+  },
+} satisfies Dictionary;
+
+export default functionContent;
+```
+
+##### Asynchronous Function Fetching
+
+Example of an asynchronous function that simulates a server fetch:
+
+```typescript
+import { setTimeout } from "node:timers/promises";
+import type { Dictionary } from "intlayer";
+
+const fakeFetch = async (): Promise<string> => {
+  return await setTimeout(200).then(
+    () => "This is the content fetched from the server"
+  );
+};
+
+const asyncFunctionContent = {
+  key: "async_function",
+  content: { text: fakeFetch },
+} satisfies Dictionary;
+
+export default asyncFunctionContent;
+```
+
+##### Using Function-Based Content in React Components
+
+To use function-based content in a React component:
+
+```tsx
+import { useIntlayer } from "react-intlayer";
+
+const MyComponent = () => {
+  const functionContent = useIntlayer("function_content");
+  const asyncFunctionContent = useIntlayer("async_function_content");
+
+  return (
+    <div>
+      <p>{functionContent.text}</p>
+      <p>{asyncFunctionContent.text}</p>
+    </div>
+  );
+};
+
+export default MyComponent;
+```
+
+This section ensures all related dynamic content and logic-driven features are grouped for clarity and ease of understanding.
+
+---
+
+## Content Declaration Formats
+
+Intlayer supports **TypeScript** (also JavaScript) and **JSON** for declaring content.
+
+> Resources:
+
+> - [Content Declaration Formats](https://github.com/aymericzip/intlayer/blob/main/docs/en/dictionary/content_extention_customization.md)
+
+(Other sections remain unchanged.)

package/en/terms_of_service.md

@@ -0,0 +1,33 @@
+# Intlayer Terms of Use
+
+## 1. Acceptance of Terms
+
+By using Intlayer, you agree to be bound by these terms of use. If you do not accept these terms, please do not use the tool.
+
+## 2. License
+
+Intlayer is distributed under the **Apache 2.0 license** which allows the use, modification, and distribution of the code for both open-source and commercial projects. Users are allowed to modify the source code and submit contributions via pull requests in accordance with the guidelines established in our [contribution guide](https://github.com/aymericzip/intlayer/blob/main/CONTRIBUTING.md). Code theft for commercial use is strictly prohibited.
+
+## 3. Commercial Use
+
+You are permitted to use Intlayer for commercial projects. However, reusing the code to create direct competitor tools based on Intlayer without significant transformation or substantial value addition is prohibited.
+
+## 4. Liability
+
+The maintainers of Intlayer strive to correct bugs and security issues as soon as they are discovered. However, they disclaim any responsibility for damages resulting from such issues on user infrastructures. We encourage users to report issues via our [issue tracking system](https://github.com/aymericzip/intlayer/issues).
+
+## 5. Privacy
+
+Intlayer does not collect or store any personal data of users.
+
+## 6. Contributions
+
+Users are encouraged to contribute to Intlayer by following the guidelines provided in our contribution guide. Any submitted code must adhere to the established quality standards and will be reviewed by the maintainers before integration.
+
+## 7. Attribution
+
+Any tool developed to extend or utilize Intlayer's code must clearly credit Intlayer as the basis of the code. This attribution must be visible in the source code as well as in any user or promotional documentation.
+
+## 8. Modification of Terms
+
+These terms of use may be modified at any time. Users will be informed of any significant changes in the terms of use and must accept the changes to continue using Intlayer.

package/en/vs_code_extension.md

@@ -0,0 +1,129 @@
+# 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**.

package/en-GB/CI_CD.md

@@ -0,0 +1,149 @@
+# 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 = {
+  internationalisation: {
+    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/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 = {
+  internationalisation: {
+    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/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/en-GB/intlayer_cli.md).