@intlayer/docs 5.5.8

package/en-GB/dictionary/content_extention_customization.md

@@ -0,0 +1,83 @@
+# Content Extension Customisation
+
+## Content File Extensions
+
+Intlayer allows you to customise the extensions for your content declaration files. This customisation provides flexibility in managing large-scale projects and helps to avoid conflicts with other modules.
+
+### Default 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`
+
+These default extensions are suitable for most applications. However, when you have specific needs, you can define custom extensions to streamline the build process and reduce the risk of conflicts with other components.
+
+### Customising Content Extensions
+
+To customise the file extensions Intlayer uses to identify content declaration files, you can specify them in the Intlayer configuration file. This approach is beneficial for large-scale projects where limiting the scope of the watch process improves build performance.
+
+Here is an example of how to define custom content extensions in your configuration:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  content: {
+    fileExtensions: [".my_content.ts", ".my_content.tsx"], // Your custom extensions
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  content: {
+    fileExtensions: [".my_content.cjs", ".my_content.cjx"], // Your custom extensions
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  content: {
+    fileExtensions: [".my_content.mjs", ".my_content.mjx"], // Your custom extensions
+  },
+};
+
+module.exports = config;
+```
+
+In this example, the configuration specifies two custom extensions: `.my_content.ts` and `.my_content.tsx`. Intlayer will only watch files with these extensions to build dictionaries.
+
+### Benefits of Custom Extensions
+
+- **Build Performance**: Reducing the scope of watched files can significantly improve build performance in large projects.
+- **Conflict Avoidance**: Custom extensions help prevent conflicts with other JavaScript or TypeScript files in your project.
+- **Organisation**: Custom extensions allow you to organise your content declaration files according to your project's needs.
+
+### Guidelines for Custom Extensions
+
+When customising content file extensions, keep the following guidelines in mind:
+
+- **Uniqueness**: Choose extensions that are unique within your project to avoid conflicts.
+- **Consistent Naming**: Use consistent naming conventions for better code readability and maintenance.
+- **Avoiding Common Extensions**: Refrain from using common extensions like `.ts` or `.js` to prevent conflicts with other modules or libraries.
+
+## Conclusion
+
+Customising content file extensions in Intlayer is a valuable feature for optimising performance and avoiding conflicts in large-scale applications. By following the guidelines outlined in this documentation, you can effectively manage your content declarations and ensure smooth integration with other parts of your project.
+
+[Learn more](https://github.com/aymericzip/intlayer/blob/main/docs/en-GB/**/*.md)

package/en-GB/dictionary/enumeration.md

@@ -0,0 +1,221 @@
+# Enumeration / Pluralisation
+
+## How Enumeration Works
+
+In Intlayer, enumeration is achieved through the `enu` function, which maps specific keys to their corresponding content. These keys can represent numeric values, ranges, or custom identifiers. When used with React Intlayer or Next Intlayer, the appropriate content is automatically selected based on the application's locale and defined rules.
+
+## Setting Up Enumeration
+
+To set up enumeration in your Intlayer project, you need to create a content module that includes enumeration definitions. Here's an example of a simple enumeration for the number of cars:
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import { enu, type Dictionary } from "intlayer";
+
+const carEnumeration = {
+  key: "car_count",
+  content: {
+    numberOfCar: enu({
+      "<-1": "Less than minus one car",
+      "-1": "Minus one car",
+      "0": "No cars",
+      "1": "One car",
+      ">5": "Some cars",
+      ">19": "Many cars",
+      "fallback": "Fallback value", // Optional
+    }),
+  },
+} satisfies Dictionary;
+
+export default carEnumeration;
+```
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+import { enu } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const carEnumeration = {
+  key: "car_count",
+  content: {
+    numberOfCar: enu({
+      "<-1": "Less than minus one car",
+      "-1": "Minus one car",
+      "0": "No cars",
+      "1": "One car",
+      ">5": "Some cars",
+      ">19": "Many cars",
+      "fallback": "Fallback value", // Optional
+    }),
+  },
+};
+
+export default carEnumeration;
+```
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+const { enu } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const carEnumeration = {
+  key: "car_count",
+  content: {
+    numberOfCar: enu({
+      "<-1": "Less than minus one car",
+      "-1": "Minus one car",
+      "0": "No cars",
+      "1": "One car",
+      ">5": "Some cars",
+      ">19": "Many cars",
+      "fallback": "Fallback value", // Optional
+    }),
+  },
+};
+
+module.exports = carEnumeration;
+```
+
+```json fileName="**/*.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "car_count",
+  "content": {
+    "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",
+        "fallback": "Fallback value" // Optional
+      }
+    }
+  }
+}
+```
+
+In this example, `enu` maps various conditions to specific content. When used in a React component, Intlayer can automatically choose the appropriate content based on the given variable.
+
+> The order of declaration is important in Intlayer enumerations. The first valid declaration is the one that will be picked up. If multiple conditions apply, ensure they are ordered correctly to avoid unexpected behaviour.
+
+> If no fallback is declared, the function will return `undefined` if no keys match.
+
+## Using Enumeration with React Intlayer
+
+To use enumeration in a React component, you can leverage the `useIntlayer` hook from the `react-intlayer` package. This hook retrieves the correct content based on the specified ID. Here's an example of how to use it:
+
+```tsx fileName="**/*.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+const CarComponent: FC = () => {
+  const { numberOfCar } = useIntlayer("car_count");
+
+  return (
+    <div>
+      <p>
+        {
+          numberOfCar(0) // Output: No cars
+        }
+      </p>
+      <p>
+        {
+          numberOfCar(6) // Output: Some cars
+        }
+      </p>
+      <p>
+        {
+          numberOfCar(20) // Output: Many cars
+        }
+      </p>
+      <p>
+        {
+          numberOfCar(0.01) // Output: Fallback value
+        }
+      </p>
+    </div>
+  );
+};
+```
+
+```javascript fileName="**/*.mjx" codeFormat="esm"
+import { useIntlayer } from "react-intlayer";
+
+const CarComponent = () => {
+  const { numberOfCar } = useIntlayer("car_count");
+
+  return (
+    <div>
+      <p>
+        {
+          numberOfCar(0) // Output: No cars
+        }
+      </p>
+      <p>
+        {
+          numberOfCar(6) // Output: Some cars
+        }
+      </p>
+      <p>
+        {
+          numberOfCar(20) // Output: Many cars
+        }
+      </p>
+      <p>
+        {
+          numberOfCar(0.01) // Output: Fallback value
+        }
+      </p>
+    </div>
+  );
+};
+
+export default CarComponent;
+```
+
+```javascript fileName="**/*.cjs" codeFormat="commonjs"
+const { useIntlayer } = require("react-intlayer");
+
+const CarComponent = () => {
+  const { numberOfCar } = useIntlayer("car_count");
+
+  return (
+    <div>
+      <p>
+        {
+          numberOfCar(0) // Output: No cars
+        }
+      </p>
+      <p>
+        {
+          numberOfCar(6) // Output: Some cars
+        }
+      </p>
+      <p>
+        {
+          numberOfCar(20) // Output: Many cars
+        }
+      </p>
+      <p>
+        {
+          numberOfCar(0.01) // Output: Fallback value
+        }
+      </p>
+    </div>
+  );
+};
+
+module.exports = CarComponent;
+```
+
+In this example, the component dynamically adjusts its output based on the number of cars. The correct content is chosen automatically, depending on the specified range.
+
+## 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-GB/intlayer_cli.md)
+- [React Intlayer Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en-GB/intlayer_with_create_react_app.md)
+- [Next Intlayer Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en-GB/intlayer_with_nextjs_15.md)
+
+These resources provide further insights into the setup and usage of Intlayer in different environments and with various frameworks.

package/en-GB/dictionary/file.md

@@ -0,0 +1,201 @@
+# File Content / Embedding Files in Intlayer
+
+## How File Embedding Works
+
+In Intlayer, the `file` function allows embedding external file content into a dictionary. This approach ensures that Intlayer recognises the source file, enabling seamless integration with the Intlayer Visual Editor and CMS. Unlike direct `import`, `require`, or `fs` file reading methods, using `file` associates the file with the dictionary, allowing Intlayer to track and update the content dynamically when the file is edited.
+
+## Setting Up File Content
+
+To embed file content in your Intlayer project, use the `file` function in a content module. Below are examples demonstrating different implementations.
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import { file, type Dictionary } from "intlayer";
+
+const myFileContent = {
+  key: "my_key",
+  content: {
+    myFile: file("./path/to/file.txt"),
+  },
+} satisfies Dictionary;
+
+export default myFileContent;
+```
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+import { file } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const myFileContent = {
+  key: "my_key",
+  content: {
+    myFile: file("./path/to/file.txt"),
+  },
+};
+
+export default myFileContent;
+```
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+const { file } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const myFileContent = {
+  key: "my_key",
+  content: {
+    myFile: file("./path/to/file.txt"),
+  },
+};
+
+module.exports = myFileContent;
+```
+
+```json5 fileName="**/*.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "my_key",
+  "content": {
+    "myFile": {
+      "nodeType": "file",
+      "value": "./path/to/file.txt",
+    },
+  },
+}
+```
+
+## Using File Content in React Intlayer
+
+To use embedded file content in a React component, import and use the `useIntlayer` hook from the `react-intlayer` package. This retrieves the content from the specified key and allows it to be displayed dynamically.
+
+```tsx fileName="**/*.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+const FileComponent: FC = () => {
+  const { myFile } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <pre>{myFile}</pre>
+    </div>
+  );
+};
+
+export default FileComponent;
+```
+
+```javascript fileName="**/*.mjx" codeFormat="esm"
+import { useIntlayer } from "react-intlayer";
+
+const FileComponent = () => {
+  const { myFile } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <pre>{myFile}</pre>
+    </div>
+  );
+};
+
+export default FileComponent;
+```
+
+```javascript fileName="**/*.cjs" codeFormat="commonjs"
+const { useIntlayer } = require("react-intlayer");
+
+const FileComponent = () => {
+  const { myFile } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <pre>{myFile}</pre>
+    </div>
+  );
+};
+
+module.exports = FileComponent;
+```
+
+## Multilingual Markdown Example
+
+To support multilingual editable Markdown files, you can use `file` in combination with `t()` and `md()` to define different language versions of a Markdown content file.
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import { file, t, md, type Dictionary } from "intlayer";
+
+const myMultilingualContent = {
+  key: "my_multilingual_key",
+  content: {
+    myContent: md(
+      t({
+        "en-GB": file("src/components/test.en-GB.md"),
+        en: file("src/components/test.en.md"),
+        fr: file("src/components/test.fr.md"),
+        es: file("src/components/test.es.md"),
+      })
+    ),
+  },
+} satisfies Dictionary;
+
+export default myMultilingualContent;
+```
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+import { file, t, md } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const myMultilingualContent = {
+  key: "my_multilingual_key",
+  content: {
+    myContent: md(
+      t({
+        "en-GB": file("src/components/test.en-GB.md"),
+        en: file("src/components/test.en.md"),
+        fr: file("src/components/test.fr.md"),
+        es: file("src/components/test.es.md"),
+      })
+    ),
+  },
+};
+
+export default myMultilingualContent;
+```
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+const { file, t, md } = require("intlayer");
+
+const myMultilingualContent = {
+  key: "my_multilingual_key",
+  content: {
+    myContent: md(
+      t({
+        "en-GB": file("src/components/test.en-GB.md"),
+        en: file("src/components/test.en.md"),
+        fr: file("src/components/test.fr.md"),
+        es: file("src/components/test.es.md"),
+      })
+    ),
+  },
+};
+```
+
+This setup allows the content to be dynamically retrieved based on the user's language preference. When used in the Intlayer Visual Editor or CMS, the system will recognise that the content comes from the specified Markdown files and ensure they remain editable.
+
+## How Intlayer Handles File Content
+
+The `file` function is based on Node.js' `fs` module to read the content of the specified file and insert it into the dictionary. When used in conjunction with the Intlayer Visual Editor or CMS, Intlayer can track the relationship between the dictionary and the file. This allows Intlayer to:
+
+- Recognise that the content originates from a specific file.
+- Automatically update the dictionary content when the linked file is edited.
+- Ensure synchronisation between the file and the dictionary, preserving the integrity of the content.
+
+## Additional Resources
+
+For more details on configuring and using file embedding in Intlayer, refer to the following resources:
+
+- [Intlayer CLI Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en-GB/intlayer_cli.md)
+- [React Intlayer Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en-GB/intlayer_with_create_react_app.md)
+- [Next Intlayer Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en-GB/intlayer_with_nextjs_15.md)
+- [Markdown Content Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en-GB/dictionary/markdown.md)
+- [Translation Content Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en-GB/dictionary/translation.md)
+
+These resources provide further insights into file embedding, content management, and Intlayer’s integration with various frameworks.

