@intlayer/docs 5.5.10 → 5.5.12

package/docs/en-GB/autoFill.md

@@ -0,0 +1,178 @@
+---
+createdAt: 2025-03-13
+updatedAt: 2025-06-29
+title: Auto Fill
+description: Learn how to use auto fill functionality in Intlayer to automatically populate content based on predefined patterns. Follow this documentation to implement auto fill features efficiently in your project.
+keywords:
+  - Auto Fill
+  - Content Automation
+  - Dynamic Content
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - auto-fill
+---
+
+# Autofill Content Declaration File Translations
+
+**Autofill content declaration files** are a way to speed up your development workflow.
+The autofill mechanism works through a _master-slave_ relationship between content declaration files. When the main (master) file is updated, Intlayer will automatically apply those changes to the derived (autofilled) declaration files.
+
+```ts fileName="src/components/example/example.content.ts"
+import { Locales, type Dictionary } from "intlayer";
+
+const exampleContent = {
+  key: "example",
+  locale: Locales.ENGLISH,
+  autoFill: "./example.content.json",
+  content: {
+    contentExample: "This is an example of content",
+  },
+} satisfies Dictionary;
+
+export default exampleContent;
+```
+
+Here is a [per-locale content declaration file](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/per_locale_file.md) using the `autoFill` instruction.
+
+Then, when you run the following command:
+
+```bash
+npx intlayer fill --file 'src/components/example/example.content.ts'
+```
+
+Intlayer will automatically generate the derived declaration file at `src/components/example/example.content.json`, filling in all locales not already declared in the main file.
+
+```json5 fileName="src/components/example/example.content.json"
+{
+  "key": "example",
+  "content": {
+    "contentExample": {
+      "nodeType": "translation",
+      "translation": {
+        "fr": "Ceci est un exemple de contenu",
+        "es": "Este es un ejemplo de contenido",
+      },
+    },
+  },
+}
+```
+
+Afterwards, both declaration files will be merged into a single dictionary, accessible using the standard `useIntlayer("example")` hook (React) / composable (Vue).
+
+## Autofilled File Format
+
+The recommended format for autofilled declaration files is **JSON**, which helps avoid formatting constraints. However, Intlayer also supports `.ts`, `.js`, `.mjs`, `.cjs`, and other formats.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "./example.filled.content.ts",
+  content: {
+    // Your content
+  },
+};
+```
+
+This will generate the file at:
+
+```
+src/components/example/example.filled.content.ts
+```
+
+> The generation of `.js`, `.ts`, and similar files works as follows:
+>
+> - If the file already exists, Intlayer will parse it using the AST (Abstract Syntax Tree) to locate each field and insert any missing translations.
+> - If the file does not exist, Intlayer will generate it using the default content declaration file template.
+
+## Absolute Paths
+
+The `autoFill` field also supports absolute paths.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "/messages/example.content.json",
+  content: {
+    // Your content
+  },
+};
+```
+
+This will generate the file at:
+
+```
+/messages/example.content.json
+```
+
+## Autogenerate Per-Locale Content Declaration Files
+
+The `autoFill` field also supports generation of **per-locale** content declaration files.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: {
+    fr: "./example.fr.content.json",
+    es: "./example.es.content.json",
+  },
+  content: {
+    // Your content
+  },
+};
+```
+
+This will generate two separate files:
+
+- `src/components/example/example.fr.content.json`
+- `src/components/example/example.es.content.json`
+
+## Filter Specific Locale Autofill
+
+Using an object for the `autoFill` field allows you to apply filters and generate only specific locale files.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: {
+    fr: "./example.fr.content.json",
+  },
+  content: {
+    // Your content
+  },
+};
+```
+
+This will only generate the French translation file.
+
+## Path Variables
+
+You can use variables inside the `autoFill` path to dynamically resolve the target paths for the generated files.
+
+**Available variables:**
+
+- `{{locale}}` – Locale code (e.g. `fr`, `es`)
+- `{{key}}` – Dictionary key (e.g. `example`)
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "/messages/{{locale}}/{{key}}.content.json",
+  content: {
+    // Your content
+  },
+};
+```
+
+This will generate:
+
+- `/messages/fr/example.content.json`
+- `/messages/es/example.content.json`
+
+## Doc History
+
+- 5.5.10 - 2025-06-29: Init history

package/docs/en-GB/configuration.md

@@ -0,0 +1,525 @@
+---
+createdAt: 2024-08-13
+updatedAt: 2025-06-29
+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:
+  - Configuration
+  - Settings
+  - Customisation
+  - Intlayer
+  - Options
+slugs:
+  - doc
+  - concept
+  - configuration
+---
+
+# Intlayer Configuration Documentation
+
+## Overview
+
+Intlayer configuration files allow customisation of various aspects of the plugin, such as internationalisation, middleware, and content handling. This document provides a detailed description of each property in the configuration.
+
+---
+
+## Configuration File Support
+
+Intlayer accepts JSON, JS, MJS, and TS configuration file formats:
+
+- `intlayer.config.ts`
+- `intlayer.config.js`
+- `intlayer.config.json`
+- `intlayer.config.cjs`
+- `intlayer.config.mjs`
+- `.intlayerrc`
+
+---
+
+## Example config file
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH],
+  },
+  content: {
+    contentDir: ["src", "../ui-library"],
+  },
+  middleware: {
+    noPrefix: false,
+  },
+  editor: {
+    applicationURL: "https://example.com",
+  },
+  ai: {
+    apiKey: process.env.OPENAI_API_KEY,
+    applicationContext: "This is a test application",
+  },
+  build: {
+    activateDynamicImport: true,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [Locales.ENGLISH],
+  },
+  content: {
+    contentDir: ["src", "../ui-library"],
+  },
+  middleware: {
+    noPrefix: false,
+  },
+  editor: {
+    applicationURL: "https://example.com",
+  },
+  ai: {
+    apiKey: process.env.OPENAI_API_KEY,
+    applicationContext: "This is a test application",
+  },
+  build: {
+    activateDynamicImport: true,
+  },
+};
+
+module.exports = config;
+```
+
+```json5 fileName=".intlayerrc" codeFormat="json"
+{
+  "internationalization": {
+    "locales": ["en"],
+  },
+  "content": {
+    "typesDir": "content/types",
+  },
+  "middleware": {
+    "noPrefix": false,
+  },
+}
+```
+
+---
+
+## Configuration Reference
+
+The following sections describe the various configuration settings available for Intlayer.
+
+---
+
+### Internationalisation Configuration
+
+Defines settings related to internationalisation, including available locales and the default locale for the application.
+
+#### Properties
+
+- **locales**:
+
+  - _Type_: `string[]`
+  - _Default_: `['en']`
+  - _Description_: The list of supported locales in the application.
+  - _Example_: `['en', 'fr', 'es']`
+
+- **requiredLocales**:
+  - _Type_: `string[]`
+  - _Default_: `[]`
+  - _Description_: The list of required locales in the application.
+  - _Example_: `[]`
+  - _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.
+  - _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 "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.
+  - _Example_: `'en'`
+  - _Note_: This is used to determine the locale when none is specified in the URL, cookie, or header.
+
+---
+
+### Editor Configuration
+
+Defines settings related to the integrated editor, including server port and active status.
+
+#### 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.
+  - _Example_:
+    - `'http://localhost:3000'`
+    - `'https://example.com'`
+    - `process.env.INTLAYER_EDITOR_URL`
+  - _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.
+
+- **cmsURL**:
+
+  - _Type_: `string`
+  - _Default_: `'https://intlayer.org'`
+  - _Description_: The URL of the Intlayer CMS.
+  - _Example_: `'https://intlayer.org'`
+  - _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.
+  - _Example_: `process.env.NODE_ENV !== 'production'`
+  - _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.
+  - _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.
+
+- **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.
+  - _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.
+
+- **hotReload**:
+
+  - _Type_: `boolean`
+  - _Default_: `false`
+  - _Description_: Indicates if the application should hot reload the locale configurations when a change is detected.
+  - _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.
+
+- **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'`
+
+### Middleware Configuration
+
+Settings that control middleware behaviour, including how the application handles cookies, headers, and URL prefixes for locale management.
+
+#### Properties
+
+- **headerName**:
+
+  - _Type_: `string`
+  - _Default_: `'x-intlayer-locale'`
+  - _Description_: The name of the HTTP header used to determine the locale.
+  - _Example_: `'x-custom-locale'`
+  - _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.
+  - _Example_: `'custom-locale'`
+  - _Note_: Used to persist the locale across sessions.
+
+- **prefixDefault**:
+
+  - _Type_: `boolean`
+  - _Default_: `true`
+  - _Description_: Whether to include the default locale in the URL.
+  - _Example_: `false`
+  - _Note_: If `false`, URLs for the default locale will not have a locale prefix.
+
+- **basePath**:
+
+  - _Type_: `string`
+  - _Default_: `''`
+  - _Description_: The base path for the application URLs.
+  - _Example_: `'/my-app'`
+  - _Note_: This affects how URLs are constructed for the application.
+
+- **serverSetCookie**:
+
+  - _Type_: `string`
+  - _Default_: `'always'`
+  - _Description_: Rule for setting the locale cookie on the server.
+  - _Options_: `'always'`, `'never'`
+  - _Example_: `'never'`
+  - _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.
+  - _Example_: `true`
+  - _Note_: If `true`, URLs will not contain locale information.
+
+---
+
+### Content Configuration
+
+Settings related to content handling within the application, including directory names, file extensions, and derived configurations.
+
+#### Properties
+
+- **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.
+  - _Example_: `['.data.ts', '.data.js', '.data.json']`
+  - _Note_: Customising file extensions can help avoid conflicts.
+
+- **baseDir**:
+
+  - _Type_: `string`
+  - _Default_: `process.cwd()`
+  - _Description_: The base directory for the project.
+  - _Example_: `'/path/to/project'`
+  - _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']`
+  - _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`.
+
+- **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.
+  - _Example_: `'translations'`
+  - _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.
+  - _Example_: `'intlayer-main'`
+
+- **excludedPath**:
+  - _Type_: `string[]`
+  - _Default_: `['node_modules']`
+  - _Description_: Directories excluded from content search.
+  - _Note_: This setting is not yet used, but is planned for future implementation.
+
+### Logger Configuration
+
+Settings that control the logger, including the prefix to use.
+
+#### Properties
+
+- **mode**:
+
+  - _Type_: `string`
+  - _Default_: `default`
+  - _Description_: Indicates the mode of the logger.
+  - _Options_: `default`, `verbose`, `disabled`
+  - _Example_: `default`
+  - _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.
+  - _Example_: `'[my custom prefix] '`
+  - _Note_: The prefix of the logger.
+
+### 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.  
+Intlayer supports multiple AI providers for enhanced flexibility and choice. Currently supported providers are:
+
+- **OpenAI** (default)
+- **Anthropic Claude**
+- **Mistral AI**
+- **DeepSeek**
+- **Google Gemini**
+- **Meta Llama**
+
+#### Properties
+
+- **provider**:
+
+  - _Type_: `string`
+  - _Default_: `'openai'`
+  - _Description_: The provider to use for the AI features of Intlayer.
+  - _Options_: `'openai'`, `'anthropic'`, `'mistral'`, `'deepseek'`, `'gemini'`
+  - _Example_: `'anthropic'`
+  - _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.
+  - _Example_: `'gpt-4o-2024-11-20'`
+  - _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.
+  - _Example_: `0.1`
+  - _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.
+
+- **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.
+
+### Build Configuration
+
+Settings that control how Intlayer optimises and builds your application's internationalisation.
+
+Build options apply to the `@intlayer/babel` and `@intlayer/swc` plugins.
+
+> In development mode, Intlayer uses a centralised static import for dictionaries to simplify the development experience.
+
+> By optimising the build, Intlayer will replace all calls of dictionaries to optimise chunking. That way the final bundle will import only the dictionaries that are used.
+
+- **Note**: `@intlayer/babel` is available by default on `vite-intlayer` package, but `@intlayer/swc` is not installed by default on `next-intlayer` package as SWC plugins are still experimental on Next.js.
+
+#### Properties
+
+- **optimize**:
+
+  - _Type_: `boolean`
+  - _Default_: `process.env.NODE_ENV === 'production'`
+  - _Description_: Controls whether the build should be optimised.
+  - _Example_: `true`
+  - _Note_: It will allow importing only the dictionaries that are used into the bundle. But all imports will remain as static imports to avoid async processing when loading the dictionaries.
+  - _Note_: When enabled, Intlayer will optimise dictionary chunking by replacing all calls of `useIntlayer` with `useDictionary` and `getIntlayer` with `getDictionary`.
+  - _Note_: Ensure all keys are declared statically in the `useIntlayer` calls. e.g. `useIntlayer('navbar')`.
+
+- **activateDynamicImport**:
+
+  - _Type_: `boolean`
+  - _Default_: `false`
+  - _Description_: Controls whether dictionary content should be dynamically imported per locale.
+  - _Example_: `true`
+  - _Note_: It will allow importing dynamically the dictionary content for the current locale only.
+  - _Note_: Dynamic imports rely on React Suspense and may slightly impact rendering performance. But if disabled all locales will be loaded at once, even if they are not used.
+  - _Note_: When enabled, Intlayer will optimise dictionary chunking by replacing all calls of `useIntlayer` with `useDynamicDictionary`.
+  - _Note_: This option will be ignored if `optimize` is disabled.
+  - _Note_: Ensure all keys are declared statically in the `useIntlayer` calls. e.g. `useIntlayer('navbar')`.
+
+- **traversePattern**:
+  - _Type_: `string[]`
+  - _Default_: `['**\/*.{js,ts,mjs,cjs,jsx,tsx,mjx,cjx}', '!**\/node_modules/**']`
+  - _Description_: Patterns that define which files should be traversed during optimisation.
+    - _Example_: `['src/**\/*.{ts,tsx}', '../ui-library/**\/*.{ts,tsx}', '!**/node_modules/**']`
+  - _Note_: Use this to limit optimisation to relevant code files and improve build performance.
+  - _Note_: This option will be ignored if `optimise` is disabled.
+  - _Note_: Use glob pattern.
+
+## Doc History
+
+- 5.5.11 - 2025-06-29: Add `docs` commands