@intlayer/docs 5.5.8

package/en/packages/intlayer/index.md

@@ -0,0 +1,476 @@
+# intlayer: NPM Package to Manage Multilingual Dictionary (i18n)
+
+**Intlayer** is a suite of packages designed specifically for JavaScript developers. It is compatible with frameworks like React, Next.js, and Express.js.
+
+**The `intlayer` package** allows you to declare your content anywhere in your code. It converts multilingual content declarations into structured dictionaries that integrate seamlessly into your application. With TypeScript, **Intlayer** enhances your development by providing stronger, more efficient tools.
+
+## Why to integrate Intlayer?
+
+- **JavaScript-Powered Content Management**: Harness the flexibility of JavaScript to define and manage your content efficiently.
+- **Type-Safe Environment**: Leverage TypeScript to ensure all your content definitions are precise and error-free.
+- **Integrated Content Files**: Keep your translations close to their respective components, enhancing maintainability and clarity.
+
+## Installation
+
+Install the necessary package using your preferred package manager:
+
+```bash packageManager="npm"
+npm install intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer
+```
+
+```bash packageManager="yarn"
+yarn add intlayer
+```
+
+### Configure Intlayer
+
+Intlayer provides a configuration file to set up your project. Place this file in the root of your project.
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+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],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+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],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+module.exports = config;
+```
+
+> For a complete list of available parameters, refer to the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/configuration.md).
+
+## Example of usage
+
+With Intlayer, you can declare your content in a structured way anywhere in your codebase.
+
+By default, Intlayer scans for files with the extension `.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}`.
+
+> can modify the default extension by setting the `contentDir` property in the [configuration file](https://github.com/aymericzip/intlayer/blob/main/docs/en/configuration.md).
+
+```bash codeFormat="typescript"
+.
+├── intlayer.config.ts
+└── src
+    ├── ClientComponent
+    │   ├── index.content.ts
+    │   └── index.tsx
+    └── ServerComponent
+        ├── index.content.ts
+        └── index.tsx
+```
+
+```bash codeFormat="esm"
+.
+├── intlayer.config.mjs
+└── src
+    ├── ClientComponent
+    │   ├── index.content.mjs
+    │   └── index.mjx
+    └── ServerComponent
+        ├── index.content.mjs
+        └── index.mjx
+```
+
+```bash codeFormat="commonjs"
+.
+├── intlayer.config.cjs
+└── src
+    ├── ClientComponent
+    │   ├── index.content.cjs
+    │   └── index.cjx
+    └── ServerComponent
+        ├── index.content.cjs
+        └── index.cjx
+```
+
+### Declare your content
+
+Here’s an example of content declaration:
+
+```tsx fileName="src/ClientComponent/index.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const clientComponentContent = {
+  key: "client-component",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    numberOfCar: enu({
+      "<-1": "Less than minus one car",
+      "-1": "Minus one car",
+      "0": "No cars",
+      "1": "One car",
+      ">5": "Some cars",
+      ">19": "Many cars",
+    }),
+  },
+} satisfies Dictionary;
+
+export default clientComponentContent;
+```
+
+```jsx fileName="src/ClientComponent/index.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const clientComponentContent = {
+  key: "client-component",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    numberOfCar: enu({
+      "<-1": "Less than minus one car",
+      "-1": "Minus one car",
+      "0": "No cars",
+      "1": "One car",
+      ">5": "Some cars",
+      ">19": "Many cars",
+    }),
+  },
+};
+
+export default clientComponentContent;
+```
+
+```jsx fileName="src/ClientComponent/index.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const clientComponentContent = {
+  key: "client-component",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    numberOfCar: enu({
+      "<-1": "Less than minus one car",
+      "-1": "Minus one car",
+      "0": "No cars",
+      "1": "One car",
+      ">5": "Some cars",
+      ">19": "Many cars",
+    }),
+  },
+};
+
+module.exports = clientComponentContent;
+```
+
+```json fileName="src/ClientComponent/index.content.json" codeFormat="json"
+{
+  "key": "client-component",
+  "content": {
+    "myTranslatedContent": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Hello World",
+        "fr": "Bonjour le monde",
+        "es": "Hola Mundo"
+      }
+    },
+    "numberOfCar": {
+      "nodeType": "enumeration",
+      "enumeration": {
+        "<-1": "Less than minus one car",
+        "-1": "Minus one car",
+        "0": "No cars",
+        "1": "One car",
+        ">5": "Some cars",
+        ">19": "Many cars"
+      }
+    }
+  }
+}
+```
+
+### Build your dictionaries
+
+You can build your dictionaries using the [intlayer-cli](https://github.com/aymericzip/intlayer/blob/main/packages/intlayer-cli/readme.md).
+
+```bash packageManager="npm"
+npx intlayer dictionaries build
+```
+
+```bash packageManager="yarn"
+yarn intlayer build
+```
+
+```bash packageManager="pnpm"
+pnpm intlayer build
+```
+
+This command scans all `*.content.*` files, compiles them, and writes the results to the directory specified in your **`intlayer.config.ts`** (by default, `./.intlayer`).
+
+A typical output might look like:
+
+```bash
+.
+└── .intlayer
+    ├── dictionary  # Contain the dictionary of your content
+    │   ├── client-component.json
+    │   └── server-component.json
+    ├── main  # Contain the entry point of your dictionary to be used in your application
+    │   ├── dictionary.cjs
+    │   └── dictionary.mjs
+    └── types  # Contain the auto-generated type definitions of your dictionary
+        ├── intlayer.d.ts  # Contain the auto-generated type definitions of Intlayer
+        ├── client-component.d.ts
+        └── server-component.d.ts
+```
+
+### Build i18next resources
+
+Intlayer can be configured to build dictionaries for [i18next](https://www.i18next.com/). For that you need to add the following configuration to your `intlayer.config.ts` file:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  /* ... */
+  content: {
+    // Tells Intlayer to generate message files for i18next
+    dictionaryOutput: ["i18next"],
+
+    // The directory where Intlayer will write your message JSON files
+    i18nextResourcesDir: "./i18next/resources",
+  },
+};
+```
+
+```typescript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  /* ... */
+  content: {
+    // Tells Intlayer to generate message files for i18next
+    dictionaryOutput: ["i18next"],
+
+    // The directory where Intlayer will write your message JSON files
+    i18nextResourcesDir: "./i18next/resources",
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  /* ... */
+  content: {
+    // Tells Intlayer to generate message files for i18next
+    dictionaryOutput: ["i18next"],
+
+    // The directory where Intlayer will write your message JSON files
+    i18nextResourcesDir: "./i18next/resources",
+  },
+};
+
+module.exports = config;
+```
+
+> For a complete list of available parameters, refer to the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/configuration.md).
+
+Output:
+
+```bash
+.
+└── i18next
+    └── resources
+        ├── en
+        │   ├── client-component.json
+        │   └── server-component.json
+        ├── es
+        │   ├── client-component.json
+        │   └── server-component.json
+        └── fr
+            ├── client-component.json
+            └── server-component.json
+```
+
+For example, the **en/client-component.json** might look like:
+
+```json fileName="intlayer/dictionary/en/client-component.json"
+{
+  "myTranslatedContent": "Hello World",
+  "zero_numberOfCar": "No cars",
+  "one_numberOfCar": "One car",
+  "two_numberOfCar": "Two cars",
+  "other_numberOfCar": "Some cars"
+}
+```
+
+### Build next-intl dictionaries
+
+Intlayer can be configured to build dictionaries for [i18next](https://www.i18next.com/) or [next-intl](https://github.com/formatjs/react-intl/tree/main/packages/next-intl). For that you need to add the following configuration to your `intlayer.config.ts` file:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  /* ... */
+  content: {
+    // Tells Intlayer to generate message files for i18next
+    dictionaryOutput: ["next-intl"],
+
+    // The directory where Intlayer will write your message JSON files
+    nextIntlMessagesDir: "./i18next/messages",
+  },
+};
+```
+
+```typescript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  /* ... */
+  content: {
+    // Tells Intlayer to generate message files for i18next
+    dictionaryOutput: ["next-intl"],
+
+    // The directory where Intlayer will write your message JSON files
+    nextIntlMessagesDir: "./i18next/messages",
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  /* ... */
+  content: {
+    // Tells Intlayer to generate message files for i18next
+    dictionaryOutput: ["next-intl"],
+
+    // The directory where Intlayer will write your message JSON files
+    nextIntlMessagesDir: "./intl/messages",
+  },
+};
+
+module.exports = config;
+```
+
+> For a complete list of available parameters, refer to the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/configuration.md).
+
+Output:
+
+```bash
+.
+└── intl
+    └── messages
+        ├── en
+        │   ├── client-component.json
+        │   └── server-component.json
+        ├── es
+        │   ├── client-component.json
+        │   └── server-component.json
+        └── fr
+            ├── client-component.json
+            └── server-component.json
+```
+
+For example, the **en/client-component.json** might look like:
+
+```json fileName="intlayer/dictionary/en/client-component.json"
+{
+  "myTranslatedContent": "Hello World",
+  "zero_numberOfCar": "No cars",
+  "one_numberOfCar": "One car",
+  "two_numberOfCar": "Two cars",
+  "other_numberOfCar": "Some cars"
+}
+```
+
+## CLI tools
+
+Intlayer provides a CLI tool to:
+
+- audit your content declarations and complete missing translations
+- build dictionaries from your content declarations
+- push and pull distant dictionaries from your CMS to your locale project
+
+Consult [intlayer-cli](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_cli.md) for more information.
+
+## Use Intlayer into your application
+
+One your content declared, you can consume your Intlayer dictionaries in your application.
+
+Intlayer is available as a package for your application.
+
+### React Application
+
+To use Intlayer in your React application, you can use [react-intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/react-intlayer/index.md).
+
+### Next.js Application
+
+To use Intlayer in your Next.js application, you can use [next-intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/next-intlayer/index.md).
+
+### Express Application
+
+To use Intlayer in your Express application, you can use [express-intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/express-intlayer/index.md).
+
+## Functions provided by `intlayer` package
+
+The `intlayer` package also provides some functions to help you to internationalize your application.
+
+- [`getConfiguration()`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getConfiguration.md)
+- [`getTranslation()`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getTranslation.md)
+- [`getEnumeration()`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getEnumeration.md)
+- [`getLocaleName()`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getLocaleName.md)
+- [`getLocaleLang()`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getLocaleLang.md)
+- [`getHTMLTextDir()`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getHTMLTextDir.md)
+- [`getPathWithoutLocale()`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getPathWithoutLocale.md)
+- [`getMultilingualUrls()`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getMultilingualUrls.md)
+- [`getLocalizedUrl()`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getLocalizedUrl.md)
+- [`getPathWithoutLocale()`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getPathWithoutLocale.md)

package/en/packages/intlayer-cli/index.md

@@ -0,0 +1,41 @@
+# intlayer-cli: NPM Package to use the Intlayer CLI
+
+**Intlayer** is a suite of packages designed specifically for JavaScript developers. It is compatible with frameworks like React, React, and Express.js.
+
+The **`intlayer-cli`** package is a NPM package that consume the `@intlayer/cli` package and make it available to the `intlayer` commands line interfaces.
+
+> Note that this package is not needed if the [`intlayer`](https://github.com/aymericzip/intlayer/tree/main/docs/en/packages/intlayer/index.md) package is installed. In comparison to the `intlayer` package, the `intlayer-cli` package is a lighter package that only contains the CLI tool, without `@intlayer/core` dependencies.
+
+## Installation
+
+Install the necessary package using your preferred package manager:
+
+```bash packageManager="npm"
+npm install intlayer-cli -g
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer-cli -g
+```
+
+```bash packageManager="yarn"
+yarn add intlayer-cli -g
+```
+
+## Usage
+
+Here an example of how to use the `intlayer-cli` package:
+
+```bash
+npx intlayer dictionaries build
+```
+
+## CLI commands
+
+Intlayer provides a CLI tool to:
+
+- audit your content declarations and complete missing translations
+- build dictionaries from your content declarations
+- push and pull distant dictionaries from your CMS to your locale project
+
+Consult [intlayer-cli](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_cli.md) for more information.

package/en/packages/intlayer-editor/index.md

@@ -0,0 +1,113 @@
+# intlayer-editor: NPM Package to use the Intlayer visual editor
+
+**Intlayer** is a suite of packages designed specifically for JavaScript developers. It is compatible with frameworks like React, React, and Express.js.
+
+The **`intlayer-editor`** package is a NPM package that integrates the Intlayer visual editor into your React project.
+
+## How Intlayer Editor Works
+
+The intlayer editor allows to interact with the Intlayer distant dictionary. It can be installed on the client side and transform your application into a CMS-like editor to manage your site's content in all configured languages.
+
+![Intlayer Editor Interface](https://github.com/aymericzip/intlayer/blob/main/docs/assets/intlayer_editor_ui.png)
+
+## Installation
+
+Install the necessary package using your preferred package manager:
+
+```bash packageManager="npm"
+npm install intlayer-editor
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer-editor
+```
+
+```bash packageManager="yarn"
+yarn add intlayer-editor
+```
+
+### Configuration
+
+In your Intlayer configuration file, you can customize the editor settings:
+
+```typescript
+const config: IntlayerConfig = {
+  // ... other configuration settings
+  editor: {
+    enabled: process.env.INTLAYER_ENABLED === "true", // If false, the editor is inactive and cannot be accessed.
+    // Client ID and client secret are required to enable the editor.
+    // They allow the identify the user who is editing the content.
+    // They can be obtained by creating a new client in the Intlayer Dashboard - Projects (https://intlayer.org/dashboard/projects).
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+};
+```
+
+> If you don't have a client ID and client secret, you can obtain them by creating a new client in the [Intlayer Dashboard - Projects](https://intlayer.org/dashboard/projects).
+
+> To see all available parameters, refer to the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/configuration.md)
+
+The `intlayer-editor` package is based on Intlayer and is available for JavaScript applications, such as React (Create React App), Vite + React, and Next.js.
+
+For more details on how to install the package, see the relevant section below:
+
+### Integrating with Next.js
+
+For integration with Next.js, refer to the [setup guide](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_with_nextjs_15.md).
+
+### Integrating with Create React App
+
+For integration with Create React App, refer to the [setup guide](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_with_create_react_app.md)
+
+### Integrating with Vite + React
+
+For integration with Vite + React, refer to the [setup guide](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_with_vite+react.md)
+
+### Example of integration
+
+To integrate the Intlayer visual editor into your React project, follow these steps:
+
+- Import the Intlayer editor component into your React application:
+
+  ```tsx fileName="src/App.jsx"
+  import { IntlayerEditorProvider } from "intlayer-editor";
+  import { IntlayerProvider } from "react-intlayer";
+
+  export default function App() {
+    return (
+      <IntlayerProvider>
+        <IntlayerEditorProvider>
+          <IntlayerEditor>{/* Your App content here */}</IntlayerEditor>
+        </IntlayerEditorProvider>
+      </IntlayerProvider>
+    );
+  }
+  ```
+
+- Import the Intlayer editor styles into your Next.js application:
+
+  ```tsx fileName="src/app/[locale]/layout.jsx"
+  import { IntlayerEditorStyles } from "intlayer-editor";
+
+  export default async function RootLayout({ children, params }) {
+    const { locale } = await params;
+    return (
+      <IntlayerClientProvider locale={locale}>
+        <IntlayerEditorProvider>
+          <html lang={locale}>
+            <body className={IntlayerEditorStyles}>{children}</body>
+          </html>
+        </IntlayerEditorProvider>
+      </IntlayerClientProvider>
+    );
+  }
+  ```
+
+## Using the Editor
+
+When the editor is installed, enabled, and started, you can view each field indexed by Intlayer by hovering over your content with your cursor.
+
+![Hovering over content](https://github.com/aymericzip/intlayer/blob/main/docs/assets/intlayer_editor_hover_content.png)
+
+If your content is outlined, you can long-press it to display the edit drawer.

package/en/packages/lynx-intlayer/index.md

@@ -0,0 +1,60 @@
+# lynx-intlayer: Internationalize (i18n) an Lynx application
+
+**Intlayer** is a suite of packages designed specifically for JavaScript developers. It is compatible with frameworks like React, React, and Express.js.
+
+**The `lynx-intlayer` package** allows you to internationalize your Vite application. It includes the Metro plugin to set the configuration through environment variables into the [Lynx bundler](https://lynxjs.org/index.html).
+
+## Why Internationalize Your Lynx Application?
+
+Internationalizing your Lynx application is essential for serving a global audience effectively. It allows your application to deliver content and messages in the preferred language of each user. This capability enhances user experience and broadens your application's reach by making it more accessible and relevant to people from different linguistic backgrounds.
+
+## Configuration
+
+The `lynx-intlayer` package works seamlessly with the [`react-intlayer` package](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/react-intlayer/index.md), and the [`intlayer` package](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/index.md). Have a look at the relevant documentation for more information.
+
+## Installation
+
+Install the necessary package using your preferred package manager:
+
+```bash packageManager="npm"
+npm install lynx-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add lynx-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add lynx-intlayer
+```
+
+## Example of usage
+
+See an example of how to include the plugins into your vite configuration.
+
+```ts
+// lynx.config.ts
+import { defineConfig } from "@lynx-js/rspeedy";
+import { pluginIntlayerLynx } from "lynx-intlayer/plugin";
+
+export default defineConfig({
+  plugins: [
+    // ... other plugins
+    pluginIntlayerLynx(),
+  ],
+});
+```
+
+## Mastering the internationalization of your Vite application
+
+Intlayer provides a lot of features to help you internationalize your Vite application.
+
+**To learn more about these features, refer to the [React Internationalization (i18n) with Intlayer and Lynx](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_with_lynx+react.md) guide for Lynx Application.**
+
+## Read about Intlayer
+
+- [Intlayer Website](https://intlayer.org)
+- [Intlayer Documentation](https://intlayer.org/doc)
+- [Intlayer GitHub](https://github.com/aymericzip/intlayer)
+
+- [Ask your questions to our smart documentation](https://intlayer.org/doc/chat)