@intlayer/docs 7.0.0-canary.1 → 7.0.0-canary.3

package/docs/en-GB/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 internationalisation workflow.
+keywords:
+  - Intlayer
+  - Localisation
+  - 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 optimisation: 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 behaviour for better content management
+- Enhanced stability with complete content declaration file updates
+- Intelligent retry management for translation accuracy
+- Parallelisation 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 behaviour:**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }
+```
+
+**v7 behaviour:**
+
+```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 optimisation: Locales as strings
+
+The `Locales` type is no longer an enum, which means it is now fully tree-shakeable and will not 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 prioritises 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 are 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 optimised 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 behaviour for better content management
+
+v7 introduces improved behaviour for the `fill` command, providing more predictable and flexible content management:
+
+### New fill behaviour
+
+- **`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 behaviour 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 synchronisation
+- **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.
+
+### Parallelisation 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. Analyses 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 require 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-GB/releases/v6.md) for more information.
+
+---
+
+## Useful links
+
+- [Configuration Reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md)
+- [Middleware Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/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/)