package/en-GB/dictionary/function_fetching.md

@@ -0,0 +1,190 @@
+# Function Fetching
+
+Intlayer allows you to declare content functions in your content modules, which can be either synchronous or asynchronous. When the application builds, Intlayer executes these functions to obtain the function's result. The return value must be a JSON object or a simple value like a string or number.
+
+> Warning: function fetching is currently not available in JSON content declaration and distant content declarations files.
+
+## Function Declarations
+
+Here's an example of a simple synchronous function fetching content:
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import type { Dictionary } from "intlayer";
+
+const functionContent = {
+  key: "function_content",
+  content: {
+    text: () => "This is the content rendered by a function",
+  },
+} satisfies Dictionary;
+
+export default functionContent;
+```
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+/** @type {import('intlayer').Dictionary} */
+const functionContent = {
+  key: "function_content",
+  content: {
+    text: () => "This is the content rendered by a function",
+  },
+};
+
+export default functionContent;
+```
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+/** @type {import('intlayer').Dictionary} */
+const functionContent = {
+  key: "function_content",
+  content: {
+    text: () => "This is the content rendered by a function",
+  },
+};
+
+module.exports = functionContent;
+```
+
+```json fileName="**/*.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "function_content",
+  "content": {
+    "text": "This is the content rendered by a function"
+  }
+}
+```
+
+In this example, the `text` key contains a function that returns a string. This content can be rendered in your React components using Intlayer's interpreter packages like `react-intlayer`.
+
+## Asynchronous Function Fetching
+
+In addition to synchronous functions, Intlayer supports asynchronous functions, allowing you to fetch data from external sources or simulate data retrieval with mock data.
+
+Below is an example of an asynchronous function that simulates a server fetch:
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import { setTimeout } from "node:timers/promises";
+import type { Dictionary } from "intlayer";
+
+const fakeFetch = async (): Promise<string> => {
+  // Wait for 200ms to simulate a fetch from the server
+  return await setTimeout(200).then(
+    () => "This is the content fetched from the server"
+  );
+};
+
+const asyncFunctionContent = {
+  key: "async_function",
+  content: { text: fakeFetch },
+} satisfies Dictionary;
+
+export default asyncFunctionContent;
+```
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+import { setTimeout } from "node:timers/promises";
+
+/** @type {import('intlayer').Dictionary} */
+const fakeFetch = async () => {
+  // Wait for 200ms to simulate a fetch from the server
+  await setTimeout(200);
+  return "This is the content fetched from the server";
+};
+
+const asyncFunctionContent = {
+  key: "async_function",
+  content: { text: fakeFetch },
+};
+
+export default asyncFunctionContent;
+```
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+const { setTimeout } = require("node:timers/promises");
+
+/** @type {import('intlayer').Dictionary} */
+const fakeFetch = async () => {
+  // Wait for 200ms to simulate a fetch from the server
+  await setTimeout(200);
+  return "This is the content fetched from the server";
+};
+
+const asyncFunctionContent = {
+  key: "async_function",
+  content: { text: fakeFetch },
+};
+
+module.exports = asyncFunctionContent;
+```
+
+```plaintext fileName="**/*.content.json" contentDeclarationFormat="json"
+No way to fetch content from a JSON file, use a .ts or .js file instead
+```
+
+In this case, the `fakeFetch` function mimics a delay to simulate server response time. Intlayer executes the asynchronous function and uses the result as the content for the `text` key.
+
+## Using Function-Based Content in React Components
+
+To use function-based content in a React component, you need to import `useIntlayer` from `react-intlayer` and call it with the content ID to retrieve the content. Here's an example:
+
+```typescript fileName="**/*.jsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+const MyComponent: FC = () => {
+  const functionContent = useIntlayer("function_content");
+  const asyncFunctionContent = useIntlayer("async_function_content");
+
+  return (
+    <div>
+      <p>{functionContent.text}</p>
+      {/* Output: This is the content rendered by a function */}
+      <p>{asyncFunctionContent.text}</p>
+      {/* Output: This is the content fetched from the server */}
+    </div>
+  );
+};
+
+export default MyComponent;
+```
+
+```javascript fileName="**/*.mjx" codeFormat="esm"
+import { useIntlayer } from "react-intlayer";
+
+const MyComponent = () => {
+  const functionContent = useIntlayer("function_content");
+  const asyncFunctionContent = useIntlayer("async_function_content");
+
+  return (
+    <div>
+      <p>{functionContent.text}</p>
+      {/* Output: This is the content rendered by a function */}
+      <p>{asyncFunctionContent.text}</p>
+      {/* Output: This is the content fetched from the server */}
+    </div>
+  );
+};
+
+export default MyComponent;
+```
+
+```javascript fileName="**/*.cjs" codeFormat="commonjs"
+const { useIntlayer } = require("react-intlayer");
+
+const MyComponent = () => {
+  const functionContent = useIntlayer("function_content");
+  const asyncFunctionContent = useIntlayer("async_function_content");
+
+  return (
+    <div>
+      <p>{functionContent.text}</p>
+      {/* Output: This is the content rendered by a function */}
+      <p>{asyncFunctionContent.text}</p>
+      {/* Output: This is the content fetched from the server */}
+    </div>
+  );
+};
+
+module.exports = MyComponent;
+```