@intlayer/docs 9.4.0-canary.0 → 9.4.1

package/docs/en-GB/packages/intlayer/getLocalizedPath.md

@@ -31,6 +31,8 @@ author: aymericzip
 
 The `getLocalizedPath` function resolves a canonical path (internal application path) into its localised equivalent based on the provided locale and rewrite rules. It is particularly useful for generating SEO-friendly URLs that vary by language.
 
+It is the relative counterpart of [`getLocalizedUrl`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/intlayer/getLocalizedUrl.md) — for a relative input both return the same value. Unlike `getLocalizedUrl`, it never returns an absolute URL: the `domains` configuration is ignored, so a locale served from its own domain still yields a path. An absolute input is accepted, but its origin is dropped — only its path, query string and hash are kept.
+
 **Key Features:**
 
 - Supports dynamic route parameters using the `[param]` syntax.
@@ -60,18 +62,23 @@ getLocalizedPath(
   - **Type**: `string`
   - **Required**: Yes
 
-- `locale: Locales`
+### Optional Parameters
+
+- `locale?: Locales`
   - **Description**: The target locale for which the path should be localised.
   - **Type**: `Locales`
-  - **Required**: Yes
-
-### Optional Parameters
+  - **Default**: The default locale of your project's configuration.
 
 - `rewriteRules?: RoutingConfig['rewrite']`
   - **Description**: An object defining custom rewrite rules. If not provided, it defaults to the `routing.rewrite` property from your project's configuration.
   - **Type**: `RoutingConfig['rewrite']`
   - **Default**: `configuration.routing.rewrite`
 
+  - `options.locales?: Locales[]` — supported locales. **Default**: `configuration.internationalization.locales`
+  - `options.defaultLocale?: Locales` — the default locale. **Default**: `configuration.internationalization.defaultLocale`
+  - `options.mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'` — how the locale appears in the path. **Default**: `configuration.routing.mode`
+  - `options.rewrite?: RoutingConfig['rewrite']` — custom rewrite rules. **Default**: `configuration.routing.rewrite`
+
 ---
 
 ## Returns
@@ -79,6 +86,28 @@ getLocalizedPath(
 - **Type**: `string`
 - **Description**: The localised path for the specified locale.
 
+The type is narrowed from the rewrite rules declared in your configuration, so the editor shows the resolved path rather than a bare `string`:
+
+```typescript codeFormat="typescript"
+// Configuration: mode 'prefix-no-default', defaultLocale 'en',
+//                { '/about': { fr: '/a-propos' }, '/product/[id]': { fr: '/produit/[id]' } }
+const about = getLocalizedPath("/about", Locales.FRENCH);
+//    ^? '/fr/a-propos'
+const product = getLocalizedPath("/product/123", Locales.FRENCH);
+//    ^? '/fr/produit/123'
+const contact = getLocalizedPath("/contact", Locales.FRENCH);
+//    ^? '/fr/contact'  (no rewrite rule matches, only the prefix is applied)
+const home = getLocalizedPath("/", Locales.FRENCH);
+//    ^? '/fr'
+```
+
+The same narrowing flows into [`getLocalizedUrl`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getLocalizedUrl.md), which applies the rewrite rules before prefixing the locale.
+
+Two cases stay widened to `string`, because they cannot be resolved at compile time:
+
+- a path that is not a string literal (e.g. one built from a variable);
+- a path matched by a rule using a multi-segment or optional parameter (`[...slug]`, `[[...slug]]`, `:param?`).
+
 ---
 
 ## Example Usage
@@ -126,8 +155,6 @@ getLocalizedPath("/contact", Locales.FRENCH, manualRules);
 // Output: "/contactez-nous"
 ```
 
----
-
 ### Omitting the Locale
 
 When no locale is given, the path is localised for the configured default locale:

package/docs/en-GB/packages/intlayer/getLocalizedUrl.md

@@ -143,36 +143,6 @@ getLocalizedUrl(
 // Output: "/about" for the default (English) locale
 ```
 
-```javascript codeFormat="esm"
-import { getLocalizedUrl, Locales } from "intlayer";
-
-getLocalizedUrl(
-  "/about",
-  Locales.FRENCH,
-  [Locales.ENGLISH, Locales.FRENCH],
-  Locales.ENGLISH,
-  false
-);
-
-// Output: "/fr/about" for the French locale
-// Output: "/about" for the default (English) locale
-```
-
-```javascript codeFormat="commonjs"
-const { getLocalizedUrl, Locales } = require("intlayer");
-
-getLocalizedUrl(
-  "/about",
-  Locales.FRENCH,
-  [Locales.ENGLISH, Locales.FRENCH],
-  Locales.ENGLISH,
-  false
-);
-
-// Output: "/fr/about" for the French locale
-// Output: "/about" for the default (English) locale
-```
-
 ### Partial Configuration Override
 
 You can also provide only some of the optional parameters. The function will use your project configuration for any parameters you don't specify:
@@ -249,6 +219,12 @@ getLocalizedUrl(
 - **Unsupported Locales:**
   - For locales not listed in `locales`, the function does not apply any prefix.
 
+- **Routing Modes:**
+  - `'prefix-no-default'`: Default locale has no prefix, others do (e.g., `/about`, `/fr/about`)
+  - `'prefix-all'`: All locales have prefixes (e.g., `/en/about`, `/fr/about`)
+  - `'no-prefix'`: No locale prefixes in URLs (locale handled elsewhere)
+  - `'search-params'`: Locale specified via query parameter (e.g., `/about?locale=fr`)
+
 ---
 
 ## Usage in Applications

package/docs/en-GB/packages/intlayer/getMultilingualUrls.md

@@ -31,6 +31,14 @@ author: aymericzip
 
 The `getMultilingualUrls` function generates a mapping of multilingual URLs by prefixing the given URL with each supported locale. It can handle both absolute and relative URLs, applying the appropriate locale prefix based on the provided configuration or defaults.
 
+**Key Features:**
+
+- Only 1 parameter is required: `url`
+- Optional `options` object with `locales`, `defaultLocale`, and `mode`
+- Uses your project's internationalisation configuration as defaults
+- Supports multiple routing modes: `prefix-no-default`, `prefix-all`, `no-prefix`, and `search-params`
+- Returns a mapping object with all locales as keys and their corresponding URLs as values
+
 ---
 
 ## Function Signature
@@ -139,8 +147,6 @@ getMultilingualUrls(
 // }
 ```
 
----
-
 ### Absolute URLs
 
 ```typescript
@@ -169,6 +175,12 @@ getMultilingualUrls(
 - **Unsupported Locales:**
   - Only the locales provided in the `locales` array are considered for generating the URLs.
 
+- **Routing Modes:**
+  - `'prefix-no-default'`: Default locale has no prefix, others do (e.g., `/dashboard`, `/fr/dashboard`)
+  - `'prefix-all'`: All locales have prefixes (e.g., `/en/dashboard`, `/fr/dashboard`)
+  - `'no-prefix'`: No locale prefixes in URLs (all locales return same URL)
+  - `'search-params'`: Locale specified via query parameter (e.g., `/dashboard?locale=fr`)
+
 ---
 
 ## Usage in Applications

package/docs/en-GB/packages/next-intlayer/t.md

@@ -162,6 +162,23 @@ In `next-intlayer`, the current locale is managed through context providers: `In
 
 #### Example:
 
+<Tabs>
+ <Tab label='Intlayer >=9.4' value='>=9.4'>
+
+```tsx codeFormat={["typescript", "esm", "commonjs"]}
+import type { FC, ReactNode } from "react";
+import type { Locales } from "intlayer";
+import { IntlayerProvider } from "next-intlayer/server";
+
+const Page: FC<{ locale: Locales; children: ReactNode }> = ({
+  locale,
+  children,
+}) => <IntlayerProvider locale={locale}>{children}</IntlayerProvider>;
+```
+
+ </Tab>
+ <Tab label='Intlayer <9.4' value='<9.4'>
+
 ```tsx codeFormat={["typescript", "esm", "commonjs"]}
 import type { FC } from "react";
 import type { Locales } from "intlayer";
@@ -177,6 +194,9 @@ const Page: FC<{ locale: Locales }> = ({ locale }) => (
 );
 ```
 
+ </Tab>
+</Tabs>
+
 ---
 
 ## Common Errors and Troubleshooting

package/docs/en-GB/packages/next-intlayer/useIntlayer.md

@@ -71,10 +71,6 @@ Depending on whether you're working on client-side or server-side components in
 
 ## Dictionary Files
 
-It is crucial that all content keys are defined within content declaration files to prevent runtime errors and ensure type safety. This approach also facilitates TypeScript integration for compile-time validation.
-
-Instructions for setting up content declaration files are available [here](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_file.md).
-
 It's crucial that all content keys are defined within content declaration files to prevent runtime errors and ensure type safety. This approach also facilitates TypeScript integration for compile-time validation.
 
 Instructions for setting up content declaration files are available [here](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/content_file.md).
@@ -83,6 +79,34 @@ Instructions for setting up content declaration files are available [here](https
 
 Here's how you can implement the `useIntlayer` hook within a Next.js page to dynamically load localised content based on the application's current locale:
 
+<Tabs>
+ <Tab label='Intlayer >=9.4' value='>=9.4'>
+
+```tsx fileName="src/pages/[locale]/index.tsx" codeFormat={["typescript", "esm"]}
+import { ClientComponentExample } from "@components/ClientComponentExample";
+import { ServerComponentExample } from "@components/ServerComponentExample";
+import { type NextPageIntlayer } from "next-intlayer";
+import { useIntlayer } from "next-intlayer";
+import { IntlayerProvider } from "next-intlayer/server";
+
+const HomePage: NextPageIntlayer = async ({ params }) => {
+  const { locale } = await params;
+
+  const content = useIntlayer("homepage", locale);
+
+  return (
+    <IntlayerProvider locale={locale}>
+      <p>{content.introduction}</p>
+      <ClientComponentExample />
+      <ServerComponentExample />
+    </IntlayerProvider>
+  );
+};
+```
+
+ </Tab>
+ <Tab label='Intlayer <9.4' value='<9.4'>
+
 ```tsx fileName="src/pages/[locale]/index.tsx" codeFormat={["typescript", "esm"]}
 import { ClientComponentExample } from "@components/ClientComponentExample";
 import { ServerComponentExample } from "@components/ServerComponentExample";
@@ -108,6 +132,9 @@ const HomePage: NextPageIntlayer = async ({ params }) => {
 };
 ```
 
+ </Tab>
+</Tabs>
+
 ```tsx fileName="src/components/ClientComponentExample.tsx" codeFormat={["typescript", "esm"]}
 "use-client";
 

package/docs/en-GB/packages/next-intlayer/useLocale.md

@@ -104,6 +104,8 @@ The `useLocale` hook accepts the following parameters:
 
 ## Return Values
 
+When you invoke the `useLocale` hook, it returns an object containing the following properties:
+
 - **`locale`**: The current locale as set in the React context.
 - **`defaultLocale`**: The primary locale defined in the configuration.
 - **`availableLocales`**: A list of all locales available as defined in the configuration.

package/docs/en-GB/packages/react-intlayer/useDictionary.md

@@ -30,8 +30,6 @@ This section provides detailed guidance on using the `useDictionary` hook within
 
 ## Example Usage in React
 
-Below is an example of how to use the `useDictionary` hook in a React component:
-
 ```tsx fileName="./ComponentExample.tsx" codeFormat={["typescript", "esm"]}
 import type { FC } from "react";
 import { useDictionary } from "react-intlayer";

package/docs/en-GB/packages/react-intlayer/useI18n.md

@@ -77,6 +77,34 @@ All dictionary keys must be declared within content declaration files to enhance
 
 Examples of using the `useI18n` hook within React components:
 
+<Tabs>
+ <Tab label='Intlayer >=9.4' value='>=9.4'>
+
+```tsx fileName="src/App.tsx" codeFormat={["typescript", "esm"]}
+import type { FC } from "react";
+import { ClientComponentExample, ServerComponentExample } from "@components";
+import { IntlayerProvider } from "react-intlayer";
+import { useI18n } from "react-intlayer/server";
+import { Locales } from "intlayer";
+
+const App: FC<{ locale: Locales }> = ({ locale }) => {
+  const t = useI18n("home-page", locale);
+
+  return (
+    <>
+      <p>{t("introduction")}</p>
+      <IntlayerProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerProvider>
+      <ServerComponentExample />
+    </>
+  );
+};
+```
+
+ </Tab>
+ <Tab label='Intlayer <9.4' value='<9.4'>
+
 ```tsx fileName="src/App.tsx" codeFormat={["typescript", "esm"]}
 import type { FC } from "react";
 import { ClientComponentExample, ServerComponentExample } from "@components";
@@ -101,6 +129,9 @@ const App: FC<{ locale: Locales }> = ({ locale }) => {
 };
 ```
 
+ </Tab>
+</Tabs>
+
 ```tsx fileName="src/components/ComponentExample.tsx" codeFormat={["typescript", "esm"]}
 import type { FC } from "react";
 import { useI18n } from "react-intlayer";

package/docs/en-GB/packages/react-intlayer/useIntlayer.md

@@ -31,48 +31,6 @@ This section provides detailed guidance on using the `useIntlayer` hook within R
 
 ## Example Usage in React
 
-Demonstrating the `useIntlayer` hook within a React component:
-
-```tsx fileName="src/app.tsx" codeFormat={["typescript", "esm"]}
-import type { FC } from "react";
-import { ClientComponentExample, ServerComponentExample } from "@components";
-import { IntlayerProvider } from "react-intlayer";
-import { useIntlayer, IntlayerServerProvider } from "react-intlayer/server";
-import { Locales } from "intlayer";
-
-const App: FC<{ locale: Locales }> = ({ locale }) => {
-  const content = useIntlayer("homepage", locale);
-
-  return (
-    <>
-      <p>{content.introduction}</p>
-      <IntlayerProvider locale={locale}>
-        <ClientComponentExample />
-      </IntlayerProvider>
-      <IntlayerServerProvider locale={locale}>
-        <ServerComponentExample />
-      </IntlayerServerProvider>
-    </>
-  );
-};
-```
-
-```tsx fileName="src/components/ComponentExample.tsx" codeFormat={["typescript", "esm"]}
-import type { FC } from "react";
-import { useIntlayer } from "react-intlayer";
-
-const ComponentExample: FC = () => {
-  const content = useIntlayer("component-example");
-
-  return (
-    <div>
-      <h1>{content.title}</h1>
-      <p>{content.description}</p>
-    </div>
-  );
-};
-```
-
 ```tsx fileName="src/components/ServerComponentExample.tsx" codeFormat={["typescript", "esm"]}
 import { useIntlayer } from "react-intlayer/server";
 

package/docs/en-GB/packages/vite-intlayer/intlayerPrune.md

@@ -28,6 +28,8 @@ author: aymericzip
 
 The `intlayerPrune` Vite plugin is used to tree-shake and prune unused dictionaries from your application's bundle. This helps reduce the final bundle size by only including the necessary multilingual content.
 
+> The plugin is already included and configured automatically when you use [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/vite-intlayer/intlayer.md). You only need to register it manually if you are composing the plugin stack yourself.
+
 ## Usage
 
 ### As part of `intlayer()` (recommended)

package/docs/en-GB/per_locale_file.md

@@ -76,6 +76,17 @@ const helloWorldContent = {
 module.exports = helloWorldContent;
 ```
 
+```json5 fileName="hello-world.en.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "hello-world",
+  "locale": "en", // Important
+  "content": {
+    "multilingualContent": "Title of my component",
+  },
+}
+```
+
 ```json fileName="hello-world.content.ts" contentDeclarationFormat="json"
 {
   "$schema": "https://intlayer.org/schema.json",
@@ -94,6 +105,8 @@ module.exports = helloWorldContent;
 
 > Recommended: This format is best when using Intlayer's visual editor or managing translations directly in the code.
 
+> Note: In both cases, the content declaration file must follow the naming pattern `*.content.{ts,tsx,js,jsx,mjs,cjs,json}` to be recognised by Intlayer. The `.[locale]` suffix is optional and used only as a naming convention.
+
 ### Global Configuration for Per-Locale Files
 
 You can configure the global configuration for per-locale files by adding the following to your `intlayer.config.ts` file:
@@ -145,17 +158,6 @@ const helloWorldContent = {
 export default helloWorldContent;
 ```
 
-```json5 fileName="hello-world.en.content.json" contentDeclarationFormat="json"
-{
-  "$schema": "https://intlayer.org/schema.json",
-  "key": "hello-world",
-  "locale": "en", // Important
-  "content": {
-    "multilingualContent": "Title of my component",
-  },
-}
-```
-
 ```json5 fileName="hello-world.es.content.json" contentDeclarationFormat="json"
 {
   "$schema": "https://intlayer.org/schema.json",
@@ -169,8 +171,6 @@ export default helloWorldContent;
 
 > Important: Ensure the locale field is defined. It indicates to Intlayer which language the file represents.
 
-> Note: In both instances, the content declaration file must adhere to the naming pattern `*.content.{ts,tsx,js,jsx,mjs,cjs,json}` to be recognised by Intlayer. The `.[locale]` suffix is optional and used solely as a naming convention.
-
 ## Mixing Formats
 
 You can combine both declaration approaches for the same content key. For example:

package/docs/en-GB/readme.md

@@ -225,8 +225,8 @@ Explore our comprehensive documentation to get started with Intlayer and learn h
   <li><a href="https://intlayer.org/doc/environment/vite-and-vue" rel=''>Vite + Vue</a></li>
   <li><a href="https://intlayer.org/doc/environment/nuxt-and-vue" rel=''>Vite + Nuxt</a></li>
   <li><a href="https://intlayer.org/doc/environment/vite-and-solid" rel=''>Vite + Solid</a></li>
-  <li><a href="https://intlayer.org/doc/environment/angular" rel=''>Angular</a></li>
-  <li>
+  <li><a href="https://intlayer.org/doc/environment/solid-start" rel=''>Solid Start</a></li>
+  <li><a href="https://intlayer.org/doc/environment/angular" rel=''>Angular</a></li>  <li>
      <a href="https://intlayer.org/doc/environment/express" rel=''>Backend</a>
      <ul>
       <li><a href="https://intlayer.org/doc/environment/express" rel=''>Express</a></li>
@@ -234,6 +234,7 @@ Explore our comprehensive documentation to get started with Intlayer and learn h
       <li><a href="https://intlayer.org/doc/environment/fastify" rel=''>Fastify</a></li>
       <li><a href="https://intlayer.org/doc/environment/adonisjs" rel=''>AdonisJS</a></li>
       <li><a href="https://intlayer.org/doc/environment/hono" rel=''>Hono</a></li>
+      <li><a href="https://intlayer.org/doc/environment/elysia" rel=''>Elysia</a></li>
     </ul>
   </li>
 </ul>

package/docs/en-GB/releases/v6.md

@@ -116,6 +116,8 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
+Auto-fill your missing translations using the `npx intlayer fill` command.
+
 You can still fine‑tune per dictionary using the `autoFill` field in content files. See the full reference in `doc/autoFill` and `doc/dictionary/content_file`.
 
 ---
@@ -175,6 +177,20 @@ See details in the [Official VS Code Extension](https://github.com/aymericzip/in
 
 ---
 
+Updated the MCP server to support the new features.
+
+- Auto-fill
+- Test missing translations
+- Live updates
+- Logging
+- Validation
+- Migration notes
+- Documentation
+
+> MCP server helps with the automation of projects using Intlayer. Testing missing translations for autogenerated code. It helps understand your config, and embed the documentation of Intlayer in your IDE.
+
+---
+
 ## Performance: 10× faster
 
 - Parallel resolution of local and remote dictionaries
@@ -264,31 +280,6 @@ export default {
 };
 ```
 
-See [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md) for all logging options.
-
----
-
-## Live updates with CMS (Production‑safe)
-
-Serve live content updates (e.g., editorial updates) in production without rebuilding your application.
-
-1. Enable live import mode:
-
-```ts fileName="intlayer.config.ts"
-import { type IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  build: {
-    importMode: "live", // "static" | "dynamic" | "live"
-  },
-  editor: {
-    liveSync: true, // enable live sync server side
-  },
-};
-
-export default config;
-```
-
 2. Run your app and live process side‑by‑side:
 
 ```bash packageManager="npm"
@@ -309,10 +300,21 @@ bun x intlayer live --with 'vite preview'
 
 Notes:
 
-- Only dictionaries flagged to use live mode will be fetched live. Others are optimised for performance.
-- Falls back to dynamic import if the live API isn’t reachable.
+See [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md) for all logging options.
+
+---
+
+## Live updates with CMS (Production‑safe)
+
+Serve live content updates (e.g., editorial updates) in production without rebuilding your application.
+
+1. Enable live import mode:
 
-See [CMS and Live Sync](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md) and [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md) for complete guidance.
+2. Run your app and live process side‑by‑side:
+
+```bash packageManager="bun"
+bun x intlayer live --with 'vite preview'
+```
 
 ---