@intlayer/docs 5.7.2 → 5.7.3

package/docs/en-GB/dictionary/gender.md

@@ -0,0 +1,275 @@
+---
+createdAt: 2025-07-27
+updatedAt: 2025-07-27
+title: Gender-Based Content
+description: Learn how to use gender-based content in Intlayer to dynamically display content based on gender. Follow this documentation to implement gender-specific content efficiently in your project.
+keywords:
+  - Gender-Based Content
+  - Dynamic Rendering
+  - Documentation
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - content
+  - gender
+---
+
+# Gender-Based Content / Gender in Intlayer
+
+## How Gender Works
+
+In Intlayer, gender-based content is achieved through the `gender` function, which maps specific gender values ('male', 'female') to their corresponding content. This approach enables you to dynamically select content based on a given gender. When integrated with React Intlayer or Next Intlayer, the appropriate content is automatically chosen according to the gender provided at runtime.
+
+## Setting Up Gender-Based Content
+
+To set up gender-based content in your Intlayer project, create a content module that includes your gender-specific definitions. Below are examples in various formats.
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import { gender, type Dictionary } from "intlayer";
+
+const myGenderContent = {
+  key: "my_key",
+  content: {
+    myGender: gender({
+      male: "my content for male users",
+      female: "my content for female users",
+      fallback: "my content when gender is not specified", // Optional
+    }),
+  },
+} satisfies Dictionary;
+
+export default myGenderContent;
+```
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+import { gender } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const myGenderContent = {
+  key: "my_key",
+  content: {
+    myGender: gender({
+      male: "my content for male users",
+      female: "my content for female users",
+      fallback: "my content when gender is not specified", // Optional
+    }),
+  },
+};
+
+export default myGenderContent;
+```
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+const { gender } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const myGenderContent = {
+  key: "my_key",
+  content: {
+    myGender: gender({
+      male: "my content for male users",
+      female: "my content for female users",
+      fallback: "my content when gender is not specified", // Optional
+    }),
+  },
+};
+
+module.exports = myGenderContent;
+```
+
+```json5 fileName="**/*.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "my_key",
+  "content": {
+    "myGender": {
+      "nodeType": "gender",
+      "gender": {
+        "male": "my content for male users",
+        "female": "my content for female users",
+        "fallback": "my content when gender is not specified", // Optional
+      },
+    },
+  },
+}
+```
+
+> If no fallback is declared, the last key declared will be taken as a fallback if the gender is not specified or does not match any defined gender.
+
+## Using Gender-Based Content with React Intlayer
+
+To utilise gender-based content within a React component, import and use the `useIntlayer` hook from the `react-intlayer` package. This hook fetches the content for the specified key and allows you to pass in a gender to select the appropriate output.
+
+```tsx fileName="**/*.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+const GenderComponent: FC = () => {
+  const { myGender } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <p>
+        {
+          /* Output: my content for male users */
+          myGender("male")
+        }
+      </p>
+      <p>
+        {
+          /* Output: my content for female users */
+          myGender("female")
+        }
+      </p>
+      <p>
+        {
+          /* Output: my content for male users */
+          myGender("m")
+        }
+      </p>
+      <p>
+        {
+          /* Output: my content for female users */
+          myGender("f")
+        }
+      </p>
+      <p>
+        {
+          /* Output: my content when gender is not specified */
+          myGender("")
+        }
+      </p>
+      <p>
+        {
+          /* Output: my content when gender is not specified */
+          myGender(undefined)
+        }
+      </p>
+    </div>
+  );
+};
+
+export default GenderComponent;
+```
+
+```javascript fileName="**/*.mjx" codeFormat="esm"
+import { useIntlayer } from "react-intlayer";
+
+const GenderComponent = () => {
+  const { myGender } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <p>
+        {
+          /* Output: my content for male users */
+          myGender("male")
+        }
+      </p>
+      <p>
+        {
+          /* Output: my content for female users */
+          myGender("female")
+        }
+      </p>
+      <p>
+        {
+          /* Output: my content for male users */
+          myGender("m")
+        }
+      </p>
+      <p>
+        {
+          /* Output: my content for female users */
+          myGender("f")
+        }
+      </p>
+      <p>
+        {
+          /* Output: my content when gender is not specified */
+          myGender("")
+        }
+      </p>
+      <p>
+        {
+          /* Output: my content when gender is not specified */
+          myGender(undefined)
+        }
+      </p>
+    </div>
+  );
+};
+
+export default GenderComponent;
+```
+
+```javascript fileName="**/*.cjs" codeFormat="commonjs"
+const { useIntlayer } = require("react-intlayer");
+
+const GenderComponent = () => {
+  const { myGender } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <p>
+        {
+          /* Output: my content for male users */
+          myGender("male")
+        }
+      </p>
+      <p>
+        {
+          /* Output: my content for female users */
+          myGender("female")
+        }
+      </p>
+      <p>
+        {
+          /* Output: my content for male users */
+          myGender("m")
+        }
+      </p>
+      <p>
+        {
+          /* Output: my content for female users */
+          myGender("f")
+        }
+      </p>
+      <p>
+        {
+          /* Output: my content when gender is not specified */
+          myGender("")
+        }
+      </p>
+      <p>
+        {
+          /* Output: my content when gender is not specified */
+          myGender(undefined)
+        }
+      </p>
+    </div>
+  );
+};
+
+module.exports = GenderComponent;
+```
+
+## 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/docs/en-GB/intlayer_cli.md)
+- [React Intlayer Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_create_react_app.md)
+- [Next Intlayer Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_nextjs_15.md)
+
+These resources offer further insights into the setup and usage of Intlayer across various environments and frameworks.
+
+## Doc History
+
+| Version | Date       | Changes                        |
+| ------- | ---------- | ------------------------------ |
+| 5.7.2   | 2025-07-27 | Introduce gender-based content |

package/docs/en-GB/how_works_intlayer.md

@@ -93,7 +93,7 @@ Intlayer also provides a visual editor to allow you to edit your content in a vi
 
 - The server is a simple Express application that listens to requests from the client and retrieves the content of your application, such as the `dictionaries` and the configuration to make it accessible on the client side.
 - On the other hand, the client is a React application that is used to interact with your content using a visual interface.
-  When you call your content using `useIntlayer` and the editor is enabled, it automatically wraps your strings with a Proxy object named `IntlayerNode`. This node uses `window.sendMessage` to communicate with a wrapped iframe containing the visual editor interface.  
+  When you call your content using `useIntlayer` and the editor is enabled, it automatically wraps your strings with a Proxy object named `IntlayerNode`. This node uses `window.postMessage` to communicate with a wrapped iframe containing the visual editor interface.  
   On the editor side, the editor listens to these messages and simulates real interaction with your content, allowing you to edit text directly in your application's context.
 
 ## App build optimisation

package/docs/en-GB/locale_mapper.md

@@ -0,0 +1,244 @@
+---
+createdAt: 2025-07-27
+updatedAt: 2025-07-27
+title: Locale Mapper
+description: Discover how Locale Mapper works. See the steps used by Locale Mapper in your application. See what the different packages do.
+keywords:
+  - Locale Mapper
+  - Get started
+  - Intlayer
+  - Application
+  - Packages
+slugs:
+  - doc
+  - locale-mapper
+---
+
+# Locale Mapper
+
+The Locale Mapper is a powerful utility that helps you work with internationalisation data in your Intlayer application. It provides three main functions to transform and organise locale-specific data: `localeMap`, `localeFlatMap`, and `localeRecord`.
+
+## How Locale Mapper Works
+
+The Locale Mapper operates on a `LocaleData` object that contains all the necessary information about a locale:
+
+```typescript
+type LocaleData = {
+  locale: LocalesValues; // Current locale code (e.g., 'en', 'fr')
+  defaultLocale: LocalesValues; // Default locale code
+  isDefault: boolean; // Whether this is the default locale
+  locales: LocalesValues[]; // Array of all available locales
+  urlPrefix: string; // URL prefix for this locale (e.g., '/fr' or '')
+};
+```
+
+The mapper functions automatically generate this data for each locale in your configuration, taking into account:
+
+- Your configured list of locales
+- The default locale setting
+- Whether the default locale should be prefixed in URLs
+
+## Core Functions
+
+### `localeMap`
+
+Transforms each locale into a single object using a mapper function.
+
+```typescript
+localeMap<T>(
+  mapper: (locale: LocaleData) => T,
+  locales?: LocalesValues[],
+  defaultLocale?: LocalesValues,
+  prefixDefault?: boolean
+): T[]
+```
+
+**Example: Creating route objects**
+
+```typescript
+import { localeMap } from "intlayer";
+
+const routes = localeMap((localizedData) => ({
+  path: localizedData.urlPrefix,
+  name: localizedData.locale,
+  isDefault: localizedData.isDefault,
+  locales: localizedData.locales,
+  defaultLocale: localizedData.defaultLocale,
+}));
+
+// Result:
+// [
+//   { path: '/', name: 'en', isDefault: true, locales: ['en', 'fr', 'es'], defaultLocale: 'en' },
+//   { path: '/fr', name: 'fr', isDefault: false, locales: ['en', 'fr', 'es'], defaultLocale: 'en' },
+//   { path: '/es', name: 'es', isDefault: false, locales: ['en', 'fr', 'es'], defaultLocale: 'en' }
+// ]
+```
+
+### `localeFlatMap`
+
+Similar to `localeMap`, but the mapper function returns an array of objects that gets flattened into a single array.
+
+```typescript
+localeFlatMap<T>(
+  mapper: (locale: LocaleData) => T[],
+  locales?: LocalesValues[],
+  defaultLocale?: LocalesValues,
+  prefixDefault?: boolean
+): T[]
+```
+
+**Example: Creating multiple routes per locale**
+
+```typescript
+import { localeFlatMap } from "intlayer";
+
+const routes = localeFlatMap((localizedData) => [
+  {
+    path: localizedData.urlPrefix,
+    name: localizedData.locale,
+    isDefault: localizedData.isDefault,
+  },
+  {
+    path: `${localizedData.urlPrefix}/about`,
+    name: `${localizedData.locale}-about`,
+    isDefault: localizedData.isDefault,
+  },
+]);
+
+// Result:
+// [
+//   { path: '/', name: 'en', isDefault: true },
+//   { path: '/about', name: 'en-about', isDefault: true },
+//   { path: '/fr', name: 'fr', isDefault: false },
+//   { path: '/fr/about', name: 'fr-about', isDefault: false },
+//   { path: '/es', name: 'es', isDefault: false },
+//   { path: '/es/about', name: 'es-about', isDefault: false }
+// ]
+```
+
+### `localeRecord`
+
+Creates a record object where each locale is a key mapping to a value transformed by the mapper function.
+
+```typescript
+localeRecord<T>(
+  mapper: (locale: LocaleData) => T,
+  locales?: Locales[],
+  defaultLocale?: Locales,
+  prefixDefault?: boolean
+): Record<Locales, T>
+```
+
+**Example: Loading translation files**
+
+```typescript
+import { localeRecord } from "intlayer";
+
+const translations = localeRecord(({ locale }) =>
+  require(`./translations/${locale}.json`)
+);
+
+// Result:
+// {
+//   en: { welcome: 'Welcome', hello: 'Hello' },
+//   fr: { welcome: 'Bienvenue', hello: 'Bonjour' },
+//   es: { welcome: 'Bienvenido', hello: 'Hola' }
+// }
+```
+
+## Setting Up Locale Mapper
+
+The Locale Mapper automatically uses your Intlayer configuration, but you can override the defaults by passing parameters:
+
+### Using Default Configuration
+
+```typescript
+import { localeMap } from "intlayer";
+
+// Uses configuration from intlayer.config.ts
+const routes = localeMap((data) => ({
+  path: data.urlPrefix,
+  locale: data.locale,
+}));
+```
+
+### Overriding Configuration
+
+```typescript
+import { localeMap } from "intlayer";
+
+// Override locales and default locale
+const customRoutes = localeMap(
+  (data) => ({ path: data.urlPrefix, locale: data.locale }),
+  ["en", "fr", "de"], // Custom locales
+  "en", // Custom default locale
+  true // Prefix default locale in URLs
+);
+```
+
+## Advanced Usage Examples
+
+### Creating Navigation Menus
+
+```typescript
+import { localeMap } from "intlayer";
+
+const navigationItems = localeMap((data) => ({
+  label: data.locale.toUpperCase(),
+  href: data.urlPrefix || "/",
+  isActive: data.isDefault,
+  flag: `/flags/${data.locale}.svg`,
+}));
+```
+
+### Generating Sitemap Data
+
+```typescript
+import { localeFlatMap } from "intlayer";
+
+const sitemapUrls = localeFlatMap((data) => [
+  {
+    url: `${data.urlPrefix}/`,
+    lastmod: new Date().toISOString(),
+    changefreq: "daily",
+    priority: data.isDefault ? 1.0 : 0.8,
+  },
+  {
+    url: `${data.urlPrefix}/about`,
+    lastmod: new Date().toISOString(),
+    changefreq: "monthly",
+    priority: data.isDefault ? 0.8 : 0.6,
+  },
+]);
+```
+
+### Dynamic Translation Loading
+
+```typescript
+import { localeRecord } from "intlayer";
+
+const translationModules = localeRecord(({ locale }) => ({
+  messages: import(`./locales/${locale}/messages.json`),
+  validation: import(`./locales/${locale}/validation.json`),
+  metadata: {
+    locale,
+    direction: ["ar", "he", "fa"].includes(locale) ? "rtl" : "ltr",
+  },
+}));
+```
+
+## Configuration Integration
+
+The Locale Mapper seamlessly integrates with your Intlayer configuration:
+
+- **Locales**: Automatically uses `configuration.internationalization.locales`
+- **Default Locale**: Uses `configuration.internationalization.defaultLocale`
+- **URL Prefixing**: Respects `configuration.middleware.prefixDefault`
+
+This ensures consistency across your application and reduces configuration duplication.
+
+## Doc History
+
+| Version | Date       | Changes                         |
+| ------- | ---------- | ------------------------------- |
+| 5.7.2   | 2025-07-27 | Add locale mapper documentation |