@intlayer/docs 6.0.0 → 6.0.2-canary.0

package/docs/en-GB/releases/v6.md

@@ -0,0 +1,297 @@
+---
+createdAt: 2025-09-22
+updatedAt: 2025-09-22
+title: New Intlayer v6 - What's new?
+description: Discover what's new in Intlayer v6. Major improvements in performance, developer experience, and new features to enhance your internationalisation workflow.
+keywords:
+  - Intlayer
+  - Localisation
+  - Development
+  - Performance
+  - Developer Experience
+  - Features
+  - React
+  - Next.js
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - releases
+  - v6
+---
+
+# New Intlayer v6 - What's new?
+
+Welcome to Intlayer v6! This release focuses on performance, developer experience, and reliability. Below are the highlights, with migration notes and copy‑pasteable examples.
+
+## Highlights
+
+- New command: `npx intlayer content test` to detect missing translations
+- New global `autoFill` option to auto‑generate missing translations
+- Fill command defaults to skipping existing translations: `npx intlayer fill`
+- VS Code extension: new Intlayer Activity Bar (Search & Dictionaries), toolbar/context actions, auto‑reveal, Fill/Test commands
+- 10× faster builds thanks to promise parallelisation
+- Remote dictionary caching to avoid refetch at app start
+- Improved logging: set `log.mode: 'verbose'` to inspect behaviour
+- Stronger validation to prevent app crashes on dictionary issues
+- Live updates with CMS using `build.importMode = 'live'` and `pnpm intlayer live`
+- Fixes: Vue.js integration, Lynx adapter, Visual Editor on Windows
+
+---
+
+## New: Test missing translations
+
+Quickly audit your project to find which keys/locales are missing.
+
+```bash
+npx intlayer content test
+```
+
+Output:
+
+```bash
+pnpm intlayer content test
+Missing translations:
+ - blog-data       - Japanese (ja), Korean (ko), Chinese (zh), German (de), Italian (it) - src/components/BlogPage/blogData.content.ts
+ - demo-page       - French (fr), Italian (it)                                         - src/components/DemoPage/demo.content.ts
+ - locale-switcher - Italian (it), Portuguese (pt)                                       - src/components/LocaleSwitcher/localeSwitcher.content.ts
+Locales: English (en), Russian (ru), Japanese (ja), French (fr), Korean (ko), Chinese (zh), Spanish (es), German (de), Arabic (ar), Italian (it), British English (en-GB), Portuguese (pt), Hindi (hi)
+Required locales: English (en)
+Missing locales: Japanese (ja), Korean (ko), Chinese (zh), German (de), Italian (it), French (fr), Portuguese (pt)
+Missing required locales: -
+Total missing locales: 7
+Total missing required locales: 0
+```
+
+See more options in the CLI docs: [CLI reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_cli.md) → "Test missing translations". As well as the [Testing](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/testing.md) guide.
+
+---
+
+## New: Global autoFill to complete missing translations
+
+You can now enable auto-fill globally so any dictionary with missing translations gets completed automatically.
+
+```ts fileName="intlayer.config.ts"
+import { type IntlayerConfig, Locales } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+  },
+  content: {
+    // Auto-generate missing translations for all dictionaries
+    autoFill: "./{{fileName}}.content.ts",
+    //
+    // autoFill: "/messages/{{locale}}/{{key}}/{{fileName}}.content.json",
+    //
+    // autoFill: true, // auto-generate missing translations for all dictionaries like using "./{{fileName}}.content.json"
+    //
+    // autoFill: {
+    //   en: "./{{fileName}}.en.content.json",
+    //   fr: "./{{fileName}}.fr.content.json",
+    //   es: "./{{fileName}}.es.content.json",
+    // },
+  },
+};
+
+export default config;
+```
+
+You can still fine‑tune per dictionary using the `autoFill` field in content files. See the full reference in `doc/autoFill` and `doc/dictionary/content_file`.
+
+---
+
+## Fill command: safer defaults
+
+The fill command now, by default, only fills missing translations and skips existing content.
+
+```bash
+npx intlayer fill
+```
+
+```bash
+Affected dictionary keys for processing: access-key-creation-form-schema, doc-search-metadata, doc-search-page
+  - [access-key-creation-form-schema]      Dictionary has no file path. Skipping.
+  - [access-key-creation-form-schema]      Processing content declaration: src/components/Dashboard/ProjectForm/AccessKey/useAccessKeyCreationFormSchema.content.ts
+  - [access-key-creation-form-schema]      No locales to fill - Skipping dictionary
+  - [doc-search-metadata]                  Dictionary has no file path. Skipping.
+  - [doc-search-metadata]                  Processing content declaration: src/app/[locale]/(docs)/doc/search/metadata.content.ts
+  - [doc-search-metadata]                  No locales to fill - Skipping dictionary
+  - [doc-search-page]                      Dictionary has no file path. Skipping.
+  - [doc-search-page]                      Processing content declaration: src/app/[locale]/(docs)/doc/search/page.content.ts
+  - [doc-search-page]                     [Russian (ru)]                   Preparing translation for dictionary from English (en) to Russian (ru)
+[intlayer]  Applied Prettier formatting to src/app/[locale]/(docs)/doc/search/page.content.ts
+  - [doc-search-page]                      Content declaration written to src/app/[locale]/(docs)/doc/search/page.content.ts
+```
+
+CI examples are available in [CI/CD](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/CI_CD.md).
+
+---
+
+## Updated VS Code extension
+
+The extension now includes a dedicated Intlayer tab in the Activity Bar and several workflow improvements:
+
+- Intlayer Activity Bar with two views:
+  - Search webview (`intlayer.searchBar`) for live dictionary/content search
+  - Dictionaries tree (`intlayer.dictionaries`) listing environments, dictionaries, and contributing files
+- Toolbar on Dictionaries view: Build, Pull, Push, Fill, Refresh, Test, Create Dictionary File
+- Context menus: Pull/Push on dictionaries; Fill on files
+- Auto‑reveal: the current editor file is highlighted in the Dictionaries tree when applicable
+- New commands available from the Command Palette: Fill Dictionaries and Test Dictionaries
+
+See details in the [Official VS Code Extension](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/vs_code_extension.md) documentation.
+
+---
+
+## Performance: 10× faster
+
+- Parallel resolution of local and remote dictionaries
+- Remote dictionaries are cached to avoid re‑fetching at app startup
+
+```bash
+npx intlayer build
+```
+
+Output:
+
+```bash
+[intlayer]  Preparing Intlayer (v6.0.1)
+[intlayer]  Dictionaries:
+[intlayer]  ✓ Local content: 163/163
+[intlayer]  ✓ Remote content: 100/100
+[intlayer]   - access-key-creation-form             [local: ✔ built] [distant: ✔ imported]
+[intlayer]   - access-key-creation-form-schema      [local: ✔ built] [distant: ✔ imported]
+[intlayer]   - access-key-form                      [local: ✔ built] [distant: ✔ imported]
+[intlayer]   - ai-ab-testing-section                                 [distant: ✔ imported]
+[intlayer]   - application-not-running-view         [local: ✔ built] [distant: ✔ imported]
+[intlayer]   - application-template-message         [local: ✔ built] [distant: ✔ fetched]
+[intlayer]   - aside-navigation                     [local: ✔ built] [distant: ✔ imported]
+[intlayer]   - ask-reset-password                   [local: ✔ built] [distant: ✔ imported]
+[intlayer]   - ask-reset-password-schema            [local: ✔ built] [distant: ✔ imported]
+[intlayer]   - autocompletion-section               [local: ✔ built] [distant: ✔ fetched]
+[intlayer]   - available-techno-section             [local: ✔ built] [distant: ✔ imported]
+[intlayer]   - blog-data                            [local: ✔ built]
+[intlayer]   - blog-metadata                        [local: ✔ built]
+[intlayer]   - blog-nav-list                        [local: ✔ built] [distant: ✔ imported]
+[intlayer]   - blog-page                                             [distant: ✔ fetched]
+[intlayer]   - blog-search-metadata                 [local: ✔ built] [distant: ✔ imported]
+[intlayer]   - blog-search-page                     [local: ✔ built] [distant: ✔ imported]
+...
+[intlayer]  Content loaded  (Total: 8401ms - Local: 4050ms - Remote: 4222ms)
+```
+
+---
+
+## Logging improvements
+
+The logging system has been improved to provide more detailed information about what happens during build and runtime transformations.
+
+> Enable verbose logs to better understand what happens during build and runtime transformations.
+
+```ts fileName="intlayer.config.ts"
+export default {
+  log: {
+    mode: "verbose", // options: "default" | "verbose" | "disabled"
+  },
+};
+```
+
+See [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md) for all logging options.
+
+---
+
+## Stronger validation
+
+Dictionary processing now performs more robust validation. When a dictionary fails to process, Intlayer avoids breaking your application and surfaces actionable errors.
+
+---
+
+## Live updates with CMS (Production‑safe)
+
+The logging system has been improved to provide more detailed information about what happens during build and runtime transformations.
+
+> Enable verbose logs to better understand what happens during build and runtime transformations.
+
+```ts fileName="intlayer.config.ts"
+export default {
+  log: {
+    mode: "verbose", // options: "default" | "verbose" | "disabled"
+  },
+};
+```
+
+See [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md) for all logging options.
+
+---
+
+## Stronger validation
+
+Dictionary processing now performs more robust validation. When a dictionary fails to process, Intlayer avoids breaking your application and surfaces actionable errors.
+
+---
+
+## Live updates with CMS (Production‑safe)
+
+Serve live content updates (e.g., editorial updates) in production without rebuilding your application.
+
+1. Enable live import mode:
+
+```ts fileName="intlayer.config.ts"
+import { type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  build: {
+    importMode: "live", // "static" | "dynamic" | "live"
+  },
+  editor: {
+    liveSync: true, // enable live sync server side
+  },
+};
+
+export default config;
+```
+
+2. Run your app and live process side‑by‑side:
+
+```bash
+npx intlayer live --process 'vite preview'
+```
+
+Notes:
+
+- Only dictionaries flagged to use live mode will be fetched live. Others are optimised for performance.
+- Falls back to dynamic import if the live API isn’t reachable.
+
+See [CMS and Live Sync](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md) and [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md) for complete guidance.
+
+---
+
+## Migration notes
+
+- Removed: `dictionaryOutput` (previously `i18next` or `next-intl`). This will return as pluggable adapters in future versions. Remove the field from your config.
+- Related removal: `i18nextResourcesDir` (see `doc/configuration` changelog).
+- Prefer the new global `content.autoFill` option to generate missing translations at scale.
+- Use `npx intlayer content test` to gate PRs on missing translations.
+- For verbose diagnostics, set `log.mode = 'verbose'`.
+
+---
+
+## Fixes
+
+- Vue.js integration stability
+- Lynx adapter improvements
+- Visual Editor on Windows
+
+---
+
+## Useful links
+
+- [CLI reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_cli.md)
+- [Auto‑fill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/autoFill.md)
+- [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md)
+- [Content file reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/content_file.md)
+- [Official VS Code Extension](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/vs_code_extension.md)
+- [CMS and Live Sync](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md)

