@intlayer/docs 5.5.10 → 5.5.11

package/en/dictionary/translation.md

@@ -1,285 +0,0 @@
-# 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

@@ -1,37 +0,0 @@
-# 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

@@ -1,92 +0,0 @@
-# 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

@@ -1,9 +0,0 @@
-# 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

@@ -1,121 +0,0 @@
-# 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

@@ -1,135 +0,0 @@
-# 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
-    ```