@intlayer/docs 5.5.9 → 5.5.11

package/docs/zh/packages/next-intlayer/useIntlayer.md

@@ -0,0 +1,265 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-06-29
+title: useIntlayer Hook 文档 | next-intlayer
+description: 查看如何使用 next-intlayer 包中的 useIntlayer hook
+keywords:
+  - useIntlayer
+  - 字典
+  - 键
+  - Intlayer
+  - 国际化
+  - 文档
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - next-intlayer
+  - useIntlayer
+---
+
+# Next.js 集成：`useIntlayer` Hook 文档
+
+`useIntlayer` hook 专为 Next.js 应用设计，用于高效获取和管理本地化内容。本篇文档将重点介绍如何在 Next.js 项目中使用该 hook，确保正确的本地化实践。
+
+## 在 Next.js 中导入 `useIntlayer`
+
+根据你是在 Next.js 应用中处理客户端组件还是服务器端组件，可以按如下方式导入 `useIntlayer` hook：
+
+- **客户端组件：**
+
+  ```typescript codeFormat="typescript"
+  import { useIntlayer } from "next-intlayer"; // 用于客户端组件
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useIntlayer } from "next-intlayer"; // 用于客户端组件
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useIntlayer } = require("next-intlayer"); // 用于客户端组件
+  ```
+
+- **服务器端组件：**
+
+  ```tsx codeFormat="typescript"
+  import { useIntlayer } from "next-intlayer/server"; // 用于服务器端组件
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useIntlayer } from "next-intlayer/server"; // 用于服务器端组件
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useIntlayer } = require("next-intlayer/server"); // 用于服务器端组件
+  ```
+
+## 参数
+
+1. **`key`**：用于检索内容的字典键的字符串标识符。
+2. **`locale`**（可选）：指定要使用的语言环境。如果省略，hook 会默认使用客户端或服务器上下文中设置的语言环境。
+
+## 字典文件
+
+确保所有内容键都在内容声明文件中定义，以防止运行时错误并确保类型安全。这种方法还便于 TypeScript 集成，实现编译时验证。
+
+有关设置内容声明文件的说明，请参见[此处](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/get_started.md)。
+
+## 在 Next.js 中的示例用法
+
+以下示例展示了如何在 Next.js 页面中实现 `useIntlayer` 钩子，根据应用程序当前的语言环境动态加载本地化内容：
+
+```tsx fileName="src/pages/[locale]/index.tsx" codeFormat="typescript"
+import { ClientComponentExample } from "@components/ClientComponentExample";
+import { ServerComponentExample } from "@components/ServerComponentExample";
+import { type NextPageIntlayer, IntlayerClientProvider } from "next-intlayer";
+import { useIntlayer, IntlayerServerProvider } from "next-intlayer/server";
+
+const HomePage: NextPageIntlayer = async ({ params }) => {
+  const { locale } = await params;
+
+  const content = useIntlayer("homepage", locale);
+
+  return (
+    <>
+      <p>{content.introduction}</p>
+      <IntlayerClientProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerClientProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```jsx fileName="src/pages/[locale]/index.csx" codeFormat="esm"
+import { ClientComponentExample } from "@components/ClientComponentExample";
+import { ServerComponentExample } from "@components/ServerComponentExample";
+import { IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";
+
+const HomePage = ({ locale }) => {
+  const content = useIntlayer("homepage", locale);
+
+  return (
+    <>
+      <p>{content.introduction}</p>
+      <IntlayerClientProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerClientProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```jsx fileName="src/components/ClientComponentExample.csx" codeFormat="commonjs"
+const {
+  ClientComponentExample,
+} = require("@components/ClientComponentExample");
+const {
+  ServerComponentExample,
+} = require("@components/ServerComponentExample");
+const { IntlayerClientProvider } = require("next-intlayer");
+const { useIntlayer } = require("next-intlayer/server");
+
+const HomePage = ({ locale }) => {
+  const content = useIntlayer("homepage", locale);
+
+  return (
+    <>
+      <p>{content.introduction}</p>
+      <IntlayerClientProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerClientProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```tsx fileName="src/components/ClientComponentExample.tsx" codeFormat="typescript"
+"use-client";
+
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer";
+
+const ClientComponentExample: FC = () => {
+  const content = useIntlayer("component-content"); // 使用 useIntlayer 钩子获取组件内容
+
+  return (
+    <div>
+      <h1>{content.title}</h1> {/* 显示内容标题 */}
+      <p>{content.description}</p> {/* 显示内容描述 */}
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ClientComponentExample.msx" codeFormat="esm"
+"use-client";
+
+import { useIntlayer } from "next-intlayer";
+
+const ServerComponentExample = () => {
+  const content = useIntlayer("component-content"); // 使用 useIntlayer 钩子获取组件内容
+
+  return (
+    <div>
+      <h1>{content.title}</h1> {/* 显示内容标题 */}
+      <p>{content.description}</p> {/* 显示内容描述 */}
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ClientComponentExample.csx" codeFormat="commonjs"
+"use-client";
+
+const { useIntlayer } = require("next-intlayer");
+
+const ServerComponentExample = () => {
+  const content = useIntlayer("component-content"); // 使用 useIntlayer 钩子获取组件内容
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+```tsx fileName="src/components/ServerComponentExample.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer/server";
+
+const ServerComponentExample: FC = () => {
+  const content = useIntlayer("component-content");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ServerComponentExample.mjx" codeFormat="esm"
+import { useIntlayer } from "next-intlayer/server";
+
+const ServerComponentExample = () => {
+  const content = useIntlayer("component-content");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+  );
+};
+```
+
+```jsx fileName="src/components/ServerComponentExample.csx" codeFormat="commonjs"
+const { useIntlayer } = require("next-intlayer/server");
+
+const ServerComponentExample = () => {
+  const content = useIntlayer("component-content");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+## 处理属性本地化
+
+要本地化诸如 `alt`、`title`、`href`、`aria-label` 等属性，请确保正确引用内容：
+
+```tsx
+<img src={content.image.src.value} alt={content.image.alt.value} />
+```
+
+## 更多信息
+
+- **Intlayer 可视化编辑器**：了解如何使用可视化编辑器以更轻松地管理内容，请点击[这里](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md)。
+
+本档说明文档专门介绍了在 Next.js 环境中使用 `useIntlayer` 钩子，提供了一个强大的解决方案来管理您 Next.js 应用中的本地化内容。
+
+## 文档历史
+
+- 5.5.10 - 2025-06-29：初始化历史

package/docs/zh/packages/next-intlayer/useIntlayerAsync.md

@@ -0,0 +1,239 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-06-29
+title: useIntlayerAsync Hook 文档 | next-intlayer
+description: 查看如何使用 next-intlayer 包中的 useIntlayerAsync Hook
+keywords:
+  - useIntlayerAsync
+  - 字典
+  - 键
+  - Intlayer
+  - 国际化
+  - 文档
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - next-intlayer
+  - useIntlayerAsync
+---
+
+# Next.js 集成：`useIntlayerAsync` Hook 文档
+
+`useIntlayerAsync` Hook 扩展了 `useIntlayer` 的功能，不仅返回预渲染的字典，还能异步获取更新，非常适合那些在初始渲染后频繁更新本地化内容的应用。
+
+## 概述
+
+- **异步字典加载：**  
+  在客户端，`useIntlayerAsync` 首先返回预渲染的本地化字典（与 `useIntlayer` 相同），然后异步获取并合并任何新可用的远程字典。
+- **进度状态管理：**  
+  该 Hook 还提供了一个 `isLoading` 状态，指示何时正在获取远程字典。这样开发者可以显示加载指示器或骨架屏，以提供更流畅的用户体验。
+
+## 环境设置
+
+Intlayer 提供了一个无头内容源管理（CSM）系统，使非开发人员能够无缝管理和更新应用内容。通过使用 Intlayer 直观的仪表盘，您的团队可以编辑本地化文本、图像和其他资源，而无需直接修改代码。这简化了内容管理流程，促进了协作，并确保更新能够快速且轻松地完成。
+
+要开始使用 Intlayer，您首先需要在 [仪表盘](https://intlayer.org/dashboard) 注册并获取访问令牌。获得凭证后，将其添加到您的配置文件中，如下所示：
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import type { IntlayerConfig } from "intlayer";
+
+export default {
+  // ...
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+} satisfies IntlayerConfig;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { type IntlayerConfig } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+// 配置对象
+const config = {
+  // ...
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID, // 客户端ID
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET, // 客户端密钥
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+/** @type {import('intlayer').IntlayerConfig} */
+// 配置对象
+const config = {
+  // ...
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID, // 客户端ID
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET, // 客户端密钥
+  },
+};
+
+module.exports = config;
+```
+
+配置好您的凭据后，您可以通过运行以下命令将新的本地化词典推送到 Intlayer：
+
+```bash
+npx intlayer dictionary push -d my-first-dictionary-key
+```
+
+此命令会上传您的初始内容词典，使其可通过 Intlayer 平台进行异步获取和编辑。
+
+## 在 Next.js 中导入 `useIntlayerAsync`
+
+由于 `useIntlayerAsync` 旨在用于**客户端**组件，您需要从与 `useIntlayer` 相同的客户端入口导入它：
+
+```tsx codeFormat="typescript"
+"use client";
+
+import { useIntlayerAsync } from "next-intlayer";
+```
+
+```javascript codeFormat="esm"
+"use client";
+
+import { useIntlayerAsync } from "next-intlayer";
+```
+
+```javascript codeFormat="commonjs"
+"use client";
+
+const { useIntlayerAsync } = require("next-intlayer");
+```
+
+如果您使用的是 Next.js App Router 并且服务器组件与客户端组件分开，请确保导入文件顶部标注了 `"use client"`。
+
+## 参数
+
+1. **`key`**：  
+   **类型**：`DictionaryKeys`  
+   用于标识本地化内容块的字典键。该键应在您的内容声明文件中定义。
+
+2. **`locale`**（可选）：  
+   **类型**：`Locales`  
+   您想要定位的特定语言环境。如果省略，钩子将使用客户端上下文中的语言环境。
+
+3. **`isRenderEditor`**（可选，默认值为 `true`）：  
+   **类型**：`boolean`  
+   确定内容是否应准备好通过 Intlayer 编辑器覆盖层进行渲染。如果设置为 `false`，返回的字典数据将不包含编辑器特定的功能。
+
+## 返回值
+
+该 Hook 返回一个字典对象，包含以 `key` 和 `locale` 为键的本地化内容。同时还包含一个 `isLoading` 布尔值，指示是否正在获取远程字典。
+
+## 在 Next.js 中的示例用法
+
+### 客户端组件示例
+
+```tsx fileName="src/components/AsyncClientComponentExample.tsx" codeFormat="typescript"
+"use client";
+
+import { useEffect, type FC } from "react";
+import { useIntlayerAsync } from "next-intlayer";
+
+export const AsyncClientComponentExample: FC = () => {
+  const { title, description, isLoading } = useIntlayerAsync("async-component");
+
+  useEffect(() => {
+    if (isLoading) {
+      console.log("内容正在加载...");
+    }
+  }, [isLoading]);
+
+  return (
+    <div>
+      <h1>{title.value}</h1>
+      <p>{description.value}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/AsyncClientComponentExample.mjx" codeFormat="esm"
+"use client";
+
+import { useEffect } from "react";
+import { useIntlayerAsync } from "next-intlayer";
+
+const AsyncClientComponentExample = () => {
+  const { title, description, isLoading } = useIntlayerAsync("async-component");
+
+  useEffect(() => {
+    if (isLoading) {
+      console.log("内容正在加载...");
+    }
+  }, [isLoading]);
+
+  return (
+    <div>
+      <h1>{title.value}</h1>
+      <p>{description.value}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/AsyncClientComponentExample.csx" codeFormat="commonjs"
+"use client";
+
+const { useEffect } = require("react");
+const { useIntlayerAsync } = require("next-intlayer");
+
+const AsyncClientComponentExample = () => {
+  const { title, description, isLoading } = useIntlayerAsync("async-component");
+
+  useEffect(() => {
+    if (isLoading) {
+      console.log("内容正在加载...");
+    }
+  }, [isLoading]);
+
+  return (
+    <div>
+      <h1>{title.value}</h1>
+      <p>{description.value}</p>
+    </div>
+  );
+};
+```
+
+**关键点：**
+
+- 在初始渲染时，`title` 和 `description` 来自预渲染的本地化字典。
+- 当 `isLoading` 为 `true` 时，会在后台发起远程请求以获取更新后的字典。
+- 请求完成后，`title` 和 `description` 会更新为最新内容，且 `isLoading` 会变回 `false`。
+
+## 处理属性本地化
+
+与 `useIntlayer` 类似，您可以获取各种 HTML 属性的本地化属性值（例如 `alt`、`title`、`aria-label`）：
+
+```tsx
+<img src={title.image.src.value} alt={title.image.alt.value} />
+```
+
+## 字典文件
+
+所有内容键必须在您的内容声明文件中定义，以确保类型安全并防止运行时错误。这些文件支持 TypeScript 验证，确保您始终引用存在的键和语言环境。
+
+/// 设置内容声明文件的说明请参见[这里](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/get_started.md)。
+
+## 进一步信息
+
+- **Intlayer 可视化编辑器：**  
+  集成 Intlayer 可视化编辑器，直接从 UI 管理和编辑内容。更多详情请见[这里](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md)。
+
+---
+
+**总结**，`useIntlayerAsync` 是一个强大的客户端钩子，旨在通过结合预渲染字典与异步字典更新，提升用户体验并保持内容的新鲜度。通过利用 `isLoading` 和基于 TypeScript 的内容声明，您可以无缝地将动态、本地化的内容集成到您的 Next.js 应用中。
+
+## 文档历史
+
+- 5.5.10 - 2025-06-29：初始化历史

package/docs/zh/packages/next-intlayer/useLocale.md

@@ -0,0 +1,131 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-06-29
+title: useLocale Hook 文档 | next-intlayer
+description: 查看如何使用 next-intlayer 包中的 useLocale 钩子
+keywords:
+  - useLocale
+  - 字典
+  - 键
+  - Intlayer
+  - 国际化
+  - 文档
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - next-intlayer
+  - useLocale
+---
+
+# Next.js 集成：`useLocale` 钩子文档（适用于 `next-intlayer`）
+
+本节提供了针对 Next.js 应用中 `next-intlayer` 库的 `useLocale` 钩子的详细文档。该钩子旨在高效处理语言环境切换和路由。
+
+## 在 Next.js 中导入 `useLocale`
+
+要在 Next.js 应用中使用 `useLocale` 钩子，请按如下方式导入：
+
+```javascript
+import { useLocale } from "next-intlayer"; // 用于管理 Next.js 中的语言环境和路由
+```
+
+## 用法
+
+以下是在 Next.js 组件中实现 `useLocale` 钩子的方法：
+
+```tsx fileName="src/components/LocaleSwitcher.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { Locales } from "intlayer";
+import { useLocale } from "next-intlayer";
+
+const LocaleSwitcher: FC = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>当前语言环境: {locale}</h1>
+      <p>默认语言环境: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.mjx" codeFormat="esm"
+"use client";
+
+import { Locales } from "intlayer";
+import { useLocale } from "next-intlayer";
+
+const LocaleSwitcher = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>当前语言环境: {locale}</h1>
+      <p>默认语言环境: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.csx" codeFormat="commonjs"
+"use client";
+
+const { Locales } = require("intlayer");
+const { useLocale } = require("next-intlayer");
+
+const LocaleSwitcher = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>当前语言环境: {locale}</h1>
+      <p>默认语言环境: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+```
+
+## 参数和返回值
+
+当你调用 `useLocale` 钩子时，它会返回一个包含以下属性的对象：
+
+- **`locale`**：当前在 React 上下文中设置的语言环境。
+- **`defaultLocale`**：配置中定义的主要语言环境。
+- **`availableLocales`**：配置中定义的所有可用语言环境列表。
+- **`setLocale`**：一个用于更改应用程序语言环境并相应更新 URL 的函数。它会处理前缀规则，根据配置决定是否将语言环境添加到路径中。利用 `next/navigation` 中的 `useRouter` 来执行导航功能，如 `push` 和 `refresh`。
+- **`pathWithoutLocale`**：一个计算属性，返回不包含语言环境的路径。它对于比较 URL 非常有用。例如，如果当前语言环境是 `fr`，且 URL 是 `fr/my_path`，则不含语言环境的路径为 `/my_path`。利用 `next/navigation` 中的 `usePathname` 获取当前路径。
+
+## 结论
+
+`next-intlayer` 的 `useLocale` 钩子是管理 Next.js 应用中多语言环境的关键工具。它通过无缝处理语言环境存储、状态管理和 URL 修改，提供了一种集成的方法来适配多语言应用。
+
+## 文档历史
+
+- 5.5.10 - 2025-06-29：初始化历史

package/docs/zh/packages/nuxt-intlayer/index.md

@@ -0,0 +1,53 @@
+---
+createdAt: 2025-06-18
+updatedAt: 2025-06-29
+title: 包文档 | nuxt-intlayer
+description: 查看如何使用 nuxt-intlayer 包
+keywords:
+  - Intlayer
+  - nuxt-intlayer
+  - 国际化
+  - 文档
+  - JavaScript
+  - Nuxt
+slugs:
+  - doc
+  - packages
+  - nuxt-intlayer
+---
+
+# nuxt-intlayer：用于国际化（i18n）Vue 应用的 NPM 包
+
+**Intlayer** 是一套专为 JavaScript 开发者设计的包集合。它兼容 Vue、Vue 和 Express.js 等框架。
+
+**`nuxt-intlayer` 包** 允许您对 Vue 应用进行国际化。它为 Vue 国际化提供了上下文提供者和钩子。
+
+## 为什么要对您的 Vue 应用进行国际化？
+
+对 Vue 应用进行国际化对于有效服务全球用户至关重要。它使您的应用能够以每个用户偏好的语言传递内容和信息。这种能力提升了用户体验，并通过使应用对不同语言背景的人更易访问和相关，扩大了应用的影响范围。
+
+## 为什么要集成 Intlayer？
+
+- **基于 JavaScript 的内容管理**：利用 JavaScript 的灵活性高效定义和管理您的内容。
+- **类型安全环境**：利用 TypeScript 确保所有内容定义准确无误，避免错误。
+- **集成内容文件**：将翻译内容与各自组件紧密结合，提高可维护性和清晰度。
+
+## 安装
+
+使用您喜欢的包管理器安装所需的包：
+
+```bash packageManager="npm"
+npm install nuxt-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add nuxt-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add nuxt-intlayer
+```
+
+## 文档历史
+
+- 5.5.10 - 2025-06-29：初始化历史