package/docs/en-GB/roadmap.md

@@ -112,18 +112,16 @@ Intlayer provides various methods to insert and manage dynamic content, ensuring
 Intlayer supports **TypeScript** (also JavaScript) and **JSON** for declaring content.
 
 - **TypeScript**:
-
   - Ensures your content structure is correct and that no translations are missing.
   - Offers strict or more flexible validation modes.
   - Allows dynamic data fetching from variables, functions, or external APIs.
 
 - **JSON**:
-
   - Makes it easy to integrate with external tools (such as visual editors) due to its standardised format.
 
   > Resources:
   >
-  > - [Content Declaration Formats](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_extention_customization.md)
+  > - [Content Declaration Formats](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_file.md)
 
 ### 7. Purging, bundle optimisation and dynamic imports
 

package/docs/en-GB/vs_code_extension.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-17
-updatedAt: 2025-06-29
+updatedAt: 2025-09-22
 title: Official VS Code Extension
 description: Learn how to use the Intlayer extension in VS Code to enhance your development workflow. Quickly navigate between localised content and manage your dictionaries efficiently.
 keywords:
@@ -21,7 +21,7 @@ slugs:
 
 ## Overview
 
-[**Intlayer**](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension) is the official Visual Studio Code extension for **Intlayer**, designed to enhance the developer experience when working with localised content in your projects.
+[**Intlayer**](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension) is the official Visual Studio Code extension for **Intlayer**, designed to improve the developer experience when working with localised content in your projects.
 
 ![Intlayer VS Code Extension](https://github.com/aymericzip/intlayer/blob/main/docs/assets/vs_code_extension_demo.gif)
 
@@ -31,7 +31,7 @@ Extension link: [https://marketplace.visualstudio.com/items?itemName=Intlayer.in
 
 ### Instant Navigation
 
-**Go to Definition Support** – Use `Cmd+Click` (Mac) or `Ctrl+Click` (Windows/Linux) on a `useIntlayer` key to open the corresponding content file instantly.  
+**Go to Definition Support** – Use `⌘ + Click` (Mac) or `Ctrl + Click` (Windows/Linux) on a `useIntlayer` key to open the corresponding content file instantly.  
 **Seamless Integration** – Works effortlessly with **react-intlayer** and **next-intlayer** projects.  
 **Multi-language Support** – Supports localised content across different languages.  
 **VS Code Integration** – Smoothly integrates with VS Code’s navigation and command palette.
@@ -40,18 +40,66 @@ Extension link: [https://marketplace.visualstudio.com/items?itemName=Intlayer.in
 
 Manage your content dictionaries directly from VS Code:
 
-- **Build Dictionaries** (`extension.buildDictionaries`) – Generate content files based on your project structure.
-- **Push Dictionaries** (`extension.pushDictionaries`) – Upload the latest dictionary content to your repository.
-- **Pull Dictionaries** (`extension.pullDictionaries`) – Sync the latest dictionary content from your repository to your local environment.
+- **Build Dictionaries** – Generate content files based on your project structure.
+- **Push Dictionaries** – Upload the latest dictionary content to your repository.
+- **Pull Dictionaries** – Synchronise the latest dictionary content from your repository to your local environment.
+- **Fill Dictionaries** – Populate dictionaries with content from your project.
+- **Test Dictionaries** – Identify missing or incomplete translations.
 
 ### Content Declaration Generator
 
 Easily generate structured dictionary files in different formats:
 
-- **TypeScript (`.ts`)** – `extension.createDictionaryFile.ts`
-- **ES Module (`.esm`)** – `extension.createDictionaryFile.esm`
-- **CommonJS (`.cjs`)** – `extension.createDictionaryFile.cjs`
-- **JSON (`.json`)** – `extension.createDictionaryFile.json`
+If you are currently working on a component, it will generate the `.content.{ts,tsx,js,jsx,mjs,cjs,json}` file for you.
+
+Example of component:
+
+```tsx fileName="src/components/MyComponent/index.tsx"
+const MyComponent = () => {
+  const { myTranslatedContent } = useIntlayer("my-component");
+
+  return <span>{myTranslatedContent}</span>;
+};
+```
+
+Generated file in TypeScript format:
+
+```tsx fileName="src/components/MyComponent/index.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+const componentContent = {
+  key: "my-component",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      es: "Hola Mundo",
+      fr: "Bonjour le monde",
+    }),
+  },
+};
+
+export default componentContent;
+```
+
+Available formats:
+
+- **TypeScript (`.ts`)**
+- **ES Module (`.esm`)**
+- **CommonJS (`.cjs`)**
+- **JSON (`.json`)**
+
+### Intlayer Tab (Activity Bar)
+
+Open the Intlayer tab by clicking the Intlayer icon in the VS Code Activity Bar. It contains two views:
+
+- **Search**: A live search bar to quickly filter dictionaries and their content. Typing updates the results instantly.
+- **Dictionaries**: A tree view of your environments/projects, dictionary keys, and the files contributing entries. You can:
+  - Click a file to open it in the editor.
+  - Use the toolbar to run actions: Build, Pull, Push, Fill, Refresh, Test, and Create Dictionary File.
+  - Use the context menu for item‑specific actions:
+    - On a dictionary: Pull or Push
+    - On a file: Fill Dictionary
+  - When you switch editors, the tree will reveal the matching file if it belongs to a dictionary.
 
 ## Installation
 
@@ -62,12 +110,6 @@ You can install **Intlayer** directly from the VS Code Marketplace:
 3. Search for **"Intlayer"**.
 4. Click **Install**.
 
-Alternatively, install it via the command line:
-
-```sh
-code --install-extension intlayer
-```
-
 ## Usage
 
 ### Quick Navigation
@@ -84,6 +126,14 @@ code --install-extension intlayer
 
 ### Managing Content Dictionaries
 
+### Intlayer Tab (Activity Bar)
+
+Use the side tab to browse and manage dictionaries:
+
+- Open the Intlayer icon in the Activity Bar.
+- In **Search**, type to filter dictionaries and entries in real time.
+- In **Dictionaries**, browse environments, dictionaries, and files. Use the toolbar for Build, Pull, Push, Fill, Refresh, Test, and Create Dictionary File. Right‑click for context actions (Pull/Push on dictionaries, Fill on files). The current editor file auto‑reveals in the tree when applicable.
+
 #### Building Dictionaries
 
 Generate all dictionary content files with:
@@ -110,43 +160,24 @@ Sync the latest dictionary content:
 2. Search for **Pull Dictionaries**.
 3. Choose the dictionaries to pull.
 
-## Development & Contribution
-
-Want to contribute? We welcome community contributions!
-
-Repo URL: https://github.com/aymericzip/intlayer-vs-code-extension
+#### Filling Dictionaries
 
-### Getting Started
-
-Clone the repository and install dependencies:
-
-```sh
-git clone https://github.com/aymericzip/intlayer-vs-code-extension.git
-cd intlayer-vs-code-extension
-npm install
-```
+Fill dictionaries with content from your project:
 
-> Use the `npm` package manager for compatibility with the `vsce` package to build and publish the extension.
-
-### Run in Development Mode
-
-1. Open the project in **VS Code**.
-2. Press `F5` to launch a new **Extension Development Host** window.
-
-### Submit a Pull Request
-
-If you improve the extension, submit a PR on [GitHub](https://github.com/aymericzip/intlayer-vs-code-extension).
-
-## Feedback & Issues
-
-Found a bug or have a feature request? Open an issue on our **GitHub repository**:
+1. Open the **Command Palette**.
+2. Search for **Fill Dictionaries**.
+3. Run the command to populate dictionaries.
 
-[GitHub Issues](https://github.com/aymericzip/intlayer-vs-code-extension/issues)
+#### Testing Dictionaries
 
-## Licence
+Validate dictionaries and find missing translations:
 
-Intlayer is released under the **MIT Licence**.
+1. Open the **Command Palette**.
+2. Search for **Test Dictionaries**.
+3. Review the reported issues and fix as needed.
 
 ## Doc History
 
-- 5.5.10 - 2025-06-29: Init history
+| Version | Date       | Changes      |
+| ------- | ---------- | ------------ |
+| 5.5.10  | 2025-06-29 | Init history |