@intlayer/docs 5.5.8

package/zh/packages/next-intlayer/useDictionary.md

@@ -0,0 +1,242 @@
+# React 集成：`useDictionary` 钩子文档
+
+本节提供了在 React 应用程序中使用 `useDictionary` 钩子的详细指南，支持在没有可视化编辑器的情况下高效处理本地化内容。
+
+## 在 React 中导入 `useDictionary`
+
+可以通过以下方式将 `useDictionary` 钩子集成到 React 应用程序中：
+
+- **客户端组件：**
+
+  ```typescript codeFormat="typescript"
+  import { useDictionary } from "next-intlayer"; // 用于客户端的 React 组件
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useDictionary } from "next-intlayer"; // 用于客户端的 React 组件
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useDictionary } = require("next-intlayer"); // 用于客户端的 React 组件
+  ```
+
+- **服务端组件：**
+
+  ```typescript codeFormat="typescript"
+  import { useDictionary } from "next-intlayer/server"; // 用于服务端的 React 组件
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useDictionary } from "next-intlayer/server"; // 用于服务端的 React 组件
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useDictionary } = require("next-intlayer/server"); // 用于服务端的 React 组件
+  ```
+
+## 参数
+
+该钩子接受两个参数：
+
+1. **`dictionary`**：一个声明的字典对象，包含特定键的本地化内容。
+2. **`locale`**（可选）：所需的语言环境。如果未指定，则默认为当前上下文的语言环境。
+
+## 字典
+
+所有字典对象应在结构化内容文件中声明，以确保类型安全并防止运行时错误。您可以在[此处](https://github.com/aymericzip/intlayer/blob/main/docs/zh/dictionary/get_started.md)找到设置说明。以下是内容声明的示例：
+
+```typescript fileName="component.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const exampleContent = {
+  key: "component-example",
+  content: {
+    title: t({
+      en: "Client Component Example",
+      fr: "Exemple de composant client",
+      es: "Ejemplo de componente cliente",
+    }),
+    content: t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido de un ejemplo de componente cliente",
+    }),
+  },
+} satisfies Dictionary;
+
+export default exampleContent;
+```
+
+```javascript fileName="component.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const exampleContent = {
+  key: "component-example",
+  content: {
+    title: t({
+      en: "Client Component Example",
+      fr: "Exemple de composant client",
+      es: "Ejemplo de componente cliente",
+    }),
+    content: t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido de un ejemplo de componente cliente",
+    }),
+  },
+};
+
+export default exampleContent;
+```
+
+```javascript fileName="component.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const exampleContent = {
+  key: "component-example",
+  content: {
+    title: t({
+      en: "Client Component Example",
+      fr: "Exemple de composant client",
+      es: "Ejemplo de componente cliente",
+    }),
+    content: t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido de un ejemplo de componente cliente",
+    }),
+  },
+};
+
+module.exports = exampleContent;
+```
+
+## 在 React 客户端组件中的示例用法
+
+以下是如何在 React 组件中使用 `useDictionary` 钩子的示例：
+
+```tsx fileName="ClientComponentExample.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { useDictionary } from "next-intlayer";
+import clientComponentExampleContent from "./component.content";
+
+const ClientComponentExample: FC = () => {
+  const { title, content } = useDictionary(clientComponentExampleContent);
+
+  return (
+    <div>
+      <h1>{title}</h1>
+      <p>{content}</p>
+    </div>
+  );
+};
+```
+
+```javascript fileName="ClientComponentExample.mjs" codeFormat="esm"
+"use client";
+
+import type { FC } from "react";
+import { useDictionary } from "next-intlayer";
+import exampleContent from "./component.content";
+
+const ClientComponentExample: FC = () => {
+  const { title, content } = useDictionary(exampleContent);
+
+  return (
+    <div>
+      <h1>{title}</h1>
+      <p>{content}</p>
+    </div>
+  );
+};
+```
+
+```javascript fileName="ClientComponentExample.cjs" codeFormat="commonjs"
+"use client";
+
+const { useDictionary } = require("next-intlayer");
+const exampleContent = require("./component.content");
+
+const ClientComponentExample = () => {
+  const { title, content } = useDictionary(exampleContent);
+
+  return (
+    <div>
+      <h1>{title}</h1>
+      <p>{content}</p>
+    </div>
+  );
+};
+```
+
+## 在 React 服务端组件中的示例用法
+
+如果您在 `IntlayerServerProvider` 之外使用 `useDictionary` 钩子，则在渲染组件时必须显式提供语言环境作为参数：
+
+```tsx fileName="ServerComponentExample.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useDictionary } from "next-intlayer/server";
+import clientComponentExampleContent from "./component.content";
+
+const ServerComponentExample: FC = () => {
+  const { content } = useDictionary(clientComponentExampleContent);
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+```javascript fileName="ServerComponentExample.mjs" codeFormat="esm"
+import { useDictionary } from "next-intlayer/server";
+import clientComponentExampleContent from "./component.content";
+
+const ServerComponentExample = () => {
+  const { content } = useDictionary(clientComponentExampleContent);
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+```javascript fileName="ServerComponentExample.cjs" codeFormat="commonjs"
+import { useDictionary } from "next-intlayer/server";
+import clientComponentExampleContent from "./component.content";
+
+const ServerComponentExample = () => {
+  const { content } = useDictionary(clientComponentExampleContent);
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+## 关于属性的注意事项
+
+与使用可视化编辑器的集成不同，这里不适用诸如 `buttonTitle.value` 之类的属性。相反，直接访问您内容中声明的本地化字符串。
+
+```jsx
+<button title={content.title}>{content.content}</button>
+```
+
+## 其他提示
+
+- **类型安全**：始终使用 `Dictionary` 定义您的字典以确保类型安全。
+- **本地化更新**：更新内容时，请确保所有语言环境一致，以避免遗漏翻译。
+
+本篇文档专注于 `useDictionary` 钩子的集成，提供了一种无需依赖可视化编辑器功能的简化本地化内容管理方法。

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

@@ -0,0 +1,237 @@
+# Next.js 集成：`useIntlayer` 钩子文档
+
+`useIntlayer` 钩子专为 Next.js 应用程序设计，用于高效地获取和管理本地化内容。本篇文档将重点介绍如何在 Next.js 项目中使用该钩子，确保正确的本地化实践。
+
+## 在 Next.js 中导入 `useIntlayer`
+
+根据您在 Next.js 应用中是使用客户端组件还是服务端组件，可以按以下方式导入 `useIntlayer` 钩子：
+
+- **客户端组件：**
+
+  ```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`**（可选）：要使用的特定语言环境。如果未提供，钩子将默认使用客户端或服务端上下文中设置的语言环境。
+
+## 字典文件
+
+确保所有内容键都在内容声明文件中定义，以防止运行时错误并确保类型安全。这种方法还可以通过 TypeScript 集成实现编译时验证。
+
+有关设置内容声明文件的说明，请参阅[此处](https://github.com/aymericzip/intlayer/blob/main/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");
+
+  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");
+
+  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");
+
+  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/zh/intlayer_visual_editor.md)。
+
+本篇文档专门介绍了在 Next.js 环境中使用 `useIntlayer` 钩子，为您的 Next.js 应用程序提供了管理本地化的强大解决方案。

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

@@ -0,0 +1,211 @@
+# Next.js 集成: `useIntlayerAsync` 钩子文档
+
+`useIntlayerAsync` 钩子扩展了 `useIntlayer` 的功能，不仅返回预渲染的字典，还可以异步获取更新，非常适合在初始渲染后频繁更新本地化内容的应用程序。
+
+## 概述
+
+- **异步字典加载：**  
+  在客户端，`useIntlayerAsync` 首先返回预渲染的语言环境字典（与 `useIntlayer` 类似），然后异步获取并合并任何新可用的远程字典。
+- **进度状态管理：**  
+  该钩子还提供了一个 `isLoading` 状态，指示何时正在获取远程字典。这使开发人员能够显示加载指示器或骨架状态，从而提供更流畅的用户体验。
+
+## 环境设置
+
+Intlayer 提供了一个无头内容源管理（CSM）系统，使非开发人员能够无缝管理和更新应用程序内容。通过使用 Intlayer 的直观仪表板，您的团队可以编辑本地化文本、图像和其他资源，而无需直接修改代码。这简化了内容管理流程，促进了协作，并确保可以快速轻松地进行更新。
+
+要开始使用 Intlayer，您需要先注册并在 [https://intlayer.org/dashboard](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,
+    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,
+    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`，返回的字典数据将排除编辑器特定功能。
+
+## 返回值
+
+该钩子返回一个包含按 `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/zh/dictionary/get_started.md)。
+
+## 更多信息
+
+- **Intlayer 可视化编辑器：**  
+  集成 Intlayer 可视化编辑器以直接从 UI 管理和编辑内容。更多详情请参阅 [这里](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_visual_editor.md)。
+
+---
+
+**总结**，`useIntlayerAsync` 是一个强大的客户端钩子，旨在通过结合预渲染字典和异步字典更新来增强用户体验并保持内容的新鲜度。通过利用 `isLoading` 和基于 TypeScript 的内容声明，您可以将动态、本地化内容无缝集成到您的 Next.js 应用程序中。