@intlayer/docs 5.7.4 → 5.7.6-canary.0

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

@@ -0,0 +1,250 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-06-29
+title: Документация по хуку useI18n | react-intlayer
+description: Узнайте, как использовать хук useI18n в пакете react-intlayer
+keywords:
+  - useI18n
+  - i18n
+  - перевод
+  - словарь
+  - Intlayer
+  - интернационализация
+  - документация
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - react-intlayer
+  - useI18n
+---
+
+# Интеграция с React: Документация по хуку `useI18n`
+
+В этом разделе представлено подробное руководство по использованию хука `useI18n` в приложениях React, что позволяет эффективно локализовать контент.
+
+## Импортирование `useI18n` в React
+
+Хук `useI18n` можно импортировать и интегрировать в приложения 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/ru/dictionary/get_started.md).
+
+## Примеры использования в React
+
+Примеры использования хука `useI18n` в React-компонентах:
+
+```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/ru/intlayer_visual_editor.md).
+
+Этот раздел специально охватывает интеграцию хука `useI18n` в React-приложениях, упрощая процесс локализации и обеспечивая согласованность контента между различными локалями.
+
+## История документации
+
+- 6.0.0 - 2025-06-29: Первоначальное написание документации по хуку `useI18n`

package/docs/ru/vs_code_extension.md

@@ -14,7 +14,6 @@ keywords:
   - TypeScript
 slugs:
   - doc
-  - ru
   - vs-code-extension
 ---
 

package/docs/zh/configuration.md

@@ -268,10 +268,12 @@ module.exports = config;
 - **prefixDefault**:
 
   - _类型_: `boolean`
-  - _默认值_: `true`
+  - _默认值_: `false`
   - _描述_: 是否在 URL 中包含默认语言环境。
-  - _示例_: `false`
-  - _注意_: 如果为 `false`，默认语言环境的 URL 将不会有语言环境前缀。
+  - _示例_: `true`
+  - _注意_:
+    - 如果 `true` 且 `defaultLocale = 'en'`: path = `/en/dashboard` 或 `/fr/dashboard`
+    - 如果 `false` 且 `defaultLocale = 'en'`: path = `/dashboard` 或 `/fr/dashboard`
 
 - **basePath**:
 
@@ -279,7 +281,11 @@ module.exports = config;
   - _默认值_: `''`
   - _描述_: 应用程序 URL 的基础路径。
   - _示例_: `'/my-app'`
-  - _注意_: 这会影响应用程序 URL 的构建方式。
+  - _注意_:
+    - 如果应用程序托管在 `https://example.com/my-app`
+    - 基础路径是 `'/my-app'`
+    - URL 将是 `https://example.com/my-app/en`
+    - 如果基础路径未设置，URL 将是 `https://example.com/en`
 
 - **serverSetCookie**:
 
@@ -291,11 +297,42 @@ module.exports = config;
   - _注意_: 控制是否在每个请求上设置语言环境 Cookie 或从不设置。
 
 - **noPrefix**:
+
   - _类型_: `boolean`
   - _默认值_: `false`
   - _描述_: 是否从 URL 中省略语言环境前缀。
   - _示例_: `true`
-  - _注意_: 如果为 `true`，URL 将不包含语言环境信息。
+  - _注意_:
+    - 如果 `true`: URL 中没有前缀
+    - 如果 `false`: URL 中有前缀
+    - 使用 `basePath = '/my-app'` 的示例:
+      - 如果 `noPrefix = false`: URL 将是 `https://example.com/my-app/en`
+      - 如果 `noPrefix = true`: URL 将是 `https://example.com`
+
+- **detectLocaleOnPrefetchNoPrefix**:
+
+  - _类型_: `boolean`
+  - _默认值_: `false`
+  - _描述_: 控制是否在 Next.js 预取请求期间进行语言环境检测。
+  - _示例_: `true`
+  - _注意_: 此设置影响 Next.js 处理语言环境预取的方式:
+    - **示例场景:**
+      - 用户的浏览器语言是 `'fr'`
+      - 当前页面是 `/fr/about`
+      - 链接预取 `/about`
+    - **使用 `detectLocaleOnPrefetchNoPrefix: true`:**
+      - 预取从浏览器检测到 `'fr'` 语言环境
+      - 将预取重定向到 `/fr/about`
+    - **使用 `detectLocaleOnPrefetchNoPrefix: false` (默认):**
+      - 预取使用默认语言环境
+      - 将预取重定向到 `/en/about` (假设 `'en'` 是默认值)
+    - **何时使用 `true`:**
+      - 您的应用程序使用非本地化的内部链接 (例如 `<a href="/about">`)
+      - 您希望在常规请求和预取请求之间保持一致的语言环境检测行为
+    - **何时使用 `false` (默认):**
+      - 您的应用程序使用带语言环境前缀的链接 (例如 `<a href="/fr/about">`)
+      - 您希望优化预取性能
+      - 您希望避免潜在的重定向循环
 
 ---
 

package/docs/zh/dictionary/enumeration.md

@@ -15,7 +15,6 @@ slugs:
   - doc
   - concept
   - content
-  - zh
   - enumeration
 ---
 

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: