@intlayer/docs 5.5.8

package/en/intlayer_CMS.md

@@ -0,0 +1,334 @@
+# Intlayer Content Management System (CMS) Documentation
+
+<iframe title="Visual Editor + CMS for Your Web App: Intlayer Explained" class="m-auto aspect-[16/9] w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/UDDTnirwi_4?autoplay=0&amp;origin=http://intlayer.org&amp;controls=0&amp;rel=1"/>
+
+The Intlayer CMS is am Application that allows you to externalize your content of an Intlayer project.
+
+For that, Intlayer introduce the concept of 'distant dictionaries'.
+
+![Intlayer CMS Interface](https://github.com/aymericzip/intlayer/blob/main/docs/assets/CMS.png)
+
+## Understanding distant dictionaries
+
+Intlayer make a difference between 'local' and 'distant' dictionaries.
+
+- A 'local' dictionary is a dictionary that is declared in your Intlayer project. Such as the declaration file of a button, or your navigation bar. Externalizing your content do not make sense in this case because this content is not supposed to change often.
+
+- A 'distant' dictionary is a dictionary that is managed through the Intlayer CMS. It could be useful to allow your team to manage your content in direct on your website, and also aims to use A/B testing features and SEO automatic optimization.
+
+## Visual editor vs CMS
+
+The [Intlayer Visual](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_visual_editor.md) editor is a tool that allows you to manage your content in a visual editor for local dictionaries. Once a change is made, the content will be replaced in the code-base. That means that the application will be rebuilt and the page will be reloaded to display the new content.
+
+In contrast, the Intlayer CMS is a tool that allows you to manage your content in a visual editor for distant dictionaries. Once a change is made, the content will **not** impact your code-base. And the website will automatically display the changed content.
+
+## Integrating
+
+For more details on how to install the package, see the relevant section below:
+
+### Integrating with Next.js
+
+For integration with Next.js, refer to the [setup guide](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_with_nextjs_15.md).
+
+### Integrating with Create React App
+
+For integration with Create React App, refer to the [setup guide](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_with_create_react_app.md).
+
+### Integrating with Vite + React
+
+For integration with Vite + React, refer to the [setup guide](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_with_vite+react.md).
+
+## Configuration
+
+In your Intlayer configuration file, you can customize the CMS settings:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... other configuration settings
+  editor: {
+    /**
+     * Required
+     *
+     * The URL of the application.
+     * This is the URL targeted by the visual editor.
+     */
+    applicationURL: process.env.INTLAYER_APPLICATION_URL,
+
+    /**
+     * Required
+     *
+     * Client ID and client secret are required to enable the editor.
+     * They allow the identify the user who is editing the content.
+     * They can be obtained by creating a new client in the Intlayer Dashboard - Projects (https://intlayer.org/dashboard/projects).
+     * clientId: process.env.INTLAYER_CLIENT_ID,
+     * clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+     */
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+
+    /**
+     * Optional
+     *
+     * In the case you are self-hosting the Intlayer CMS, you can set the URL of the CMS.
+     *
+     * The URL of the Intlayer CMS.
+     * By default, it is set to https://intlayer.org
+     */
+    cmsURL: process.env.INTLAYER_CMS_URL,
+
+    /**
+     * Optional
+     *
+     * In the case you are self-hosting the Intlayer CMS, you can set the URL of the backend.
+     *
+     * The URL of the Intlayer CMS.
+     * By default, it is set to https://back.intlayer.org
+     */
+    backendURL: process.env.INTLAYER_BACKEND_URL,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ... other configuration settings
+  editor: {
+    /**
+     * Required
+     *
+     * The URL of the application.
+     * This is the URL targeted by the visual editor.
+     */
+    applicationURL: process.env.INTLAYER_APPLICATION_URL,
+
+    /**
+     * Required
+     *
+     * Client ID and client secret are required to enable the editor.
+     * They allow the identify the user who is editing the content.
+     * They can be obtained by creating a new client in the Intlayer Dashboard - Projects (https://intlayer.org/dashboard/projects).
+     * clientId: process.env.INTLAYER_CLIENT_ID,
+     * clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+     */
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+
+    /**
+     * Optional
+     *
+     * In the case you are self-hosting the Intlayer CMS, you can set the URL of the CMS.
+     *
+     * The URL of the Intlayer CMS.
+     * By default, it is set to https://intlayer.org
+     */
+    cmsURL: process.env.INTLAYER_CMS_URL,
+
+    /**
+     * Optional
+     *
+     * In the case you are self-hosting the Intlayer CMS, you can set the URL of the backend.
+     *
+     * The URL of the Intlayer CMS.
+     * By default, it is set to https://back.intlayer.org
+     */
+    backendURL: process.env.INTLAYER_BACKEND_URL,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ... other configuration settings
+  editor: {
+    /**
+     * Required
+     *
+     * The URL of the application.
+     * This is the URL targeted by the visual editor.
+     */
+    applicationURL: process.env.INTLAYER_APPLICATION_URL,
+
+    /**
+     * Required
+     *
+     * Client ID and client secret are required to enable the editor.
+     * They allow the identify the user who is editing the content.
+     * They can be obtained by creating a new client in the Intlayer Dashboard - Projects (https://intlayer.org/dashboard/projects).
+     * clientId: process.env.INTLAYER_CLIENT_ID,
+     * clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+     */
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+
+    /**
+     * Optional
+     *
+     * In the case you are self-hosting the Intlayer CMS, you can set the URL of the CMS.
+     *
+     * The URL of the Intlayer CMS.
+     * By default, it is set to https://intlayer.org
+     */
+    cmsURL: process.env.INTLAYER_CMS_URL,
+
+    /**
+     * Optional
+     *
+     * In the case you are self-hosting the Intlayer CMS, you can set the URL of the backend.
+     *
+     * The URL of the Intlayer CMS.
+     * By default, it is set to https://back.intlayer.org
+     */
+    backendURL: process.env.INTLAYER_BACKEND_URL,
+  },
+};
+
+module.exports = config;
+```
+
+> If you don't have a client ID and client secret, you can obtain them by creating a new client in the [Intlayer Dashboard - Projects](https://intlayer.org/dashboard/projects).
+
+> To see all available parameters, refer to the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/configuration.md).
+
+## Using the CMS
+
+### Push your configuration
+
+To configure the Intlayer CMS, you can use the [intlayer CLI](https://github.com/aymericzip/intlayer/tree/main/docs/en/intlayer_cli.md) commands.
+
+```bash
+npx intlayer config push
+```
+
+> If you use environment variables in your `intlayer.config.ts` configuration file, you can specify the desired environment using the `--env` argument:
+
+```bash
+npx intlayer config push --env production
+```
+
+This command uploads your configuration to the Intlayer CMS.
+
+### Push a dictionary
+
+To transform your locale dictionaries in a distant dictionary, you can use the [intlayer CLI](https://github.com/aymericzip/intlayer/tree/main/docs/en/intlayer_cli.md) commands.
+
+```bash
+npx intlayer dictionary push -d my-first-dictionary-key
+```
+
+> If you use environment variables in your `intlayer.config.ts` configuration file, you can specify the desired environment using the `--env` argument:
+
+```bash
+npx intlayer dictionary push -d my-first-dictionary-key --env production
+```
+
+This command uploads your initial content dictionaries, making them available for asynchronous fetching and editing through the Intlayer platform.
+
+### Edit the dictionary
+
+Then you will be able to see and manage your dictionary in the [Intlayer CMS](https://intlayer.org/dashboard/content).
+
+## Hot reloading
+
+The Intlayer CMS is able to hot reload the dictionaries when a change is detected.
+
+Without the hot reloading, a new build of the application will be needed to display the new content.
+
+By activating the [`hotReload`](https://intlayer.org/doc/concept/configuration#editor-configuration) configuration, the application will automatically replace the updated content when it is detected.
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... other configuration settings
+  editor: {
+    // ... other configuration settings
+
+    /**
+     * Indicates if the application should hot reload the locale configurations when a change is detected.
+     * For example, when a new dictionary is added or updated, the application will update the content tu display in the page.
+     *
+     * Because the hot reloading needs an continuous connection to the server, it is only available for clients of the `enterprise` plan
+     *
+     * Default: false
+     */
+    hotReload: true,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ... other configuration settings
+  editor: {
+    // ... other configuration settings
+
+    /**
+     * Indicates if the application should hot reload the locale configurations when a change is detected.
+     * For example, when a new dictionary is added or updated, the application will update the content tu display in the page.
+     *
+     * Because the hot reloading needs an continuous connection to the server, it is only available for clients of the `enterprise` plan
+     *
+     * Default: false
+     */
+    hotReload: true,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ... other configuration settings
+  editor: {
+    // ... other configuration settings
+
+    /**
+     * Indicates if the application should hot reload the locale configurations when a change is detected.
+     * For example, when a new dictionary is added or updated, the application will update the content tu display in the page.
+     *
+     * Because the hot reloading needs an continuous connection to the server, it is only available for clients of the `enterprise` plan
+     *
+     * Default: false
+     */
+    hotReload: true,
+  },
+};
+
+module.exports = config;
+```
+
+The hot reloading replace the content in both server and client side.
+
+- On the server side, you should ensure that the application process has the write access to the `.intlayer/dictionaries` directory.
+- On the client side, the hot reloading allow the application to hot reload the content in the browser, without needing to reload the page. However, this feature is only available for clients components.
+
+> Because the hot reloading needs an continuous connection to the server using an `EventListener`, it is only available for clients of the `enterprise` plan.
+
+## Debug
+
+If you encounter any issues with the CMS, check the following:
+
+- The application is running.
+
+- The [`editor`](https://intlayer.org/doc/concept/configuration#editor-configuration) configuration are correctly set in your Intlayer configuration file.
+
+  - Required fields:
+    - The application URL should match the one you set in the editor configuration (`applicationURL`).
+    - The CMS URL
+
+- Ensure that the project configuration was pushed to the Intlayer CMS.
+
+- The visual editor use an iframe to display your website. Ensure that the Content Security Policy (CSP) of your website allows the CMS url as `frame-ancestors` ('https://intlayer.org' by default). Check the editor console for any error.

package/en/intlayer_cli.md

@@ -0,0 +1,309 @@
+# Intlayer CLI
+
+## 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/en/dictionary/get_started.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/en/configuration.md).
+
+## Run intlayer commands
+
+### Build dictionaries
+
+To build your dictionaries, you can run the commands:
+
+```bash
+npx intlayer build
+```
+
+or in watch mode
+
+```bash
+npx intlayer build --watch
+```
+
+This command will find your declaration content files as default as `./src/**/*.content.{ts|js|mjs|cjs|json|tsx|jsx}`. And build the dictionaries in the `.intlayer` directory.
+
+##### Aliases:
+
+- `npx intlayer dictionaries build`
+- `npx intlayer dictionary build`
+- `npx intlayer dic build`
+
+### Push dictionaries
+
+```bash
+npx intlayer dictionary push
+```
+
+If [intlayer editor](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_visual_editor.md) is installed, you can also push dictionaries to the editor. This command will allow to make the dictionaries available to [the editor](https://intlayer.org/dashboard). By this way, you can share your dictionaries with your team and edit your content without editing the code of your application.
+
+##### Aliases:
+
+- `npx intlayer dictionaries push`
+- `npx intlayer dictionary push`
+- `npx intlayer dic push`
+
+##### Arguments:
+
+- `-d`, `--dictionaries`: ids of the dictionaries to pull. If not specified, all dictionaries will be pushed.
+  > Example: `npx intlayer dictionary push -d my-dictionary-id my-other-dictionary-id`
+- `-r`, `--deleteLocaleDictionary`: Skip the question that asking to delete the locales directories once the dictionaries are pushed, and remove them. By default, is the dictionary is defined locally, it will overwrite distant dictionaries content.
+  > Example: `npx intlayer dictionary push -r`
+- `-k`, `--keepLocaleDictionary`: Skip the question that asking to delete the locales directories once the dictionaries are pushed, and keep them. By default, is the dictionary is defined locally, it will overwrite distant dictionaries content.
+  > Example: `npx intlayer dictionary push -k`
+- `--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.
+- `--verbose`: Enable verbose logging for debugging.
+- `--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.
+
+### Pull distant dictionaries
+
+```bash
+npx intlayer pull
+```
+
+If [intlayer editor](https://github.com/aymericzip/intlayer/blob/main/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:
+
+- `-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`
+- `--newDictionariesPath` : 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.
+- `--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.
+- `--verbose`: Enable verbose logging for debugging.
+
+##### Example:
+
+```bash
+npx intlayer dictionary pull --newDictionariesPath ./my-dictionaries-dir/
+```
+
+### 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:
+
+- `-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}` files will be audited.
+
+- `--exclude [excludedGlobs...]`
+  Globs pattern to exclude from the audit (e.g. `--exclude "src/test/**"`).
+
+- `--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', or 'missing-only'. Default is 'missing-only'.
+
+- `--git-diff`
+  Filters 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`
+  Filters dictionaries that includes uncommitted changes.
+
+- `--unpushed`
+  Filters dictionaries that includes unpushed changes.
+
+- `--untracked`
+  Filters dictionaries that includes untracked files.
+
+- `--keys [keys...]`
+  Filter dictionaries based on specified keys.
+
+- `--excluded-keys [excludedKeys...]`
+  Filter out dictionaries based on specified keys.
+
+- `--path-filter [pathFilters...]`
+  Filter dictionaries based on glob pattern for file paths.
+
+- `--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.
+
+- `--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.
+
+- `--verbose`
+  Enable verbose logging for debugging.
+
+##### 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.
+
+### Manage Configuration
+
+#### Get Configuration
+
+The `configuration get` command retrieves the current configuration for Intlayer, particularly the locale settings. This is useful for verifying your setup.
+
+```bash
+npx intlayer configuration get
+```
+
+##### Aliases:
+
+- `npx intlayer config get`
+- `npx intlayer conf get`
+
+##### Arguments:
+
+- **`--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.
+- **`--verbose`**: Enable verbose logging for debugging.
+
+#### Push Configuration
+
+The `configuration push` command uploads your configuration to the Intlayer CMS and editor. This step is necessary to enable the use of distant dictionaries in the Intlayer Visual Editor.
+
+```bash
+npx intlayer configuration push
+```
+
+##### Aliases:
+
+- `npx intlayer config push`
+- `npx intlayer conf push`
+
+##### Arguments:
+
+- **`--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.
+- **`--verbose`**: Enable verbose logging for debugging.
+
+By pushing the configuration, your project is fully integrated with the Intlayer CMS, enabling seamless dictionary management across teams.
+
+## 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"
+}
+```
+
+## Debug intlayer command
+
+### 1. **Ensure you're using the latest version**
+
+Run:
+
+```bash
+npx intlayer --version                  # current locale intlayer version
+npx intlayer@latest --version           # current latest intlayer version
+```
+
+### 2. **Check if the command is registered**
+
+You can check with:
+
+```bash
+npx intlayer --help                     # Shows the list of available commands and usage information
+npx intlayer dictionary build --help    # Shows the list of available options for a command
+```
+
+### 3. **Restart your terminal**
+
+Sometimes a terminal restart is needed to recognize new commands.
+
+### 4. **Clear npx cache (if you're stuck with an older version)**
+
+```bash
+npx clear-npx-cache
+```