@intlayer/docs 5.7.2-canary.3 → 5.7.3

package/docs/zh/dictionary/gender.md

@@ -0,0 +1,275 @@
+---
+createdAt: 2025-07-27
+updatedAt: 2025-07-27
+title: 基于性别的内容
+description: 了解如何在 Intlayer 中使用基于性别的内容，根据性别动态显示内容。按照本指南高效地在项目中实现性别特定内容。
+keywords:
+  - 基于性别的内容
+  - 动态渲染
+  - 文档
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - content
+  - gender
+---
+
+# 基于性别的内容 / Intlayer 中的性别
+
+## 性别的工作原理
+
+在 Intlayer 中，基于性别的内容是通过 `gender` 函数实现的，该函数将特定的性别值（'male'，'female'）映射到相应的内容。此方法使您能够根据给定的性别动态选择内容。当与 React Intlayer 或 Next Intlayer 集成时，会根据运行时提供的性别自动选择适当的内容。
+
+## 设置基于性别的内容
+
+要在您的 Intlayer 项目中设置基于性别的内容，请创建一个包含性别特定定义的内容模块。以下是各种格式的示例。
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import { gender, type Dictionary } from "intlayer";
+
+const myGenderContent = {
+  key: "my_key",
+  content: {
+    myGender: gender({
+      male: "针对男性用户的内容",
+      female: "针对女性用户的内容",
+      fallback: "未指定性别时的内容", // 可选
+    }),
+  },
+} 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: "针对男性用户的内容",
+      female: "针对女性用户的内容",
+      fallback: "未指定性别时的内容", // 可选
+    }),
+  },
+};
+
+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: "针对男性用户的内容",
+      female: "针对女性用户的内容",
+      fallback: "未指定性别时的内容", // 可选
+    }),
+  },
+};
+
+module.exports = myGenderContent;
+```
+
+```json5 fileName="**/*.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "my_key",
+  "content": {
+    "myGender": {
+      "nodeType": "gender",
+      "gender": {
+        "male": "针对男性用户的内容",
+        "female": "针对女性用户的内容",
+        "fallback": "未指定性别时的内容", // 可选
+      },
+    },
+  },
+}
+```
+
+> 如果未声明回退内容，当性别未指定或不匹配任何定义的性别时，将使用最后声明的键作为回退内容。
+
+## 在 React Intlayer 中使用基于性别的内容
+
+要在 React 组件中使用基于性别的内容，请从 `react-intlayer` 包中导入并使用 `useIntlayer` 钩子。该钩子会获取指定键的内容，并允许你传入性别以选择合适的输出。
+
+```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>
+        {
+          /* 输出：针对男性用户的内容 */
+          myGender("male")
+        }
+      </p>
+      <p>
+        {
+          /* 输出：针对女性用户的内容 */
+          myGender("female")
+        }
+      </p>
+      <p>
+        {
+          /* 输出：针对男性用户的内容 */
+          myGender("m")
+        }
+      </p>
+      <p>
+        {
+          /* 输出：针对女性用户的内容 */
+          myGender("f")
+        }
+      </p>
+      <p>
+        {
+          /* 输出：当未指定性别时的内容 */
+          myGender("")
+        }
+      </p>
+      <p>
+        {
+          /* 输出：当未指定性别时的内容 */
+          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>
+        {
+          /* 输出：男性用户的内容 */
+          myGender("male")
+        }
+      </p>
+      <p>
+        {
+          /* 输出：女性用户的内容 */
+          myGender("female")
+        }
+      </p>
+      <p>
+        {
+          /* 输出：男性用户的内容 */
+          myGender("m")
+        }
+      </p>
+      <p>
+        {
+          /* 输出：女性用户的内容 */
+          myGender("f")
+        }
+      </p>
+      <p>
+        {
+          /* 输出：未指定性别时的内容 */
+          myGender("")
+        }
+      </p>
+      <p>
+        {
+          /* 输出：未指定性别时的内容 */
+          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>
+        {
+          /* 输出：针对男性用户的内容 */
+          myGender("male")
+        }
+      </p>
+      <p>
+        {
+          /* 输出：针对女性用户的内容 */
+          myGender("female")
+        }
+      </p>
+      <p>
+        {
+          /* 输出：针对男性用户的内容 */
+          myGender("m")
+        }
+      </p>
+      <p>
+        {
+          /* 输出：针对女性用户的内容 */
+          myGender("f")
+        }
+      </p>
+      <p>
+        {
+          /* 输出：当性别未指定时的内容 */
+          myGender("")
+        }
+      </p>
+      <p>
+        {
+          /* 输出：当性别未指定时的内容 */
+          myGender(undefined)
+        }
+      </p>
+    </div>
+  );
+};
+
+module.exports = GenderComponent;
+```
+
+## 附加资源
+
+有关配置和使用的更详细信息，请参阅以下资源：
+
+- [Intlayer CLI 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_cli.md)
+- [React Intlayer 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_create_react_app.md)
+- [Next Intlayer 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_nextjs_15.md)
+
+这些资源提供了关于在各种环境和框架中设置和使用 Intlayer 的更多见解。
+
+## 文档历史
+
+| 版本  | 日期       | 变更内容                   |
+| ----- | ---------- | -------------------------- |
+| 5.7.2 | 2025-07-27 | 引入基于性别的内容显示功能 |

package/docs/zh/how_works_intlayer.md

@@ -94,7 +94,7 @@ Intlayer 还提供了一个可视化编辑器，允许您以可视化的方式
 
 - 服务器是一个简单的 Express 应用程序，监听来自客户端的请求并检索您的应用内容，例如 `dictionaries` 和配置，以便在客户端访问。
 - 另一方面，客户端是一个 React 应用程序，用于通过可视化界面与您的内容交互。
-  当您使用 `useIntlayer` 调用内容且编辑器已启用时，它会自动使用名为 `IntlayerNode` 的 Proxy 对象包装您的字符串。该节点使用 `window.sendMessage` 与包含可视化编辑器界面的嵌套 iframe 通信。  
+  当您使用 `useIntlayer` 调用内容且编辑器已启用时，它会自动使用名为 `IntlayerNode` 的 Proxy 对象包装您的字符串。该节点使用 `window.postMessage` 与包含可视化编辑器界面的嵌套 iframe 通信。  
   在编辑器端，编辑器监听这些消息并模拟与您的内容的真实交互，允许您直接在应用程序的上下文中编辑文本。
 
 ## 应用构建优化

package/docs/zh/locale_mapper.md

@@ -0,0 +1,244 @@
+---
+createdAt: 2025-07-27
+updatedAt: 2025-07-27
+title: 本地化映射器
+description: 了解本地化映射器的工作原理。查看本地化映射器在您的应用程序中使用的步骤。了解不同包的功能。
+keywords:
+  - 本地化映射器
+  - 入门
+  - Intlayer
+  - 应用程序
+  - 包
+slugs:
+  - doc
+  - locale-mapper
+---
+
+# 本地化映射器
+
+本地化映射器是一个强大的工具，帮助您在 Intlayer 应用程序中处理国际化数据。它提供了三个主要功能，用于转换和组织特定于语言环境的数据：`localeMap`、`localeFlatMap` 和 `localeRecord`。
+
+## 本地化映射器的工作原理
+
+本地化映射器基于一个 `LocaleData` 对象，该对象包含有关语言环境的所有必要信息：
+
+```typescript
+type LocaleData = {
+  locale: LocalesValues; // 当前语言环境代码（例如，'en'，'fr'）
+  defaultLocale: LocalesValues; // 默认语言环境代码
+  isDefault: boolean; // 是否为默认语言环境
+  locales: LocalesValues[]; // 所有可用语言环境的数组
+  urlPrefix: string; // 该语言环境的 URL 前缀（例如，'/fr' 或 ''）
+};
+```
+
+映射函数会自动为配置中的每个语言环境生成这些数据，考虑到：
+
+- 您配置的语言环境列表
+- 默认语言环境设置
+- 是否应在 URL 中为默认语言环境添加前缀
+
+## 核心函数
+
+### `localeMap`
+
+使用映射函数将每个语言环境转换为单个对象。
+
+```typescript
+localeMap<T>(
+  mapper: (locale: LocaleData) => T,
+  locales?: LocalesValues[],
+  defaultLocale?: LocalesValues,
+  prefixDefault?: boolean
+): T[]
+```
+
+**示例：创建路由对象**
+
+```typescript
+import { localeMap } from "intlayer";
+
+const routes = localeMap((localizedData) => ({
+  path: localizedData.urlPrefix,
+  name: localizedData.locale,
+  isDefault: localizedData.isDefault,
+  locales: localizedData.locales,
+  defaultLocale: localizedData.defaultLocale,
+}));
+
+// 结果：
+// [
+//   { 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`
+
+类似于 `localeMap`，但映射函数返回一个对象数组，这些数组会被展平成一个单一数组。
+
+```typescript
+localeFlatMap<T>(
+  mapper: (locale: LocaleData) => T[],
+  locales?: LocalesValues[],
+  defaultLocale?: LocalesValues,
+  prefixDefault?: boolean
+): T[]
+```
+
+**示例：为每个语言创建多个路由**
+
+```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,
+  },
+]);
+
+// 结果：
+// [
+//   { 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`
+
+创建一个记录对象，其中每个 locale 是一个键，映射到由映射函数转换的值。
+
+```typescript
+localeRecord<T>(
+  mapper: (locale: LocaleData) => T,
+  locales?: Locales[],
+  defaultLocale?: Locales,
+  prefixDefault?: boolean
+): Record<Locales, T>
+```
+
+**示例：加载翻译文件**
+
+```typescript
+import { localeRecord } from "intlayer";
+
+const translations = localeRecord(({ locale }) =>
+  require(`./translations/${locale}.json`)
+);
+
+// 结果:
+// {
+//   en: { welcome: 'Welcome', hello: 'Hello' },
+//   fr: { welcome: 'Bienvenue', hello: 'Bonjour' },
+//   es: { welcome: 'Bienvenido', hello: 'Hola' }
+// }
+```
+
+## 设置 Locale Mapper
+
+Locale Mapper 会自动使用你的 Intlayer 配置，但你可以通过传递参数来覆盖默认设置：
+
+### 使用默认配置
+
+```typescript
+import { localeMap } from "intlayer";
+
+// 使用 intlayer.config.ts 中的配置
+const routes = localeMap((data) => ({
+  path: data.urlPrefix,
+  locale: data.locale,
+}));
+```
+
+### 覆盖配置
+
+```typescript
+import { localeMap } from "intlayer";
+
+// 覆盖 locales 和默认 locale
+const customRoutes = localeMap(
+  (data) => ({ path: data.urlPrefix, locale: data.locale }),
+  ["en", "fr", "de"], // 自定义语言环境
+  "en", // 自定义默认语言环境
+  true // 在 URL 中为默认语言环境添加前缀
+);
+```
+
+## 高级用法示例
+
+### 创建导航菜单
+
+```typescript
+import { localeMap } from "intlayer";
+
+const navigationItems = localeMap((data) => ({
+  label: data.locale.toUpperCase(), // 标签显示为大写的语言代码
+  href: data.urlPrefix || "/", // 链接地址，默认根路径
+  isActive: data.isDefault, // 是否为默认语言
+  flag: `/flags/${data.locale}.svg`, // 语言对应的国旗图标路径
+}));
+```
+
+### 生成网站地图数据
+
+```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, // 优先级，默认语言为1.0，其他为0.8
+  },
+  {
+    url: `${data.urlPrefix}/about`,
+    lastmod: new Date().toISOString(),
+    changefreq: "monthly",
+    priority: data.isDefault ? 0.8 : 0.6,
+  },
+]);
+```
+
+### 动态加载翻译
+
+```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", // 右到左语言方向判断
+  },
+}));
+```
+
+## 配置集成
+
+Locale Mapper 无缝集成到您的 Intlayer 配置中：
+
+- **Locales（语言环境）**：自动使用 `configuration.internationalization.locales`
+- **默认语言环境**：使用 `configuration.internationalization.defaultLocale`
+- **URL 前缀**：遵循 `configuration.middleware.prefixDefault`
+
+这确保了您的应用程序的一致性，并减少了配置重复。
+
+## 文档历史
+
+| 版本  | 日期       | 变更内容             |
+| ----- | ---------- | -------------------- |
+| 5.7.2 | 2025-07-27 | 添加了区域映射器文档 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intlayer/docs",
-  "version": "5.7.2-canary.3",
+  "version": "5.7.3",
   "private": false,
   "description": "Intlayer documentation",
   "keywords": [
@@ -49,8 +49,8 @@
     "legal"
   ],
   "dependencies": {
-    "intlayer": "5.7.2-canary.3",
-    "@intlayer/config": "5.7.2-canary.3"
+    "intlayer": "5.7.3",
+    "@intlayer/config": "5.7.3"
   },
   "devDependencies": {
     "@types/node": "^22.15.30",
@@ -65,16 +65,16 @@
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",
     "vitest": "^3.2.2",
-    "@intlayer/api": "5.7.2-canary.3",
-    "@intlayer/cli": "5.7.2-canary.3",
     "@utils/ts-config": "1.0.4",
     "@utils/tsup-config": "1.0.4",
-    "@utils/ts-config-types": "1.0.4"
+    "@utils/ts-config-types": "1.0.4",
+    "@intlayer/api": "5.7.3",
+    "@intlayer/cli": "5.7.3"
   },
   "peerDependencies": {
-    "@intlayer/api": "5.7.2-canary.3",
-    "@intlayer/cli": "5.7.2-canary.3",
-    "@intlayer/config": "5.7.2-canary.3"
+    "@intlayer/api": "5.7.3",
+    "@intlayer/config": "5.7.3",
+    "@intlayer/cli": "5.7.3"
   },
   "engines": {
     "node": ">=14.18"
@@ -84,7 +84,8 @@
   },
   "scripts": {
     "prebuild": "tsx tools/generateEntry.ts",
-    "build": "pnpm build:package & pnpm build:types",
+    "build": "pnpm clean & pnpm build:ci",
+    "build:ci": "pnpm build:package & pnpm build:types",
     "build:package": "tsup",
     "build:types": "tsc --project ./tsconfig.types.json && tsc-alias --project ./tsconfig.types.json",
     "clean": "rimraf ./dist",
@@ -93,7 +94,6 @@
     "lint:fix": "eslint . --cache --fix",
     "prettier": "prettier . --check",
     "prettier:fix": "prettier . --write",
-    "reset": "pnpm clean & pnpm build",
     "review": "tsx tools/review.ts",
     "serve": "webpack serve --config ./webpack.config.ts",
     "test": "vitest run",

package/src/generated/docs.entry.ts

@@ -457,6 +457,47 @@ export const docsEntry = {
       )
     ),
   } as unknown as Record<LocalesValues, Promise<string>>,
