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

package/docs/en/dictionary/plurial.md

@@ -104,7 +104,10 @@ export default openingsContent;
 >
 > The `{{count}}` placeholder is automatically replaced with the count you pass at runtime. You can include other placeholders too (see [Custom placeholders](#custom-placeholders) below).
 
-## Using Plural Content with React Intlayer
+## Using Plural Content
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
 
 To use plural content inside a React component, retrieve it via the `useIntlayer` hook and call it with a count. The active locale and the count are combined to pick the matching CLDR category.
 
@@ -117,11 +120,6 @@ const OpeningsComponent: FC<{ count: number }> = ({ count }) => {
 
   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>
   );
@@ -130,13 +128,160 @@ const OpeningsComponent: FC<{ count: number }> = ({ count }) => {
 export default OpeningsComponent;
 ```
 
-You can call the returned function in two equivalent ways:
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+
+To use plural content in Next.js Client Components, retrieve it via the `useIntlayer` hook and call it with a count. Here's an example:
+
+```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
+"use client";
+
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer";
+
+const OpeningsComponent: FC<{ count: number }> = ({ count }) => {
+  const { totalOpenings } = useIntlayer("total_openings");
+
+  return (
+    <div>
+      <p>{totalOpenings(count)}</p>
+    </div>
+  );
+};
+
+export default OpeningsComponent;
+```
+
+  </Tab>
+  <Tab label="Vue" value="vue">
+
+To use plural content in Vue components, retrieve it via the `useIntlayer` hook and call it with a count. Here's an example:
+
+```vue fileName="**/*.vue"
+<script setup lang="ts">
+import { useIntlayer } from "vue-intlayer";
+
+defineProps<{ count: number }>();
+
+const { totalOpenings } = useIntlayer("total_openings");
+</script>
+
+<template>
+  <div>
+    <p>{{ totalOpenings(count) }}</p>
+  </div>
+</template>
+```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+
+To use plural content in Svelte components, retrieve it via the `useIntlayer` hook and call it with a count. The store is accessed with `$`. Here's an example:
+
+```svelte fileName="**/*.svelte"
+<script lang="ts">
+import { useIntlayer } from "svelte-intlayer";
+
+export let count: number;
+
+const content = useIntlayer("total_openings");
+</script>
+
+<div>
+  <p>{$content.totalOpenings(count)}</p>
+</div>
+```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+
+To use plural content in Preact components, retrieve it via the `useIntlayer` hook and call it with a count. Here's an example:
+
+```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
+import type { FC } from "preact";
+import { useIntlayer } from "preact-intlayer";
+
+const OpeningsComponent: FC<{ count: number }> = ({ count }) => {
+  const { totalOpenings } = useIntlayer("total_openings");
+
+  return (
+    <div>
+      <p>{totalOpenings(count)}</p>
+    </div>
+  );
+};
+
+export default OpeningsComponent;
+```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+
+To use plural content in SolidJS components, retrieve it via the `useIntlayer` hook and call it with a count. Here's an example:
+
+```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
+import type { Component } from "solid-js";
+import { useIntlayer } from "solid-intlayer";
+
+const OpeningsComponent: Component<{ count: number }> = (props) => {
+  const { totalOpenings } = useIntlayer("total_openings");
+
+  return (
+    <div>
+      <p>{totalOpenings(props.count)}</p>
+    </div>
+  );
+};
+
+export default OpeningsComponent;
+```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+
+To use plural content in Angular components, retrieve it via the `useIntlayer` hook and call it with a count. Here's an example:
+
+```typescript fileName="app.component.ts" codeFormat="typescript"
+import { Component, Input } from "@angular/core";
+import { useIntlayer } from "angular-intlayer";
+
+@Component({
+  selector: "app-openings",
+  template: `
+    <div>
+      <p>{{ content().totalOpenings(count) }}</p>
+    </div>
+  `,
+})
+export class OpeningsComponent {
+  @Input() count!: number;
+
+  content = useIntlayer("total_openings");
+}
+```
+
+  </Tab>
+  <Tab label="Vanilla JS" value="vanilla">
 
-```tsx
-totalOpenings(21); // shorthand: count only
-totalOpenings({ count: 21 }); // explicit form
+To use plural content with `vanilla-intlayer`, retrieve it via the `useIntlayer` hook and call it with a count. Here's an example:
+
+```typescript fileName="**/*.ts" codeFormat={["typescript", "esm"]}
+import { installIntlayer, useIntlayer } from "vanilla-intlayer";
+
+installIntlayer();
+
+const content = useIntlayer("total_openings").onChange((newContent) => {
+  document.getElementById("openings")!.textContent =
+    newContent.totalOpenings(5);
+});
+
+// Initial render
+document.getElementById("openings")!.textContent = content.totalOpenings(5);
 ```
 
+  </Tab>
+</Tabs>
+
 ## Custom placeholders
 
 Plural strings can include placeholders other than `{{count}}`. Pass them in the object form alongside `count`:

package/docs/en/dictionary/translation.md

@@ -83,7 +83,10 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-## Using Translations in React Components
+## Using Translations
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
 
 With `react-intlayer`, you can use translations in React components. Here's an example:
 
@@ -106,63 +109,153 @@ export default MyComponent;
 
 This component fetches the corresponding translation based on the current locale set in your application.
 
-## Custom Content Objects
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
 
-`intlayer` supports custom content objects for translation, allowing you to define more complex structures while ensuring type safety. Here's an example with a custom object:
+With `next-intlayer`, you can use translations in React Server Components or Client Components. Here's an example in a Client Component:
 
-```typescript fileName="**/*.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
-import { t, type Dictionary } from "intlayer";
+```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
+"use client";
 
-interface ICustomContent {
-  title: string;
-  content: string;
-}
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer";
 
-const customContent = {
-  key: "custom_content",
-  content: {
-    profileText: t<ICustomContent>({
-      en: {
-        title: "Page Title",
-        content: "Page Content",
-      },
-      fr: {
-        title: "Titre de la Page",
-        content: "Contenu de la Page",
-      },
-      es: {
-        title: "Título de la Página",
-        content: "Contenido de la Página",
-      },
-    }),
-  },
-} satisfies Dictionary;
+const MyComponent: FC = () => {
+  const content = useIntlayer("multi_lang");
 
-export default customContent;
+  return (
+    <div>
+      <p>{content.welcomeMessage}</p>
+    </div>
+  );
+};
+
+export default MyComponent;
 ```
 
-```json fileName="**/*.content.json" contentDeclarationFormat="json"
-{
-  "$schema": "https://intlayer.org/schema.json",
-  "key": "custom_content",
-  "content": {
-    "profileText": {
-      "nodeType": "translation",
-      "translation": {
-        "en": {
-          "title": "Page Title",
-          "content": "Page Content"
-        },
-        "fr": {
-          "title": "Titre de la Page",
-          "content": "Contenu de la Page"
-        },
-        "es": {
-          "title": "Título de la Página",
-          "content": "Contenido de la Página"
-        }
-      }
-    }
-  }
+  </Tab>
+  <Tab label="Vue" value="vue">
+
+With `vue-intlayer`, you can use translations in Vue components. Here's an example:
+
+```vue fileName="**/*.vue"
+<script setup lang="ts">
+import { useIntlayer } from "vue-intlayer";
+
+const content = useIntlayer("multi_lang");
+</script>
+
+<template>
+  <div>
+    <p>{{ content.welcomeMessage }}</p>
+  </div>
+</template>
+```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+
+With `svelte-intlayer`, you can use translations in Svelte components. The hook returns a Svelte store. Here's an example:
+
+```svelte fileName="**/*.svelte"
+<script lang="ts">
+import { useIntlayer } from "svelte-intlayer";
+
+const content = useIntlayer("multi_lang");
+</script>
+
+<div>
+  <p>{$content.welcomeMessage}</p>
+</div>
+```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+
+With `preact-intlayer`, you can use translations in Preact components. Here's an example:
+
+```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
+import type { FC } from "preact";
+import { useIntlayer } from "preact-intlayer";
+
+const MyComponent: FC = () => {
+  const content = useIntlayer("multi_lang");
+
+  return (
+    <div>
+      <p>{content.welcomeMessage}</p>
+    </div>
+  );
+};
+
+export default MyComponent;
+```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+
+With `solid-intlayer`, you can use translations in SolidJS components. Here's an example:
+
+```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
+import type { Component } from "solid-js";
+import { useIntlayer } from "solid-intlayer";
+
+const MyComponent: Component = () => {
+  const content = useIntlayer("multi_lang");
+
+  return (
+    <div>
+      <p>{content.welcomeMessage}</p>
+    </div>
+  );
+};
+
+export default MyComponent;
+```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+
+With `angular-intlayer`, you can use translations in Angular components. Here's an example:
+
+```typescript fileName="app.component.ts" codeFormat="typescript"
+import { Component } from "@angular/core";
+import { useIntlayer } from "angular-intlayer";
+
+@Component({
+  selector: "app-my-component",
+  template: `
+    <div>
+      <p>{{ content().welcomeMessage }}</p>
+    </div>
+  `,
+})
+export class MyComponent {
+  content = useIntlayer("multi_lang");
 }
 ```
+
+  </Tab>
+  <Tab label="Vanilla JS" value="vanilla">
+
+With `vanilla-intlayer`, you can use translations by subscribing to content changes. Here's an example:
+
+```typescript fileName="**/*.ts" codeFormat={["typescript", "esm"]}
+import { installIntlayer, useIntlayer } from "vanilla-intlayer";
+
+installIntlayer();
+
+const content = useIntlayer("multi_lang").onChange((newContent) => {
+  document.getElementById("welcome-message")!.textContent = String(
+    newContent.welcomeMessage
+  );
+});
+
+// Initial render
+document.getElementById("welcome-message")!.textContent = String(
+  content.welcomeMessage
+);
+```
+
+  </Tab>
+</Tabs>

package/docs/en/dynamic_dictionaries/collections.md

@@ -14,7 +14,7 @@ slugs:
   - concept
   - collections
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-12
     changes: "Release of the collection dictionaries feature"
 author: aymericzip

package/docs/en/dynamic_dictionaries/dynamic_content.md

@@ -15,7 +15,7 @@ slugs:
   - concept
   - dynamic-records
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-12
     changes: "Release of the dynamic content feature"
 author: aymericzip

package/docs/en/dynamic_dictionaries/index.md

@@ -15,7 +15,7 @@ slugs:
   - concept
   - dynamic-dictionaries
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-12
     changes: "Release of the dynamic dictionaries feature"
 author: aymericzip

package/docs/en/dynamic_dictionaries/variants.md

@@ -15,7 +15,7 @@ slugs:
   - concept
   - variants
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-12
     changes: "Release of the variants feature"
 author: aymericzip

package/docs/en/migration_from_i18next_to_intlayer.md

@@ -16,7 +16,7 @@ slugs:
   - migration
   - i18next
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-05
     changes: "Init history"
 author: aymericzip

package/docs/en/migration_from_next-i18next_to_intlayer.md

@@ -19,7 +19,7 @@ slugs:
   - migration
   - next-i18next
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-05
     changes: "Init history"
 author: aymericzip

package/docs/en/migration_from_next-intl_to_intlayer.md

@@ -17,7 +17,7 @@ slugs:
   - migration
   - next-intl
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-05
     changes: "Init history"
 author: aymericzip

package/docs/en/migration_from_nuxtjs_i18n_to_intlayer.md

@@ -18,7 +18,7 @@ slugs:
   - migration
   - nuxtjs-i18n
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-05
     changes: "Init history"
 author: aymericzip

package/docs/en/migration_from_react-i18next_to_intlayer.md

@@ -18,7 +18,7 @@ slugs:
   - migration
   - react-i18next
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-05
     changes: "Init history"
 author: aymericzip

package/docs/en/migration_from_vue-i18n_to_intlayer.md

@@ -17,7 +17,7 @@ slugs:
   - migration
   - vue-i18n
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-05
     changes: "Init history"
 author: aymericzip

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"
@@ -182,6 +185,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 +210,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 +374,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 +398,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.