@intlayer/docs 9.4.0-canary.0 → 9.4.0

package/docs/en-GB/cli/fill.md

@@ -39,14 +39,6 @@ bun x intlayer fill
 
 This command analyses your content declaration files for potential issues such as missing translations, structural inconsistencies, or type mismatches. If it finds any problems, **intlayer fill** will propose or apply updates to keep your dictionaries consistent and complete.
 
-Key Points:
-
-- Splits large JSON files into chunks to stay within the AI model's context window limits.
-- Retries translation if the output format is incorrect.
-- Incorporates application and file-specific context for improved translation accuracy.
-- Preserves existing translations by not overwriting them.
-- Processes files, chunks, and locales in parallel using a queue system to increase speed.
-
 ## Key Points:
 
 - Splits large JSON files into chunks to stay within the AI model's context window limits.

package/docs/en-GB/cli/index.md

@@ -127,6 +127,8 @@ To learn how to configure the available languages or other parameters, take a lo
 
 - **[Login](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/login.md)** - Authenticate with the Intlayer CMS and get the access credentials
 
+> `intlayer login` issues an **access key** (`clientId` / `clientSecret`) that every credentialed command uses. The secret is a server-side credential and never reaches your client bundle — see [Keeping the access key safe](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/login.md#keeping-the-access-key-safe).
+
 ### Core Commands
 
 - **[Build Dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/build.md)** - Build your dictionaries from your content declaration files

package/docs/en-GB/cli/list_projects.md

@@ -52,8 +52,6 @@ This command searches for and lists all Intlayer projects by finding directories
 
   > Example: `npx intlayer projects list --base-dir /path/to/workspace`
 
-  > Example: `npx intlayer projects list --base-dir /path/to/workspace`
-
 - **`--git-root`**: Search from the git root directory rather than the base directory. This is useful for finding all Intlayer projects in a monorepo or git repository.
 
   > Example: `npx intlayer projects list --git-root`

package/docs/en-GB/cli/login.md

@@ -118,6 +118,34 @@ INTLAYER_CLIENT_SECRET=your_client_secret
 }
 ```
 
+## Keeping the access key safe
+
+`intlayer login` issues an **access key**: a `clientId` / `clientSecret` pair that every credentialed command (`push`, `pull`, `fill`, `configuration push`, `live`, …) uses to authenticate.
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+};
+
+export default config;
+```
+
+> **`clientSecret` is a server-side credential.** It grants full project-scoped API access — reading and writing your dictionaries, your project and your organisation. Keep it in `.env` (git-ignored) or your CI secret store, and never inline it in the configuration file.
+
+Intlayer enforces this rather than only documenting it:
+
+- `clientSecret` is **stripped from the configuration your bundler inlines**, so it cannot reach a browser bundle whatever framework integration you use. It is only ever read server-side, at runtime, from the environment.
+- `clientId` is different: it is the **public** project key, safe to ship, and used by [`@intlayer/analytics`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md#how-events-are-authenticated) to obtain a short-lived, ingest-only token.
+
+Commenting `clientId` out is enough to disable every credentialed behaviour — remote dictionary fetching, CMS access, analytics — even when the environment variables are still defined.
+
+For CI pipelines, prefer the [`ci` command](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/ci.md), which injects the credentials for the duration of a single run instead of persisting them.
+
 ## Manual Configuration
 
 If the browser does not open automatically, you can manually visit the URL displayed in the terminal.

package/docs/en-GB/compiler.md

@@ -40,6 +40,12 @@ The **Intlayer Compiler** is a powerful tool designed to automate the process of
 
 ## Why Use the Intlayer Compiler?
 
+- **Automation**: Eliminates manual copy-pasting of content into dictionaries.
+
+- **Speed**: Optimised content extraction ensuring your build process remains fast.
+
+- **Developer Experience**: Keep content declarations right where they are used, improving maintainability.
+
 - **Automation**: Eliminates manual copy-pasting of content into dictionaries.
 - **Speed**: Optimised content extraction ensuring your build process remains fast.
 - **Developer Experience**: Keep content declarations right where they are used, improving maintainability.
@@ -54,6 +60,8 @@ Whilst the compiler offers an excellent "just works" experience, it also introdu
 - **Heuristic ambiguity**: The compiler must guess what is user-facing content vs. application logic (e.g., `className="active"`, status codes, product IDs). In complex codebases, this can lead to false positives or missed strings that require manual annotations and exceptions.
 - **Static-only extraction**: Compiler-based extraction relies on static analysis. Strings that only exist at runtime (API error codes, CMS fields, etc.) cannot be discovered or translated by the compiler alone, so you still need a complementary runtime i18n strategy.
 
+- **Static-only extraction**: Compiler-based extraction relies on static analysis. Strings that only exist at runtime (API error codes, CMS fields, etc.) cannot be discovered or translated by the compiler alone, so you still need a complementary runtime i18n strategy.
+
 For a deeper architectural comparison, see the blog post [Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en-GB/compiler_vs_declarative_i18n.md).
 
 As an alternative, to automate your i18n process whilst keeping full control of your content, Intlayer also provides an auto-extraction command `intlayer extract` (see [CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/extract.md)), or the `Intlayer: extract content to Dictionary` command from the Intlayer VS Code extension (see [VS Code extension documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/vs_code_extension.md)).
@@ -94,12 +102,18 @@ export default defineConfig({
 });
 ```
 
+> The standalone `intlayerCompiler()` plugin is still exported for advanced setups. Registering it alongside `intlayer()` is safe — the compiler deduplicates itself and runs only once.
+
 See complete tutorial: [Intlayer Compiler with Vite+React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_vite+react_compiler.md)
 
 #### Framework Support
 
 The Vite plugin automatically detects and handles different file types:
 
+- **React / JSX / TSX**: Handled natively.
+
+- **Vue**: Requires `@intlayer/vue-compiler`.
+
 - **React / JSX / TSX**: Handled natively.
 - **Vue**: Requires `@intlayer/vue-compiler`.
 - **Svelte**: Requires `@intlayer/svelte-compiler`.

package/docs/en-GB/custom_domains.md

@@ -138,6 +138,38 @@ getMultilingualUrls("/about", { currentDomain: "intlayer.org" });
 
 These absolute URLs are ready to use in `<link rel="alternate" hreflang="...">` tags for SEO.
 
+## Type Inference
+
+`routing.domains` is serialized into the generated module augmentation, so
+`getLocalizedUrl` and `getLocalizedPath` narrow their return type to the exact
+URL a domain-routed locale resolves to — the prefix suppression included.
+
+```ts
+// routing: { mode: 'prefix-no-default', domains: { en: 'intlayer.org', zh: 'intlayer.zh' } }
+
+getLocalizedUrl("/about", "zh");
+//     ^? "https://intlayer.zh/about" | "/about"
+
+getLocalizedPath("/about", "zh");
+//     ^? "/about"   (never an origin, and no /zh/ prefix)
+```
+
+The URL type is the **union** of the two values the function can return: the
+absolute URL on the locale's domain, and the relative one it returns when the
+page being rendered already lives on that domain. `getLocalizedPath` has no such
+ambiguity - it never emits an origin - so it stays a single literal.
+
+Locales that share a domain keep their normal prefix in the type as well:
+
+```ts
+getLocalizedUrl("/about", "fr");
+//     ^? "https://intlayer.org/fr/about" | "/fr/about"
+```
+
+> Regenerate the types (`npx intlayer build`, or any dev server run) after
+> changing `routing.domains` - the narrowing comes from the generated
+> `__RoutingRegistry`, not from the config file itself.
+
 ## Proxy Behaviour
 
 ### Next.js
@@ -170,6 +202,8 @@ GET intlayer.zh/about
 
 The `intlayerProxy` Vite plugin applies the same logic during development:
 
+> Since Intlayer v9, `intlayerProxy()` is bundled directly into the `intlayer()` plugin and enabled by default through the `routing.enableProxy` option (`true` by default). Registering it separately as shown below is now optional — it is kept for backward compatibility and for setups that need to control plugin order. Set `routing.enableProxy: false` to opt out. See the [v9 release notes](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/releases/v9.md).
+
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
 import { intlayer } from "vite-intlayer";

package/docs/en-GB/custom_url_rewrites.md

@@ -248,7 +248,7 @@ To ensure that the browser's address bar always reflects the "pretty" localised
 
 <Tabs group='framework'>
   <Tab label="Next.js" value="nextjs">
-  
+
     ```tsx
     'use client';
 
@@ -263,7 +263,7 @@ To ensure that the browser's address bar always reflects the "pretty" localised
   </Tab>
 
   <Tab label="React Router" value="reactrouter">
-  
+
     ```tsx
     'use client';
 
@@ -279,7 +279,7 @@ To ensure that the browser's address bar always reflects the "pretty" localised
   </Tab>
 
   <Tab label="Vue" value="vue">
-  
+
     ```vue
     <script setup>
     import { useRewriteURL } from "vue-intlayer";
@@ -291,7 +291,7 @@ To ensure that the browser's address bar always reflects the "pretty" localised
 
   </Tab>
   <Tab label="Solid" value="solid">
-  
+
     ```tsx
     import { useRewriteURL } from "solid-intlayer";
 
@@ -303,7 +303,7 @@ To ensure that the browser's address bar always reflects the "pretty" localised
 
   </Tab>
   <Tab label="Svelte" value="svelte">
-  
+
     ```svelte
     <script>
     import { useRewriteURL } from "svelte-intlayer";
@@ -340,6 +340,8 @@ export function middleware(request: NextRequest) {
 
 For SolidJS, Vue, and Svelte, the `intlayerProxy` Vite plugin manages the rewrites during development.
 
+> Since Intlayer v9, `intlayerProxy()` is bundled directly into the `intlayer()` plugin and enabled by default through the `routing.enableProxy` option (`true` by default). Registering it separately as shown below is now optional — it is kept for backward compatibility and for setups that need to control plugin order. Set `routing.enableProxy: false` to opt out. See the [v9 release notes](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/releases/v9.md).
+
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
 import { intlayer } from "vite-intlayer";

package/docs/en-GB/dictionary/condition.md

@@ -27,209 +27,8 @@ author: aymericzip
 
 ## How Condition Works
 
-<Tabs group="framework">
-  <Tab label="React" value="react">
-
-To utilize conditional content within a React component, import and use the `useIntlayer` hook from the `react-intlayer` package. This hook fetches the content for the specified key and allows you to pass in a condition to select the appropriate output.
-
-```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
-import type { FC } from "react";
-import { useIntlayer } from "react-intlayer";
-
-const ConditionalComponent: FC = () => {
-  const { myCondition } = useIntlayer("my_key");
-
-  return (
-    <div>
-      <p>
-        {
-          /* Output: my content when it's true */
-          myCondition(true)
-        }
-      </p>
-      <p>
-        {
-          /* Output: my content when it's false */
-          myCondition(false)
-        }
-      </p>
-      <p>
-        {
-          /* Output: my content when the condition fails */
-          myCondition("")
-        }
-      </p>
-      <p>
-        {
-          /* Output: my content when the condition fails */
-          myCondition(undefined)
-        }
-      </p>
-    </div>
-  );
-};
-
-export default ConditionalComponent;
-```
-
-  </Tab>
-  <Tab label="Next.js" value="nextjs">
-
 To utilize conditional content in Next.js Client Components, retrieve it via the `useIntlayer` hook. Here's an example:
 
-```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
-"use client";
-
-import type { FC } from "react";
-import { useIntlayer } from "next-intlayer";
-
-const ConditionalComponent: FC = () => {
-  const { myCondition } = useIntlayer("my_key");
-
-  return (
-    <div>
-      <p>{myCondition(true)}</p>
-      <p>{myCondition(false)}</p>
-    </div>
-  );
-};
-
-export default ConditionalComponent;
-```
-
-  </Tab>
-  <Tab label="Vue" value="vue">
-
-To utilize conditional content in Vue components, retrieve it via the `useIntlayer` hook. Here's an example:
-
-```vue fileName="**/*.vue"
-<script setup lang="ts">
-import { useIntlayer } from "vue-intlayer";
-
-const { myCondition } = useIntlayer("my_key");
-</script>
-
-<template>
-  <div>
-    <p>{{ myCondition(true) }}</p>
-    <p>{{ myCondition(false) }}</p>
-  </div>
-</template>
-```
-
-  </Tab>
-  <Tab label="Svelte" value="svelte">
-
-To utilize conditional content in Svelte components, retrieve it via the `useIntlayer` hook. The store is accessed with `$`. Here's an example:
-
-```svelte fileName="**/*.svelte"
-<script lang="ts">
-import { useIntlayer } from "svelte-intlayer";
-
-const content = useIntlayer("my_key");
-</script>
-
-<div>
-  <p>{$content.myCondition(true)}</p>
-  <p>{$content.myCondition(false)}</p>
-</div>
-```
-
-  </Tab>
-  <Tab label="Preact" value="preact">
-
-To utilize conditional content in Preact components, retrieve it via the `useIntlayer` hook. Here's an example:
-
-```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
-import type { FC } from "preact";
-import { useIntlayer } from "preact-intlayer";
-
-const ConditionalComponent: FC = () => {
-  const { myCondition } = useIntlayer("my_key");
-
-  return (
-    <div>
-      <p>{myCondition(true)}</p>
-      <p>{myCondition(false)}</p>
-    </div>
-  );
-};
-
-export default ConditionalComponent;
-```
-
-  </Tab>
-  <Tab label="Solid" value="solid">
-
-To utilize conditional content in SolidJS components, retrieve it via the `useIntlayer` hook. Here's an example:
-
-```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
-import type { Component } from "solid-js";
-import { useIntlayer } from "solid-intlayer";
-
-const ConditionalComponent: Component = () => {
-  const { myCondition } = useIntlayer("my_key");
-
-  return (
-    <div>
-      <p>{myCondition(true)}</p>
-      <p>{myCondition(false)}</p>
-    </div>
-  );
-};
-
-export default ConditionalComponent;
-```
-
-  </Tab>
-  <Tab label="Angular" value="angular">
-
-To utilize conditional content in Angular components, retrieve it via the `useIntlayer` hook. Here's an example:
-
-```typescript fileName="app.component.ts" codeFormat="typescript"
-import { Component } from "@angular/core";
-import { useIntlayer } from "angular-intlayer";
-
-@Component({
-  selector: "app-conditional",
-  template: `
-    <div>
-      <p>{{ content().myCondition(true) }}</p>
-      <p>{{ content().myCondition(false) }}</p>
-    </div>
-  `,
-})
-export class ConditionalComponent {
-  content = useIntlayer("my_key");
-}
-```
-
-  </Tab>
-  <Tab label="Vanilla JS" value="vanilla">
-
-To utilize conditional content with `vanilla-intlayer`, retrieve it via the `useIntlayer` hook. Here's an example:
-
-```typescript fileName="**/*.ts" codeFormat={["typescript", "esm"]}
-import { installIntlayer, useIntlayer } from "vanilla-intlayer";
-
-installIntlayer();
-
-const content = useIntlayer("my_key").onChange((newContent) => {
-  document.getElementById("true-content")!.textContent =
-    newContent.myCondition(true);
-  document.getElementById("false-content")!.textContent =
-    newContent.myCondition(false);
-});
-
-// Initial render
-document.getElementById("true-content")!.textContent =
-  content.myCondition(true);
-document.getElementById("false-content")!.textContent =
-  content.myCondition(false);
-```
-
-  </Tab>
-</Tabs>
 ## Setting Up Conditional Content
 
 To set up conditional content in your Intlayer project, create a content module that includes your conditional definitions. Below are examples in various formats.

package/docs/en-GB/dictionary/content_file.md

@@ -1131,8 +1131,5 @@ export default {
    - Leverage tags for categorisation
    - Use the `autoFill` to automatically fill the missing translations
 
-3. **Performance**:
-   - Adjust the content configuration to limit the scope of watched files
-
 - Use live dictionaries only when real-time updates are necessary, (e.g. A/B testing, etc.)
 - Ensure the build transformation plugin (`@intlayer/swc`, or `@intlayer/babel`) is enabled to optimise the dictionary at build time

package/docs/en-GB/dictionary/enumeration.md

@@ -27,191 +27,8 @@ author: aymericzip
 
 ## How Enumeration Works
 
-<Tabs group="framework">
-  <Tab label="React" value="react">
-
-To use enumeration in a React component, you can leverage the `useIntlayer` hook from the `react-intlayer` package. This hook retrieves the correct content based on the specified ID. Here's an example of how to use it:
-
-```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
-import type { FC } from "react";
-import { useIntlayer } from "react-intlayer";
-
-const CarComponent: FC = () => {
-  const { numberOfCar } = useIntlayer("car_count");
-
-  return (
-    <div>
-      <p>
-        {
-          numberOfCar(0) // Output: No cars
-        }
-      </p>
-      <p>
-        {
-          numberOfCar(6) // Output: Some cars
-        }
-      </p>
-      <p>
-        {
-          numberOfCar(20) // Output: Many cars
-        }
-      </p>
-      <p>
-        {
-          numberOfCar(0.01) // Output: Fallback value
-        }
-      </p>
-    </div>
-  );
-};
-```
-
-  </Tab>
-  <Tab label="Next.js" value="nextjs">
-
 To use enumeration in Next.js Client Components, retrieve it via the `useIntlayer` hook. Here's an example:
 
-```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
-"use client";
-
-import type { FC } from "react";
-import { useIntlayer } from "next-intlayer";
-
-const CarComponent: FC = () => {
-  const { numberOfCar } = useIntlayer("car_count");
-
-  return (
-    <div>
-      <p>{numberOfCar(6)}</p>
-    </div>
-  );
-};
-
-export default CarComponent;
-```
-
-  </Tab>
-  <Tab label="Vue" value="vue">
-
-To use enumeration in Vue components, retrieve it via the `useIntlayer` hook. Here's an example:
-
-```vue fileName="**/*.vue"
-<script setup lang="ts">
-import { useIntlayer } from "vue-intlayer";
-
-const { numberOfCar } = useIntlayer("car_count");
-</script>
-
-<template>
-  <div>
-    <p>{{ numberOfCar(6) }}</p>
-  </div>
-</template>
-```
-
-  </Tab>
-  <Tab label="Svelte" value="svelte">
-
-To use enumeration in Svelte components, retrieve it via the `useIntlayer` hook. The store is accessed with `$`. Here's an example:
-
-```svelte fileName="**/*.svelte"
-<script lang="ts">
-import { useIntlayer } from "svelte-intlayer";
-
-const content = useIntlayer("car_count");
-</script>
-
-<div>
-  <p>{$content.numberOfCar(6)}</p>
-</div>
-```
-
-  </Tab>
-  <Tab label="Preact" value="preact">
-
-To use enumeration in Preact components, retrieve it via the `useIntlayer` hook. Here's an example:
-
-```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
-import type { FC } from "preact";
-import { useIntlayer } from "preact-intlayer";
-
-const CarComponent: FC = () => {
-  const { numberOfCar } = useIntlayer("car_count");
-
-  return (
-    <div>
-      <p>{numberOfCar(6)}</p>
-    </div>
-  );
-};
-
-export default CarComponent;
-```
-
-  </Tab>
-  <Tab label="Solid" value="solid">
-
-To use enumeration in SolidJS components, retrieve it via the `useIntlayer` hook. Here's an example:
-
-```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
-import type { Component } from "solid-js";
-import { useIntlayer } from "solid-intlayer";
-
-const CarComponent: Component = () => {
-  const { numberOfCar } = useIntlayer("car_count");
-
-  return (
-    <div>
-      <p>{numberOfCar(6)}</p>
-    </div>
-  );
-};
-
-export default CarComponent;
-```
-
-  </Tab>
-  <Tab label="Angular" value="angular">
-
-To use enumeration in Angular components, retrieve it via the `useIntlayer` hook. Here's an example:
-
-```typescript fileName="app.component.ts" codeFormat="typescript"
-import { Component } from "@angular/core";
-import { useIntlayer } from "angular-intlayer";
-
-@Component({
-  selector: "app-car",
-  template: `
-    <div>
-      <p>{{ content().numberOfCar(6) }}</p>
-    </div>
-  `,
-})
-export class CarComponent {
-  content = useIntlayer("car_count");
-}
-```
-
-  </Tab>
-  <Tab label="Vanilla JS" value="vanilla">
-
-To use enumeration with `vanilla-intlayer`, retrieve it via the `useIntlayer` hook. Here's an example:
-
-```typescript fileName="**/*.ts" codeFormat={["typescript", "esm"]}
-import { installIntlayer, useIntlayer } from "vanilla-intlayer";
-
-installIntlayer();
-
-const content = useIntlayer("car_count").onChange((newContent) => {
-  document.getElementById("cars")!.textContent = newContent.numberOfCar(6);
-});
-
-// Initial render
-document.getElementById("cars")!.textContent = content.numberOfCar(6);
-```
-
-  </Tab>
-</Tabs>
 ## Setting Up Enumeration
 
 To set up enumeration in your Intlayer project, you need to create a content module that includes enumeration definitions. Here's an example of a simple enumeration for the number of cars: