@intlayer/docs 6.1.6 → 7.0.0-canary.1

package/docs/en/releases/v7.md

@@ -0,0 +1,486 @@
+---
+createdAt: 2025-09-22
+updatedAt: 2025-09-23
+title: New Intlayer v7 - What's new?
+description: Discover what's new in Intlayer v7. Major improvements in performance, developer experience, and new features to enhance your internationalization workflow.
+keywords:
+  - Intlayer
+  - Localization
+  - Development
+  - Performance
+  - Developer Experience
+  - Features
+  - React
+  - Next.js
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - releases
+  - v7
+---
+
+# New Intlayer v7 - What's new?
+
+Welcome to Intlayer v7! This major release introduces significant improvements in performance, type safety, and developer experience. Below are the highlights, with migration notes and practical examples.
+
+## Highlights
+
+- Caching strategy for faster builds
+- Improved TypeScript type generation with locale-specific types
+- Bundle optimization: Locales as strings instead of enum
+- New routing modes: `prefix-no-default`, `prefix-all`, `no-prefix`, `search-params`
+- GDPR-compliant locale storage with localStorage as default
+- Flexible storage configuration: cookies, localStorage, sessionStorage, or multiple
+- 30% smaller Visual Editor package size
+- Enhanced middleware configuration options
+- Updated fill command behavior for better content management
+- Enhanced stability with complete content declaration file updates
+- Intelligent retry management for translation accuracy
+- Parallelization for faster translation processing
+- Smart chunking to handle large files within AI context limits
+
+---
+
+## Performance: Caching for faster builds
+
+Instead of rebuilding content declarations with esbuild on every build, v7 implements a caching strategy that speeds up the build process.
+
+```bash
+npx intlayer build
+```
+
+The new caching system:
+
+- Stores compiled content declarations to avoid redundant processing
+- Detects changes and rebuilds only modified files
+- Significantly reduces build times for large projects
+
+---
+
+## TypeScript: Locale-specific type generation
+
+TypeScript types are now generated per locale, providing stronger typing and eliminating union types across all locales.
+
+**v6 behavior:**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }
+```
+
+**v7 behavior:**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" }
+```
+
+Benefits:
+
+- More precise autocomplete in your IDE
+- Better type safety with no cross-locale type pollution
+- Improved performance by reducing type complexity
+
+---
+
+## Bundle optimization: Locales as strings
+
+The `Locales` type is no longer an enum, which means it's now fully tree-shakeable and won't bloat your bundle with thousands of unused locale records.
+
+**v6:**
+
+```typescript
+import { Locales } from "intlayer";
+// Enum including all locales -> not tree-shakeable
+
+const locale: Locales = Locales.ENGLISH;
+```
+
+**v7:**
+
+```typescript
+import { Locales, Locale } from "intlayer";
+// String type -> fully tree-shakeable
+
+const locale: Locale = Locales.ENGLISH;
+```
+
+> Because `Locales` is not an enum anymore, you will have to change the type from `Locales` to `Locale` to get the locale as a type.
+
+See the [implementation details](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts) for more information.
+
+---
+
+## New routing modes for greater flexibility
+
+v7 introduces a unified `routing.mode` configuration that replaces the previous `prefixDefault` and `noPrefix` options, offering more granular control over URL structure.
+
+### Available routing modes
+
+- **`prefix-no-default`** (default): Default locale has no prefix, other locales do
+  - `/dashboard` (en) or `/fr/dashboard` (fr)
+- **`prefix-all`**: All locales have a prefix
+  - `/en/dashboard` (en) or `/fr/dashboard` (fr)
+- **`no-prefix`**: No locale prefixes in URLs (locale handled via storage/headers)
+  - `/dashboard` for all locales
+- **`search-params`**: Locale passed as a query parameter
+  - `/dashboard?locale=en` or `/dashboard?locale=fr`
+
+### Basic configuration
+
+```typescript
+// intlayer.config.ts
+export default {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default", // default
+  },
+};
+```
+
+---
+
+## GDPR compliance: localStorage / cookies storage
+
+v7 prioritizes user privacy by using `localStorage` as the default storage mechanism instead of cookies. This change helps with GDPR compliance by avoiding cookie consent requirements for locale preferences.
+
+### Storage configuration options
+
+The new `routing.storage` field is also available in addition to the previous `middleware.cookieName` and `middleware.serverSetCookie` options, offering flexible storage configurations:
+
+```typescript
+// Disable storage
+storage: false
+
+// Simple storage types
+storage: 'cookie'
+storage: 'localStorage'
+storage: 'sessionStorage'
+
+// Cookie with custom attributes
+storage: {
+  type: 'cookie',
+  name: 'custom-locale',
+  domain: '.example.com',
+  secure: true,
+  sameSite: 'strict'
+}
+
+// localStorage with custom key
+storage: {
+  type: 'localStorage',
+  name: 'custom-locale'
+}
+
+// Multiple storage types for redundancy
+storage: ['cookie', 'localStorage']
+```
+
+### GDPR-compliant configuration example
+
+For production applications that need to balance functionality with GDPR compliance:
+
+```typescript
+// intlayer.config.ts
+export default {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default",
+    storage: [
+      {
+        type: "localStorage", // Primary storage (no consent needed)
+        name: "user-locale",
+      },
+      {
+        type: "cookie", // Optional cookie storage (requires consent)
+        name: "user-locale",
+        secure: true,
+        sameSite: "strict",
+        httpOnly: false,
+      },
+    ],
+  },
+};
+```
+
+### Enable / disable the cookie storage
+
+Example using React / Next.js:
+
+Can be defined globally:
+
+```typescript
+<IntlayerProvider isCookieEnabled={false}>
+  <App />
+</IntlayerProvider>
+```
+
+Can override it locally for each hook:
+
+```ts
+const { setLocale } = useLocale({ isCookieEnabled: false });
+
+setLocale("en");
+```
+
+**Note:** Cookies is enabled by default.
+**Note:** Check [GDPR cookie requirements](https://gdpr.eu/cookies/) for your specific use case.
+
+---
+
+## Visual Editor: 30% smaller package
+
+The Visual Editor package has been optimized to be 30% smaller than the previous version, thanks to:
+
+- Code editor performance improvements
+- Removal of unnecessary dependencies on Intlayer core packages
+- Better tree-shaking and module bundling
+
+This results in faster download times and improved runtime performance for your application.
+
+---
+
+## Fill command: Updated behavior for better content management
+
+v7 introduces improved behavior for the `fill` command, providing more predictable and flexible content management:
+
+### New fill behavior
+
+- **`fill: true`** - Rewrites the current file with filled content for all locales
+- **`fill: "path/to/file"`** - Fills the specified file without modifying the current file
+- **`fill: false`** - Disables auto-fill completely
+
+### Enhanced support for complex content structures
+
+The fill command now supports complex content declaration structures, including:
+
+- **Composed objects**: Content declarations that reference other objects
+- **Destructured content**: Content that uses destructuring patterns
+- **Nested references**: Objects that call each other in complex hierarchies
+- **Dynamic content structures**: Content with conditional or computed properties
+
+### Benefits
+
+- **Clearer intent**: The behavior is now more explicit about what gets modified
+- **Better separation**: Content files can be kept separate from filled translations
+- **Improved workflow**: Developers have more control over where translations are stored
+- **Complex structure support**: Handle sophisticated content architectures with multiple interconnected objects
+
+### Example usage
+
+```typescript
+// Rewrite current file with all locales
+const content = {
+  key: "example",
+  fill: true, // Rewrites this file
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Fill separate file without modifying current file
+const content = {
+  key: "example",
+  fill: "./translations.json", // Creates/updates translations.json
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Disable auto-fill
+const content = {
+  key: "example",
+  fill: false, // No auto-fill
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Complex content structure with composed objects
+const sharedContent = {
+  buttons: {
+    save: "Save",
+    cancel: "Cancel",
+  },
+};
+
+const content = {
+  key: "complex-example",
+  fill: true,
+  content: {
+    // References to other objects
+    sharedContent,
+
+    // Destructured content
+    ...sharedContent,
+
+    // Nested references
+    sections: [
+      {
+        ...sharedContent.buttons,
+        header: "Section 1",
+      },
+    ],
+  },
+};
+```
+
+---
+
+## Enhanced stability and translation management
+
+v7 introduces several improvements to make content translation more reliable and efficient:
+
+### Complete content declaration file updates
+
+The system now updates `.content.{ts,js,cjs,mjs}` files rather than partial updates, ensuring:
+
+- **Data integrity**: Complete file rewrites prevent partial updates that could corrupt content
+- **Consistency**: All locales are updated atomically, maintaining synchronization
+- **Reliability**: Reduces the risk of incomplete or malformed content files
+
+### Intelligent retry management
+
+New retry mechanisms prevent pushing content in incorrect formats, and avoid breaking the whole fill process if one request fails.
+
+### Parallelization for faster processing
+
+Translation operations now run in a queue to run them in parallel. This significantly speeds up the process.
+
+### Smart chunking for large files
+
+Advanced chunking strategies handle large content files without exceeding AI context windows:
+
+### Example workflow
+
+```typescript
+// Large content file gets automatically chunked
+const content = {
+  key: "large-documentation",
+  fill: true,
+  content: {
+    // Large content automatically chunked for AI processing
+    introduction: "..." // 5000+ characters
+    sections: [
+      // Multiple large sections
+    ]
+  }
+};
+```
+
+The system automatically:
+
+1. Analyzes content size and structure
+2. Chunks content appropriately
+3. Processes chunks in parallel
+4. Validates and retries if needed
+5. Reconstructs the complete file
+
+---
+
+## Migration notes from v6
+
+### Removed configurations
+
+- **`middleware.cookieName`**: Replaced by `routing.storage`
+- **`middleware.serverSetCookie`**: Replaced by `routing.storage`
+- **`middleware.prefixDefault`**: Replaced by `routing.mode`
+- **`middleware.noPrefix`**: Replaced by `routing.mode`
+
+### Migration mapping
+
+#### Configuration mapping
+
+| v6 Configuration           | v7 Configuration                                     |
+| -------------------------- | ---------------------------------------------------- |
+| `autoFill: xxx`            | `fill: xxx`                                          |
+| `prefixDefault: false`     | `mode: 'prefix-no-default'`                          |
+| `prefixDefault: true`      | `mode: 'prefix-all'`                                 |
+| `noPrefix: true`           | `mode: 'no-prefix'`                                  |
+| `cookieName: 'my-locale'`  | `storage: { type: 'cookie', name: 'my-locale' }`     |
+| `serverSetCookie: 'never'` | `storage: false` or remove cookie from storage array |
+
+#### Example migration
+
+**Before (v6):**
+
+```typescript
+export default {
+  middleware: {
+    headerName: "x-intlayer-locale",
+    cookieName: "intlayer-locale",
+    prefixDefault: false,
+    basePath: "",
+    serverSetCookie: "always",
+    noPrefix: false,
+  },
+};
+```
+
+**After (v7):**
+
+```typescript
+export default {
+  routing: {
+    mode: "prefix-no-default",
+    storage: "localStorage", // or 'cookie' if you need cookie storage
+    headerName: "x-intlayer-locale",
+    basePath: "",
+    detectLocaleOnPrefetchNoPrefix: false,
+  },
+};
+```
+
+#### Dictionary content mapping
+
+| v6 Dictionary content | v7 Dictionary content |
+| --------------------- | --------------------- |
+| `autoFill: xxx`       | `fill: xxx`           |
+
+#### Example migration
+
+**Before (v6):**
+
+```typescript
+const content = {
+  key: "example",
+  autoFill: true, // Rewrites this file
+  content: {
+    title: "Hello World",
+  },
+};
+```
+
+**After (v7):**
+
+```typescript
+const content = {
+  key: "example",
+  fill: true, // Rewrites this file
+  content: {
+    title: "Hello World",
+  },
+};
+```
+
+---
+
+## Migration notes from v5 to v6
+
+Check the [migration notes from v5 to v6](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/releases/v6.md) for more information.
+
+---
+
+## Useful links
+
+- [Configuration Reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
+- [Middleware Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/next-intlayer/index.md)
+- [TypeScript Types](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts)
+- [GDPR Cookie Guidelines](https://gdpr.eu/cookies/)

package/docs/en/roadmap.md

@@ -13,6 +13,16 @@ keywords:
 slugs:
   - doc
   - roadmap
+history:
+  - version: 5.5.10
+    date: 2025-06-30
+    changes: Add Preact and Nuxt support, MCP Server, update CLI
+  - version: 5.5.11
+    date: 2025-06-29
+    changes: Add `docs` commands
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Init history
 ---
 
 # Intlayer: Feature Overview & Roadmap
@@ -328,11 +338,3 @@ Intlayer aims to be a one-stop solution for content management and international
 Stay tuned for upcoming releases, and feel free to explore the existing features to see how Intlayer can help centralize and optimize your content management processes today!
 
 ---
-
-## Doc History
-
-| Version | Date       | Changes                                             |
-| ------- | ---------- | --------------------------------------------------- |
-| 5.5.10  | 2025-06-30 | Add Preact and Nuxt support, MCP Server, update CLI |
-| 5.5.11  | 2025-06-29 | Add `docs` commands                                 |
-| 5.5.10  | 2025-06-29 | Init history                                        |

package/docs/en/testing.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-01
-updatedAt: 2025-09-20
+updatedAt: 2025-10-05
 title: Testing your content
 description: Discover how to test your content with Intlayer.
 keywords:
@@ -13,6 +13,13 @@ keywords:
 slugs:
   - doc
   - testing
+history:
+  - version: 6.0.1
+    date: 2025-10-05
+    changes: Make test async and add build option
+  - version: 6.0.0
+    date: 2025-09-20
+    changes: Introduction of testing
 ---
 
 # Testing your content
@@ -44,6 +51,7 @@ Useful flags:
 - `--base-dir [path]`: set the app base directory for resolution.
 - `--verbose`: show verbose logs.
 - `--prefix [label]`: prefix log lines.
+- `--build [build]`: build the dictionaries before testing to ensure the content is up to date. True will force the build, false will skip the build, undefined will allow using the cache of the build.
 
 Note: the CLI prints a detailed report but does not exit non‑zero on failures. For CI gating, add a unit test (below) that asserts zero missing required locales.
 
@@ -59,8 +67,8 @@ import { listMissingTranslations } from "intlayer/cli";
 import { describe, expect, it } from "vitest";
 
 describe("translations", () => {
-  it("has no missing required locales", () => {
-    const result = listMissingTranslations();
+  it("has no missing required locales", async () => {
+    const result = await listMissingTranslations();
 
     if (result.missingRequiredLocales.length > 0) {
       // Helpful when the test fails locally or in CI
@@ -77,8 +85,8 @@ Jest equivalent:
 ```ts fileName=i18n.test.ts
 import { listMissingTranslations } from "intlayer/cli";
 
-test("has no missing required locales", () => {
-  const result = listMissingTranslations();
+test("has no missing required locales", async () => {
+  const result = await listMissingTranslations();
 
   if (result.missingRequiredLocales.length > 0) {
     // Helpful when the test fails locally or in CI
@@ -192,9 +200,3 @@ npx intlayer content test --verbose
 - For mixed monorepos, use `--base-dir` to point the CLI at the correct application root.
 
 ---
-
-## Doc History
-
-| Version | Date       | Changes                 |
-| ------- | ---------- | ----------------------- |
-| 6.0.0   | 2025-09-20 | Introduction of testing |

package/docs/en/vs_code_extension.md

@@ -15,6 +15,19 @@ keywords:
 slugs:
   - doc
   - vs-code-extension
+history:
+  - version: 6.1.5
+    date: 2025-09-30
+    changes: Add demo gif
+  - version: 6.1.0
+    date: 2025-09-24
+    changes: Added environment selection section
+  - version: 6.0.0
+    date: 2025-09-22
+    changes: Intlayer Tab / Fill & Test commands
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Init history
 ---
 
 # Official VS Code Extension
@@ -111,12 +124,3 @@ The extension can load environment variables from your workspace to run Intlayer
 #### Monorepos and custom directories
 
 If your `.env` files live outside the workspace root, set the **Base Directory** in `Settings → Extensions → Intlayer`. The loader will look for `.env` files relative to that directory.
-
-## Doc History
-
-| Version | Date       | Changes                             |
-| ------- | ---------- | ----------------------------------- |
-| 6.1.5   | 2025-09-30 | Add demo gif                        |
-| 6.1.0   | 2025-09-24 | Added environment selection section |
-| 6.0.0   | 2025-09-22 | Intlayer Tab / Fill & Test commands |
-| 5.5.10  | 2025-06-29 | Init history                        |

package/docs/en-GB/CI_CD.md

@@ -15,6 +15,10 @@ slugs:
   - doc
   - concept
   - ci-cd
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Initial history
 ---
 
 # Auto-Generate Translations in a CI/CD Pipeline
@@ -190,9 +194,3 @@ To set up the environment variables, go to GitHub → Settings → Secrets and v
 > By default, the `--git-diff` argument filters dictionaries that include changes from the base (default `origin/main`) to the current branch (default: `HEAD`).
 
 > For more information about Intlayer CLI commands and their usage, refer to the [CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_cli.md).
-
-## Doc History
-
-| Version | Date       | Changes         |
-| ------- | ---------- | --------------- |
-| 5.5.10  | 2025-06-29 | Initial history |

package/docs/en-GB/autoFill.md

@@ -15,6 +15,16 @@ slugs:
   - doc
   - concept
   - auto-fill
+history:
+  - version: 6.0.0
+    date: 2025-09-20
+    changes: Add global configuration
+  - version: 6.0.0
+    date: 2025-09-17
+    changes: Add `{{fileName}}` variable
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Initialise history
 ---
 
 # Autofill Content Declaration File Translations
@@ -191,11 +201,3 @@ This will generate:
 
 - `./index.content.json`
 - `./index.content.json`
-
-## Doc History
-
-| Version | Date       | Changes                     |
-| ------- | ---------- | --------------------------- |
-| 6.0.0   | 2025-09-20 | Add global configuration    |
-| 6.0.0   | 2025-09-17 | Add `{{fileName}}` variable |
-| 5.5.10  | 2025-06-29 | Initialise history          |

package/docs/en-GB/configuration.md

@@ -13,6 +13,22 @@ slugs:
   - doc
   - concept
   - configuration
+history:
+  - version: 6.0.0
+    date: 2025-09-16
+    changes: Add `live` import mode
+  - version: 6.0.0
+    date: 2025-09-04
+    changes: Replace `hotReload` field with `liveSync` and add `liveSyncPort` and `liveSyncURL` fields
+  - version: 5.6.1
+    date: 2025-07-25
+    changes: Replace `activateDynamicImport` with `importMode` option
+  - version: 5.6.0
+    date: 2025-07-13
+    changes: Change default contentDir from `['src']` to `['.']`
+  - version: 5.5.11
+    date: 2025-06-29
+    changes: Add `docs` commands
 ---
 
 # Intlayer Configuration Documentation
@@ -563,13 +579,3 @@ Build options apply to the `@intlayer/babel` and `@intlayer/swc` plugins.
   - _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
-
-| 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                                                                       |