@intlayer/docs 5.5.8

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

@@ -0,0 +1,184 @@
+# React 集成：`useLocale` 钩子文档
+
+本节提供了关于 `react-intlayer` 库中的 `useLocale` 钩子的全面详细信息，该库专为在 React 应用程序中处理语言环境管理而设计。
+
+## 在 React 中导入 `useLocale`
+
+要将 `useLocale` 钩子集成到您的 React 应用程序中，请从其相应的包中导入：
+
+```typescript codeFormat="typescript"
+import { useLocale } from "react-intlayer"; // 在 React 组件中用于语言环境管理
+```
+
+```javascript codeFormat="esm"
+import { useLocale } from "react-intlayer"; // 在 React 组件中用于语言环境管理
+```
+
+```javascript codeFormat="commonjs"
+const { useLocale } = require("react-intlayer"); // 在 React 组件中用于语言环境管理
+```
+
+## 概述
+
+`useLocale` 钩子提供了一种简单的方法来访问和操作 React 组件中的语言环境设置。它提供对当前语言环境、默认语言环境、所有可用语言环境以及更新语言环境设置的功能的访问。
+
+## 用法
+
+以下是如何在 React 组件中使用 `useLocale` 钩子：
+
+```tsx fileName="src/components/LocaleSwitcher.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useLocale } from "react-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>
+  );
+};
+
+export default LocaleSwitcher;
+```
+
+```jsx fileName="src/components/LocaleSwitcher.mjx" codeFormat="esm"
+import { useLocale } from "react-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>
+  );
+};
+
+export default LocaleSwitcher;
+```
+
+```jsx fileName="src/components/LocaleSwitcher.csx" codeFormat="commonjs"
+const { useLocale } = require("react-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>
+  );
+};
+
+export default LocaleSwitcher;
+```
+
+## 参数和返回值
+
+当您调用 `useLocale` 钩子时，它返回一个包含以下属性的对象：
+
+- **`locale`**: 在 React 上下文中设置的当前语言环境。
+- **`defaultLocale`**: 配置中定义的主要语言环境。
+- **`availableLocales`**: 配置中定义的所有可用语言环境的列表。
+- **`setLocale`**: 用于更新应用程序上下文中当前语言环境的函数。
+
+## 示例
+
+此示例展示了一个使用 `useLocale` 钩子的组件，用于渲染一个语言环境切换器，允许用户动态更改应用程序的语言环境：
+
+```tsx fileName="src/components/LocaleSelector.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useLocale } from "react-intlayer";
+
+const LocaleSelector: FC = () => {
+  const { locale, setLocale, availableLocales } = useLocale();
+
+  const handleLocaleChange = (newLocale) => {
+    setLocale(newLocale);
+  };
+
+  return (
+    <select value={locale} onChange={(e) => handleLocaleChange(e.target.value)}>
+      {availableLocales.map((locale) => (
+        <option key={locale} value={locale}>
+          {locale}
+        </option>
+      ))}
+    </select>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSelector.mjx" codeFormat="esm"
+import { useLocale } from "react-intlayer";
+
+const LocaleSelector = () => {
+  const { locale, setLocale, availableLocales } = useLocale();
+
+  const handleLocaleChange = (newLocale) => {
+    setLocale(newLocale);
+  };
+
+  return (
+    <select value={locale} onChange={(e) => handleLocaleChange(e.target.value)}>
+      {availableLocales.map((locale) => (
+        <option key={locale} value={locale}>
+          {locale}
+        </option>
+      ))}
+    </select>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSelector.csx" codeFormat="commonjs"
+const { useLocale } = require("react-intlayer");
+
+const LocaleSelector = () => {
+  const { locale, setLocale, availableLocales } = useLocale();
+
+  const handleLocaleChange = (newLocale) => {
+    setLocale(newLocale);
+  };
+
+  return (
+    <select value={locale} onChange={(e) => handleLocaleChange(e.target.value)}>
+      {availableLocales.map((locale) => (
+        <option key={locale} value={locale}>
+          {locale}
+        </option>
+      ))}
+    </select>
+  );
+};
+```
+
+## 结论
+
+`react-intlayer` 的 `useLocale` 钩子是管理 React 应用程序中语言环境的基本工具，提供了有效适应各种国际受众所需的功能。

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