+  './docs/en/dictionary/gender.md': {
+    en: Promise.resolve(
+      readFile(join(dir, '../../../docs/en/dictionary/gender.md'), 'utf8')
+    ),
+    fr: Promise.resolve(
+      readFile(join(dir, '../../../docs/fr/dictionary/gender.md'), 'utf8')
+    ),
+    ru: Promise.resolve(
+      readFile(join(dir, '../../../docs/ru/dictionary/gender.md'), 'utf8')
+    ),
+    ja: Promise.resolve(
+      readFile(join(dir, '../../../docs/ja/dictionary/gender.md'), 'utf8')
+    ),
+    ko: Promise.resolve(
+      readFile(join(dir, '../../../docs/ko/dictionary/gender.md'), 'utf8')
+    ),
+    zh: Promise.resolve(
+      readFile(join(dir, '../../../docs/zh/dictionary/gender.md'), 'utf8')
+    ),
+    es: Promise.resolve(
+      readFile(join(dir, '../../../docs/es/dictionary/gender.md'), 'utf8')
+    ),
+    de: Promise.resolve(
+      readFile(join(dir, '../../../docs/de/dictionary/gender.md'), 'utf8')
+    ),
+    ar: Promise.resolve(
+      readFile(join(dir, '../../../docs/ar/dictionary/gender.md'), 'utf8')
+    ),
+    pt: Promise.resolve(
+      readFile(join(dir, '../../../docs/pt/dictionary/gender.md'), 'utf8')
+    ),
+    'en-GB': Promise.resolve(
+      readFile(join(dir, '../../../docs/en-GB/dictionary/gender.md'), 'utf8')
+    ),
+    it: Promise.resolve(
+      readFile(join(dir, '../../../docs/it/dictionary/gender.md'), 'utf8')
+    ),
+    hi: Promise.resolve(
+      readFile(join(dir, '../../../docs/hi/dictionary/gender.md'), 'utf8')
+    ),
+  } as unknown as Record<LocalesValues, Promise<string>>,
   './docs/en/dictionary/get_started.md': {
     en: Promise.resolve(
       readFile(join(dir, '../../../docs/en/dictionary/get_started.md'), 'utf8')
@@ -1859,6 +1900,47 @@ export const docsEntry = {
       readFile(join(dir, '../../../docs/hi/introduction.md'), 'utf8')
     ),
   } as unknown as Record<LocalesValues, Promise<string>>,
+  './docs/en/locale_mapper.md': {
+    en: Promise.resolve(
+      readFile(join(dir, '../../../docs/en/locale_mapper.md'), 'utf8')
+    ),
+    fr: Promise.resolve(
+      readFile(join(dir, '../../../docs/fr/locale_mapper.md'), 'utf8')
+    ),
+    ru: Promise.resolve(
+      readFile(join(dir, '../../../docs/ru/locale_mapper.md'), 'utf8')
+    ),
+    ja: Promise.resolve(
+      readFile(join(dir, '../../../docs/ja/locale_mapper.md'), 'utf8')
+    ),
+    ko: Promise.resolve(
+      readFile(join(dir, '../../../docs/ko/locale_mapper.md'), 'utf8')
+    ),
+    zh: Promise.resolve(
+      readFile(join(dir, '../../../docs/zh/locale_mapper.md'), 'utf8')
+    ),
+    es: Promise.resolve(
+      readFile(join(dir, '../../../docs/es/locale_mapper.md'), 'utf8')
+    ),
+    de: Promise.resolve(
+      readFile(join(dir, '../../../docs/de/locale_mapper.md'), 'utf8')
+    ),
+    ar: Promise.resolve(
+      readFile(join(dir, '../../../docs/ar/locale_mapper.md'), 'utf8')
+    ),
+    pt: Promise.resolve(
+      readFile(join(dir, '../../../docs/pt/locale_mapper.md'), 'utf8')
+    ),
+    'en-GB': Promise.resolve(
+      readFile(join(dir, '../../../docs/en-GB/locale_mapper.md'), 'utf8')
+    ),
+    it: Promise.resolve(
+      readFile(join(dir, '../../../docs/it/locale_mapper.md'), 'utf8')
+    ),
+    hi: Promise.resolve(
+      readFile(join(dir, '../../../docs/hi/locale_mapper.md'), 'utf8')
+    ),
+  } as unknown as Record<LocalesValues, Promise<string>>,
   './docs/en/mcp_server.md': {
     en: Promise.resolve(
       readFile(join(dir, '../../../docs/en/mcp_server.md'), 'utf8')