@intlayer/docs 5.8.1 → 6.0.0-canary.1

package/docs/en-GB/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2025-06-29
+updatedAt: 2025-09-16
 title: Configuration
 description: Learn how to configure Intlayer for your application. Understand the various settings and options available to customise Intlayer to your needs.
 keywords:
@@ -46,6 +46,7 @@ const config: IntlayerConfig = {
     locales: [Locales.ENGLISH],
   },
   content: {
+    autoFill: "./{{fileName}}.content.json",
     contentDir: ["src", "../ui-library"],
   },
   middleware: {
@@ -70,6 +71,7 @@ export default config;
 const { Locales } = require("intlayer");
 
 /** @type {import('intlayer').IntlayerConfig} */
+// Configuration object for Intlayer
 const config = {
   internationalization: {
     locales: [Locales.ENGLISH],
@@ -101,11 +103,21 @@ module.exports = config;
     "locales": ["en"],
   },
   "content": {
-    "typesDir": "content/types",
+    "contentDir": ["src", "../ui-library"],
   },
   "middleware": {
     "noPrefix": false,
   },
+  "editor": {
+    "applicationURL": "https://example.com",
+  },
+  "ai": {
+    "apiKey": "XXXX",
+    "applicationContext": "This is a test application",
+  },
+  "build": {
+    "importMode": "dynamic",
+  },
 }
 ```
 
@@ -124,7 +136,6 @@ Defines settings related to internationalisation, including available locales an
 #### Properties
 
 - **locales**:
-
   - _Type_: `string[]`
   - _Default_: `['en']`
   - _Description_: The list of supported locales in the application.
@@ -138,16 +149,14 @@ Defines settings related to internationalisation, including available locales an
   - _Note_: If empty, all locales are required in `strict` mode.
   - _Note_: Ensure required locales are also defined in the `locales` field.
 - **strictMode**:
-
   - _Type_: `string`
   - _Default_: `inclusive`
-  - _Description_: Ensure strong implementations of internationalised content using TypeScript.
+  - _Description_: Ensures strong implementations of internationalised content using TypeScript.
   - _Note_: If set to "strict", the translation `t` function will require each declared locale to be defined. If one locale is missing, or if a locale is not declared in your config, it will throw an error.
-  - _Note_: If set to "inclusive", the translation `t` function will require each declared locale to be defined. If one locale is missing, it will throw a warning. But will accept if a locale is not declared in your config, but exists.
+  - _Note_: If set to "inclusive", the translation `t` function will require each declared locale to be defined. If one locale is missing, it will throw a warning. But it will accept if a locale is not declared in your config, but exists.
   - _Note_: If set to "loose", the translation `t` function will accept any existing locale.
 
 - **defaultLocale**:
-
   - _Type_: `string`
   - _Default_: `'en'`
   - _Description_: The default locale used as a fallback if the requested locale is not found.
@@ -163,7 +172,6 @@ Defines settings related to the integrated editor, including server port and act
 #### Properties
 
 - **applicationURL**:
-
   - _Type_: `string`
   - _Default_: `http://localhost:3000`
   - _Description_: The URL of the application. Used to restrict the origin of the editor for security reasons.
@@ -174,23 +182,20 @@ Defines settings related to the integrated editor, including server port and act
   - _Note_: The URL of the application. Used to restrict the origin of the editor for security reasons. If set to `'*'`, the editor is accessible from any origin.
 
 - **port**:
-
   - _Type_: `number`
   - _Default_: `8000`
   - _Description_: The port used by the visual editor server.
 
 - **editorURL**:
-
   - _Type_: `string`
   - _Default_: `'http://localhost:8000'`
   - _Description_: The URL of the editor server. Used to restrict the origin of the editor for security reasons.
     - `'http://localhost:3000'`
     - `'https://example.com'`
     - `process.env.INTLAYER_EDITOR_URL`
-  - _Note_: The URL of the editor server to reach from the application. Used to restrict the origins that can interact with the application for security reasons. If set to `'*'`, the editor is accessible from any origin. Should be set if port is changed, or if the editor is hosted on a different domain.
+  - _Note_: The URL of the editor server to reach from the application. Used to restrict the origins that can interact with the application for security reasons. If set to `'*'`, the editor is accessible from any origin. Should be set if the port is changed, or if the editor is hosted on a different domain.
 
 - **cmsURL**:
-
   - _Type_: `string`
   - _Default_: `'https://intlayer.org'`
   - _Description_: The URL of the Intlayer CMS.
@@ -198,14 +203,12 @@ Defines settings related to the integrated editor, including server port and act
   - _Note_: The URL of the Intlayer CMS.
 
 - **backendURL**:
-
   - _Type_: `string`
   - _Default_: `https://back.intlayer.org`
   - _Description_: The URL of the backend server.
   - _Example_: `http://localhost:4000`
 
 - **enabled**:
-
   - _Type_: `boolean`
   - _Default_: `true`
   - _Description_: Indicates if the application interacts with the visual editor.
@@ -213,35 +216,46 @@ Defines settings related to the integrated editor, including server port and act
   - _Note_: If true, the editor will be able to interact with the application. If false, the editor will not be able to interact with the application. In any case, the editor can only be enabled by the visual editor. Disabling the editor for specific environments is a way to enforce security.
 
 - **clientId**:
-
   - _Type_: `string` | `undefined`
   - _Default_: `undefined`
-  - _Description_: clientId and clientSecret allow the intlayer packages to authenticate with the backend using oAuth2 authentication. An access token is used to authenticate the user related to the project. To get an access token, go to https://intlayer.org/dashboard/project and create an account.
+  - _Description_: clientId and clientSecret allow the intlayer packages to authenticate with the backend using oAuth2 authentication. An access token is used to authenticate the user related to the project. To obtain an access token, visit https://intlayer.org/dashboard/project and create an account.
   - _Example_: `true`
-  - _Note_: Important: The clientId and clientSecret should be kept secret and not shared publicly. Please ensure to keep them in a secure location, such as environment variables.
+  - _Note_: Important: The clientId and clientSecret should be kept confidential and not shared publicly. Please ensure they are stored securely, such as in environment variables.
 
 - **clientSecret**:
-
   - _Type_: `string` | `undefined`
   - _Default_: `undefined`
-  - _Description_: clientId and clientSecret allow the intlayer packages to authenticate with the backend using oAuth2 authentication. An access token is used to authenticate the user related to the project. To get an access token, go to https://intlayer.org/dashboard/project and create an account.
+  - _Description_: clientId and clientSecret allow the intlayer packages to authenticate with the backend using oAuth2 authentication. An access token is used to authenticate the user related to the project. To obtain an access token, visit https://intlayer.org/dashboard/project and create an account.
   - _Example_: `true`
-  - _Note_: Important: The clientId and clientSecret should be kept secret and not shared publicly. Please ensure to keep them in a secure location, such as environment variables.
+  - _Note_: Important: The clientId and clientSecret should be kept confidential and not shared publicly. Please ensure they are stored securely, such as in environment variables.
 
-- **hotReload**:
+- **dictionaryPriorityStrategy**:
+  - _Type_: `string`
+  - _Default_: `'local_first'`
+  - _Description_: The strategy to prioritise dictionaries in the case of both local and distant dictionaries being present. If set to `'distant_first'`, the application will prioritise distant dictionaries over local dictionaries. If set to `'local_first'`, the application will prioritise local dictionaries over distant dictionaries.
+  - _Example_: `'distant_first'`
 
+- **liveSync**:
   - _Type_: `boolean`
   - _Default_: `false`
-  - _Description_: Indicates if the application should hot reload the locale configurations when a change is detected.
+  - _Description_: Indicates if the application server should hot reload the content of the application when a change is detected on the CMS / Visual Editor / Backend.
   - _Example_: `true`
   - _Note_: For example, when a new dictionary is added or updated, the application will update the content to display on the page.
-  - _Note_: Because hot reloading requires a continuous connection to the server, it is only available for clients of the `enterprise` plan.
+  - _Note_: Live sync needs to externalise the content of the application to another server. This means that it can slightly impact the performance of the application. To limit this, we recommend hosting the application and the live sync server on the same machine. Also, the combination of live sync and `optimize` can generate a considerable number of requests to the live sync server. Depending on your infrastructure, we recommend testing both options and their combination.
 
-- **dictionaryPriorityStrategy**:
+- **liveSyncPort**:
+  - _Type_: `number`
+  - _Default_: `4000`
+  - _Description_: The port of the live sync server.
+  - _Example_: `4000`
+  - _Note_: The port of the live sync server.
+
+- **liveSyncURL**:
   - _Type_: `string`
-  - _Default_: `'local_first'`
-  - _Description_: The strategy to prioritise dictionaries in the case of both local and distant dictionaries being present. If set to `'distant_first'`, the application will prioritise distant dictionaries over local dictionaries. If set to `'local_first'`, the application will prioritise local dictionaries over distant dictionaries.
-  - _Example_: `'distant_first'`
+  - _Default_: `'http://localhost:{liveSyncPort}'`
+  - _Description_: The URL of the live sync server.
+  - _Example_: `'https://example.com'`
+  - _Note_: Points to localhost by default but can be changed to any URL in the case of a remote live sync server.
 
 ### Middleware Configuration
 
@@ -250,7 +264,6 @@ Settings that control middleware behaviour, including how the application handle
 #### Properties
 
 - **headerName**:
-
   - _Type_: `string`
   - _Default_: `'x-intlayer-locale'`
   - _Description_: The name of the HTTP header used to determine the locale.
@@ -258,7 +271,6 @@ Settings that control middleware behaviour, including how the application handle
   - _Note_: This is useful for API-based locale determination.
 
 - **cookieName**:
-
   - _Type_: `string`
   - _Default_: `'intlayer-locale'`
   - _Description_: The name of the cookie used to store the locale.
@@ -266,7 +278,6 @@ Settings that control middleware behaviour, including how the application handle
   - _Note_: Used to persist the locale across sessions.
 
 - **prefixDefault**:
-
   - _Type_: `boolean`
   - _Default_: `false`
   - _Description_: Whether to include the default locale in the URL.
@@ -276,7 +287,6 @@ Settings that control middleware behaviour, including how the application handle
     - If `false` and `defaultLocale = 'en'`: path = `/dashboard` or `/fr/dashboard`
 
 - **basePath**:
-
   - _Type_: `string`
   - _Default_: `''`
   - _Description_: The base path for the application URLs.
@@ -288,7 +298,6 @@ Settings that control middleware behaviour, including how the application handle
     - If the base path is not set, the URL will be `https://example.com/en`
 
 - **serverSetCookie**:
-
   - _Type_: `string`
   - _Default_: `'always'`
   - _Description_: Rule for setting the locale cookie on the server.
@@ -297,7 +306,6 @@ Settings that control middleware behaviour, including how the application handle
   - _Note_: Controls whether the locale cookie is set on every request or never.
 
 - **noPrefix**:
-
   - _Type_: `boolean`
   - _Default_: `false`
   - _Description_: Whether to omit the locale prefix from URLs.
@@ -310,7 +318,6 @@ Settings that control middleware behaviour, including how the application handle
       - If `noPrefix = true`: URL will be `https://example.com`
 
 - **detectLocaleOnPrefetchNoPrefix**:
-
   - _Type_: `boolean`
   - _Default_: `false`
   - _Description_: Controls whether locale detection occurs during Next.js prefetch requests.
@@ -342,14 +349,24 @@ Settings related to content handling within the application, including directory
 
 #### Properties
 
-- **watch**:
+- **autoFill**:
+  - _Type_: `boolean | string | { [key in Locales]?: string }`
+  - _Default_: `undefined`
+  - _Description_: Indicates how the content should be automatically filled using AI. Can be declared globally in the `intlayer.config.ts` file.
+  - _Example_: true
+  - _Example_: `'./{{fileName}}.content.json'`
+  - _Example_: `{ fr: './{{fileName}}.fr.content.json', es: './{{fileName}}.es.content.json' }`
+  - _Note_: The auto fill configuration. It can be:
+    - boolean: Enable auto fill for all locales
+    - string: Path to a single file or template with variables
+    - object: Per-locale file paths
 
+- **watch**:
   - _Type_: `boolean`
   - _Default_: `process.env.NODE_ENV === 'development'`
   - _Description_: Indicates if Intlayer should watch for changes in the content declaration files in the app to rebuild the related dictionaries.
 
 - **fileExtensions**:
-
   - _Type_: `string[]`
   - _Default_: `['.content.ts', '.content.js', '.content.cjs', '.content.mjs', '.content.json', '.content.tsx', '.content.jsx']`
   - _Description_: File extensions to look for when building dictionaries.
@@ -357,7 +374,6 @@ Settings related to content handling within the application, including directory
   - _Note_: Customising file extensions can help avoid conflicts.
 
 - **baseDir**:
-
   - _Type_: `string`
   - _Default_: `process.cwd()`
   - _Description_: The base directory for the project.
@@ -365,48 +381,41 @@ Settings related to content handling within the application, including directory
   - _Note_: This is used to resolve all Intlayer-related directories.
 
 - **dictionaryOutput**:
-
   - _Type_: `string[]`
   - _Default_: `['intlayer']`
   - _Description_: The type of dictionary output to use, e.g., `'intlayer'` or `'i18next'`.
 
 - **contentDir**:
-
   - _Type_: `string[]`
-  - _Default_: `['src']`
+  - _Default_: `['.']`
   - _Example_: `['src', '../../ui-library', require.resolve("@my-package/content")]`
   - _Description_: The directory path where content is stored.
 
 - **dictionariesDir**:
-
   - _Type_: `string`
   - _Default_: `'.intlayer/dictionaries'`
   - _Description_: The directory path for storing intermediate or output results.
 
 - **moduleAugmentationDir**:
-
   - _Type_: `string`
   - _Default_: `'.intlayer/types'`
   - _Description_: Directory for module augmentation, allowing better IDE suggestions and type checking.
   - _Example_: `'intlayer-types'`
-  - _Note_: Be sure to include this in `tsconfig.json`.
+  - _Note_: Ensure this is included in `tsconfig.json`.
 
 - **unmergedDictionariesDir**:
-
   - _Type_: `string`
   - _Default_: `'.intlayer/unmerged_dictionary'`
   - _Description_: The directory for storing unmerged dictionaries.
   - _Example_: `'translations'`
 
 - **dictionariesDir**:
-
   - _Type_: `string`
   - _Default_: `'.intlayer/dictionary'`
   - _Description_: The directory for storing localisation dictionaries.
   - _Example_: `'translations'`
 
 - **i18nextResourcesDir**:
-
   - _Type_: `string`
   - _Default_: `'i18next_dictionary'`
   - _Description_: The directory for storing i18n dictionaries.
@@ -414,14 +423,12 @@ Settings related to content handling within the application, including directory
   - _Note_: Ensure this directory is configured for the i18next output type.
 
 - **typesDir**:
-
   - _Type_: `string`
   - _Default_: `'types'`
   - _Description_: The directory for storing dictionary types.
   - _Example_: `'intlayer-types'`
 
 - **mainDir**:
-
   - _Type_: `string`
   - _Default_: `'main'`
   - _Description_: The directory where main application files are stored.
@@ -431,7 +438,7 @@ Settings related to content handling within the application, including directory
   - _Type_: `string[]`
   - _Default_: `['node_modules']`
   - _Description_: Directories excluded from content search.
-  - _Note_: This setting is not yet used, but is planned for future implementation.
+  - _Note_: This setting is not yet used, but planned for future implementation.
 
 ### Logger Configuration
 
@@ -440,7 +447,6 @@ Settings that control the logger, including the prefix to use.
 #### Properties
 
 - **mode**:
-
   - _Type_: `string`
   - _Default_: `default`
   - _Description_: Indicates the mode of the logger.
@@ -449,7 +455,6 @@ Settings that control the logger, including the prefix to use.
   - _Note_: The mode of the logger. Verbose mode will log more information, but can be used for debugging purposes. Disabled mode will disable the logger.
 
 - **prefix**:
-
   - _Type_: `string`
   - _Default_: `'[intlayer] '`
   - _Description_: The prefix of the logger.
@@ -459,10 +464,12 @@ Settings that control the logger, including the prefix to use.
 ### AI Configuration
 
 Settings that control the AI features of Intlayer, including the provider, model, and API key.
-This configuration is optional if you're registered on the [Intlayer Dashboard](https://intlayer.org/dashboard/project) using an access key. Intlayer will automatically manage the most efficient and cost-effective AI solution for your needs. Using the default options ensures better long-term maintainability as Intlayer continuously updates to use the most relevant models.
 
-If you prefer to use your own API key or specific model, you can define your custom AI configuration.  
-This AI configuration will be used globally across your Intlayer environment. CLI commands will use these settings as defaults for the commands (e.g. `fill`), as well as the SDK, Visual Editor, and CMS. You can override these default values for specific use cases using command parameters.  
+This configuration is optional if you are registered on the [Intlayer Dashboard](https://intlayer.org/dashboard/project) using an access key. Intlayer will automatically manage the most efficient and cost-effective AI solution for your needs. Using the default options ensures better long-term maintainability as Intlayer continuously updates to use the most relevant models.
+
+If you prefer to use your own API key or specific model, you can define your custom AI configuration.
+This AI configuration will be used globally across your Intlayer environment. CLI commands will use these settings as defaults for the commands (e.g. `fill`), as well as the SDK, Visual Editor, and CMS. You can override these default values for specific use cases using command parameters.
+
 Intlayer supports multiple AI providers for enhanced flexibility and choice. Currently supported providers are:
 
 - **OpenAI** (default)
@@ -475,7 +482,6 @@ Intlayer supports multiple AI providers for enhanced flexibility and choice. Cur
 #### Properties
 
 - **provider**:
-
   - _Type_: `string`
   - _Default_: `'openai'`
   - _Description_: The provider to use for the AI features of Intlayer.
@@ -484,7 +490,6 @@ Intlayer supports multiple AI providers for enhanced flexibility and choice. Cur
   - _Note_: Different providers may require different API keys and have different pricing models.
 
 - **model**:
-
   - _Type_: `string`
   - _Default_: None
   - _Description_: The model to use for the AI features of Intlayer.
@@ -492,7 +497,6 @@ Intlayer supports multiple AI providers for enhanced flexibility and choice. Cur
   - _Note_: The specific model to use varies by provider.
 
 - **temperature**:
-
   - _Type_: `number`
   - _Default_: None
   - _Description_: The temperature controls the randomness of the AI's responses.
@@ -500,17 +504,16 @@ Intlayer supports multiple AI providers for enhanced flexibility and choice. Cur
   - _Note_: A higher temperature will make the AI more creative and less predictable.
 
 - **apiKey**:
-
   - _Type_: `string`
   - _Default_: None
   - _Description_: Your API key for the selected provider.
   - _Example_: `process.env.OPENAI_API_KEY`
-  - _Note_: Important: API keys should be kept secret and not shared publicly. Please ensure to keep them in a secure location, such as environment variables.
+  - _Note_: Important: API keys should be kept confidential and not shared publicly. Please ensure they are stored securely, such as in environment variables.
 
 - **applicationContext**:
   - _Type_: `string`
   - _Default_: None
-  - _Description_: Provides additional context about your application to the AI model, helping it generate more accurate and contextually appropriate translations. This can include information about your app's domain, target audience, tone, or specific terminology.
+  - _Description_: Provides additional context about your application to the AI model, assisting it in generating more accurate and contextually appropriate translations. This can include information about your app's domain, target audience, tone, or specific terminology.
 
 ### Build Configuration
 
@@ -525,33 +528,32 @@ Build options apply to the `@intlayer/babel` and `@intlayer/swc` plugins.
 #### Properties
 
 - **optimize**:
-
   - _Type_: `boolean`
   - _Default_: `process.env.NODE_ENV === 'production'`
   - _Description_: Controls whether the build should be optimised.
   - _Example_: `true`
-  - _Note_: When enabled, Intlayer will replace all calls of dictionaries to optimise chunking. That way the final bundle will import only the dictionaries that are used. All imports will stay as static import to avoid async processing when loading the dictionaries.
+  - _Note_: When enabled, Intlayer will replace all calls of dictionaries to optimise chunking. That way the final bundle will import only the dictionaries that are used. All imports will remain as static imports to avoid async processing when loading the dictionaries.
   - _Note_: Intlayer will replace all calls of `useIntlayer` with the defined mode by the `importMode` option and `getIntlayer` with `getDictionary`.
   - _Note_: This option relies on the `@intlayer/babel` and `@intlayer/swc` plugins.
   - _Note_: Ensure all keys are declared statically in the `useIntlayer` calls. e.g. `useIntlayer('navbar')`.
 
 - **importMode**:
-
-  - _Type_: `'static' | 'dynamic' | 'async'`
+  - _Type_: `'static' | 'dynamic' | 'live'`
   - _Default_: `'static'`
   - _Description_: Controls how dictionaries are imported.
   - _Example_: `'dynamic'`
   - _Note_: Available modes:
     - "static": Dictionaries are imported statically. Replaces `useIntlayer` with `useDictionary`.
     - "dynamic": Dictionaries are imported dynamically using Suspense. Replaces `useIntlayer` with `useDictionaryDynamic`.
-    - "async": Dictionaries are imported dynamically asynchronously. Replaces `useIntlayer` with `await useDictionaryAsync`.
-  - _Note_: Dynamic imports rely on Suspense and may slightly impact rendering performance.
-  - _Note_: If disabled all locales will be loaded at once, even if they are not used.
+    - "live": Dictionaries are fetched dynamically using the live sync API. Replaces `useIntlayer` with `useDictionaryFetch`.
+  - _Note_: Dynamic imports rely on Suspense and may slightly affect rendering performance.
+  - _Note_: If disabled, all locales will be loaded at once, even if they are not used.
   - _Note_: This option relies on the `@intlayer/babel` and `@intlayer/swc` plugins.
-  - _Note_: Ensure all keys are declared statically in the `useIntlayer` calls. e.g. `useIntlayer('navbar')`.
+  - _Note_: Ensure all keys are declared statically in the `useIntlayer` calls, e.g. `useIntlayer('navbar')`.
   - _Note_: This option will be ignored if `optimize` is disabled.
-  - _Note_: In most cases, `"dynamic"` will be used for React applications, `"async"` for Vue.js applications.
-  - _Note_: This option will not impact the `getIntlayer`, `getDictionary`, `useDictionary`, `useDictionaryAsync` and `useDictionaryDynamic` functions.
+  - _Note_: If set to "live", only the dictionaries that include remote content and are flagged as "live" will be transformed into live mode. Others will be imported dynamically as "dynamic" mode to optimise the number of fetch queries and load performance.
+  - _Note_: Live mode will use the live sync API to fetch the dictionaries. If the API call fails, the dictionaries will be imported dynamically as "dynamic" mode.
+  - _Note_: This option will not affect the `getIntlayer`, `getDictionary`, `useDictionary`, `useDictionaryAsync` and `useDictionaryDynamic` functions.
 
 - **traversePattern**:
   - _Type_: `string[]`
@@ -564,4 +566,10 @@ Build options apply to the `@intlayer/babel` and `@intlayer/swc` plugins.
 
 ## Doc History
 
-- 5.5.11 - 2025-06-29: Add `docs` commands
+| Version | Date       | Changes                                                                                   |
+| ------- | ---------- | ----------------------------------------------------------------------------------------- |
+| 6.0.0   | 2025-09-16 | Add `live` import mode                                                                    |
+| 6.0.0   | 2025-09-04 | Replace `hotReload` field with `liveSync` and add `liveSyncPort` and `liveSyncURL` fields |
+| 5.6.1   | 2025-07-25 | Replace `activateDynamicImport` with `importMode` option                                  |
+| 5.6.0   | 2025-07-13 | Change default contentDir from `['src']` to `['.']`                                       |
+| 5.5.11  | 2025-06-29 | Add `docs` commands                                                                       |