@@ -0,0 +1,57 @@
+**Intlayer** 是专为 JavaScript 开发者设计的一套工具包。它兼容 React、React 和 Express.js 等框架。
+
+**`react-native-intlayer` 包** 允许您对 Vite 应用程序进行国际化。它包括 Metro 插件，通过环境变量在 [Metro bundler](https://docs.expo.dev/guides/customizing-metro/) 中设置配置。
+
+## 为什么要对您的 React Native 应用程序进行国际化？
+
+对您的 React Native 应用程序进行国际化对于有效服务全球用户至关重要。它允许您的应用程序以每个用户首选的语言提供内容和消息。这种功能增强了用户体验，并通过使应用程序对来自不同语言背景的人更具可访问性和相关性，从而扩大了应用程序的影响范围。
+
+## 配置
+
+`react-native-intlayer` 包与 [`react-intlayer` 包](https://github.com/aymericzip/intlayer/blob/main/docs/zh/packages/react-intlayer/index.md) 和 [`intlayer` 包](https://github.com/aymericzip/intlayer/blob/main/docs/zh/packages/intlayer/index.md) 无缝协作。请查看相关文档以获取更多信息。
+
+## 安装
+
+使用您首选的包管理器安装必要的包：
+
+```bash packageManager="npm"
+npm install react-native-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add react-native-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add react-native-intlayer
+```
+
+## 使用示例
+
+以下是如何将插件包含到您的 Vite 配置中的示例。
+
+```js
+// metro.config.js
+const { getDefaultConfig } = require("expo/metro-config");
+const { configMetroIntlayer } = require("react-native-intlayer/metro");
+
+module.exports = (async () => {
+  const defaultConfig = getDefaultConfig(__dirname);
+
+  return await configMetroIntlayer(defaultConfig);
+})();
+```
+
+## 掌握 Vite 应用程序的国际化
+
+Intlayer 提供了许多功能来帮助您国际化您的 Vite 应用程序。
+
+**要了解更多这些功能，请参考 [使用 Intlayer 和 React Native 进行 React 国际化 (i18n)](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_with_react_native+expo.md) 指南，适用于 React Native 应用程序。**
+
+## 阅读关于 Intlayer 的内容
+
+- [Intlayer 网站](https://intlayer.org)
+- [Intlayer 文档](https://intlayer.org/doc)
+- [Intlayer GitHub](https://github.com/aymericzip/intlayer)
+
+- [向我们的智能文档提问](https://intlayer.org/docchat)

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

@@ -0,0 +1,57 @@
+# react-scripts-intlayer: 用于在 React Create App 应用程序中使用 Intlayer 的 NPM 包
+
+**Intlayer** 是专为 JavaScript 开发人员设计的一套软件包。它兼容 React、React 和 Express.js 等框架。
+
+**`react-scripts-intlayer` 包** 包括用于将 Intlayer 集成到基于 Create React App 的应用程序中的 `react-scripts-intlayer` 命令和插件。这些插件基于 [craco](https://craco.js.org/)，并包括对 [Webpack](https://webpack.js.org/) 打包器的额外配置。
+
+## 配置
+
+`react-scripts-intlayer` 包与 [`react-intlayer` 包](https://github.com/aymericzip/intlayer/blob/main/docs/zh/packages/react-intlayer/index.md) 和 [`intlayer` 包](https://github.com/aymericzip/intlayer/blob/main/docs/zh/packages/intlayer/index.md) 无缝协作。请查看相关文档以获取更多信息。
+
+## 安装
+
+使用您喜欢的包管理器安装必要的包：
+
+```bash packageManager="npm"
+npm install react-scripts-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add react-scripts-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add react-scripts-intlayer
+```
+
+## 使用方法
+
+### CLI 命令
+
+`react-scripts-intlayer` 包提供以下 CLI 命令：
+
+- `npx react-scripts-intlayer build`：使用 Intlayer 配置构建 React 应用程序。
+- `npx react-scripts-intlayer start`：使用 Intlayer 配置启动开发服务器。
+
+### 替换 package.json 脚本
+
+要使用 `react-scripts-intlayer` 包，您需要将 `package.json` 脚本替换为以下命令：
+
+```json fileName="package.json"
+{
+  "scripts": {
+    "start": "react-scripts-intlayer start",
+    "build": "react-scripts-intlayer build"
+  }
+}
+```
+
+## 使用自定义 Webpack 配置
+
+`react-scripts-intlayer` 基于 [craco](https://craco.js.org/)，允许您自定义 Webpack 配置。
+如果您需要自定义 Webpack 配置，也可以基于 intlayer craco 插件实现自己的设置。[查看示例](https://github.com/aymericzip/intlayer/blob/main/examples/react-app/craco.config.js)。
+
+## 阅读完整的 Intlayer React Create App 指南
+
+Intlayer 提供了许多功能来帮助您国际化您的 React 应用程序。
+[查看如何在 React Create App 中使用 Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_with_create_react_app.md)。

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

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

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

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

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

@@ -0,0 +1,53 @@
+# vite-intlayer: 用于国际化 (i18n) Vite 应用的 NPM 包
+
+**Intlayer** 是专为 JavaScript 开发者设计的一套工具包。它兼容 React、React 和 Express.js 等框架。
+
+**`vite-intlayer` 包** 允许您对 Vite 应用进行国际化。它包括一个 Vite 插件，通过环境变量将配置设置到 [Vite 打包器](https://vitejs.dev/guide/why.html#why-bundle-for-production)。此外，它还提供中间件来检测用户的首选语言环境，并根据 [配置](https://github.com/aymericzip/intlayer/blob/main/docs/zh/configuration.md) 将用户重定向到适当的 URL。
+
+## 为什么要对 Vite 应用进行国际化？
+
+对 Vite 应用进行国际化对于有效服务全球用户至关重要。它使您的应用能够以每个用户的首选语言提供内容和消息。这种能力提升了用户体验，并通过使您的应用对不同语言背景的用户更具可访问性和相关性，从而扩大了应用的覆盖范围。
+
+## 配置
+
+`vite-intlayer` 包可以无缝地与 [`react-intlayer` 包](https://github.com/aymericzip/intlayer/blob/main/docs/zh/packages/react-intlayer/index.md) 和 [`intlayer` 包](https://github.com/aymericzip/intlayer/blob/main/docs/zh/packages/intlayer/index.md) 一起使用。有关更多信息，请参阅相关文档。
+
+## 安装
+
+使用您喜欢的包管理器安装必要的包：
+
+```bash packageManager="npm"
+npm install vite-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add vite-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add vite-intlayer
+```
+
+## 使用示例
+
+查看如何将插件包含到您的 Vite 配置中的示例。
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayerPlugin, intLayerMiddlewarePlugin } from "vite-intlayer";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [intlayerPlugin(), intLayerMiddlewarePlugin()],
+});
+```
+
+> `intlayerPlugin()` Vite 插件用于将 Intlayer 集成到 Vite 中。它确保内容声明文件的构建，并在开发模式下监视它们。它在 Vite 应用中定义 Intlayer 环境变量。此外，它还提供别名以优化性能。
+
+> `intLayerMiddlewarePlugin()` 为您的应用添加服务器端路由。此插件将根据 URL 自动检测当前语言环境并设置适当的语言环境 Cookie。如果未指定语言环境，插件将根据用户的浏览器语言偏好确定最合适的语言环境。如果未检测到语言环境，它将重定向到默认语言环境。
+
+## 掌握 Vite 应用的国际化
+
+Intlayer 提供了许多功能来帮助您对 Vite 应用进行国际化。
+
+**要了解更多这些功能，请参考 [使用 Intlayer 和 Vite 以及 React 进行国际化 (i18n)](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_with_vite+react.md) 的指南，适用于 Vite 和 React 应用。**

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

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

package/zh/per_locale_file.md

@@ -0,0 +1,298 @@
+# Intlayer 支持两种方式声明多语言内容：
+
+- 单文件包含所有翻译
+- 每种语言一个文件（每语言格式）
+
+这种灵活性使得：
+
+- 从其他 i18n 工具轻松迁移
+- 支持自动化翻译工作流
+- 将翻译清晰地组织到独立的、特定语言的文件中
+
+## 单文件包含多种翻译
+
+这种格式适合：
+
+- 在代码中快速迭代。
+- 与 CMS 无缝集成。
+
+这是大多数使用场景的推荐方法。它集中管理翻译，使得迭代和与 CMS 集成变得容易。
+
+```tsx fileName="hello-world.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const helloWorldContent = {
+  key: "hello-world",
+  content: {
+    multilingualContent: t({
+      zh: "我的组件标题",
+      en: "Title of my component",
+      es: "Título de mi componente",
+    }),
+  },
+} satisfies Dictionary;
+
+export default helloWorldContent;
+```
+
+```js fileName="hello-world.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const helloWorldContent = {
+  key: "hello-world",
+  content: {
+    multilingualContent: t({
+      zh: "我的组件标题",
+      en: "Title of my component",
+      es: "Título de mi componente",
+    }),
+  },
+};
+
+export default helloWorldContent;
+```
+
+```js fileName="hello-world.content.cjs" contentDeclarationFormat="json"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const helloWorldContent = {
+  key: "hello-world",
+  content: {
+    multilingualContent: t({
+      zh: "我的组件标题",
+      en: "Title of my component",
+      es: "Título de mi componente",
+    }),
+  },
+};
+
+module.exports = helloWorldContent;
+```
+
+```json fileName="hello-world.content.ts" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "hello-world",
+  "content": {
+    "multilingualContent": {
+      "nodeType": "translation",
+      "translation": {
+        "zh": "我的组件标题",
+        "en": "Title of my component",
+        "es": "Título de mi componente"
+      }
+    }
+  }
+}
+```
+
+> 推荐：当使用 Intlayer 的可视化编辑器或直接在代码中管理翻译时，这种格式是最佳选择。
+
+## 每语言格式
+
+这种格式适用于以下情况：
+
+- 您希望独立版本化或覆盖翻译。
+- 您正在集成机器或人工翻译工作流。
+
+您还可以通过指定 locale 字段将翻译拆分为单独的语言文件：
+
+```tsx fileName="hello-world.en.content.ts" contentDeclarationFormat="typescript"
+import { t, Locales, type Dictionary } from "intlayer";
+
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.ENGLISH, // 重要
+  content: { multilingualContent: "Title of my component" },
+} satisfies Dictionary;
+
+export default helloWorldContent;
+```
+
+```tsx fileName="hello-world.es.content.ts" contentDeclarationFormat="typescript"
+import { t, Locales, type Dictionary } from "intlayer";
+
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.SPANISH, // 重要
+  content: { multilingualContent: "Título de mi componente" },
+};
+```
+
+```js fileName="hello-world.en.content.mjs" contentDeclarationFormat="esm"
+import { t, Locales } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.ENGLISH, // 重要
+  content: { multilingualContent: "Title of my component" },
+};
+
+export default helloWorldContent;
+```
+
+```tsx fileName="hello-world.es.content.mjs" contentDeclarationFormat="esm"
+import { t, Locales } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.SPANISH, // 重要
+  content: { multilingualContent: "Título de mi componente" },
+};
+
+export default helloWorldContent;
+```
+
+```js fileName="hello-world.en.content.cjs" contentDeclarationFormat="commonjs"
+const { t, Locales } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.ENGLISH, // 重要
+  content: {
+    multilingualContent: "Title of my component",
+  },
+};
+
+module.exports = helloWorldContent;
+```
+
+```tsx fileName="hello-world.es.content.cjs" contentDeclarationFormat="commonjs"
+const { t, Locales } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.SPANISH, // 重要
+  content: {
+    multilingualContent: "Título de mi componente",
+  },
+};
+
+module.exports = helloWorldContent;
+```
+
+```json5 fileName="hello-world.en.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "hello-world",
+  "locale": "en", // 重要
+  "content": {
+    "multilingualContent": "Title of my component",
+  },
+}
+```
+
+```json5 fileName="hello-world.es.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "hello-world",
+  "locale": "es", // 重要
+  "content": {
+    "multilingualContent": "Título de mi componente",
+  },
+}
+```
+
+> 重要：确保定义了 locale 字段。它告诉 Intlayer 文件代表的语言。
+
+> 注意：在这两种情况下，内容声明文件必须遵循命名模式 `*.content.{ts,tsx,js,jsx,mjs,cjs,json}` 才能被 Intlayer 识别。`.[locale]` 后缀是可选的，仅用作命名约定。
+
+## 混合格式
+
+您可以为同一内容键混合使用这两种方法。例如：
+
+静态声明默认或基础内容（例如 `index.content.ts`）
+
+在 `index.content.json`、`index.fr.content.ts` 等中添加或覆盖特定语言的内容。
+
+这在以下情况下特别有用：
+
+- 您希望在代码库中静态声明基础内容，并通过 CMS 自动填充翻译。
+
+```bash codeFormat="typescript"
+.
+└── Components
+    └── MyComponent
+        ├── index.content.ts
+        ├── index.content.json
+        └── index.ts
+```
+
+### 示例
+
+以下是一个多语言内容声明文件：
+
+```tsx fileName="Components/MyComponent/index.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.ENGLISH,
+  content: {
+    multilingualContent: "Title of my component",
+    projectName: "My project",
+  },
+} satisfies Dictionary;
+
+export default helloWorldContent;
+```
+
+```json fileName="Components/MyComponent/index.content.json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "hello-world",
+  "content": {
+    "multilingualContent": {
+      "nodeType": "translation",
+      "translation": {
+        "zh": "我的组件标题",
+        "fr": "Titre de mon composant",
+        "es": "Título de mi componente"
+      }
+    }
+  }
+}
+```
+
+Intlayer 会自动合并多语言和每语言文件。
+
+```tsx fileName="Components/MyComponent/index.ts"
+import { getIntlayer, Locales } from "intlayer";
+
+const intlayer = getIntlayer("hello-world"); // 默认语言是 ENGLISH，因此它将返回 ENGLISH 内容
+
+console.log(JSON.stringify(intlayer, null, 2));
+// 结果：
+// {
+//  "multilingualContent": "Title of my component",
+//  "projectName": "My project"
+// }
+
+const intlayer = getIntlayer("hello-world", Locales.SPANISH);
+
+console.log(JSON.stringify(intlayer, null, 2));
+// 结果：
+// {
+//  "multilingualContent": "Título de mi componente",
+//  "projectName": "My project"
+// }
+
+const intlayer = getIntlayer("hello-world", Locales.FRENCH);
+
+console.log(JSON.stringify(intlayer, null, 2));
+// 结果：
+// {
+//  "multilingualContent": "Titre de mon composant",
+//  "projectName": "My project"
+// }
+```
+
+### 自动翻译生成
+
+使用 [intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_cli.md) 根据您首选的服务自动填充缺失的翻译。