@intlayer/docs 5.5.8

package/en/dictionary/translation.md

@@ -0,0 +1,285 @@
+# Translation
+
+## Defining Translations
+
+The `t` function in `intlayer` allows you to declare content in multiple languages. This function ensures type safety, raising an error if any translations are missing, which is particularly useful in TypeScript environments.
+
+Here's an example of how to declare content with translations.
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+interface Content {
+  welcomeMessage: string;
+}
+
+export default {
+  key: "multi_lang",
+  content: {
+    welcomeMessage: t({
+      en: "Welcome to our application",
+      fr: "Bienvenue dans notre application",
+      es: "Bienvenido a nuestra aplicación",
+    }),
+  },
+} satisfies Dictionary<Content>;
+```
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+export default {
+  key: "multi_lang",
+  content: {
+    welcomeMessage: t({
+      en: "Welcome to our application",
+      fr: "Bienvenue dans notre application",
+      es: "Bienvenido a nuestra aplicación",
+    }),
+  },
+};
+```
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+module.exports = {
+  key: "multi_lang",
+  content: {
+    welcomeMessage: t({
+      en: "Welcome to our application",
+      fr: "Bienvenue dans notre application",
+      es: "Bienvenido a nuestra aplicación",
+    }),
+  },
+};
+```
+
+```json fileName="**/*.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "multi_lang",
+  "content": {
+    "welcomeMessage": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Welcome to our application",
+        "fr": "Bienvenue dans notre application",
+        "es": "Bienvenido a nuestra aplicación"
+      }
+    }
+  }
+}
+```
+
+## Configuration for Locales
+
+To ensure proper translation handling, you can configure the accepted locales in `intlayer.config.ts`. This configuration allows you to define the languages that your application supports:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+  },
+};
+
+module.exports = config;
+```
+
+## Using Translations in React Components
+
+With `react-intlayer`, you can use translations in React components. Here's an example:
+
+```jsx fileName="**/*.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+const MyComponent: FC = () => {
+  const content = useIntlayer("multi_lang");
+
+  return (
+    <div>
+      <p>{content.welcomeMessage}</p>
+    </div>
+  );
+};
+
+export default MyComponent;
+```
+
+```javascript fileName="**/*.mjx" codeFormat="esm"
+import { useIntlayer } from "react-intlayer";
+
+const MyComponent = () => {
+  const content = useIntlayer("multi_lang");
+
+  return (
+    <div>
+      <p>{content.welcomeMessage}</p>
+    </div>
+  );
+};
+
+export default MyComponent;
+```
+
+```javascript fileName="**/*.cjs" codeFormat="commonjs"
+const { useIntlayer } = require("react-intlayer");
+
+const MyComponent = () => {
+  const content = useIntlayer("multi_lang");
+
+  return (
+    <div>
+      <p>{content.welcomeMessage}</p>
+    </div>
+  );
+};
+
+module.exports = MyComponent;
+```
+
+This component fetches the corresponding translation based on the current locale set in your application.
+
+## Custom Content Objects
+
+`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:
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+interface ICustomContent {
+  title: string;
+  content: string;
+}
+
+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;
+
+export default customContent;
+```
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+export default {
+  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",
+        },
+      },
+  },
+};
+```
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+module.exports = {
+  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",
+        },
+      },
+  },
+};
+```
+
+```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"
+        }
+      }
+    }
+  }
+}
+```

package/en/frequent_questions/build_dictionaries.md

