@intlayer/docs 5.7.5 → 5.7.6-canary.0

package/docs/zh/packages/react-intlayer/useI18n.md

@@ -0,0 +1,250 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-06-29
+title: useI18n Hook 文档 | react-intlayer
+description: 学习如何在 react-intlayer 包中使用 useI18n Hook
+keywords:
+  - useI18n
+  - i18n
+  - 翻译
+  - 词典
+  - Intlayer
+  - 国际化
+  - 文档
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - react-intlayer
+  - useI18n
+---
+
+# React 集成：`useI18n` Hook 文档
+
+本节详细介绍如何在 React 应用中使用 `useI18n` Hook，实现高效的内容本地化。
+
+## 在 React 中导入 `useI18n`
+
+可以根据不同的上下文，将 `useI18n` Hook 导入并集成到 React 应用中，具体如下：
+
+- **客户端组件：**
+
+  ```typescript codeFormat="typescript"
+  import { useI18n } from "react-intlayer"; // 在客户端 React 组件中使用
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useI18n } from "react-intlayer"; // 在客户端 React 组件中使用
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useI18n } = require("react-intlayer"); // 在客户端 React 组件中使用
+  ```
+
+- **服务器组件：**
+
+  ```typescript codeFormat="commonjs"
+  import { useI18n } from "react-intlayer/server"; // 在服务器端 React 组件中使用
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useI18n } from "react-intlayer/server"; // 在服务器端 React 组件中使用
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useI18n } = require("react-intlayer/server"); // 在服务器端 React 组件中使用
+  ```
+
+## 参数
+
+此钩子接受两个参数：
+
+1. **`namespace`**：用于限定翻译键的字典命名空间。
+2. **`locale`**（可选）：期望使用的语言环境。如果未指定，则默认使用上下文的语言环境。
+
+## 字典
+
+所有字典键必须在内容声明文件中声明，以增强类型安全并防止错误。[配置说明请参见此处](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/get_started.md)。
+
+## React 中的使用示例
+
+以下是在 React 组件中使用 `useI18n` 钩子的示例：
+
+```tsx fileName="src/App.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { ClientComponentExample, ServerComponentExample } from "@components";
+import { IntlayerProvider } from "react-intlayer";
+import { useI18n, IntlayerServerProvider } from "react-intlayer/server";
+import { Locales } from "intlayer";
+
+const App: FC<{ locale: Locales }> = ({ locale }) => {
+  const t = useI18n("home-page", locale);
+
+  return (
+    <>
+      <p>{t("introduction")}</p>
+      <IntlayerProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```jsx fileName="src/app.jsx" codeFormat="esm"
+import { ClientComponentExample, ServerComponentExample } from "@components";
+import { IntlayerProvider } from "react-intlayer";
+import { IntlayerServerProvider, useI18n } from "react-intlayer/server";
+
+const App = ({ locale }) => {
+  const t = useI18n("home-page", locale);
+
+  return (
+    <>
+      <p>{t("introduction")}</p>
+      <IntlayerProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```jsx fileName="src/app.cjs" codeFormat="commonjs"
+const { IntlayerProvider } = require("react-intlayer");
+const { IntlayerServerProvider, useI18n } = require("react-intlayer/server");
+
+const App = ({ locale }) => {
+  const t = useI18n("home-page", locale);
+
+  return (
+    <>
+      <p>{t("introduction")}</p>
+      <IntlayerProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```tsx fileName="src/components/ComponentExample.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useI18n } from "react-intlayer";
+
+const ComponentExample: FC = () => {
+  const t = useI18n("component-example");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1> {/* 显示标题 */}
+      <p>{t("description")}</p> {/* 显示描述 */}
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.jsx" codeFormat="esm"
+import { useI18n } from "react-intlayer";
+
+const ComponentExample = () => {
+  const t = useI18n("component-example");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1> {/* 显示标题 */}
+      <p>{t("description")}</p> {/* 显示描述 */}
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.cjs" codeFormat="commonjs"
+const { useI18n } = require("react-intlayer");
+
+const ComponentExample = () => {
+  const t = useI18n("component-example");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1> {/* 显示标题 */}
+      <p>{t("description")}</p> {/* 显示描述 */}
+    </div>
+  );
+};
+```
+
+```tsx fileName="src/components/ServerComponentExample.tsx" codeFormat="typescript"
+import { useI18n } from "react-intlayer/server";
+
+const ServerComponentExample = () => {
+  const t = useI18n("server-component");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1> {/* 显示标题 */}
+      <p>{t("description")}</p> {/* 显示描述 */}
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ServerComponentExample.jsx" codeFormat="esm"
+import { useI18n } from "react-intlayer/server";
+
+const ServerComponentExample = () => {
+  const t = useI18n("server-component");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1> {/* 显示标题 */}
+      <p>{t("description")}</p> {/* 显示描述 */}
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ServerComponentExample.cjs" codeFormat="commonjs"
+const { useI18n } = require("react-intlayer/server");
+
+const ServerComponentExample = () => {
+  const t = useI18n("server-component");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1>
+      <p>{t("description")}</p>
+    </div>
+  );
+};
+```
+
+## 属性处理
+
+在本地化属性时，请适当地访问翻译值：
+
+```jsx
+<!-- 对于无障碍属性（例如 aria-label），请使用 .value，因为需要纯字符串 -->
+<button aria-label={t("button.ariaLabel").value}>{t("button.text")}</button>
+```
+
+## 额外资源
+
+- **Intlayer 可视化编辑器**：为了获得更直观的内容管理体验，请参阅可视化编辑器文档 [这里](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md)。
+
+本节特别涵盖了在 React 应用中集成 `useI18n` 钩子，简化本地化流程并确保不同语言环境下内容的一致性。
+
+## 文档历史
+
+- 6.0.0 - 2025-06-29：`useI18n` 钩子文档的初始编写

package/frequent_questions/ar/unknown_command.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - أمر-غير-معروف
+  - unknown-command
 ---
 
 # خطأ: أمر غير معروف fill / build / إلخ

package/frequent_questions/de/array_as_content_declaration.md

@@ -11,7 +11,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - array-als-inhaltsdeklaration
+  - array-as-content-declaration
 ---
 
 # Kann ich ein Array als Inhaltsdeklaration verwenden?

package/frequent_questions/de/build_dictionaries.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - wörterbücher-erstellen
+  - build-dictionaries
 ---
 
 # Wörterbücher erstellen

package/frequent_questions/de/build_error_CI_CD.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - build-fehler-ci-cd
+  - build-error-ci-cd
 ---
 
 # Fehler beim Build in CI/CD

package/frequent_questions/de/customized_locale_list.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - angepasste-sprachen-liste
+  - customized-locale-list
 ---
 
 # Ist es möglich, einen Sprachtyp wie Englisch zu blockieren? Ich füge Englisch in meine Wörterbücher ein, möchte Englisch aber noch nicht auf der Webseite verfügbar machen

package/frequent_questions/de/esbuild_error.md

@@ -16,7 +16,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - esbuild-fehler
+  - esbuild-error
 ---
 
 # ESBuild-Fehler

package/frequent_questions/de/intlayer_command_undefined.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - intlayer-befehl-nicht-definiert
+  - intlayer-command-undefined
 ---
 
 # Intlayer-Befehl nicht definiert

package/frequent_questions/de/locale_incorect_in_url.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - locale-falsch-in-url
+  - locale-incorect-in-url
 ---
 
 # Falsche Locale aus URL abgerufen

package/frequent_questions/de/static_rendering.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - statisches-rendering
+  - static-rendering
 ---
 
 # Statisches vs. dynamisches Rendering mit i18n in Next.js

package/frequent_questions/de/translated_path_url.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - übersetzter-pfad-url
+  - translated-path-url
 ---
 
 # Ist es möglich, URLs wie folgt zu übersetzen:

package/frequent_questions/de/unknown_command.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - unbekannter-befehl
+  - unknown-command
 ---
 
 # Fehler: unbekannter Befehl fill / build / etc.

package/frequent_questions/en-GB/customized_locale_list.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - customised-locale-list
+  - customized-locale-list
 ---
 
 # Is it possible to block a language type, like English? I am adding English in my dictionaries but I don't want English available on the website just yet

package/frequent_questions/es/array_as_content_declaration.md

@@ -11,7 +11,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - arreglo-como-declaracion-de-contenido
+  - array-as-content-declaration
 ---
 
 # ¿Puedo usar un arreglo como declaración de contenido?

package/frequent_questions/es/build_dictionaries.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - construir-diccionarios
+  - build-dictionaries
 ---
 
 # Construir Diccionarios

package/frequent_questions/es/customized_locale_list.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - lista-de-locales-personalizada
+  - customized-locale-list
 ---
 
 # ¿Es posible bloquear un tipo de idioma, como inglés? Estoy agregando inglés en mis diccionarios pero no quiero que el inglés esté disponible en el sitio web todavía

package/frequent_questions/es/domain_routing.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - enrutamiento-por-dominio
+  - domain-routing
 ---
 
 # ¿Cómo configuro el **enrutamiento basado en dominios** con Intlayer en lugar de rutas `/[locale]/`?

package/frequent_questions/es/get_locale_cookie.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - obtener-configuracion-regional-cookie
+  - get-locale-cookie
 ---
 
 # Cómo recuperar la configuración regional desde las cookies / encabezados

package/frequent_questions/es/intlayer_command_undefined.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - comando-intlayer-indefinido
+  - intlayer-command-undefined
 ---
 
 # Comando Intlayer indefinido

package/frequent_questions/es/locale_incorect_in_url.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - localizacion-incorrecta-en-url
+  - locale-incorect-in-url
 ---
 
 # Localización incorrecta obtenida desde la URL

package/frequent_questions/es/static_rendering.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - renderizado-estatico
+  - static-rendering
 ---
 
 # Renderizado Estático vs Dinámico con i18n en Next.js

package/frequent_questions/es/translated_path_url.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - ruta-url-traducida
+  - translated-path-url
 ---
 
 # ¿Es posible traducir la URL como sigue?

package/frequent_questions/es/unknown_command.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - comando-desconocido
+  - unknown-command
 ---
 
 # error: comando desconocido fill / build / etc

package/frequent_questions/fr/array_as_content_declaration.md

@@ -11,7 +11,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - tableau-comme-declaration-de-contenu
+  - array-as-content-declaration
 ---
 
 # Puis-je utiliser un tableau comme déclaration de contenu ?

package/frequent_questions/fr/build_dictionaries.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - construire-dictionnaires
+  - build-dictionaries
 ---
 
 # Construire des dictionnaires

package/frequent_questions/fr/customized_locale_list.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - liste-langues-personnalisee
+  - customized-locale-list
 ---
 
 # Est-il possible de bloquer un type de langue, comme l'anglais ? J'ajoute l'anglais dans mes dictionnaires mais je ne veux pas que l'anglais soit encore disponible sur le site web

package/frequent_questions/fr/domain_routing.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - routage-domaine
+  - domain-routing
 ---
 
 # Comment configurer le **routage basé sur le domaine** avec Intlayer au lieu des chemins `/[locale]/` ?

package/frequent_questions/fr/esbuild_error.md

@@ -16,7 +16,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - erreur-esbuild
+  - esbuild-error
 ---
 
 # Erreur ESBuild

package/frequent_questions/fr/intlayer_command_undefined.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - commande-intlayer-non-definie
+  - intlayer-command-undefined
 ---
 
 # Commande Intlayer non définie

package/frequent_questions/fr/static_rendering.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - rendu-statique
+  - static-rendering
 ---
 
 # Rendu statique vs dynamique avec i18n dans Next.js

package/frequent_questions/fr/translated_path_url.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - chemin-url-traduit
+  - translated-path-url
 ---
 
 # Est-il possible de traduire l'URL comme suit :

package/frequent_questions/fr/unknown_command.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - commande-inconnue
+  - unknown-command
 ---
 
 # erreur : commande inconnue fill / build / etc

package/frequent_questions/it/array_as_content_declaration.md

@@ -11,7 +11,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - array-come-dichiarazione-di-contenuto
+  - array-as-content-declaration
 ---
 
 # Posso usare un array come dichiarazione di contenuto?

package/frequent_questions/it/build_dictionaries.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - costruire-dizionari
+  - build-dictionaries
 ---
 
 # Costruire Dizionari

package/frequent_questions/it/customized_locale_list.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - lista-localizzazioni-personalizzata
+  - customized-locale-list
 ---
 
 # È possibile bloccare un tipo di lingua, come l'inglese? Sto aggiungendo l'inglese nei miei dizionari ma non voglio che l'inglese sia ancora disponibile sul sito web

package/frequent_questions/it/esbuild_error.md

@@ -16,7 +16,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - errore-esbuild
+  - esbuild-error
 ---
 
 # Errore ESBuild

package/frequent_questions/it/intlayer_command_undefined.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - comando-intlayer-non-definito
+  - intlayer-command-undefined
 ---
 
 # Comando Intlayer non definito

package/frequent_questions/it/locale_incorect_in_url.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - locale-errato-nell-url
+  - locale-incorect-in-url
 ---
 
 # Locale Errato Recuperato dall'URL

package/frequent_questions/it/static_rendering.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - rendering-statico
+  - static-rendering
 ---
 
 # Rendering Statico vs Dinamico con i18n in Next.js

package/frequent_questions/it/translated_path_url.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - percorso-url-tradotto
+  - translated-path-url
 ---
 
 # È possibile tradurre l'URL come segue:

package/frequent_questions/it/unknown_command.md

@@ -17,7 +17,7 @@ keywords:
 slugs:
   - doc
   - faq
-  - comando-sconosciuto
+  - unknown-command
 ---
 
 # errore: comando sconosciuto fill / build / ecc.

package/frequent_questions/ko/build_dictionaries.md

@@ -15,9 +15,9 @@ keywords:
   - next.js
   - vite
 slugs:
-  - 문서
+  - doc
   - faq
-  - 사전-빌드
+  - build-dictionaries
 ---
 
 # 사전 빌드