@intlayer/docs 9.0.0-canary.2 → 9.0.0-canary.20

package/docs/en-GB/intlayer_with_vite+vue.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-04-18
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "Vite + Vue i18n - Complete guide to translate your app"
 description: "No more i18next. The 2026 guide to building a multilingual (i18n) Vite + Vue app. Translate with AI agents and optimise bundle size, SEO and performances."
 keywords:
@@ -34,6 +34,10 @@ author: aymericzip
 
 See [Application Template](https://github.com/aymericzip/intlayer-vite-vue-template) on GitHub.
 
+## Table of Contents
+
+<TOC/>
+
 ## Why Intlayer over alternatives?
 
 Compared to main solutions like `vue-i18n` or `i18next`, Intlayer is a solution that comes with integrated optimizations such as:
@@ -89,7 +93,7 @@ More than just an i18n solution, Intlayer provides an **self-hosted [visual edit
 
 <Tabs defaultTab="video">
   <Tab label="Video" value="video">
-  
+
 <iframe title="The best i18n solution for Vite and Vue? Discover Intlayer" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/IE3XWkZ6a5U?autoplay=0&amp;origin=https://intlayer.org&amp;controls=0&amp;rel=1"/>
 
   </Tab>
@@ -125,28 +129,48 @@ See [Application Template](https://github.com/aymericzip/intlayer-vite-vue-templ
 
 Install the necessary packages using npm:
 
+```bash packageManager="npm"
+npx intlayer@canary init --interactive    # v9
+# npx intlayer init                       # v8
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer@canary init --interactive   # v9
+# pnpm dlx intlayer init                      # v8
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer@canary init --interactive   # v9
+# yarn dlx intlayer init                      # v8
+```
+
+```bash packageManager="bun"
+bunx intlayer@canary init --interactive   # v9
+# bunx intlayer init                      # v8
+```
+
+> the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.
+
+> This command will detect your environment and install the required packages. For example:
+
 ```bash packageManager="npm"
 npm install intlayer vue-intlayer
 npm install vite-intlayer --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer vue-intlayer
 pnpm add vite-intlayer --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer vue-intlayer
 yarn add vite-intlayer --save-dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer vue-intlayer
 bun add vite-intlayer --dev
-bun x intlayer init
 ```
 
 - **intlayer**
@@ -607,14 +631,17 @@ In parallel, you can also use the `intlayerProxy` to add server-side routing to
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
 import vue from "@vitejs/plugin-vue";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // should be placed first
     vue(),
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```
@@ -833,157 +860,6 @@ useI18nHTMLAttributes();
 
 </Step>
 
-<Step number={10} title="Creating a Localised Link Component" isOptional={true}>
-
-To ensure that your application’s navigation respects the current locale, you can create a custom `Link` component. This component automatically prefixes internal URLs with the current language. For example, when a French-speaking user clicks on a link to the "About" page, they are redirected to `/fr/about` instead of `/about`.
-
-This behaviour is useful for several reasons:
-
-- **SEO and User Experience**: Localised URLs help search engines index language-specific pages correctly and provide users with content in their preferred language.
-- **Consistency**: By using a localised link throughout your application, you guarantee that navigation stays within the current locale, preventing unexpected language switches.
-- **Maintainability**: Centralising the localisation logic in a single component simplifies the management of URLs, making your codebase easier to maintain and extend as your application grows.
-
-```vue fileName="src/components/Link.vue"
-<template>
-  <a :href="localizedHref" v-bind="$attrs">
-    <slot />
-  </a>
-</template>
-
-<script setup lang="ts">
-import { computed } from "vue";
-import { getLocalizedUrl } from "intlayer";
-import { useLocale } from "vue-intlayer";
-
-const props = defineProps({
-  href: {
-    type: String,
-    required: true,
-  },
-});
-
-const { locale } = useLocale();
-
-// Check if the link is external
-const isExternalLink = computed(() => /^https?:\/\//.test(props.href || ""));
-
-// Create a localised href for internal links
-const localizedHref = computed(() =>
-  isExternalLink.value ? props.href : getLocalizedUrl(props.href, locale.value)
-);
-</script>
-```
-
-For use with Vue Router, create a router-specific version:
-
-```vue fileName="src/components/RouterLink.vue"
-<template>
-  <router-link :to="localizedTo" v-bind="$attrs">
-    <slot />
-  </router-link>
-</template>
-
-<script setup lang="ts">
-import { computed } from "vue";
-import { getLocalizedUrl } from "intlayer";
-import { useLocale } from "vue-intlayer";
-
-const props = defineProps({
-  to: {
-    type: [String, Object],
-    required: true,
-  },
-});
-
-const { locale } = useLocale();
-
-// Create localised to-prop for router-link
-const localizedTo = computed(() => {
-  if (typeof props.to === "string") {
-    return getLocalizedUrl(props.to, locale.value);
-  } else {
-    // If 'to' is an object, localise the path property
-    return {
-      ...props.to,
-      path: getLocalizedUrl(props.to.path ?? "/", locale.value),
-    };
-  }
-});
-</script>
-```
-
-Use these components in your application:
-
-```vue fileName="src/App.vue"
-<template>
-  <div>
-    <!-- Vue router  -->
-    <RouterLink to="/">Root</RouterLink>
-    <RouterLink to="/home">Home</RouterLink>
-    <!-- Other -->
-    <Link href="/">Root</Link>
-    <Link href="/home">Home</Link>
-  </div>
-</template>
-
-<script setup lang="ts">
-import Link from "@components/Link.vue";
-import RouterLink from "@components/RouterLink.vue";
-</script>
-```
-
-</Step>
-
-<Step number={11} title="Render Markdown" isOptional={true}>
-
-Intlayer supports rendering Markdown content directly in your Vue application. By default, Markdown is treated as plain text. To convert Markdown into rich HTML, you can integrate [markdown-it](https://github.com/markdown-it/markdown-it), a Markdown parser.
-
-This is particularly useful when your translations include formatted content such as lists, links, or emphasis.
-
-By default, Intlayer renders Markdown as a string. However, Intlayer also provides a way to render Markdown into HTML using the `installIntlayerMarkdown` function.
-
-> To see how to declare Markdown content using the `intlayer` package, see the [markdown doc](https://github.com/aymericzip/intlayer/tree/main/docs/docs/en-GB/dictionary/markdown.md).
-
-```ts fileName="main.ts"
-import MarkdownIt from "markdown-it";
-import { createApp, h } from "vue";
-import { installIntlayer, installIntlayerMarkdown } from "vue-intlayer";
-
-const app = createApp(App);
-
-app.use(intlayer);
-
-const md = new MarkdownIt({
-  html: true, // allow HTML tags
-  linkify: true, // auto-link URLs
-  typographer: true, // enable smart quotes, dashes, etc.
-});
-
-// Tell Intlayer to use md.render() whenever it needs to turn markdown into HTML
-installIntlayerMarkdown(app, (markdown) => {
-  const html = md.render(markdown);
-  return h("div", { innerHTML: html });
-});
-```
-
-Once registered, you can use the component-based syntax to display the Markdown content directly:
-
-```vue
-<template>
-  <div>
-    <myMarkdownContent />
-  </div>
-</template>
-
-<script setup lang="ts">
-import { useIntlayer } from "vue-intlayer";
-
-const { myMarkdownContent } = useIntlayer("my-component");
-</script>
-```
-
-</Step>
-
 </Steps>
 
 ### (Optional) Sitemap and robots.txt (build-time)
@@ -1062,13 +938,13 @@ Adjust if you use pnpm or yarn. You can also invoke the same script from CI or a
 
 ### Configure TypeScript
 
-Intlayer uses module augmentation to leverage the benefits of TypeScript and strengthen your codebase.
+Intlayer uses module augmentation to take advantage of TypeScript and make your codebase stronger.
 
 ![Autocompletion](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
 
 ![Translation error](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
 
-Ensure your TypeScript configuration includes the auto-generated types.
+Ensure your TypeScript configuration includes the autogenerated types.
 
 ```json5 fileName="tsconfig.json"
 {
@@ -1082,7 +958,7 @@ Ensure your TypeScript configuration includes the auto-generated types.
 
 ### Git Configuration
 
-It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.
+It is recommended to ignore the files generated by Intlayer. This prevents you from committing them to your Git repository.
 
 To do this, you can add the following instructions to your `.gitignore` file:
 
@@ -1093,7 +969,7 @@ To do this, you can add the following instructions to your `.gitignore` file:
 
 ### VS Code Extension
 
-To improve your development experience with Intlayer, you can install the official **Intlayer VS Code Extension**.
+To enhance your development experience with Intlayer, you can install the official **Intlayer VS Code Extension**.
 
 [Install from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
 
@@ -1104,28 +980,6 @@ This extension provides:
 - **Inline previews** of translated content.
 - **Quick actions** to easily create and update translations.
 
-It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.
-
-To do this, you can add the following instructions to your `.gitignore` file:
-
-```bash
-# Ignore the files generated by Intlayer
-.intlayer
-```
-
-### VS Code Extension
-
-To improve your development experience with Intlayer, you can install the official **Intlayer VS Code Extension**.
-
-[Install from the VS Code Marketplace](https://marketplace.visualstudio.com/items?=itemName=intlayer.intlayer-vs-code-extension)
-
-This extension provides:
-
-- **Autocompletion** for translation keys.
-- **Real-time error detection** for missing translations.
-- **Inline previews** of translated content.
-- **Quick actions** to easily create and update translations.
-
 For more details on how to use the extension, refer to the [Intlayer VS Code Extension documentation](https://intlayer.org/doc/vs-code-extension).
 
 ---
@@ -1133,5 +987,3 @@ For more details on how to use the extension, refer to the [Intlayer VS Code Ext
 ### Go Further
 
 To go further, you can implement the [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_visual_editor.md) or externalise your content using the [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md).
-
----

package/docs/en-GB/live-sync.md

@@ -0,0 +1,173 @@
+---
+createdAt: 2026-07-08
+updatedAt: 2026-07-08
+title: Live Sync | Reflect CMS content changes at runtime
+description: Let your app reflect Intlayer CMS content changes at runtime, with no rebuild or redeploy required.
+keywords:
+  - Live Sync
+  - CMS
+  - Visual Editor
+  - Internationalisation
+  - Documentation
+  - Intlayer
+  - Next.js
+  - Vite
+history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "Extracted from the Intlayer CMS documentation into its own page"
+  - version: 6.0.1
+    date: 2025-09-22
+    changes: "Add live sync documentation"
+  - version: 6.0.0
+    date: 2025-09-04
+    changes: "Replace `hotReload` field with `liveSync`"
+author: aymericzip
+---
+
+# Live sync
+
+Live Sync allows your app to reflect CMS content changes at runtime. No rebuild or redeploy is required. When enabled, updates are streamed to a Live Sync server that refreshes the dictionaries your application reads.
+
+## Table of contents
+
+<TOC/>
+
+---
+
+## Enabling Live Sync
+
+> Live Sync requires a continuous server connection and is available on the enterprise plan.
+
+Enable Live Sync by updating your Intlayer configuration:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... other configuration settings
+  editor: {
+    /**
+     * Enables hot reloading of locale configurations when changes are detected.
+     * For example, when a dictionary is added or updated, the application updates
+     * the content displayed on the page.
+     *
+     * Because hot reloading requires a continuous connection to the server, it is
+     * only available for clients of the `enterprise` plan.
+     *
+     * Default: false
+     */
+    liveSync: true,
+  },
+  dictionary: {
+    /**
+     * Controls how dictionaries are imported:
+     *
+     * - "fetch": Dictionaries are fetched dynamically using the Live Sync API.
+     *   Replaces useIntlayer with useDictionaryDynamic.
+     *
+     * Note: Live mode uses the Live Sync API to fetch dictionaries. If the API call
+     * fails, dictionaries are imported dynamically.
+     * Note: Only dictionaries with remote content and "live" flags use live mode.
+     * Others use dynamic mode for performance.
+     */
+    importMode: "fetch",
+  },
+};
+
+export default config;
+```
+
+Start the Live Sync server to wrap your application:
+
+Example using Next.js:
+
+```json5 fileName="package.json"
+{
+  "scripts": {
+    // ... other scripts
+    "build": "next build",
+    "dev": "next dev",
+    "start": "npx intlayer live --with 'next start'",
+  },
+}
+```
+
+Example using Vite:
+
+```json5 fileName="package.json"
+{
+  "scripts": {
+    // ... other scripts
+    "build": "vite build",
+    "dev": "vite dev",
+    "start": "npx intlayer live --with 'vite start'",
+  },
+}
+```
+
+The Live Sync server wraps your application and automatically applies updated content as it arrives.
+
+To receive change notifications from the CMS, the Live Sync server maintains an SSE connection to the backend. When content changes in the CMS, the backend forwards the update to the Live Sync server, which writes the new dictionaries. Your application will reflect the update on the next navigation or browser reload, no rebuild required.
+
+Flow chart (CMS/Backend -> Live Sync Server -> Application Server -> Frontend):
+
+![Live Sync Logic Schema](https://github.com/aymericzip/intlayer/blob/main/docs/assets/live_sync_logic_schema.svg)
+
+How it works:
+
+![Live Sync Flow CMS/Backend/Live Sync Server/Application Server/Frontend Schema](https://github.com/aymericzip/intlayer/blob/main/docs/assets/live_sync_flow_scema.svg)
+
+## Development workflow (local)
+
+- In development, all remote dictionaries are fetched when the application starts, so you can test updates quickly.
+- To test Live Sync locally with Next.js, wrap your dev server:
+
+```json5 fileName="package.json"
+{
+  "scripts": {
+    // ... other scripts
+    "dev": "npx intlayer live --with 'next dev'",
+    // "dev": "npx intlayer live --with 'vite dev'", // For Vite
+  },
+}
+```
+
+Enable optimisation so Intlayer applies the Live import transformations during development:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    applicationURL: "http://localhost:5173",
+    liveSyncURL: "http://localhost:4000",
+    liveSync: true,
+  },
+  dictionary: {
+    importMode: "fetch",
+  },
+  build: {
+    optimize: true,
+  },
+};
+
+export default config;
+```
+
+This setup wraps your dev server with the Live Sync server, fetches remote dictionaries at startup, and streams updates from the CMS via SSE. Refresh the page to see changes.
+
+## Notes and constraints
+
+- Add the live sync origin to your site security policy (CSP). Ensure the live sync URL is allowed in `connect-src` (and `frame-ancestors` if relevant).
+- Live Sync does not work with static output. For Next.js, the page must be dynamic to receive updates at runtime (e.g., use `generateStaticParams`, `generateMetadata`, `getServerSideProps`, or `getStaticProps` appropriately to avoid full static-only constraints).
+- In the CMS, each dictionary has a `live` flag. Only dictionaries with `live=true` are fetched via the live sync API; others are imported dynamically and remain unchanged at runtime.
+- The `live` flag is evaluated for each dictionary at build time. If remote content was not flagged `live=true` during build, you must rebuild to enable Live Sync for that dictionary.
+- The live sync server must be able to write to `.intlayer`. In containers, ensure write access to `/.intlayer`.
+
+## Useful links
+
+- [Intlayer CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md)
+- [Intlayer Visual Editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_visual_editor.md)
+- [Configuration Reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md)
+- [Self-Hosting Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/self_hosting.md)