@@ -0,0 +1,37 @@
+# Build Dictionaries
+
+## How to Build Dictionaries
+
+Intlayer provides a command-line tool to build dictionaries.
+
+```bash
+npx intlayer dictionaries build
+```
+
+This command:
+
+- Scans all content declaration files (`.content.{ts,tsx,js,mjs,cjs,json,...}`) in your project.
+- Generates dictionaries and stores them in the `.intlayer/dictionary` folder.
+
+### Watch Mode
+
+If you want to automatically update dictionaries when changes are made to content declaration files, run the following command:
+
+```bash
+npx intlayer dictionaries build --watch
+```
+
+In this mode, Intlayer will scan and build dictionaries whenever changes are made to content declaration files and automatically update the `.intlayer/dictionary` folder.
+
+### Using the VSCode extension
+
+You can also use the [Intlayer VSCode extension](https://github.com/aymericzip/intlayer/tree/main/docs/en/vs_code_extension.md) to enhance your Intlayer experience in VSCode.
+
+### Using the plugin for your favorite application framework
+
+If you are using a framework like Next.js (Webpack / Turbopack), Vite, or React Native, Lynx etc. Intlayer provides a plugin that you can use to integrate Intlayer into your application.
+
+Intlayer would build dictionaries before the build of your application.
+In the same way, in development mode, Intlayer would watch for changes in your content declaration files and rebuild dictionaries automatically.
+
+So refer to the specific documentation of your framework to learn how to integrate the plugin.

package/en/frequent_questions/domain_routing.md

@@ -0,0 +1,92 @@
+# How do I configure **domain‑based routing** with Intlayer instead of `/[locale]/` paths?
+
+## Short answer
+
+Domain-based routing is simpler than path-based routing (`example.com/[locale]/`) because you can skip all the middleware and routing configuration. Just deploy your app to each language domain and set one environment variable per domain.
+
+## Step‑by‑step
+
+1. **Deploy once per domain** (`example.com`, `exemple.fr`, `ejemplo.es`, …).
+2. For every deployment, set `LOCALE` (and the usual Intlayer env vars) to the locale that domain should serve.
+3. Reference that variable as `defaultLocale` in your `intlayer.config.[ts|js]`.
+
+```ts
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: process.env.LOCALE, // 👈 domain decides the locale
+  },
+  // ... rest of your config
+};
+
+export default config;
+```
+
+That's all—works the same for **Next.js**, **Vite + React**, **Vite + Vue**, etc.
+
+## What if every domain hits the **same** deployment?
+
+If all domains point to the same application bundle, you'll need to detect the host at runtime and pass the locale manually through the provider.
+
+### For Next.js
+
+```tsx
+// src/IntlayerProvider.tsx
+import {
+  IntlayerClientProvider,
+  type IntlayerClientProviderProps,
+} from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+import type { FC } from "react";
+
+export const IntlayerProvider: FC<IntlayerClientProviderProps> = ({
+  children,
+  locale,
+}) => {
+  const resolvedLocale = locale ?? getLocaleFromHostname();
+  return (
+    <IntlayerServerProvider locale={resolvedLocale}>
+      <IntlayerClientProvider locale={resolvedLocale}>
+        {children}
+      </IntlayerClientProvider>
+    </IntlayerServerProvider>
+  );
+};
+```
+
+### For Vue
+
+```ts
+import { createApp } from "vue";
+import { installIntlayer } from "vue-intlayer";
+import App from "./App.vue";
+import { router } from "./routes";
+
+const app = createApp(App);
+app.use(router);
+installIntlayer(app, getLocaleFromHostname());
+app.mount("#app");
+```
+
+Replace `getLocaleFromHostname()` with your own lookup logic.
+
+## Update your locale switcher
+
+When using domain-based routing, changing languages means navigating to another domain:
+
+```ts
+const { locale } = useLocale();
+
+function changeLanguage(target: Locale) {
+  window.location.href = domainForLocale[target];
+}
+```
+
+## Benefits of domain-based routing
+
+1. **Simpler configuration**: No need to configure `intlayerMiddleware`, `generateStaticParams`, `react-router`, or `vue-router`
+2. **Better SEO**: Each language has its own domain
+3. **Cleaner URLs**: No locale prefix in the path
+4. **Easier maintenance**: Each language deployment is independent

package/en/frequent_questions/esbuild_error.md

@@ -0,0 +1,9 @@
+# ESBuild Error
+
+If you encounter an ESBuild error during the build process, it's likely that the Intlayer plugin has not been configured correctly.
+
+ESBuild is responsible for reading the content declaration files (`.content.{ts,js,mjs,cjs,json}`) and generating the corresponding dictionaries in the `.intlayer/dictionary` folder. As well as reading the configuration file (`intlayer.config.ts`).
+
+Intlayer provides plugins to integrate with your bundlers. It is designed to alias components that are meant to run on the server side only.
+
+If you are using a framework like Next.js (Webpack / Turbopack), Vite, or React Native, Lynx etc. Intlayer provides a plugin that you can use to integrate Intlayer into your application. So refer to the specific documentation of your framework to learn how to integrate the plugin.

package/en/frequent_questions/get_locale_cookie.md

@@ -0,0 +1,121 @@
+# How to retrieve the locale from the cookies / headers
+
+## Using Hooks (Recommended)
+
+For most use cases, it's recommended to retrieve the current locale using the `useLocale` hook because it's auto-resolved. This works similarly to the `useLocale` composable in Vue.js.
+
+```ts
+import { useLocale } from "next-intlayer";
+// or import { useLocale } from "react-intlayer";
+// or import { useLocale } from "vue-intlayer";
+
+// Client-side usage
+const { locale } = useLocale();
+```
+
+For server components, you can import it from:
+
+```tsx
+import { useLocale } from "next-intlayer/server";
+
+const Test = () => {
+  const { locale } = useLocale();
+  return <>{locale}</>;
+};
+
+const Page = async ({ params }) => {
+  const { locale } = await params;
+
+  return (
+    <IntlayerServerProvider locale={locale}>
+      <Test />
+    </IntlayerServerProvider>
+  );
+};
+```
+
+There is also a `useLocaleCookie` hook that only resolves the cookie value.
+
+## Manual Cookie Configuration
+
+You can declare custom cookie name as
+
+```ts
+import { type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  middleware: {
+    cookieName: "myCustomLocaleCookie", // default is 'intlayer-locale'
+  },
+};
+
+export default config;
+```
+
+the retreave it as
+
+### Client-side
+
+```ts
+// Using the default cookie name
+const locale = document.cookie
+  .split("; ")
+  .find((row) => row.startsWith("intlayer-locale="))
+  ?.split("=")[1];
+
+// Using custom cookie name
+const locale = document.cookie
+  .split("; ")
+  .find((row) => row.startsWith("myCustomLocaleCookie="))
+  ?.split("=")[1];
+```
+
+### Server-side (Next.js)
+
+```ts
+import { cookies } from "next/headers";
+
+// Using the default cookie name
+const locale = cookies().get("intlayer-locale")?.value;
+
+// Using custom cookie name
+const locale = cookies().get("myCustomLocaleCookie")?.value;
+```
+
+### If locale not set yet
+
+The locale is set as a cookie only once the user select explicitly the locale. By default, for new visitors, the locale is interpreted from the headers fields.
+
+You can detect the user's preferred locale from the request headers. Here's an example of how to handle this:
+
+```ts
+/**
+ * Detects the locale from the request headers
+ *
+ * The accept-language header is the most important one for locale detection.
+ * It contains a list of language codes with quality values (q-values) that indicate
+ * the user's preferred languages in order of preference.
+ *
+ * Example: "en-US,en;q=0.9,fr;q=0.8,es;q=0.7"
+ * - en-US is the primary language (q=1.0 is implied)
+ * - en is the second choice (q=0.9)
+ * - fr is the third choice (q=0.8)
+ * - es is the fourth choice (q=0.7)
+ */
+import { localeDetector } from "@intlayer/core";
+
+/**
+ * Example of negotiator headers that browsers typically send
+ * These headers help determine the user's preferred language
+ */
+const exampleNegotiatorHeaders: Record<string, string> = {
+  "accept-language": "en-US,en;q=0.9,fr;q=0.8,es;q=0.7",
+  "accept":
+    "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
+  "user-agent":
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
+};
+
+// Usage example:
+const detectedLocale = localeDetector(exampleNegotiatorHeaders);
+```

package/en/frequent_questions/intlayer_command_undefined.md

@@ -0,0 +1,135 @@
+# Intlayer command undefined
+
+## Overview
+
+The Intlayer CLI provides a convenient way to control your intlayer content, including building dictionaries, pushing translations, and more. However, it's not essential for your project to work. If you're using the bundler plugin (like `withIntlayer()` for Next.js or `intlayerPlugin()` for Vite), Intlayer will automatically build dictionaries during app build or development server startup. In development mode, it will also watch for changes and rebuild content declaration files automatically.
+
+You can access the intlayer commands in different ways:
+
+- Using the `intlayer` cli command directly
+- Using the [VSCode extension](https://github.com/aymericzip/intlayer/blob/main/docs/en/vs_code_extension.md)
+- Using the `@intlayer/cli` SDK
+
+## Problem
+
+When trying to use the `intlayer` command, you might encounter this error:
+
+```bash
+'intlayer' is not recognized as an internal or external command,
+operable program or batch file.
+```
+
+## Solutions
+
+Try these solutions in order:
+
+1. **Verify the command is installed**
+
+```bash
+npx intlayer -h
+```
+
+Expected output:
+
+```bash
+Usage: intlayer [options] [command]
+
+Intlayer CLI
+
+Options:
+    -V, --version            output the version number
+    -h, --help               display help for command
+
+Commands:
+    dictionary|dictionaries  Dictionaries operations
+    configuration|config     Configuration operations
+    help [command]           display help for command
+```
+
+2. **Install the intlayer-cli package globally**
+
+```bash
+npm install intlayer-cli -g -g
+```
+
+> It should not be necessary if you've already installed `intlayer` package
+
+3. **Install the package globally**
+
+```bash
+npm install intlayer -g
+```
+
+4. **Restart your terminal**
+   Sometimes a terminal restart is needed to recognize new commands.
+
+5. **Clean and reinstall**
+   If the above solutions don't work:
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+6. **Verify installation files**
+   If the issue persists, check that these files exist:
+
+   - `node_modules/intlayer/dist/cjs/cli.cjs`
+   - `node_modules/intlayer/package.json` (should have a `bin` field referencing `./dist/cjs/cli.cjs`)
+
+7. **Check PATH environment variable**
+   Make sure the npm global bin directory is in your PATH:
+
+```bash
+# For Unix-based systems (macOS/Linux)
+echo $PATH
+# Should include something like /usr/local/bin or ~/.npm-global/bin
+
+# For Windows
+echo %PATH%
+# Should include the npm global bin directory
+```
+
+8. **Use npx with full path**
+   If the command is still not found, try using npx with the full path:
+
+```bash
+npx ./node_modules/intlayer/ dictionaries build
+```
+
+9. **Check for conflicting installations**
+
+```bash
+# List all globally installed packages
+npm list -g --depth=0
+
+# Remove any conflicting global installations
+npm uninstall -g intlayer
+npm uninstall -g intlayer-cli
+# Then reinstall
+npm install -g intlayer
+```
+
+10. **Verify Node.js and npm versions**
+    Make sure you're using compatible versions:
+
+```bash
+node --version
+npm --version
+```
+
+    If you're using an outdated version, consider updating Node.js and npm.
+
+11. **Check for permission issues**
+    If you're getting permission errors:
+
+    ```bash
+    # For Unix-based systems
+    sudo npm install -g intlayer
+
+    # Or change npm's default directory
+    mkdir ~/.npm-global
+    npm config set prefix '~/.npm-global'
+    # Add to your ~/.profile or ~/.bashrc:
+    export PATH=~/.npm-global/bin:$PATH
+    ```