@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.11

package/docs/en/plugins/sync-json.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-12-13
+updatedAt: 2026-06-21
 title: Sync JSON plugin
 description: Synchronize Intlayer dictionaries with third‑party i18n JSON files (i18next, next-intl, react-intl, vue-i18n, and more). Keep your existing i18n while using Intlayer to manage, translate, and test your messages.
 keywords:
@@ -24,6 +24,9 @@ slugs:
   - sync-json
 youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
 history:
+  - version: 9.0.0
+    date: 2026-06-21
+    changes: "Add splitKeys option (one dictionary per top-level namespace key) for next-intl / react-intl single-file layouts"
   - version: 7.5.0
     date: 2025-12-13
     changes: "Add ICU and i18next format support"
@@ -105,7 +108,6 @@ const config: IntlayerConfig = {
      * Will load, and write the output and translations back to the JSON files in the locales directory
      */
     syncJSON({
-      format: "i18next",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
       priority: 0,
       format: "i18next",
@@ -182,6 +184,7 @@ syncJSON({
   location?: string, // optional label, default: "plugin"
   priority?: number, // optional priority for conflict resolution, default: 0
   format?: 'intlayer' | 'icu' | 'i18next', // optional formatter, used for intlayer runtime compatibility
+  splitKeys?: boolean, // optional, split a single file into one dictionary per top-level key (auto-detected)
 });
 ```
 
@@ -206,6 +209,38 @@ syncJSON({
 }),
 ```
 
+#### `splitKeys` (boolean)
+
+Controls whether a single JSON file whose **first-level keys are namespaces** should become one dictionary per top-level key, instead of a single dictionary holding the whole file.
+
+This matches the namespace model of libraries like `next-intl` and `react-intl`, where one `messages/{locale}.json` file groups several namespaces by its first-level keys, each addressed independently (e.g. `useTranslations('Hero')` resolves to the `Hero` dictionary).
+
+- `undefined` (default): **auto-detected** — the file is split when the `source` pattern has no `{key}` segment (one file holds every namespace), and kept as a single dictionary otherwise (one file per key).
+- `true`: always split each top-level key into its own dictionary.
+- `false`: never split; the whole file becomes a single dictionary.
+
+Given a single `messages/{locale}.json` file:
+
+```json fileName="messages/en.json"
+{
+  "Hero": { "title": "Full-stack developer" },
+  "Nav": { "work": "Work", "about": "About" },
+  "About": { "lead": "I build apps end to end." }
+}
+```
+
+```ts fileName="intlayer.config.ts"
+syncJSON({
+  format: "icu",
+  source: ({ locale }) => `./messages/${locale}.json`,
+  // splitKeys: true, // implied because the pattern has no `{key}` segment
+}),
+```
+
+This produces three dictionaries — `Hero`, `Nav`, and `About` — so `useTranslations('Hero')` (next-intl) resolves correctly. On write-back, all namespaces are re-assembled into the same per-locale file.
+
+> When you keep the explicit `{key}` segment in your `source` (e.g. `./locales/${locale}/${key}.json`), each file is already one namespace, so splitting is disabled by default.
+
 ### Multiple JSON sources and priority
 
 You can add multiple `syncJSON` plugins to synchronize different JSON sources. This is useful when you have multiple i18n libraries or different JSON structures in your project.
@@ -338,6 +373,9 @@ loadJSON({
 
   // Optional formatter for the JSON content
   format?: 'intlayer' | 'icu' | 'i18next', // default: 'intlayer'
+
+  // Split a single file into one dictionary per top-level key (auto-detected)
+  splitKeys?: boolean,
 });
 ```
 
@@ -359,10 +397,25 @@ loadJSON({
 }),
 ```
 
+#### `splitKeys` (boolean)
+
+Same behavior as in [`syncJSON`](#splitkeys-boolean): when a single JSON file groups several namespaces by its first-level keys, each top-level key becomes its own dictionary.
+
+- `undefined` (default): **auto-detected** — split when the `source` pattern has no `{key}` segment, single dictionary otherwise.
+- `true` / `false`: force or disable splitting.
+
+```ts
+loadJSON({
+  source: ({ locale }) => `./messages/${locale}.json`,
+  format: "icu",
+  // splitKeys auto-enabled: `Hero`, `Nav`, `About`, … each become a dictionary
+}),
+```
+
 ### Behavior and conventions
 
 - If your `source` mask includes a locale placeholder, only files for the selected `locale` are ingested.
-- If there is no `{key}` segment in your mask, the dictionary key is "index".
+- If there is no `{key}` segment in your mask, each top-level key of the file becomes its own dictionary by default (see [`splitKeys`](#splitkeys-boolean)). Set `splitKeys: false` to instead load the whole file as a single `index` dictionary.
 - Keys are derived from file paths by substituting the `{key}` placeholder in your `source` builder.
 - The plugin only uses discovered files and does not fabricate missing locales or keys.
 - The `fill` path is inferred from your `source` and used to update missing values via CLI when you opt‑in.

package/docs/en/releases/v8.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-09-22
-updatedAt: 2026-01-26
+updatedAt: 2026-06-14
 title: New Intlayer v8 - What's new?
 description: Discover what's new in Intlayer v8. Major improvements in developer experience, content validation, and dictionary management.
 keywords:
@@ -409,6 +409,16 @@ For more details, see the [HTML Content Documentation](https://github.com/aymeri
 
 ---
 
+## YAML & Markdown Content Files (v8.10.0)
+
+You can now declare content directly using the `.content.md` and `.content.yaml` file extensions. This is perfect for long-form content, blogs, documentation, and privacy policies.
+
+These files are fully editable from the Visual Editor, providing a streamlined workflow for non-technical team members.
+
+For more details, see the [YAML Content Files Documentation](https://intlayer.org/doc/concept/content#yaml-content-file) and [Markdown Content Files Documentation](https://intlayer.org/doc/concept/content/markdown).
+
+---
+
 ## Custom URL Rewrites
 
 Intlayer v8 introduces support for **Custom URL Rewrites**, allowing you to define locale-specific paths that differ from the standard `/locale/path` structure. This is a powerful feature for improving local SEO and providing a more natural user experience for non-English speakers.
@@ -753,6 +763,58 @@ export default {
   </Tab>
 </Tabs>
 
+## Unicode CLDR Plural Rules (v8.8.0)
+
+A new `plural` node helper has been introduced based on the plural rules defined by the Unicode CLDR Project, improving support for complex languages.
+
+```typescript fileName="src/openings.content.ts"
+import { plural, t, type Dictionary } from "intlayer";
+
+const openingsContent = {
+  key: "total_openings",
+  content: {
+    totalOpenings: t({
+      en: plural({
+        one: "{{count}} opening",
+        other: "{{count}} openings",
+      }),
+      fr: plural({
+        one: "{{count}} offre",
+        other: "{{count}} offres",
+      }),
+    }),
+  },
+} satisfies Dictionary;
+
+export default openingsContent;
+```
+
+You can then pass the count dynamically in your framework component:
+
+```tsx
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+const OpeningsComponent: FC<{ count: number }> = ({ count }) => {
+  const { totalOpenings } = useIntlayer("total_openings");
+
+  return (
+    <div>
+      {/* In English:                                  */}
+      {/*  count=0  → "0 openings"   (other)           */}
+      {/*  count=1  → "1 opening"    (one)             */}
+      {/*  count=2  → "2 openings"   (other)           */}
+      {/*  count=21 → "21 openings"  (other)           */}
+      <p>{totalOpenings(count)}</p>
+    </div>
+  );
+};
+```
+
+For more information, see the [Pluralization Documentation](https://intlayer.org/doc/concept/content/plural).
+
+---
+
 ## Content Schema Validation
 
 Intlayer v8 introduces schema validation for dictionaries. You can now define reusable validation schemas in your configuration using Zod and apply them to your content files. This ensures your content always adheres to the expected structure, catching errors at build time.
@@ -797,6 +859,34 @@ If the content doesn't match the schema (e.g., title is too short), the build pr
 
 ---
 
+## TypeScript: IntlayerNode Primitive Accessors
+
+The `IntlayerNode` type has been updated to allow calling primitive JavaScript methods directly on content nodes. This makes it possible to interact with your localized content directly as if it were a standard string, number, boolean, or array primitive.
+
+Supported across React, Preact, Solid, Svelte, Vue, and Angular.
+
+### String Example
+
+```typescript
+content.placeholder; // Returns IntlayerNode<string>
+content.placeholder.value; // Returns string
+content.placeholder.toString(); // Returns string
+content.placeholder.toLowerCase(); // Returns string
+String(content.placeholder); // Returns string
+content.placeholder.toUpperCase(); // Returns uppercased string
+content.placeholder.replace("a", "b"); // Returns modified string
+```
+
+### Array Example
+
+```typescript
+content.myArrayOfString             // Returns IntlayerNode<Array<string>>
+content.myArrayOfString.find(...)   // Returns element
+content.myArrayOfString.join(', ')  // Returns joined string
+```
+
+---
+
 ### Enhanced Automatic Content Detection
 
 In v8, Intlayer intelligently detects Markdown syntax, HTML tags, and variable insertions in your content strings. This means you can often omit helper functions like `md()`, `html()`, or `insert()`.
@@ -1002,6 +1092,17 @@ The Intlayer VSCode extension receives major updates in v8 to streamline your in
 
 ---
 
+## Tooling: C++ Watcher & OXC-based LSP (v8.12.0)
+
+Intlayer v8.12.0 brings major improvements to the developer experience:
+
+- **Parcel Watcher**: The content watcher has been migrated from `chokidar` to `@parcel/watcher`, leveraging native C++ file watching to provide faster updates and significantly lower memory consumption.
+- **New Language Server Protocol (LSP)**: A brand new LSP is now available. Built with OXC-based parsing, it helps your IDE and AI agents seamlessly link `useIntlayer('my-key')` calls with their corresponding `.content` files, and vice versa.
+
+For more details, see the [LSP Documentation](https://intlayer.org/doc/lsp).
+
+---
+
 ## Compiler Optimizations
 
 Intlayer v8 includes a new caching layer for the Markdown and HTML compiler. This ensures that identical content strings with the same configuration are only parsed once, significantly reducing the overhead during re-renders or when using the same content in multiple places.
@@ -1057,6 +1158,48 @@ Intlayer v8 includes a new caching layer for the Markdown and HTML compiler. Thi
 
 ---
 
+## Experimental Build Optimizations: Minify & Purge (v8.7.0)
+
+Intlayer v8.7.0 introduces new experimental build features in your `intlayer.config.ts` designed to optimize your production bundle:
+
+- **Dictionary Minification**: Minifies dictionary files to decrease size.
+- **Unused Key Purging**: Scans and removes unused translation keys from dictionaries, renaming active keys to short characters (e.g. `"products" -> "a"`, `"pricing" -> "b"`). This reduces bundle size by up to 5%.
+- **Disable TypeScript Checks**: Speed up builds by disabling TypeScript typechecking during the compilation step.
+
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  dictionary: {
+    importMode: "dynamic",
+  },
+  build: {
+    /**
+     * Minify the dictionaries to reduce the bundle size.
+     */
+    minify: true,
+
+    /**
+     * Purge the unused keys in dictionaries
+     */
+    purge: true,
+
+    /**
+     * Indicates if the build should check TypeScript types
+     */
+    checkTypes: false,
+  },
+};
+
+export default config;
+```
+
+---
+
 ## Flexibility: Unified Import Mode
 
 The `live` boolean property has been deprecated in favor of a more comprehensive `importMode` property. This allows for explicit definition of how dictionaries should be loaded: statically, dynamically, or via live sync.
@@ -1204,6 +1347,49 @@ Markdown and HTML content in Svelte now automatically parse to HTML when stringi
 
 ---
 
+## Angular Support: Vite Bundler (v8.11.0)
+
+For Angular users, Intlayer now natively supports the Vite bundler through a new custom esbuild plugin, speeding up development and build times.
+
+For details on configuration, see the [Angular Environment Documentation](https://intlayer.org/doc/environment/angular).
+
+---
+
+## Sitemap Generation (v8.6.0)
+
+Intlayer now generates sitemaps automatically based on your locales and routing mode. This is particularly useful for SEO optimization in router architectures like TanStack Router:
+
+```typescript fileName="src/routes/sitemap.xml.ts"
+import { createFileRoute } from "@tanstack/react-router";
+import { generateSitemap } from "intlayer";
+
+const SITE_URL = (
+  import.meta.env.VITE_SITE_URL ?? "http://localhost:3000"
+).replace(/\/$/, "");
+
+export const Route = createFileRoute("/sitemap.xml")({
+  server: {
+    handlers: {
+      GET: async () => {
+        const sitemap = generateSitemap(
+          [
+            { path: "/", changefreq: "daily", priority: 1.0 },
+            { path: "/about", changefreq: "monthly", priority: 0.8 },
+          ],
+          { siteUrl: SITE_URL }
+        );
+
+        return new Response(sitemap, {
+          headers: { "Content-Type": "application/xml" },
+        });
+      },
+    },
+  },
+});
+```
+
+---
+
 ## Migration notes from v7
 
 ### Configuration Changes