@intlayer/docs 7.0.9-canary.2 → 7.0.9-canary.3

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

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-08-23
-updatedAt: 2025-08-23
+updatedAt: 2025-11-16
 title: getMultilingualUrls Function Documentation | intlayer
 description: See how to use the getMultilingualUrls function for intlayer package
 keywords:
@@ -19,6 +19,9 @@ slugs:
   - intlayer
   - getMultilingualUrls
 history:
+  - version: 7.1.0
+    date: 2025-11-16
+    changes: Refactored to use options parameter with mode instead of prefixDefault
   - version: 5.5.10
     date: 2025-06-29
     changes: Init history
@@ -30,49 +33,120 @@ history:
 
 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 internationalization 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
+
+```typescript
+getMultilingualUrls(
+  url: string,                   // Required
+  options?: {                    // Optional
+    locales?: Locales[];
+    defaultLocale?: Locales;
+    mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params';
+  }
+): StrictModeLocaleMap<string>
+```
+
 ---
 
 ## Parameters
 
+### Required Parameters
+
 - `url: string`
   - **Description**: The original URL string to be prefixed with locales.
   - **Type**: `string`
-
-- `locales: Locales[]`
-  - **Description**: Optional array of supported locales. Defaults to the configured locales in the project.
-  - **Type**: `Locales[]`
-  - **Default**: `localesDefault`
-
-- `defaultLocale: Locales`
-  - **Description**: The default locale for the application. Defaults to the configured default locale in the project.
-  - **Type**: `Locales`
-  - **Default**: `defaultLocaleDefault`
-
-- `prefixDefault: boolean`
-  - **Description**: Whether to prefix the default locale. Defaults to the configured value in the project.
-  - **Type**: `boolean`
-  - **Default**: `prefixDefaultDefault`
+  - **Required**: Yes
+
+### Optional Parameters
+
+- `options?: object`
+  - **Description**: Configuration object for URL localization behavior.
+  - **Type**: `object`
+  - **Required**: No (Optional)
+
+  - `options.locales?: Locales[]`
+    - **Description**: Array of supported locales. If not provided, uses the configured locales from your project configuration.
+    - **Type**: `Locales[]`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md#middleware)
+
+  - `options.defaultLocale?: Locales`
+    - **Description**: The default locale for the application. If not provided, uses the configured default locale from your project configuration.
+    - **Type**: `Locales`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md#middleware)
+
+  - `options.mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Description**: The URL routing mode for locale handling. If not provided, uses the configured mode from your project configuration.
+    - **Type**: `'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md#middleware)
+    - **Modes**:
+      - `prefix-no-default`: No prefix for default locale, prefix for all others
+      - `prefix-all`: Prefix for all locales including default
+      - `no-prefix`: No locale prefix in URL
+      - `search-params`: Use query parameters for locale (e.g., `?locale=fr`)
 
 ### Returns
 
-- **Type**: `IConfigLocales<string>`
+- **Type**: `StrictModeLocaleMap<string>`
 - **Description**: An object mapping each locale to its corresponding multilingual URL.
 
 ---
 
 ## Example Usage
 
-### Relative URLs
+### Basic Usage (Uses Project Configuration)
 
 ```typescript codeFormat="typescript"
 import { getMultilingualUrls, Locales } from "intlayer";
 
-getMultilingualUrls(
-  "/dashboard",
-  [Locales.ENGLISH, Locales.FRENCH],
-  Locales.ENGLISH,
-  false
-);
+// Uses your project's configuration for locales, defaultLocale, and mode
+getMultilingualUrls("/dashboard");
+// Output (assuming project config has en, fr with mode 'prefix-no-default'):
+// {
+//   en: "/dashboard",
+//   fr: "/fr/dashboard"
+// }
+```
+
+```javascript codeFormat="esm"
+import { getMultilingualUrls, Locales } from "intlayer";
+
+getMultilingualUrls("/dashboard");
+// Output: {
+//   en: "/dashboard",
+//   fr: "/fr/dashboard"
+// }
+```
+
+```javascript codeFormat="commonjs"
+const { getMultilingualUrls, Locales } = require("intlayer");
+
+getMultilingualUrls("/dashboard");
+// Output: {
+//   en: "/dashboard",
+//   fr: "/fr/dashboard"
+// }
+```
+
+### Relative URLs with Options
+
+```typescript codeFormat="typescript"
+import { getMultilingualUrls, Locales } from "intlayer";
+
+getMultilingualUrls("/dashboard", {
+  locales: [Locales.ENGLISH, Locales.FRENCH],
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-no-default",
+});
 // Output: {
 //   en: "/dashboard",
 //   fr: "/fr/dashboard"
@@ -82,12 +156,11 @@ getMultilingualUrls(
 ```javascript codeFormat="esm"
 import { getMultilingualUrls, Locales } from "intlayer";
 
