@intlayer/docs 7.2.3 → 7.3.0

package/docs/en-GB/cli/index.md

@@ -0,0 +1,163 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: CLI
+description: Discover how to use the Intlayer CLI to manage your multilingual website. Follow the steps in this online documentation to set up your project in a few minutes.
+keywords:
+  - CLI
+  - Command Line Interface
+  - Internationalisation
+  - Documentation
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - cli
+history:
+  - version: 7.2.3
+    date: 2025-11-22
+    changes: Add transform command
+  - version: 7.1.0
+    date: 2025-11-05
+    changes: Add skipIfExists option to translate command
+  - version: 6.1.4
+    date: 2025-01-27
+    changes: Add aliases for CLI arguments and commands
+  - version: 6.1.3
+    date: 2025-10-05
+    changes: Add build option to commands
+  - version: 6.1.2
+    date: 2025-09-26
+    changes: Add version command
+  - version: 6.1.0
+    date: 2025-09-26
+    changes: Set verbose option to default to true using CLI
+  - version: 6.1.0
+    date: 2025-09-23
+    changes: Add watch command and with option
+  - version: 6.0.1
+    date: 2025-09-23
+    changes: Add editor command
+  - version: 6.0.0
+    date: 2025-09-17
+    changes: Add content test and list command
+  - version: 5.5.11
+    date: 2025-07-11
+    changes: Update CLI command parameters documentation
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Init history
+---
+
+# Intlayer CLI
+
+---
+
+## Table of Contents
+
+<TOC/>
+
+---
+
+## Install Package
+
+Install the necessary packages using npm:
+
+```bash packageManager="npm"
+npm install intlayer-cli -g
+```
+
+```bash packageManager="yarn"
+yarn add intlayer-cli -g
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer-cli -g
+```
+
+> If the `intlayer` package is already installed, the CLI is automatically installed. You can skip this step.
+
+## intlayer-cli package
+
+The `intlayer-cli` package is intended to transpile your [intlayer declarations](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/content_file.md) into dictionaries.
+
+This package will transpile all intlayer files, such as `src/**/*.content.{ts|js|mjs|cjs|json}`. [See how to declare your Intlayer declaration files](https://github.com/aymericzip/intlayer/blob/main/packages/intlayer/README.md).
+
+To interpret intlayer dictionaries you can use interpreters, such as [react-intlayer](https://www.npmjs.com/package/react-intlayer), or [next-intlayer](https://www.npmjs.com/package/next-intlayer)
+
+## Configuration File Support
+
+Intlayer accepts multiple configuration file formats:
+
+- `intlayer.config.ts`
+- `intlayer.config.js`
+- `intlayer.config.json`
+- `intlayer.config.cjs`
+- `intlayer.config.mjs`
+- `.intlayerrc`
+
+To see how to configure available locales, or other parameters, refer to the [configuration documentation here](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md).
+
+## Run intlayer commands
+
+### Core Commands
+
+- **[Build Dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/build.md)** - Build your dictionaries from content declaration files
+- **[Watch Dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/watch.md)** - Watch for changes and automatically build dictionaries
+- **[Check CLI Version](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/version.md)** - Check the installed Intlayer CLI version
+
+### Dictionary Management
+
+- **[Push Dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/push.md)** - Push dictionaries to the Intlayer editor and CMS
+- **[Pull Dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/pull.md)** - Pull dictionaries from the Intlayer editor and CMS
+- **[Fill Dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/fill.md)** - Fill, audit, and translate dictionaries using AI
+- **[Test Missing Translations](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/test.md)** - Test and identify missing translations
+- **[List Content Declaration Files](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/list.md)** - List all content declaration files in your project
+
+### Component Management
+
+- **[Transform Components](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/transform.md)** - Transform existing components to use Intlayer
+
+### Configuration
+
+- **[Manage Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/configuration.md)** - Get and push your Intlayer configuration to the CMS
+
+### Documentation Management
+
+- **[Translate Document](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/doc-translate.md)** - Automatically translate documentation files using AI
+- **[Review Document](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/doc-review.md)** - Review documentation files for quality and consistency
+
+### Editor & Live Sync
+
+- **[Editor Commands](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/editor.md)** - Use the Intlayer editor commands
+- **[Live Sync Commands](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/live.md)** - Use Live Sync to reflect CMS content changes at runtime
+
+### Development Tools
+
+- **[CLI SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/sdk.md)** - Use the Intlayer CLI SDK in your own code
+- **[Debug Intlayer Command](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/debug.md)** - Debug and troubleshoot Intlayer CLI issues
+
+## Use intlayer commands in your `package.json`
+
+```json fileName="package.json"
+"scripts": {
+  "intlayer:build": "npx intlayer build",
+  "intlayer:watch": "npx intlayer build --watch",
+  "intlayer:push": "npx intlayer push",
+  "intlayer:pull": "npx intlayer pull",
+  "intlayer:fill": "npx intlayer fill",
+  "intlayer:list": "npx intlayer content list",
+  "intlayer:test": "npx intlayer content test",
+  "intlayer:transform": "npx intlayer transform",
+  "intlayer:doc:translate": "npx intlayer doc translate",
+  "intlayer:doc:review": "npx intlayer doc review"
+}
+```
+
+> **Note**: You can also use the shorter aliases:
+>
+> - `npx intlayer list` instead of `npx intlayer content list`
+> - `npx intlayer test` instead of `npx intlayer content test`

package/docs/en-GB/cli/list.md

@@ -0,0 +1,53 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: List Content Declaration Files
+description: Learn how to list all content declaration files in your project.
+keywords:
+  - List
+  - Content Declaration
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - list
+---
+
+# List content declaration files
+
+```bash
+npx intlayer content list
+```
+
+## Aliases:
+
+- `npx intlayer list`
+
+This command displays all content declaration files in your project, showing their dictionary keys and file paths. It is useful for obtaining an overview of all your content files and verifying that they are properly discovered by Intlayer.
+
+## Example:
+
+```bash
+npx intlayer content list
+```
+
+## Example output:
+
+```bash
+npx intlayer content list
+Content declaration files:
+ - home-page        - src/components/HomePage/homePage.content.ts
+ - server-component - src/components/ServerComponent/serverComponent.content.ts
+ - client-component - src/components/ClientComponent/clientComponent.content.ts
+
+Total content declaration files: 3
+```
+
+This command will output:
+
+- A formatted list of all content declaration files with their keys and relative file paths
+- The total count of content declaration files found
+
+The output helps you verify that all your content files are properly configured and discoverable by the Intlayer system.

package/docs/en-GB/cli/live.md

@@ -0,0 +1,41 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Live Sync Commands
+description: Learn how to use Live Sync to reflect CMS content changes at runtime.
+keywords:
+  - Live Sync
+  - CMS
+  - Runtime
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - live
+---
+
+# Live Sync commands
+
+Live Sync allows your app to reflect CMS content changes at runtime. No rebuild or redeploy is required. When enabled, updates are streamed to a Live Sync server that refreshes the dictionaries your application reads. See [Intlayer CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md) for more details.
+
+```json fileName="package.json"
+"scripts": {
+  "intlayer:live:start": "npx intlayer live start --with 'next dev --turbopack'"
+}
+```
+
+## Arguments:
+
+**Configuration options:**
+
+- **`--base-dir`**: Specify the base directory for the project. To retrieve the intlayer configuration, the command will look for the `intlayer.config.{ts,js,json,cjs,mjs}` file in the base directory.
+
+- **`--no-cache`**: Disable the cache.
+
+  > Example: `npx intlayer dictionary push --env-file .env.production.local`
+
+**Log options:**
+
+- **`--verbose`**: Enable verbose logging for debugging. (defaults to true when using the CLI)

package/docs/en-GB/cli/pull.md

@@ -0,0 +1,78 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Pull Dictionaries
+description: Learn how to pull dictionaries from the Intlayer editor and CMS.
+keywords:
+  - Pull
+  - Dictionaries
+  - CLI
+  - Intlayer
+  - Editor
+  - CMS
+slugs:
+  - doc
+  - concept
+  - cli
+  - pull
+---
+
+# Pull Distant Dictionaries
+
+```bash
+npx intlayer pull
+```
+
+If the [intlayer editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_visual_editor.md) is installed, you can also pull dictionaries from the editor. This way, you can overwrite the content of your dictionaries to suit the needs of your application.
+
+## Aliases:
+
+- `npx intlayer dictionaries pull`
+- `npx intlayer dictionary pull`
+- `npx intlayer dic pull`
+
+## Arguments:
+
+**Dictionary options:**
+
+- **`-d, --dictionaries`**: IDs of the dictionaries to pull. If not specified, all dictionaries will be pulled.
+
+  > Example: `npx intlayer dictionary pull -d my-dictionary-id my-other-dictionary-id`
+
+- **`--dictionary`**: IDs of the dictionaries to pull (alias for --dictionaries).
+
+  > Example: `npx intlayer dictionary pull --dictionary my-dictionary-id my-other-dictionary-id`
+
+**Configuration options:**
+
+- **`--base-dir`**: Specify the base directory for the project. To retrieve the intlayer configuration, the command will look for the `intlayer.config.{ts,js,json,cjs,mjs}` file in the base directory.
+
+  > Example: `npx intlayer dictionary push --env-file .env.production.local`
+
+- **`--no-cache`**: Disable the cache.
+
+  > Example: `npx intlayer build --no-cache`
+
+**Environment variables options:**
+
+- **`--env`**: Specify the environment (e.g., `development`, `production`).
+- **`--env-file`**: Provide a custom environment file to load variables from.
+- **`--base-dir`**: Specify the base directory for the project. To retrieve the intlayer configuration, the command will look for the `intlayer.config.{ts,js,json,cjs,mjs}` file in the base directory.
+
+  > Example: `npx intlayer dictionary push --env-file .env.production.local`
+
+  > Example: `npx intlayer dictionary push --env production`
+
+**Output options:**
+
+- **`--new-dictionaries-path`** : Path to the directory where the new dictionaries will be saved. If not specified, the new dictionaries will be saved in the `./intlayer-dictionaries` directory of the project. If a `filePath` field is specified in your dictionary content, the dictionaries will not consider this argument and will be saved in the specified `filePath` directory.
+
+**Log options:**
+
+- **`--verbose`**: Enable verbose logging for debugging. (default is true when using the CLI)
+
+## Example:
+
+```bash
+npx intlayer dictionary pull --newDictionariesPath ./my-dictionaries-dir/
+```

package/docs/en-GB/cli/push.md

@@ -0,0 +1,98 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Push Dictionaries
+description: Learn how to push your dictionaries to the Intlayer editor and CMS.
+keywords:
+  - Push
+  - Dictionaries
+  - CLI
+  - Intlayer
+  - Editor
+  - CMS
+slugs:
+  - doc
+  - concept
+  - cli
+  - push
+---
+
+# Push Dictionaries
+
+```bash
+npx intlayer dictionary push
+```
+
+If the [intlayer editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_visual_editor.md) is installed, you can also push dictionaries to the editor. This command will allow you to make the dictionaries available to [the editor](https://intlayer.org/dashboard). In this way, you can share your dictionaries with your team and edit your content without modifying the code of your application.
+
+## Aliases:
+
+- `npx intlayer dictionaries push`
+- `npx intlayer dictionary push`
+- `npx intlayer dic push`
+
+## Arguments:
+
+**Dictionary options:**
+
+- **`-d`, `--dictionaries`**: IDs of the dictionaries to push. If not specified, all dictionaries will be pushed.
+
+  > Example: `npx intlayer dictionary push -d my-dictionary-id my-other-dictionary-id`
+
+- **`--dictionary`**: IDs of the dictionaries to push (alias for --dictionaries).
+
+  > Example: `npx intlayer dictionary push --dictionary my-dictionary-id my-other-dictionary-id`
+
+**Configuration options:**
+
+- **`--base-dir`**: Specify the base directory for the project. To retrieve the Intlayer configuration, the command will look for the `intlayer.config.{ts,js,json,cjs,mjs}` file in the base directory.
+
+  > Example: `npx intlayer dictionary push --env-file .env.production.local`
+
+- **`--no-cache`**: Disable the cache.
+
+  > Example: `npx intlayer build --no-cache`
+
+**Environment variables options:**
+
+- **`--env`**: Specify the environment (e.g., `development`, `production`). Useful if you use environment variables in your Intlayer configuration file.
+- **`--env-file`**: Provide a custom environment file to load variables from. Useful if you use environment variables in your Intlayer configuration file.
+
+  > Example: `npx intlayer dictionary push --env-file .env.production.local`
+
+  > Example: `npx intlayer dictionary push --env production`
+
+**Output options:**
+
+- **`-r`, `--delete-locale-dictionary`**: Skip the question asking whether to delete the locales directories once the dictionaries are pushed, and remove them. By default, if the dictionary is defined locally, it will overwrite the content of remote dictionaries.
+
+  > Example: `npx intlayer dictionary push -r`
+
+  > Example: `npx intlayer dictionary push --delete-locale-dictionary`
+
+- **`-k`, `--keep-locale-dictionary`**: Skip the question asking whether to delete the locales directories once the dictionaries are pushed, and keep them. By default, if the dictionary is defined locally, it will overwrite the content of remote dictionaries.
+
+  > Example: `npx intlayer dictionary push -k`
+
+  > Example: `npx intlayer dictionary push --keep-locale-dictionary`
+
+**Preparation options:**
+
+- **`--build`**: Build the dictionaries before pushing to ensure the content is up to date. True will force the build, false will skip the build, undefined will allow using the cache of the build.
+
+**Log options:**
+
+- **`--verbose`**: Enable verbose logging for debugging. (defaults to true when using CLI)
+
+**Git options:**
+
+- **`--git-diff`**: Only run on dictionaries that include changes from the base (default `origin/main`) to the current branch (default: `HEAD`).
+- **`--git-diff-base`**: Specify the base reference for git diff (default `origin/main`).
+- **`--git-diff-current`**: Specify the current reference for git diff (default: `HEAD`).
+- **`--uncommitted`**: Include uncommitted changes.
+- **`--unpushed`**: Include unpushed changes.
+- **`--untracked`**: Include untracked files.
+
+  > Example: `npx intlayer dictionary push --git-diff --git-diff-base origin/main --git-diff-current HEAD`
+
+  > Example: `npx intlayer dictionary push --uncommitted --unpushed --untracked`

package/docs/en-GB/cli/sdk.md

@@ -0,0 +1,67 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: CLI SDK
+description: Learn how to use the Intlayer CLI SDK in your own code.
+keywords:
+  - SDK
+  - CLI
+  - Intlayer
+  - Programmatic
+slugs:
+  - doc
+  - concept
+  - cli
+  - sdk
+---
+
+# CLI SDK
+
+The CLI SDK is a library that allows you to use the Intlayer CLI in your own code.
+
+```bash packageManager="npm"
+npm install @intlayer/cli --save-dev
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/cli --save-dev
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/cli --save-dev
+```
+
+Example of usage:
+
+```ts
+import {
+  push,
+  pull,
+  fill,
+  build,
+  listContentDeclaration,
+  testMissingTranslations,
+  docTranslate,
+  docReview,
+  transform,
+} from "@intlayer/cli";
+
+push();
+// ...
+pull();
+// ...
+fill();
+// ...
+build();
+// ...
+listContentDeclaration();
+// ...
+testMissingTranslations();
+// ...
+docTranslate();
+// ...
+docReview();
+// ...
+transform();
+// ...
+```

package/docs/en-GB/cli/test.md

@@ -0,0 +1,100 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Test Missing Translations
+description: Learn how to test and identify missing translations in your dictionaries.
+keywords:
+  - Test
+  - Missing Translations
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - test
+---
+
+# Test missing translations
+
+```bash
+npx intlayer content test
+```
+
+## Aliases:
+
+- `npx intlayer test`
+
+This command analyses your content declaration files to identify missing translations across all configured locales. It provides a comprehensive report showing which translation keys are missing for which locales, helping you maintain consistency across your multilingual content.
+
+## Example output:
+
+```bash
+pnpm intlayer content test
+Missing translations:
+ - home-page                      - tr         - src/components/HomePage/homePage.content.ts
+ - server-component               - es, tr     - src/components/ServerComponent/serverComponent.content.ts
+ - client-component               - pl, tr     - src/components/ClientComponent/clientComponent.content.ts
+Locales: en, ru, ja, fr, ko, zh, es, de, ar, it, en-GB, pt, hi, tr, pl
+Required locales: en
+Missing locales: pl, tr, es
+Missing required locales: -
+Total missing locales: 3
+Total missing required locales: 0
+```
+
+## Arguments:
+
+**Configuration options:**
+
+- **`--env`**: Specify the environment (e.g., `development`, `production`).
+- **`--env-file [envFile]`**: Provide a custom environment file to load variables from.
+- **`--base-dir`**: Specify the base directory for the project.
+
+  > Example: `npx intlayer content test --base-dir ./src --env-file .env.production.local`
+
+- **`--no-cache`**: Disable the cache.
+
+  > Example: `npx intlayer build --no-cache`
+
+**Preparation options:**
+
+- **`--build`**: Build the dictionaries before pushing to ensure the content is up to date. True will force the build, false will skip the build, undefined will allow using the cache of the build.
+
+**Log options:**
+
+- **`--verbose`**: Enable verbose logging for debugging. (default to true when using CLI)
+
+  > Example: `npx intlayer content test --verbose`
+
+## Example:
+
+```bash
+npx intlayer content test --verbose
+```
+
+The output helps you quickly identify which translations need to be completed to ensure your application works correctly across all configured locales.
+
+> Example: `npx intlayer content test --base-dir ./src --env-file .env.production.local`
+
+- **`--no-cache`**: Disable the cache.
+
+  > Example: `npx intlayer build --no-cache`
+
+**Preparation options:**
+
+- **`--build`**: Build the dictionaries before pushing to ensure the content is up to date. True will force the build, false will skip the build, undefined will allow using the cache of the build.
+
+**Log options:**
+
+- **`--verbose`**: Enable verbose logging for debugging. (default to true using CLI)
+
+  > Example: `npx intlayer content test --verbose`
+
+## Example:
+
+```bash
+npx intlayer content test --verbose
+```
+
+The output helps you quickly identify which translations need to be completed to ensure your application works properly across all configured locales.

package/docs/en-GB/cli/transform.md

@@ -0,0 +1,65 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Transform Components
+description: Learn how to transform existing components to use Intlayer.
+keywords:
+  - Transform
+  - Components
+  - Migration
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - transform
+---
+
+# Transform components
+
+```bash
+npx intlayer transform
+```
+
+This command analyses your code files to help migrate existing components to use Intlayer. It supports interactive file selection or specific file targeting.
+
+## Aliases:
+
+- `npx intlayer trans`
+
+## Arguments:
+
+**File selection options:**
+
+- **`-f, --file [files...]`**: List of specific files to transform. If not provided, the CLI will scan for matching files (`**/*.{tsx,jsx,vue,svelte,ts,js}`) and prompt you to select which ones to transform.
+
+> Example: `npx intlayer transform -f src/components/MyComponent.tsx`
+
+**Output options:**
+
+- **`-o, --output-content-declarations [outputContentDeclarations]`**: Directory to save the generated content declaration files.
+
+  > Example: `npx intlayer transform -o src/content`
+
+- **`--code-only`**: Only transform the component code (do not write content declaration).
+
+  > Example: `npx intlayer transform --code-only`
+
+- **`--declaration-only`**: Only generate content declaration (do not rewrite component).
+
+  > Example: `npx intlayer transform --declaration-only`
+
+**Configuration options:**
+
+- **`--base-dir`**: Specify the base directory for the project.
+- **`--env`**: Specify the environment.
+- **`--env-file`**: Provide a custom environment file.
+- **`--verbose`**: Enable verbose logging.
+
+**Required plugins:**
+
+The transform command works without additional plugins on TypeScript / JSX files. However, it requires the following plugins to be installed for Vue and Svelte projects:
+
+- **`@intlayer/vue-transformer`**: For Vue files.
+- **`@intlayer/svelte-transformer`**: For Svelte files.

package/docs/en-GB/cli/version.md

@@ -0,0 +1,24 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Check CLI Version
+description: Learn how to check the installed Intlayer CLI version.
+keywords:
+  - Version
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - version
+---
+
+# Check CLI version
+
+```bash
+npx intlayer --version
+npx intlayer version
+```
+
+Both commands display the installed Intlayer CLI version.