@intlayer/docs 5.5.8

package/en/dictionary/get_started.md

@@ -0,0 +1,504 @@
+# Getting Started the declaration of your content
+
+<iframe title="i18n, Markdown, JSON… one single solution to manage it all | Intlayer" class="m-auto aspect-[16/9] w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/1VHgSY_j9_I?autoplay=0&amp;origin=http://intlayer.org&amp;controls=0&amp;rel=1"/>
+
+## Files extensions
+
+By default, Intlayer watches all files with the following extensions for content declarations:
+
+- `.content.json`
+- `.content.ts`
+- `.content.tsx`
+- `.content.js`
+- `.content.jsx`
+- `.content.mjs`
+- `.content.mjx`
+- `.content.cjs`
+- `.content.cjx`
+
+The application will search for files that match the `./src/**/*.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}` glob pattern by default.
+
+These default extensions are suitable for most applications. However, if you have specific requirements, refer to the [content extension customization guide](https://github.com/aymericzip/intlayer/blob/main/docs/en/configuration.md#content-configuration) for instructions on how to manage them.
+
+For a full list of configuration options, visit the configuration documentation.
+
+## Declare Your Content
+
+Create and manage your dictionaries:
+
+```tsx fileName="src/example.content.tsx" contentDeclarationFormat="typescript"
+import { type ReactNode } from "react";
+import {
+  t,
+  enu,
+  cond,
+  nest,
+  md,
+  insert,
+  file,
+  type Dictionary,
+} from "intlayer";
+
+interface Content {
+  imbricatedContent: {
+    imbricatedContent2: {
+      stringContent: string;
+      numberContent: number;
+      booleanContent: boolean;
+      javaScriptContent: string;
+    };
+  };
+  multilingualContent: string;
+  quantityContent: string;
+  conditionalContent: string;
+  markdownContent: never;
+  externalContent: string;
+  insertionContent: string;
+  nestedContent: string;
+  fileContent: string;
+  jsxContent: ReactNode;
+}
+
+export default {
+  key: "page",
+  content: {
+    imbricatedContent: {
+      imbricatedContent2: {
+        stringContent: "Hello World",
+        numberContent: 123,
+        booleanContent: true,
+        javaScriptContent: `${process.env.NODE_ENV}`,
+      },
+    },
+    multilingualContent: t({
+      en: "English content",
+      "en-GB": "English content (UK)",
+      fr: "French content",
+      es: "Spanish content",
+    }),
+    quantityContent: enu({
+      "<-1": "Less than minus one car",
+      "-1": "Minus one car",
+      "0": "No cars",
+      "1": "One car",
+      ">5": "Some cars",
+      ">19": "Many cars",
+    }),
+    conditionalContent: cond({
+      true: "Validation is enabled",
+      false: "Validation is disabled",
+    }),
+    insertionContent: insert("Hello {{name}}!"),
+    nestedContent: nest(
+      "navbar", // The key of the dictionary to nest
+      "login.button" // [Optional] The path to the content to nest
+    ),
+    fileContent: file("./path/to/file.txt"),
+    externalContent: fetch("https://example.com").then((res) => res.json()),
+    markdownContent: md("# Markdown Example"),
+
+    /*
+     * Only available using `react-intlayer` or `next-intlayer`
+     */
+    jsxContent: <h1>My title</h1>,
+  },
+} satisfies Dictionary<Content>; // [optional] Dictionary is generic and allow you to strengthen the formatting of your dictionary
+```
+
+```javascript fileName="src/example.content.mjx" contentDeclarationFormat="esm"
+import { t, enu, cond, nest, md, insert, file } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+export default {
+  key: "page",
+  content: {
+    imbricatedContent: {
+      imbricatedContent2: {
+        stringContent: "Hello World",
+        numberContent: 123,
+        booleanContent: true,
+        javaScriptContent: `${process.env.NODE_ENV}`,
+      },
+      imbricatedArray: [1, 2, 3],
+    },
+    multilingualContent: t({
+      en: "English content",
+      "en-GB": "English content (UK)",
+      fr: "French content",
+      es: "Spanish content",
+    }),
+    quantityContent: enu({
+      "<-1": "Less than minus one car",
+      "-1": "Minus one car",
+      "0": "No cars",
+      "1": "One car",
+      ">5": "Some cars",
+      ">19": "Many cars",
+    }),
+    conditionalContent: cond({
+      true: "Validation is enabled",
+      false: "Validation is disabled",
+    }),
+    insertionContent: insert("Hello {{name}}!"),
+    nestedContent: nest(
+      "navbar", // The key of the dictionary to nest
+      "login.button" // [Optional] The path to the content to nest
+    ),
+    markdownContent: md("# Markdown Example"),
+    fileContent: file("./path/to/file.txt"),
+    externalContent: fetch("https://example.com").then((res) => res.json())
+
+    // Only available using `react-intlayer` or `next-intlayer`
+    jsxContent: <h1>My title</h1>,
+  },
+};
+```
+
+```javascript fileName="src/example.content.cjx" contentDeclarationFormat="commonjs"
+const { t, enu, cond, nest, md, insert, file } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+module.exports = {
+  key: "page",
+  content: {
+    imbricatedContent: {
+      imbricatedContent2: {
+        stringContent: "Hello World",
+        numberContent: 123,
+        booleanContent: true,
+        javaScriptContent: `${process.env.NODE_ENV}`,
+      },
+      imbricatedArray: [1, 2, 3],
+    },
+    multilingualContent: t({
+      en: "English content",
+      "en-GB": "English content (UK)",
+      fr: "French content",
+      es: "Spanish content",
+    }),
+    quantityContent: enu({
+      "<-1": "Less than minus one car",
+      "-1": "Minus one car",
+      "0": "No cars",
+      "1": "One car",
+      ">5": "Some cars",
+      ">19": "Many cars",
+    }),
+    conditionalContent: cond({
+      true: "Validation is enabled",
+      false: "Validation is disabled",
+    }),
+    insertionContent: insert("Hello {{name}}!"),
+    nestedContent: nest(
+      "navbar", // The key of the dictionary to nest
+      "login.button" // [Optional] The path to the content to nest
+    ),
+    markdownContent: md("# Markdown Example"),
+    fileContent: file("./path/to/file.txt"),
+    externalContent: fetch("https://example.com").then((res) => res.json())
+
+    // Only available using `react-intlayer` or `next-intlayer`
+    jsxContent: <h1>My title</h1>,
+  },
+};
+```
+
+```json5 fileName="src/example.content.json"  contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "page",
+  "content": {
+    "imbricatedContent": {
+      "imbricatedContent2": {
+        "stringContent": "Hello World",
+        "numberContent": 123,
+        "booleanContent": true,
+      },
+      "imbricatedArray": [1, 2, 3],
+    },
+    "multilingualContent": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "English content",
+        "en-GB": "English content (UK)",
+        "fr": "French content",
+        "es": "Spanish content",
+      },
+    },
+    "quantityContent": {
+      "nodeType": "enumeration",
+      "enumeration": {
+        "0": "No cars",
+        "1": "One car",
+        "<-1": "Less than minus one car",
+        "-1": "Minus one car",
+        ">5": "Some cars",
+        ">19": "Many cars",
+      },
+    },
+    "conditionalContent": {
+      "nodeType": "condition",
+      "condition": {
+        "true": "Validation is enabled",
+        "false": "Validation is disabled",
+      },
+    },
+    "insertionContent": {
+      "nodeType": "insertion",
+      "insertion": "Hello {{name}}!",
+    },
+    "nestedContent": {
+      "nodeType": "nested",
+      "nested": { "dictionaryKey": "app" },
+    },
+    "markdownContent": {
+      "nodeType": "markdown",
+      "markdown": "# Markdown Example",
+    },
+    "fileContent": {
+      "nodeType": "file",
+      "file": "./path/to/file.txt",
+    },
+    "jsxContent": {
+      "type": "h1",
+      "key": null,
+      "ref": null,
+      "props": {
+        "children": ["My title"],
+      },
+    },
+  },
+}
+```
+
+## Function imbrication
+
+You can without problem imbricate functions into other ones.
+
+Example :
+
+```javascript fileName="src/example.content.tsx" contentDeclarationFormat="typescript"
+import { t, enu, cond, nest, md, type Dictionary } from "intlayer";
+
+const getName = async () => "John Doe";
+
+export default {
+  key: "page",
+  content: {
+    // `getIntlayer('page','en').hiMessage` returns `['Hi', ' ', 'John Doe']`
+    hiMessage: [
+      t({
+        en: "Hi",
+        fr: "Salut",
+        es: "Hola",
+      }),
+      " ",
+      getName(),
+    ],
+    // Composite content imbricating condition, enumeration, and multilingual content
+    // `getIntlayer('page','en').advancedContent(true)(10) returns 'Multiple items found'`
+    advancedContent: cond({
+      true: enu({
+        "0": t({
+          en: "No items found",
+          fr: "Aucun article trouvé",
+          es: "No se encontraron artículos",
+        }),
+        "1": t({
+          en: "One item found",
+          fr: "Un article trouvé",
+          es: "Se encontró un artículo",
+        }),
+        ">1": t({
+          en: "Multiple items found",
+          fr: "Plusieurs articles trouvés",
+          es: "Se encontraron múltiples artículos",
+        }),
+      }),
+      false: t({
+        en: "No valid data available",
+        fr: "Aucune donnée valide disponible",
+        es: "No hay datos válidos disponibles",
+      }),
+    }),
+  },
+} satisfies Dictionary;
+```
+
+```javascript fileName="src/example.content.mjx" contentDeclarationFormat="esm"
+import { t, enu, cond, nest, md } from "intlayer";
+
+const getName = async () => "John Doe";
+
+/** @type {import('intlayer').Dictionary} */
+export default {
+  key: "page",
+  content: {
+    // `getIntlayer('page','en').hiMessage` returns `['Hi', ' ', 'John Doe']`
+    hiMessage: [
+      t({
+        en: "Hi",
+        fr: "Salut",
+        es: "Hola",
+      }),
+      " ",
+      getName(),
+    ],
+    // Composite content imbricating condition, enumeration, and multilingual content
+    // `getIntlayer('page','en').advancedContent(true)(10) returns 'Multiple items found'`
+    advancedContent: cond({
+      true: enu({
+        "0": t({
+          en: "No items found",
+          fr: "Aucun article trouvé",
+          es: "No se encontraron artículos",
+        }),
+        "1": t({
+          en: "One item found",
+          fr: "Un article trouvé",
+          es: "Se encontró un artículo",
+        }),
+        ">1": t({
+          en: "Multiple items found",
+          fr: "Plusieurs articles trouvés",
+          es: "Se encontraron múltiples artículos",
+        }),
+      }),
+      false: t({
+        en: "No valid data available",
+        fr: "Aucune donnée valide disponible",
+        es: "No hay datos válidos disponibles",
+      }),
+    }),
+  },
+};
+```
+
+```javascript fileName="src/example.content.cjx" contentDeclarationFormat="commonjs"
+const { t, enu, cond, nest, md } = require("intlayer");
+
+const getName = async () => "John Doe";
+
+/** @type {import('intlayer').Dictionary} */
+module.exports = {
+  key: "page",
+  content: {
+    // `getIntlayer('page','en').hiMessage` returns `['Hi', ' ', 'John Doe']`
+    hiMessage: [
+      t({
+        en: "Hi",
+        fr: "Salut",
+        es: "Hola",
+      }),
+      " ",
+      getName(),
+    ],
+    // Composite content imbricating condition, enumeration, and multilingual content
+    // `getIntlayer('page','en').advancedContent(true)(10) returns 'Multiple items found'`
+    advancedContent: cond({
+      true: enu({
+        "0": t({
+          en: "No items found",
+          fr: "Aucun article trouvé",
+          es: "No se encontraron artículos",
+        }),
+        "1": t({
+          en: "One item found",
+          fr: "Un article trouvé",
+          es: "Se encontró un artículo",
+        }),
+        ">1": t({
+          en: "Multiple items found",
+          fr: "Plusieurs articles trouvés",
+          es: "Se encontraron múltiples artículos",
+        }),
+      }),
+      false: t({
+        en: "No valid data available",
+        fr: "Aucune donnée valide disponible",
+        es: "No hay datos válidos disponibles",
+      }),
+    }),
+  },
+};
+```
+
+```json5 fileName="src/example.content.json"  contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "page",
+  "content": {
+    "hiMessage": {
+      "nodeType": "composite",
+      "composite": [
+        {
+          "nodeType": "translation",
+          "translation": {
+            "en": "Hi",
+            "fr": "Salut",
+            "es": "Hola",
+          },
+        },
+        " ",
+        "John Doe",
+      ],
+    },
+    "advancedContent": {
+      "nodeType": "condition",
+      "condition": {
+        "true": {
+          "nodeType": "enumeration",
+          "enumeration": {
+            "0": {
+              "nodeType": "translation",
+              "translation": {
+                "en": "No items found",
+                "fr": "Aucun article trouvé",
+                "es": "No se encontraron artículos",
+              },
+            },
+            "1": {
+              "nodeType": "translation",
+              "translation": {
+                "en": "One item found",
+                "fr": "Un article trouvé",
+                "es": "Se encontró un artículo",
+              },
+            },
+            ">1": {
+              "nodeType": "translation",
+              "translation": {
+                "en": "Multiple items found",
+                "fr": "Plusieurs articles trouvés",
+                "es": "Se encontraron múltiples artículos",
+              },
+            },
+          },
+        },
+        "false": {
+          "nodeType": "translation",
+          "translation": {
+            "en": "No valid data available",
+            "fr": "Aucune donnée valide disponible",
+            "es": "No hay datos válidos disponibles",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## Additional Resources
+
+For more details in Intlayer, refer to the following resources:
+
+- [Per-Locale Content Declaration Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/dictionary/per_locale_file.md)
+- [Translation Content Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/dictionary/translation.md)
+- [Enumeration Content Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/dictionary/enumeration.md)
+- [Condition Content Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/dictionary/condition.md)
+- [Insertion Content Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/dictionary/insertion.md)
+- [File Content Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/dictionary/file.md)
+- [Nesting Content Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/dictionary/nesting.md)
+- [Markdown Content Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/dictionary/markdown.md)
+- [Function Fetching Content Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/dictionary/function_fetching.md)

package/en/dictionary/insertion.md

@@ -0,0 +1,167 @@
+# Insertion Content / Insertion in Intlayer
+
+## How Insertion Works
+
+In Intlayer, insertion content is achieved through the `insertion` function, which identifies placeholder fields in a string (such as `{{name}}` or `{{age}}`) that can be replaced dynamically at runtime. This approach allows you to create flexible, template-like strings where specific parts of the content are determined by data passed in from your application.
+
+When integrated with React Intlayer or Next Intlayer, you can simply provide the data object containing the values for each placeholder, and Intlayer will automatically render the content with the placeholders replaced.
+
+## Setting Up Insertion Content
+
+To set up insertion content in your Intlayer project, create a content module that includes your insertion definitions. Below are examples in various formats.
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import { insert, type Dictionary } from "intlayer";
+
+const myInsertionContent = {
+  key: "my_key",
+  content: {
+    myInsertion: insert(
+      "Hello, my name is {{name}} and I am {{age}} years old!"
+    ),
+  },
+} satisfies Dictionary;
+
+export default myInsertionContent;
+```
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+import { insert } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const myInsertionContent = {
+  key: "my_key",
+  content: {
+    myInsertion: insert(
+      "Hello, my name is {{name}} and I am {{age}} years old!"
+    ),
+  },
+};
+
+export default myInsertionContent;
+```
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+const { insert } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const myInsertionContent = {
+  key: "my_key",
+  content: {
+    myInsertion: insert(
+      "Hello, my name is {{name}} and I am {{age}} years old!"
+    ),
+  },
+};
+
+module.exports = myInsertionContent;
+```
+
+```json5 fileName="**/*.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "my_key",
+  "content": {
+    "myInsertion": {
+      "nodeType": "insertion",
+      "insertion": "Hello, my name is {{name}} and I am {{age}} years old!",
+    },
+  },
+}
+```
+
+## Using Insertion Content with React Intlayer
+
+To utilize insertion content within a React component, import and use the `useIntlayer` hook from the `react-intlayer` package. This hook retrieves the content for the specified key and allows you to pass in an object that maps each placeholder in your content to the value you wish to display.
+
+```tsx fileName="**/*.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+const InsertionComponent: FC = () => {
+  const { myInsertion } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <p>
+        {
+          /* Output: "Hello, my name is John and I am 30 years old!" */
+          myInsertion({ name: "John", age: "30" })
+        }
+      </p>
+      <p>
+        {
+          /* You can reuse the same insertion with different values */
+          myInsertion({ name: "Alice", age: "25" })
+        }
+      </p>
+    </div>
+  );
+};
+
+export default InsertionComponent;
+```
+
+```javascript fileName="**/*.mjx" codeFormat="esm"
+import { useIntlayer } from "react-intlayer";
+
+const InsertionComponent = () => {
+  const { myInsertion } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <p>
+        {
+          /* Output: "Hello, my name is John and I am 30 years old!" */
+          myInsertion({ name: "John", age: "30" })
+        }
+      </p>
+      <p>
+        {
+          /* You can reuse the same insertion with different values */
+          myInsertion({ name: "Alice", age: "25" })
+        }
+      </p>
+    </div>
+  );
+};
+
+export default InsertionComponent;
+```
+
+```javascript fileName="**/*.cjs" codeFormat="commonjs"
+const { useIntlayer } = require("react-intlayer");
+
+const InsertionComponent = () => {
+  const { myInsertion } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <p>
+        {
+          /* Output: "Hello, my name is John and I am 30 years old!" */
+          myInsertion({ name: "John", age: "30" })
+        }
+      </p>
+      <p>
+        {
+          /* You can reuse the same insertion with different values */
+          myInsertion({ name: "Alice", age: "25" })
+        }
+      </p>
+    </div>
+  );
+};
+
+module.exports = InsertionComponent;
+```
+
+## Additional Resources
+
+For more detailed information on configuration and usage, refer to the following resources:
+
+- [Intlayer CLI Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_cli.md)
+- [React Intlayer Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_with_create_react_app.md)
+- [Next Intlayer Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_with_nextjs_15.md)
+
+These resources offer further insights into the setup and usage of Intlayer across various environments and frameworks.