@intlayer/docs 5.5.8

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

@@ -0,0 +1,105 @@
+# Next.js 集成: `useLocale` 钩子文档 for `next-intlayer`
+
+本节提供了针对 Next.js 应用程序的 `useLocale` 钩子的详细文档，适用于 `next-intlayer` 库。它旨在高效处理语言环境的更改和路由。
+
+## 在 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 修改，使您的应用程序适应多语言环境。

package/zh/packages/preact-intlayer/index.md

@@ -0,0 +1,3 @@
+this doc will be automatically generated translated from the english doc
+
+see /docs/en/packages/preact-intlayer/index.md

package/zh/packages/react-intlayer/index.md

@@ -0,0 +1,257 @@
+# react-intlayer: 用于国际化 (i18n) React 应用的 NPM 包
+
+**Intlayer** 是一套专为 JavaScript 开发者设计的工具包。它兼容 React、React 和 Express.js 等框架。
+
+**`react-intlayer` 包** 允许您对 React 应用进行国际化。它为 React 国际化提供了上下文提供者和钩子。
+
+## 为什么要国际化您的 React 应用？
+
+国际化您的 React 应用对于有效服务全球受众至关重要。它使您的应用能够以每个用户的首选语言传递内容和消息。这种能力增强了用户体验，并通过使您的应用对不同语言背景的人更具可访问性和相关性，从而扩大了应用的覆盖范围。
+
+## 为什么要集成 Intlayer？
+
+- **JavaScript 驱动的内容管理**：利用 JavaScript 的灵活性高效地定义和管理您的内容。
+- **类型安全的环境**：利用 TypeScript 确保所有内容定义都精确且无错误。
+- **集成的内容文件**：将翻译与其相关组件紧密结合，增强可维护性和清晰度。
+
+## 安装
+
+使用您首选的包管理器安装所需的包：
+
+```bash packageManager="npm"
+npm install react-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add react-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add react-intlayer
+```
+
+## 使用示例
+
+使用 Intlayer，您可以在代码库中的任何地方以结构化方式声明内容。
+
+默认情况下，Intlayer 会扫描扩展名为 `.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}` 的文件。
+
+> 您可以通过在[配置文件](https://github.com/aymericzip/intlayer/blob/main/docs/zh/configuration.md)中设置 `contentDir` 属性来修改默认扩展名。
+
+```bash codeFormat="typescript"
+.
+├── intlayer.config.ts
+└── src
+    └── components
+        ├── Component1
+        │   ├── index.content.ts
+        │   └── index.tsx
+        └── Component2
+            ├── index.content.ts
+            └── index.tsx
+```
+
+```bash codeFormat="esm"
+.
+├── intlayer.config.mjs
+└── src
+    └── components
+        ├── Component1
+        │   ├── index.content.mjs
+        │   └── index.mjx
+        └── Component2
+            ├── index.content.mjs
+            └── index.mjx
+```
+
+```bash codeFormat="commonjs"
+.
+├── intlayer.config.cjs
+└── src
+    └── components
+        ├── Component1
+        │   ├── index.content.cjs
+        │   └── index.cjx
+        └── Component2
+            ├── index.content.cjs
+            └── index.cjx
+```
+
+### 声明您的内容
+
+`react-intlayer` 是为 [`intlayer` 包](https://github.com/aymericzip/intlayer/blob/main/docs/zh/packages/intlayer/index.md) 设计的。`intlayer` 是一个允许您在代码中的任何地方声明内容的包。它将多语言内容声明转换为结构化字典，无缝集成到您的应用中。
+
+以下是内容声明的示例：
+
+```tsx fileName="src/Component1/index.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const component1Content = {
+  key: "component-1",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    numberOfCar: enu({
+      "<-1": "Less than minus one car",
+      "-1": "Minus one car",
+      "0": "No cars",
+      "1": "One car",
+      ">5": "Some cars",
+      ">19": "Many cars",
+    }),
+  },
+} satisfies Dictionary;
+
+export default component1Content;
+```
+
+```jsx fileName="src/Component1/index.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const component1Content = {
+  key: "component-1",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    numberOfCar: enu({
+      "<-1": "Less than minus one car",
+      "-1": "Minus one car",
+      "0": "No cars",
+      "1": "One car",
+      ">5": "Some cars",
+      ">19": "Many cars",
+    }),
+  },
+};
+
+export default component1Content;
+```
+
+```jsx fileName="src/Component1/index.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const component1Content = {
+  key: "component-1",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    numberOfCar: enu({
+      "<-1": "Less than minus one car",
+      "-1": "Minus one car",
+      "0": "No cars",
+      "1": "One car",
+      ">5": "Some cars",
+      ">19": "Many cars",
+    }),
+  },
+};
+
+module.exports = component1Content;
+```
+
+```json fileName="src/Component1/index.content.json" codeFormat="json"
+{
+  "key": "component-1",
+  "content": {
+    "myTranslatedContent": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Hello World",
+        "fr": "Bonjour le monde",
+        "es": "Hola Mundo"
+      }
+    },
+    "numberOfCar": {
+      "nodeType": "enumeration",
+      "enumeration": {
+        "<-1": "Less than minus one car",
+        "-1": "Minus one car",
+        "0": "No cars",
+        "1": "One car",
+        ">5": "Some cars",
+        ">19": "Many cars"
+      }
+    }
+  }
+}
+```
+
+### 在代码中使用内容
+
+声明内容后，您可以在代码中使用它。以下是如何在 React 组件中使用内容的示例：
+
+```tsx {4,7} fileName="src/components/Component1Example.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+export const Component1Example: FC = () => {
+  const { myTranslatedContent } = useIntlayer("component-1"); // 创建相关内容声明
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/Component1Example.mjx" codeFormat="esm"
+"use client";
+
+import { useIntlayer } from "react-intlayer";
+
+const Component1Example = () => {
+  const { myTranslatedContent } = useIntlayer("component-1"); // 创建相关内容声明
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/Component1Example.csx" codeFormat="commonjs"
+"use client";
+
+const { useIntlayer } = require("react-intlayer");
+
+const Component1Example = () => {
+  const { myTranslatedContent } = useIntlayer("component-1"); // 创建相关内容声明
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+## 掌握 React 应用的国际化
+
+Intlayer 提供了许多功能来帮助您国际化您的 React 应用。
+
+**要了解更多关于这些功能的信息，请参考 [使用 Intlayer 和 Vite 以及 React 进行 React 国际化 (i18n)](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_with_vite+react.md) 的指南，或 [使用 Intlayer 和 React (CRA) 进行 React 国际化 (i18n)](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_with_create_react_app.md) 的指南。**
+
+## `react-intlayer` 包提供的功能
+
+`react-intlayer` 包还提供了一些功能来帮助您国际化您的应用。
+
+- [`t()`](https://github.com/aymericzip/intlayer/blob/main/docs/zh/packages/react-intlayer/t.md)
+- [`useIntlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/zh/packages/react-intlayer/useIntlayer.md)
+- [`useDictionary()`](https://github.com/aymericzip/intlayer/blob/main/docs/zh/packages/react-intlayer/useDictionary.md)
+- [`useLocale()`](https://github.com/aymericzip/intlayer/blob/main/docs/zh/packages/react-intlayer/useLocale.md)
+- [`useIntlayerAsync()`](https://github.com/aymericzip/intlayer/blob/main/docs/zh/packages/react-intlayer/useIntlayerAsync.md)

package/zh/packages/react-intlayer/t.md

@@ -0,0 +1,271 @@
+# 文档: `t` 函数在 `react-intlayer` 中的使用
+
+`react-intlayer` 包中的 `t` 函数是一个用于在 React 应用中实现内联国际化的基础工具。它允许您直接在组件中定义翻译，从而根据当前语言环境轻松显示本地化内容。
+
+---
+
+## 概述
+
+`t` 函数用于在组件中直接提供不同语言环境的翻译。通过传递一个包含每种支持语言环境翻译的对象，`t` 会根据 React 应用中的当前语言环境上下文返回相应的翻译。
+
+---
+
+## 主要特点
+
+- **内联翻译**: 适用于不需要单独内容声明的快速内联文本。
+- **自动语言环境选择**: 自动返回与当前语言环境对应的翻译。
+- **TypeScript 支持**: 与 TypeScript 一起使用时提供类型安全和自动补全功能。
+- **易于集成**: 可无缝地在 React 组件中使用。
+
+---
+
+## 函数签名
+
+```typescript
+t<T extends string>(content: Record<LocalesValues, T>, locale?: Locales): string
+```
+
+### 参数
+
+- `translations`: 一个对象，其中键是语言环境代码（例如 `en`、`fr`、`es`），值是相应的翻译字符串。
+
+### 返回值
+
+- 一个字符串，表示当前语言环境的翻译内容。
+
+---
+
+## 使用示例
+
+### 在组件中基本使用 `t`
+
+```tsx fileName="src/components/ComponentExample.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { t } from "react-intlayer";
+
+export const ComponentExample: FC = () => {
+  return (
+    <div>
+      <p>
+        {t({
+          en: "This is an example of a component",
+          fr: "Ceci est un exemple de composant",
+          es: "Este es un ejemplo de componente",
+        })}
+      </p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.mjx" codeFormat="esm"
+import { t } from "react-intlayer";
+
+const ComponentExample = () => {
+  return (
+    <div>
+      <p>
+        {t({
+          en: "This is an example of a component",
+          fr: "Ceci est un exemple de composant",
+          es: "Este es un ejemplo de componente",
+        })}
+      </p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.csx" codeFormat="commonjs"
+const { t } = require("react-intlayer");
+
+const ComponentExample = () => {
+  return (
+    <div>
+      <p>
+        {t({
+          en: "This is an example of a component",
+          fr: "Ceci est un exemple de composant",
+          es: "Este es un ejemplo de componente",
+        })}
+      </p>
+    </div>
+  );
+};
+```
+
+### 在属性中使用内联翻译
+
+`t` 函数特别适用于 JSX 属性中的内联翻译。当本地化 `alt`、`title`、`href` 或 `aria-label` 等属性时，可以直接在属性中使用 `t`。
+
+```jsx
+<button
+  aria-label={t({
+    en: "Submit",
+    fr: "Soumettre",
+    es: "Enviar",
+  })}
+>
+  {t({
+    en: "Submit",
+    fr: "Soumettre",
+    es: "Enviar",
+  })}
+  <img
+    src="/path/to/image"
+    alt={t({
+      en: "A beautiful scenery",
+      fr: "Un beau paysage",
+      es: "Un hermoso paisaje",
+    })}
+  />
+</button>
+```
+
+---
+
+## 高级主题
+
+### TypeScript 集成
+
+与 TypeScript 一起使用时，`t` 函数是类型安全的，确保提供所有必需的语言环境。
+
+```typescript codeFormat="typescript"
+import { t, type IConfigLocales } from "react-intlayer";
+
+const translations: IConfigLocales<string> = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="esm"
+import { t, type IConfigLocales } from "react-intlayer";
+
+/** @type {import('react-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t, type IConfigLocales } = require("react-intlayer");
+
+/** @type {import('react-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+};
+
+const greeting = t(translations);
+```
+
+### 语言环境检测与上下文
+
+在 `react-intlayer` 中，当前语言环境通过 `IntlayerProvider` 管理。确保该提供程序包裹您的组件并正确传递 `locale` 属性。
+
+#### 示例:
+
+```tsx fileName="src/app.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import type { Locales } from "intlayer";
+import { IntlayerProvider } from "react-intlayer";
+
+const App: FC<{ locale: Locales }> = ({ locale }) => (
+  <IntlayerProvider locale={locale}>{/* 您的组件 */}</IntlayerProvider>
+);
+```
+
+```jsx fileName="src/app.mjx" codeFormat="esm"
+import { IntlayerProvider } from "react-intlayer";
+
+const App = ({ locale }) => (
+  <IntlayerProvider locale={locale}>{/* 您的组件 */}</IntlayerProvider>
+);
+```
+
+```jsx fileName="src/app.csx" codeFormat="commonjs"
+const { IntlayerProvider } = require("react-intlayer");
+
+const App = ({ locale }) => (
+  <IntlayerProvider locale={locale}>{/* 您的组件 */}</IntlayerProvider>
+);
+```
+
+---
+
+## 常见错误与故障排除
+
+### `t` 返回未定义或错误翻译
+
+- **原因**: 当前语言环境未正确设置，或当前语言环境的翻译缺失。
+- **解决方案**:
+  - 验证 `IntlayerProvider` 是否正确设置并传递了适当的 `locale`。
+  - 确保您的翻译对象包含所有必要的语言环境。
+
+### TypeScript 中缺少翻译
+
+- **原因**: 翻译对象未满足所需的语言环境，导致 TypeScript 错误。
+- **解决方案**: 使用 `IConfigLocales` 类型来强制翻译的完整性。
+
+```typescript codeFormat="typescript"
+const translations: IConfigLocales<string> = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // 缺少 'es' 会导致 TypeScript 错误
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="esm"
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // 缺少 'es' 会导致 TypeScript 错误
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t, type IConfigLocales } = require("react-intlayer");
+
+/** @type {import('react-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // 缺少 'es' 会导致 TypeScript 错误
+};
+
+const text = t(translations);
+```
+
+---
+
+## 有效使用的提示
+
+1. **使用 `t` 进行简单的内联翻译**: 适用于直接在组件中翻译小段文本。
+2. **优先使用 `useIntlayer` 处理结构化内容**: 对于更复杂的翻译和内容重用，请在声明文件中定义内容并使用 `useIntlayer`。
+3. **一致提供语言环境**: 确保通过 `IntlayerProvider` 在整个应用中一致提供语言环境。
+4. **利用 TypeScript**: 使用 TypeScript 类型捕获缺失的翻译并确保类型安全。
+
+---
+
+## 结论
+
+`react-intlayer` 中的 `t` 函数是一个强大且方便的工具，用于在 React 应用中管理内联翻译。通过有效集成它，可以增强应用的国际化能力，为全球用户提供更好的体验。
+
+有关更详细的用法和高级功能，请参阅 [react-intlayer 文档](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_visual_editor.md)。
+
+---
+
+**注意**: 请确保正确设置 `IntlayerProvider`，以确保当前语言环境正确传递到组件中。这对于 `t` 函数返回正确的翻译至关重要。