@intlayer/docs 5.5.8

package/zh/dictionary/file.md

@@ -0,0 +1,209 @@
+# 文件内容 / 在 Intlayer 中嵌入文件
+
+## 文件嵌入的工作原理
+
+在 Intlayer 中，`file` 函数允许将外部文件内容嵌入到字典中。这种方法确保 Intlayer 识别源文件，从而实现与 Intlayer 可视化编辑器和 CMS 的无缝集成。与直接使用 `import`、`require` 或 `fs` 文件读取方法不同，使用 `file` 将文件与字典关联，使 Intlayer 能够在文件编辑时动态跟踪和更新内容。
+
+## 设置文件内容
+
+要在 Intlayer 项目中嵌入文件内容，请在内容模块中使用 `file` 函数。以下是展示不同实现方式的示例。
+
+### TypeScript 实现
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import { file, type Dictionary } from "intlayer";
+
+const myFileContent = {
+  key: "my_key",
+  content: {
+    myFile: file("./path/to/file.txt"),
+  },
+} satisfies Dictionary;
+
+export default myFileContent;
+```
+
+### ECMAScript 模块 (ESM) 实现
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+import { file } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const myFileContent = {
+  key: "my_key",
+  content: {
+    myFile: file("./path/to/file.txt"),
+  },
+};
+
+export default myFileContent;
+```
+
+### CommonJS 实现
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+const { file } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const myFileContent = {
+  key: "my_key",
+  content: {
+    myFile: file("./path/to/file.txt"),
+  },
+};
+
+module.exports = myFileContent;
+```
+
+### JSON 配置
+
+```json5 fileName="**/*.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "my_key",
+  "content": {
+    "myFile": {
+      "nodeType": "file",
+      "value": "./path/to/file.txt",
+    },
+  },
+}
+```
+
+## 在 React Intlayer 中使用文件内容
+
+要在 React 组件中使用嵌入的文件内容，请从 `react-intlayer` 包中导入并使用 `useIntlayer` 钩子。此钩子从指定的键中检索内容，并允许动态显示。
+
+```tsx fileName="**/*.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+const FileComponent: FC = () => {
+  const { myFile } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <pre>{myFile}</pre>
+    </div>
+  );
+};
+
+export default FileComponent;
+```
+
+```javascript fileName="**/*.mjx" codeFormat="esm"
+import { useIntlayer } from "react-intlayer";
+
+const FileComponent = () => {
+  const { myFile } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <pre>{myFile}</pre>
+    </div>
+  );
+};
+
+export default FileComponent;
+```
+
+```javascript fileName="**/*.cjs" codeFormat="commonjs"
+const { useIntlayer } = require("react-intlayer");
+
+const FileComponent = () => {
+  const { myFile } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <pre>{myFile}</pre>
+    </div>
+  );
+};
+
+module.exports = FileComponent;
+```
+
+## 多语言 Markdown 示例
+
+要支持多语言可编辑的 Markdown 文件，可以将 `file` 与 `t()` 和 `md()` 结合使用，以定义 Markdown 内容文件的不同语言版本。
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import { file, t, md, type Dictionary } from "intlayer";
+
+const myMultilingualContent = {
+  key: "my_multilingual_key",
+  content: {
+    myContent: md(
+      t({
+        zh: file("src/components/test.zh.md"),
+        en: file("src/components/test.en.md"),
+        fr: file("src/components/test.fr.md"),
+        es: file("src/components/test.es.md"),
+      })
+    ),
+  },
+} satisfies Dictionary;
+
+export default myMultilingualContent;
+```
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+import { file, t, md } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const myMultilingualContent = {
+  key: "my_multilingual_key",
+  content: {
+    myContent: md(
+      t({
+        zh: file("src/components/test.zh.md"),
+        en: file("src/components/test.en.md"),
+        fr: file("src/components/test.fr.md"),
+        es: file("src/components/test.es.md"),
+      })
+    ),
+  },
+};
+
+export default myMultilingualContent;
+```
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+const { file, t, md } = require("intlayer");
+
+const myMultilingualContent = {
+  key: "my_multilingual_key",
+  content: {
+    myContent: md(
+      t({
+        zh: file("src/components/test.zh.md"),
+        en: file("src/components/test.en.md"),
+        fr: file("src/components/test.fr.md"),
+        es: file("src/components/test.es.md"),
+      })
+    ),
+  },
+};
+```
+
+此设置允许根据用户的语言偏好动态检索内容。当在 Intlayer 可视化编辑器或 CMS 中使用时，系统将识别内容来自指定的 Markdown 文件，并确保它们保持可编辑。
+
+## Intlayer 如何处理文件内容
+
+`file` 函数基于 Node.js 的 `fs` 模块读取指定文件的内容并将其插入到字典中。当与 Intlayer 可视化编辑器或 CMS 一起使用时，Intlayer 可以跟踪字典与文件之间的关系。这使得 Intlayer 能够：
+
+- 识别内容来源于特定文件。
+- 在链接文件被编辑时自动更新字典内容。
+- 确保文件与字典之间的同步，保持内容的完整性。
+
+## 其他资源
+
+有关在 Intlayer 中配置和使用文件嵌入的更多详细信息，请参考以下资源：
+
+- [Intlayer CLI 文档](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_cli.md)
+- [React Intlayer 文档](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_with_create_react_app.md)
+- [Next Intlayer 文档](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_with_nextjs_15.md)
+- [Markdown 内容文档](https://github.com/aymericzip/intlayer/blob/main/docs/zh/dictionary/markdown.md)
+- [翻译内容文档](https://github.com/aymericzip/intlayer/blob/main/docs/zh/dictionary/translation.md)
+
+这些资源提供了有关文件嵌入、内容管理以及 Intlayer 与各种框架集成的更多见解。

package/zh/dictionary/function_fetching.md

@@ -0,0 +1,188 @@
+# 函数获取
+
+Intlayer 允许您在内容模块中声明内容函数，这些函数可以是同步的或异步的。当应用程序构建时，Intlayer 执行这些函数以获取函数的结果。返回值必须是一个 JSON 对象或一个简单的值，例如字符串或数字。
+
+> 警告：函数获取目前不支持 JSON 内容声明和远程内容声明文件。
+
+## 函数声明
+
+以下是一个简单的同步函数获取内容的示例：
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import type { Dictionary } from "intlayer";
+
+const functionContent = {
+  key: "function_content",
+  content: {
+    text: () => "这是由函数渲染的内容",
+  },
+} satisfies Dictionary;
+
+export default functionContent;
+```
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+/** @type {import('intlayer').Dictionary} */
+const functionContent = {
+  key: "function_content",
+  content: {
+    text: () => "这是由函数渲染的内容",
+  },
+};
+
+export default functionContent;
+```
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+/** @type {import('intlayer').Dictionary} */
+const functionContent = {
+  key: "function_content",
+  content: {
+    text: () => "这是由函数渲染的内容",
+  },
+};
+
+module.exports = functionContent;
+```
+
+```json fileName="**/*.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "function_content",
+  "content": {
+    "text": "这是由函数渲染的内容"
+  }
+}
+```
+
+在此示例中，`text` 键包含一个返回字符串的函数。可以使用 Intlayer 的解释器包（如 `react-intlayer`）在 React 组件中渲染此内容。
+
+## 异步函数获取
+
+除了同步函数，Intlayer 还支持异步函数，允许您从外部来源获取数据或使用模拟数据模拟数据检索。
+
+以下是一个模拟服务器获取的异步函数示例：
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import { setTimeout } from "node:timers/promises";
+import type { Dictionary } from "intlayer";
+
+const fakeFetch = async (): Promise<string> => {
+  // 等待 200 毫秒以模拟从服务器获取数据
+  return await setTimeout(200).then(() => "这是从服务器获取的内容");
+};
+
+const asyncFunctionContent = {
+  key: "async_function",
+  content: { text: fakeFetch },
+} satisfies Dictionary;
+
+export default asyncFunctionContent;
+```
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+import { setTimeout } from "node:timers/promises";
+
+/** @type {import('intlayer').Dictionary} */
+const fakeFetch = async () => {
+  // 等待 200 毫秒以模拟从服务器获取数据
+  await setTimeout(200);
+  return "这是从服务器获取的内容";
+};
+
+const asyncFunctionContent = {
+  key: "async_function",
+  content: { text: fakeFetch },
+};
+
+export default asyncFunctionContent;
+```
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+const { setTimeout } = require("node:timers/promises");
+
+/** @type {import('intlayer').Dictionary} */
+const fakeFetch = async () => {
+  // 等待 200 毫秒以模拟从服务器获取数据
+  await setTimeout(200);
+  return "这是从服务器获取的内容";
+};
+
+const asyncFunctionContent = {
+  key: "async_function",
+  content: { text: fakeFetch },
+};
+
+module.exports = asyncFunctionContent;
+```
+
+```plaintext fileName="**/*.content.json" contentDeclarationFormat="json"
+无法从 JSON 文件中获取内容，请改用 .ts 或 .js 文件
+```
+
+在这种情况下，`fakeFetch` 函数模拟了一个延迟以模拟服务器响应时间。Intlayer 执行异步函数并将结果用作 `text` 键的内容。
+
+## 在 React 组件中使用基于函数的内容
+
+要在 React 组件中使用基于函数的内容，您需要从 `react-intlayer` 导入 `useIntlayer` 并通过内容 ID 调用它以检索内容。以下是一个示例：
+
+```typescript fileName="**/*.jsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+const MyComponent: FC = () => {
+  const functionContent = useIntlayer("function_content");
+  const asyncFunctionContent = useIntlayer("async_function_content");
+
+  return (
+    <div>
+      <p>{functionContent.text}</p>
+      {/* 输出：这是由函数渲染的内容 */}
+      <p>{asyncFunctionContent.text}</p>
+      {/* 输出：这是从服务器获取的内容 */}
+    </div>
+  );
+};
+
+export default MyComponent;
+```
+
+```javascript fileName="**/*.mjx" codeFormat="esm"
+import { useIntlayer } from "react-intlayer";
+
+const MyComponent = () => {
+  const functionContent = useIntlayer("function_content");
+  const asyncFunctionContent = useIntlayer("async_function_content");
+
+  return (
+    <div>
+      <p>{functionContent.text}</p>
+      {/* 输出：这是由函数渲染的内容 */}
+      <p>{asyncFunctionContent.text}</p>
+      {/* 输出：这是从服务器获取的内容 */}
+    </div>
+  );
+};
+
+export default MyComponent;
+```
+
+```javascript fileName="**/*.cjs" codeFormat="commonjs"
+const { useIntlayer } = require("react-intlayer");
+
+const MyComponent = () => {
+  const functionContent = useIntlayer("function_content");
+  const asyncFunctionContent = useIntlayer("async_function_content");
+
+  return (
+    <div>
+      <p>{functionContent.text}</p>
+      {/* 输出：这是由函数渲染的内容 */}
+      <p>{asyncFunctionContent.text}</p>
+      {/* 输出：这是从服务器获取的内容 */}
+    </div>
+  );
+};
+
+module.exports = MyComponent;
+```