@intlayer/docs 7.2.3 → 7.3.0

package/docs/en/cli/doc-translate.md

@@ -0,0 +1,132 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Translate Document
+description: Learn how to automatically translate documentation files using AI translation services.
+keywords:
+  - Translate
+  - Document
+  - Documentation
+  - AI
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - doc-translate
+---
+
+# Translate Document
+
+The `doc translate` command automatically translates documentation files from a base locale to target locales using AI translation services.
+
+```bash
+npx intlayer doc translate
+```
+
+## Arguments:
+
+**File list options:**
+
+- **`--doc-pattern [docPattern...]`**: Glob patterns to match documentation files to translate.
+
+  > Example: `npx intlayer doc translate --doc-pattern "docs/**/*.md" "src/**/*.mdx"`
+
+- **`--excluded-glob-pattern [excludedGlobPattern...]`**: Glob patterns to exclude from translation.
+
+  > Example: `npx intlayer doc translate --excluded-glob-pattern "docs/internal/**"`
+
+- **`--skip-if-modified-before [skipIfModifiedBefore]`**: Skip the file if it has been modified before the given time.
+  - Can be an absolute time as "2025-12-05" (string or Date)
+  - Can be a relative time in ms `1 * 60 * 60 * 1000` (1 hour)
+  - This option check update time of the file using the `fs.stat` method. So it could be impacted by Git or other tools that modify the file.
+
+  > Example: `npx intlayer doc translate --skip-if-modified-before "2025-12-05"`
+
+- **`--skip-if-modified-after [skipIfModifiedAfter]`**: Skip the file if it has been modified within the given time.
+  - Can be an absolute time as "2025-12-05" (string or Date)
+  - Can be a relative time in ms `1 * 60 * 60 * 1000` (1 hour)
+  - This option check update time of the file using the `fs.stat` method. So it could be impacted by Git or other tools that modify the file.
+
+  > Example: `npx intlayer doc translate --skip-if-modified-after "2025-12-05"`
+
+- **`--skip-if-exists`**: Skip the file if it already exists.
+
+  > Example: `npx intlayer doc translate --skip-if-exists`
+
+**Entry output options:**
+
+- **`--locales [locales...]`**: Target locales to translate documentation to.
+
+  > Example: `npx intlayer doc translate --locales fr es de`
+
+- **`--base-locale [baseLocale]`**: Source locale to translate from.
+
+  > Example: `npx intlayer doc translate --base-locale en`
+
+**File processing options:**
+
+- **`--nb-simultaneous-file-processed [nbSimultaneousFileProcessed]`**: Number of files to process simultaneously for translation.
+
+  > Example: `npx intlayer doc translate --nb-simultaneous-file-processed 5`
+
+**AI options:**
+
+- **`--model [model]`**: The AI model to use for translation (e.g., `gpt-3.5-turbo`).
+- **`--provider [provider]`**: The AI provider to use for translation.
+- **`--temperature [temperature]`**: Temperature setting for the AI model.
+- **`--api-key [apiKey]`**: Provide your own API key for the AI service.
+- **`--application-context [applicationContext]`**: Provide additional context for the AI translation.
+- **`--custom-prompt [prompt]`**: Customize the base prompt used for translation. (Note: For most use cases, the `--custom-instructions` option is recommended instead as it provides better control over translation behavior.)
+
+  > Example: `npx intlayer doc translate --model deepseek-chat --provider deepseek --temperature 0.5 --api-key sk-1234567890 --application-context "My application is a cat store"`
+
+**Environment variables 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.
+- **`--no-cache`**: Disable the cache.
+
+  > Example: `npx intlayer doc translate --base-dir ./docs --env-file .env.production.local`
+
+**Log options:**
+
+- **`--verbose`**: Enable verbose logging for debugging. (default to true using CLI)
+
+  > Example: `npx intlayer doc translate --verbose`
+
+**Custom instructions options:**
+
+- **`--custom-instructions [customInstructions]`**: Custom instructions added to the prompt. Usefull to apply specific rules regarding formatting, urls translation, etc.
+  - Can be an absolute time as "2025-12-05" (string or Date)
+  - Can be a relative time in ms `1 * 60 * 60 * 1000` (1 hour)
+  - This option check update time of the file using the `fs.stat` method. So it could be impacted by Git or other tools that modify the file.
+
+  > Example: `npx intlayer doc translate --custom-instructions "Avoid translating urls, and keep the markdown format"`
+
+  > Example: `npx intlayer doc translate --custom-instructions "$(cat ./instructions.md)"`
+
+**Git options:**
+
+- **`--git-diff`**: Only run on dictionaries that includes changes from base (default `origin/main`) to 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 doc translate --git-diff --git-diff-base origin/main --git-diff-current HEAD`
+
+  > Example: `npx intlayer doc translate --uncommitted --unpushed --untracked`
+
+> Note that the output file path will be determined by replacing the following patterns
+>
+> - `/{{baseLocale}}/` by `/{{locale}}/` (Unix)
+> - `\{{baseLocale}}\` by `\{{locale}}\` (Windows)
+> - `_{{baseLocale}}.` by `_{{locale}}.`
+> - `{{baseLocale}}_` by `{{locale}}_`
+> - `.{{baseLocaleName}}.` by `.{{localeName}}.`
+>
+> If the pattern is not found, the output file will add the `.{{locale}}` at the extensions of the file. `./my/file.md` will be translated to `./my/file.fr.md` for the French locale.

package/docs/en/cli/editor.md

@@ -0,0 +1,28 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Editor Commands
+description: Learn how to use the Intlayer editor commands.
+keywords:
+  - Editor
+  - Visual Editor
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - editor
+---
+
+# Editor commands
+
+The `editor` command rewrap the `intlayer-editor` commands.
+
+> To be able to use the `editor` command, the `intlayer-editor` package must be installed. (See [Intlayer Visual Editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md))
+
+```json fileName="package.json"
+"scripts": {
+  "intlayer:editor:start": "npx intlayer editor start --with 'next dev --turbopack'"
+}
+```

package/docs/en/cli/fill.md

@@ -0,0 +1,130 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Fill Dictionaries
+description: Learn how to fill, audit, and translate your dictionaries using AI.
+keywords:
+  - Fill
+  - Audit
+  - Translate
+  - Dictionaries
+  - CLI
+  - Intlayer
+  - AI
+slugs:
+  - doc
+  - concept
+  - cli
+  - fill
+---
+
+# Fill / audit / translate dictionaries
+
+```bash
+npx intlayer fill
+```
+
+This command analyzes your content declaration files for potential issues such as missing translations, structural inconsistencies, or type mismatches. If it finds any problems, **intlayer fill** will propose or apply updates to keep your dictionaries consistent and complete.
+
+## Aliases:
+
+- `npx intlayer dictionaries fill`
+- `npx intlayer dictionary fill`
+- `npx intlayer dic fill`
+
+## Arguments:
+
+**Files list options:**
+
+- **`-f, --file [files...]`**: A list of specific content declaration files to audit. If not provided, all discovered `*.content.{ts,js,mjs,cjs,tsx,jsx,json}` based on your configuration file setup will be audited.
+
+  > Example: `npx intlayer dictionary fill -f src/home/app.content.ts`
+
+- **`-k, --keys [keys...]`**: Filter dictionaries based on keys. If not provided, all dictionaries will be audited.
+
+  > Example: `npx intlayer dictionary fill -k key1 key2`
+
+- **`--key [keys...]`**: Filter dictionaries based on keys (alias for --keys).
+
+  > Example: `npx intlayer dictionary fill --key key1 key2`
+
+- **`--excluded-keys [excludedKeys...]`**: Filter out dictionaries based on keys. If not provided, all dictionaries will be audited.
+
+  > Example: `npx intlayer dictionary fill --excluded-keys key1 key2`
+
+- **`--excluded-key [excludedKeys...]`**: Filter out dictionaries based on keys (alias for --excluded-keys).
+
+  > Example: `npx intlayer dictionary fill --excluded-key key1 key2`
+
+- **`--path-filter [pathFilters...]`**: Filter dictionaries based on glob pattern for file paths.
+
+  > Example: `npx intlayer dictionary fill --path-filter "src/home/**"`
+
+**Entry output options:**
+
+- **`--source-locale [sourceLocale]`**: The source locale to translate from. If not specified, the default locale from your configuration will be used.
+
+- **`--output-locales [outputLocales...]`**: Target locales to translate to. If not specified, all locales from your configuration will be used except the source locale.
+
+- **`--mode [mode]`**: Translation mode: `complete`, `review`. Default is `complete`. `complete` will fill all missing content, `review` will fill missing content and review existing keys.
+
+**Git options:**
+
+- **`--git-diff`**: Only run on dictionaries that includes changes from base (default `origin/main`) to 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 doc translate --git-diff --git-diff-base origin/main --git-diff-current HEAD`
+
+  > Example: `npx intlayer doc translate --uncommitted --unpushed --untracked`
+
+**AI options:**
+
+- **`--model [model]`**: The AI model to use for the translation (e.g., `gpt-3.5-turbo`).
+- **`--provider [provider]`**: The AI provider to use for the translation.
+- **`--temperature [temperature]`**: Temperature setting for the AI model.
+- **`--api-key [apiKey]`**: Provide your own API key for the AI service.
+- **`--custom-prompt [prompt]`**: Provide a custom prompt for your translation instructions.
+- **`--application-context [applicationContext]`**: Provide additional context for the AI translation.
+
+  > Example: `npx intlayer fill --model gpt-3.5-turbo --provider openai --temperature 0.5 --api-key sk-1234567890 --application-context "My application is a cat store"`
+
+**Environment variables options:**
+
+- **`--env`**: Specify the environment (e.g., `development`, `production`).
+- **`--env-file [envFile]`**: Provide a custom environment file to load variables from.
+
+  > Example: `npx intlayer fill --env-file .env.production.local`
+
+  > Example: `npx intlayer fill --env production`
+
+**Configuration options:**
+
+- **`--base-dir`**: Specify the base directory for the project.
+
+  > Example: `npx intlayer fill --base-dir ./src`
+
+- **`--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.
+
+- **`--skip-metadata`**: Skip filling missing metadata (description, title, tags) for dictionaries.
+
+**Log options:**
+
+- **`--verbose`**: Enable verbose logging for debugging. (default to true using CLI)
+
+## Example:
+
+```bash
+npx intlayer fill --file src/home/*.content.ts --source-locale en --output-locales fr es --model gpt-3.5-turbo
+```
+
+This command will translate content from English to French and Spanish for all content declaration files in the `src/home/` directory using the GPT-3.5 Turbo model.

package/docs/en/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
+  - Internationalization
+  - 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 `intlayer` package is already installed, the cli is automatically installed. You can skip this step.
+
+## intlayer-cli package
+
+`intlayer-cli` package intend to transpile your [intlayer declarations](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/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 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/configuration.md).
+
+## Run intlayer commands
+
+### Core Commands
+
+- **[Build Dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/build.md)** - Build your dictionaries from content declaration files
+- **[Watch Dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/watch.md)** - Watch for changes and automatically build dictionaries
+- **[Check CLI Version](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/version.md)** - Check the installed Intlayer CLI version
+
+### Dictionary Management
+
+- **[Push Dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/push.md)** - Push dictionaries to the Intlayer editor and CMS
+- **[Pull Dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/pull.md)** - Pull dictionaries from the Intlayer editor and CMS
+- **[Fill Dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/fill.md)** - Fill, audit, and translate dictionaries using AI
+- **[Test Missing Translations](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/test.md)** - Test and identify missing translations
+- **[List Content Declaration Files](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/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/cli/transform.md)** - Transform existing components to use Intlayer
+
+### Configuration
+
+- **[Manage Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/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/cli/doc-translate.md)** - Automatically translate documentation files using AI
+- **[Review Document](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/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/cli/editor.md)** - Use the Intlayer editor commands
+- **[Live Sync Commands](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/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/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/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/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's useful for getting 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/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 lets your app reflect CMS content changes at runtime. No rebuild or redeploy 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/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. (default to true using CLI)

package/docs/en/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 [intlayer editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md) is installed, you can also pull dictionaries from the editor. By this way, you can overwrite the content of your dictionaries for the need 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 news dictionaries will be saved in the `./intlayer-dictionaries` directory of the project. If a `filePath` fields 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 to true using CLI)
+
+## Example:
+
+```bash
+npx intlayer dictionary pull --newDictionariesPath ./my-dictionaries-dir/
+```