-getMultilingualUrls(
-  "/dashboard",
-  [Locales.ENGLISH, Locales.FRENCH],
-  Locales.ENGLISH,
-  false
-);
+getMultilingualUrls("/dashboard", {
+  locales: [Locales.ENGLISH, Locales.FRENCH],
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-no-default",
+});
 // Output: {
 //   en: "/dashboard",
 //   fr: "/fr/dashboard"
@@ -97,12 +170,11 @@ getMultilingualUrls(
 ```javascript codeFormat="commonjs"
 const { getMultilingualUrls, Locales } = require("intlayer");
 
-getMultilingualUrls(
-  "/dashboard",
-  [Locales.ENGLISH, Locales.FRENCH],
-  Locales.ENGLISH,
-  false
-);
+getMultilingualUrls("/dashboard", {
+  locales: [Locales.ENGLISH, Locales.FRENCH],
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-no-default",
+});
 // Output: {
 //   en: "/dashboard",
 //   fr: "/fr/dashboard"
@@ -112,18 +184,69 @@ getMultilingualUrls(
 ### Absolute URLs
 
 ```typescript
-getMultilingualUrls(
-  "https://example.com/dashboard",
-  [Locales.ENGLISH, Locales.FRENCH],
-  Locales.ENGLISH,
-  true
-);
+getMultilingualUrls("https://example.com/dashboard", {
+  locales: [Locales.ENGLISH, Locales.FRENCH],
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-all",
+});
 // Output: {
 //   en: "https://example.com/en/dashboard",
 //   fr: "https://example.com/fr/dashboard"
 // }
 ```
 
+### Different Routing Modes
+
+```typescript
+// prefix-no-default: No prefix for default locale
+getMultilingualUrls("/dashboard", {
+  locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-no-default",
+});
+// Output: {
+//   en: "/dashboard",
+//   fr: "/fr/dashboard",
+//   es: "/es/dashboard"
+// }
+
+// prefix-all: Prefix for all locales
+getMultilingualUrls("/dashboard", {
+  locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-all",
+});
+// Output: {
+//   en: "/en/dashboard",
+//   fr: "/fr/dashboard",
+//   es: "/es/dashboard"
+// }
+
+// no-prefix: No locale prefix in URLs
+getMultilingualUrls("/dashboard", {
+  locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+  defaultLocale: Locales.ENGLISH,
+  mode: "no-prefix",
+});
+// Output: {
+//   en: "/dashboard",
+//   fr: "/dashboard",
+//   es: "/dashboard"
+// }
+
+// search-params: Locale as query parameter
+getMultilingualUrls("/dashboard", {
+  locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+  defaultLocale: Locales.ENGLISH,
+  mode: "search-params",
+});
+// Output: {
+//   en: "/dashboard?locale=en",
+//   fr: "/dashboard?locale=fr",
+//   es: "/dashboard?locale=es"
+// }
+```
+
 ---
 
 ## Edge Cases
@@ -132,11 +255,18 @@ getMultilingualUrls(
   - The function removes any existing locale segment from the URL before generating the multilingual mappings.
 
 - **Default Locale:**
-  - When `prefixDefault` is `false`, the function does not prefix the URL for the default locale.
+  - When `mode` is `'prefix-no-default'`, the function does not prefix the URL for the default locale.
+  - When `mode` is `'prefix-all'`, the function prefixes all locales including the default.
 
 - **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
@@ -190,11 +320,8 @@ The above configuration ensures that the application recognizes `ENGLISH`, `FREN
 Using this configuration, the `getMultilingualUrls` function can dynamically generate multilingual URL mappings based on the application's supported locales:
 
 ```typescript
-getMultilingualUrls(
-  "/dashboard",
-  [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-  Locales.ENGLISH
-);
+// Using project configuration (no options needed)
+getMultilingualUrls("/dashboard");
 // Output:
 // {
 //   en: "/dashboard",
@@ -202,12 +329,25 @@ getMultilingualUrls(
 //   es: "/es/dashboard"
 // }
 
-getMultilingualUrls(
-  "https://example.com/dashboard",
-  [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-  Locales.ENGLISH,
-  true
-);
+// With explicit options
+getMultilingualUrls("/dashboard", {
+  locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-no-default",
+});
+// Output:
+// {
+//   en: "/dashboard",
+//   fr: "/fr/dashboard",
+//   es: "/es/dashboard"
+// }
+
+// Absolute URLs with prefix-all mode
+getMultilingualUrls("https://example.com/dashboard", {
+  locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-all",
+});
 // Output:
 // {
 //   en: "https://example.com/en/dashboard",

package/docs/en/packages/intlayer/getPrefix.md

@@ -0,0 +1,201 @@
+---
+createdAt: 2025-11-16
+updatedAt: 2025-11-16
+title: getPrefix Function Documentation | intlayer
+description: See how to use the getPrefix function for intlayer package
+keywords:
+  - getPrefix
+  - prefix
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getPrefix
+history:
+  - version: 7.1.0
+    date: 2025-11-16
+    changes: Initial documentation
+---
+
+# Documentation: `getPrefix` Function in `intlayer`
+
+## Description
+
+The `getPrefix` function determines the URL prefix for a given locale based on the routing mode configuration. It compares the locale with the default locale and returns the appropriate prefix string (e.g., `'en/'`) or an empty string.
+
+**Key Features:**
+
+- Takes a locale as the first parameter (optional)
+- Optional `options` object with `defaultLocale`, `mode`, and `addSlash`
+- Returns a prefix string that can be used for URL construction
+- Supports all routing modes: `prefix-no-default`, `prefix-all`, `no-prefix`, and `search-params`
+- Lightweight utility for determining when to add locale prefixes
+
+---
+
+## Function Signature
+
+```typescript
+getPrefix(
+  locale?: Locales,              // Optional
+  options?: {                    // Optional
+    defaultLocale?: Locales;
+    mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params';
+    addSlash?: boolean;
+  }
+): string
+```
+
+---
+
+## Parameters
+
+### Optional Parameters
+
+- `locale?: Locales`
+  - **Description**: The locale to check for prefix. If not provided, uses the configured default locale.
+  - **Type**: `Locales`
+  - **Required**: No (Optional)
+  - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md#middleware)
+
+- `options?: object`
+  - **Description**: Configuration object for prefix determination.
+  - **Type**: `object`
+  - **Required**: No (Optional)
+
+  - `options.defaultLocale?: Locales`
+    - **Description**: The default locale for the application. If not provided, uses the configured default locale from your project configuration.
+    - **Type**: `Locales`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md#middleware)
+
+  - `options.mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Description**: The URL routing mode for locale handling. If not provided, uses the configured mode from your project configuration.
+    - **Type**: `'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md#middleware)
+    - **Modes**:
+      - `prefix-no-default`: Returns empty string when locale matches default locale
+      - `prefix-all`: Returns prefix with default locale
+      - `no-prefix`: Returns empty string (no prefix in URLs)
+      - `search-params`: Returns empty string (locale in query parameters)
+
+  - `options.addSlash?: boolean`
+    - **Description**: Whether to add a trailing slash to the prefix. If `true`, returns `'en/'`; if `false`, returns `'en'`.
+    - **Type**: `boolean`
+    - **Default**: `true`
+
+### Returns
+
+- **Type**: `string`
+- **Description**: The prefix string for the default locale (e.g., `'en/'`, `'fr/'`) or an empty string.
+
+---
+
+## Example Usage
+
+### Basic Usage
+
+```typescript codeFormat="typescript"
+import { getPrefix, Locales } from "intlayer";
+
+// Check prefix for English locale
+getPrefix(Locales.ENGLISH, {
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-all",
+});
+// Returns: 'en/'
+
+// Check prefix for French locale
+getPrefix(Locales.FRENCH, {
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-no-default",
+});
+// Returns: 'en/'
+```
+
+```javascript codeFormat="esm"
+import { getPrefix, Locales } from "intlayer";
+
+getPrefix(Locales.ENGLISH, { mode: "prefix-all" }); // Returns: "en/"
+```
+
+```javascript codeFormat="commonjs"
+const { getPrefix, Locales } = require("intlayer");
+
+getPrefix(Locales.ENGLISH, { mode: "prefix-all" }); // Returns: "en/"
+```
+
+### Different Routing Modes
+
+```typescript
+import { getPrefix, Locales } from "intlayer";
+
+// prefix-all: Always returns prefix
+getPrefix(Locales.ENGLISH, {
+  mode: "prefix-all",
+  defaultLocale: Locales.ENGLISH,
+});
+// Returns: "en/"
+
+// prefix-no-default: No prefix when locale matches default
+getPrefix(Locales.ENGLISH, {
+  mode: "prefix-no-default",
+  defaultLocale: Locales.ENGLISH,
+});
+// Returns: ""
+
+// prefix-no-default: Returns prefix when locale differs from default
+getPrefix(Locales.FRENCH, {
+  mode: "prefix-no-default",
+  defaultLocale: Locales.ENGLISH,
+});
+// Returns: "en/"
+
+// no-prefix & search-params: Never returns prefix
+getPrefix(Locales.ENGLISH, { mode: "no-prefix" }); // Returns: ""
+getPrefix(Locales.ENGLISH, { mode: "search-params" }); // Returns: ""
+
+// Without trailing slash
+getPrefix(Locales.ENGLISH, { mode: "prefix-all", addSlash: false });
+// Returns: "en" (without trailing slash)
+```
+
+### Practical Example
+
+```typescript
+import { getPrefix, Locales } from "intlayer";
+
+// Build URLs with the appropriate prefix for a specific locale
+const locale = Locales.FRENCH;
+const prefix = getPrefix(locale, { defaultLocale: Locales.ENGLISH });
+const url = `/${prefix}about`.replace(/\/+/g, "/");
+// Result: "/en/about" if French is not default
+```
+
+---
+
+## Related Functions
+
+- [`getLocalizedUrl`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getLocalizedUrl.md): Generates a localized URL for a specific locale
+- [`getMultilingualUrls`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getMultilingualUrls.md): Generates URLs for all configured locales
+
+---
+
+## TypeScript
+
+```typescript
+function getPrefix(
+  locale?: Locales,
+  options?: {
+    defaultLocale?: Locales;
+    mode?: "prefix-no-default" | "prefix-all" | "no-prefix" | "search-params";
+    addSlash?: boolean;
+  }
+): string;
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intlayer/docs",
-  "version": "7.0.9-canary.2",
+  "version": "7.0.9-canary.3",
   "private": false,
   "description": "Intlayer documentation",
   "keywords": [
@@ -58,9 +58,9 @@
     "lint": "biome lint .",
     "lint:fix": "biome lint --write .",
     "prepublish": "cp -f ../README.md ./README.md",
-    "publish": "bun publish --access public || true",
-    "publish:canary": "bun publish --tag canary --access public || true",
-    "publish:latest": "bun publish --tag latest --access public || true",
+    "publish": "bun publish || true",
+    "publish:canary": "bun publish --tag canary || true",
+    "publish:latest": "bun publish --tag latest || true",
     "review": "bun tools/review.ts",
     "serve": "webpack serve --config ./webpack.config.ts",
     "test": "vitest run",

package/src/generated/docs.entry.ts

@@ -1079,6 +1079,25 @@ export const docsEntry = {
     id: readLocale('packages/intlayer/getPathWithoutLocale.md', 'id'),
     vi: readLocale('packages/intlayer/getPathWithoutLocale.md', 'vi'),
   } as unknown as Record<LocalesValues, Promise<string>>,
+  './docs/en/packages/intlayer/getPrefix.md': {
+    en: readLocale('packages/intlayer/getPrefix.md', 'en'),
+    ru: readLocale('packages/intlayer/getPrefix.md', 'ru'),
+    ja: readLocale('packages/intlayer/getPrefix.md', 'ja'),
+    fr: readLocale('packages/intlayer/getPrefix.md', 'fr'),
+    ko: readLocale('packages/intlayer/getPrefix.md', 'ko'),
+    zh: readLocale('packages/intlayer/getPrefix.md', 'zh'),
+    es: readLocale('packages/intlayer/getPrefix.md', 'es'),
+    de: readLocale('packages/intlayer/getPrefix.md', 'de'),
+    ar: readLocale('packages/intlayer/getPrefix.md', 'ar'),
+    it: readLocale('packages/intlayer/getPrefix.md', 'it'),
+    'en-GB': readLocale('packages/intlayer/getPrefix.md', 'en-GB'),
+    pt: readLocale('packages/intlayer/getPrefix.md', 'pt'),
+    hi: readLocale('packages/intlayer/getPrefix.md', 'hi'),
+    tr: readLocale('packages/intlayer/getPrefix.md', 'tr'),
+    pl: readLocale('packages/intlayer/getPrefix.md', 'pl'),
+    id: readLocale('packages/intlayer/getPrefix.md', 'id'),
+    vi: readLocale('packages/intlayer/getPrefix.md', 'vi'),
+  } as unknown as Record<LocalesValues, Promise<string>>,
   './docs/en/packages/intlayer/getTranslation.md': {
     en: readLocale('packages/intlayer/getTranslation.md', 'en'),
     ru: readLocale('packages/intlayer/getTranslation.md', 'ru'),