From 404916636e1adda57c003135a9673d751f6669fe Mon Sep 17 00:00:00 2001 From: y2-Whyto Date: Mon, 11 Jul 2022 22:10:39 +0800 Subject: [PATCH 001/112] =?UTF-8?q?Revert=20"Revert=20"/contribute/docs/do?= =?UTF-8?q?cument-standards.md=20=E7=BF=BB=E8=AF=91=E6=8F=90=E4=BA=A4""?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This reverts commit fd4f9817f2b318c416c1cc2e233ffffcff58a4d5. --- contribute/docs/documentation-standards.md | 268 +++++++++++++++++++++ 1 file changed, 268 insertions(+) create mode 100644 contribute/docs/documentation-standards.md diff --git a/contribute/docs/documentation-standards.md b/contribute/docs/documentation-standards.md new file mode 100644 index 00000000..dc320384 --- /dev/null +++ b/contribute/docs/documentation-standards.md @@ -0,0 +1,268 @@ + +# 文档标准概述 + + +本文档概述了 Fuchsia 文档的标准、结构、语言风格和最佳做法。 + + +## 文档位置 + + + * **为开发 Fuchsia 具体特性的专门文档：** + 针对开发者创建或维护 Fuchsia 代码库特定部分的文档，应当和源代码保存在同一目录下。这类文档通常以 `README.md` 文件的形式嵌入在 Fuchsia 代码库中。 + + * **面向 Fuchsia 开发者的总体文档：** Fuchsia 文档应当创建在 /HEAD/docs/ 中. + 在 `/docs/` 目录下，您应当在以下子目录之一内创建文档： + + * get-started: + + 有关下载、设置、开始 Fuchsia 开发的具体指南应当放进 `/get-started`。这类内容应当包含观点明确的、简短的教程，以帮助新用户入门 Fuchsia，并在 Fuchsia.dev 中链接至附加文档。 + * development: + + `/development/` 目录（在网站上显示为“指南”（Guides））中包含了针对Fuchsia开发者的说明和教程。该目录包含关于如何构建、运行和测试 Fuchsia 的文档。 + * concepts: + + `/concepts` 目录包含针对 Fuchsia 具体特性及其工作原理的深入解释，包括操作系统概述、框架、架构和软件包（package）。 + * reference: + + `/reference/` 目录包含生成的关于 Fuchsia 工具和 API 的参考文档，包括 FIDL 和内核的参考文档。 + * contribute: + + `/contribute/` 目录包含代码和文档贡献进度以及最佳做法，包含文档准则和风格指南、代码策略以及管理体系。 + * `images` + + `/images/` 目录包含在文档中使用的图像。您应当将图像放在这一公共目录中。 + + + + +大多数文档可以分为以下几类： + + +- [程序性的](documentation-types.md#procedural-documentation) + - 入门 - 初始设置的文档 + - 指南 - 任务导向的文档 + + +- [概念性的](documentation-types.md#conceptual-documentation) - 多侧重于教授 Fuchsia，Fuchsia 架构和 Fuchsia 组件的基础性文档 + + +- [参考文档](documentation-types.md#reference-documentation) - 侧重于详细说明 Fuchsia API 和 工具的语法和参数的文档。这类文档通常自动生成。 + + +要获取更多信息，请参阅[文档类型](documentation-types.md)。 + + +## 文档和代码风格指南 + + +为确保由大量贡献者创建的文档都保持一致性，遵循文档风格指南很重要。要获取具体文档指导，请参阅[文档风格指南](documentation-style-guide.md)；要获取代码样例指导，请参阅[代码样例风格指南](code-sample-style-guide.md)。 + + + +## 搜索的最佳做法 + +文档只有在用户能查到的时候才算有用。下面是一些关于可查性和搜索的最佳做法： + + - 将您的文档添加至目录：在 fuchsia.dev 的左侧导航中添加文档链接。要获取更多信息，请参阅[网站导航和目录文件](documentation-navigation-toc.md) + +- 交叉链接文档：添加指向文档主题的链接，以帮助读者更好地理解文档的内容。 例如，[Fuchsia 模拟器] (/development/build/emulator.md) 的概念文档链接到有关 Fuchsia 模拟器的相关指南和入门文档。 + +- 使用一致的术语：如果您在撰写有关 Fuchsia 中特定概念的文章，请确认您使用的是一致的术语。 使用[术语表](/glossary/README.md)来验证用语。 + + +## 文档的文件格式和文件名 + + +Fuchsia 的所有文档均使用 Markdown（`.md`）撰写，Fuchsia.dev 使用 [Hoedown Markdown Parser](https://github.com/hoedown/hoedown)。 + + +该网站的导航是由 `_toc.yaml` 文件配置的，该文件包含在每个文档目录中。请使用[网站导航和目录文件](documentation-navigation-toc.md)中的指导来更新这些文件。 + + +文件和目录名应当为小写，并使用短横线（hyphen）而非下划线（underscore）来分隔单词。在文件或目录名中请仅使用标准 ASCII 字母数字字符。如果文件名包含带有下划线的命令，那么您可以加入下划线。 + + +## 语言风格总体指导 + + +- **使用简单的美国英语撰写。** 使用清晰、直白的美国英语撰写，以使内容易于理解。使用简单的词汇，保持简洁使用（常见）缩写，如 _it's_ 或 _don't_。 + +- **心怀敬意。** 请遵循[尊重性规范](/contribute/respectful_code.md)中规定的方针。 + +- **使用第二人称（“you”）撰写。** Fuchsia文档是写给用户（“you”）的。例如，“您（you）可以通过以下步骤安装 Fuchsia……”。不要使用第三人称称呼读者（“Fuchsia 用户可以通过……安装 Fuchsia”）或使用“we”（“我们（we）可以通过……安装 Fuchsia”）。 + +- **使用现在时态撰写。** 请在记录系统时始终立足眼下（it is），而非未来（it will be）。类似“will”之类的词语非常含糊。例如“您将看到”这种说法将引起如“我何时将会看到？”之类的问题。1分钟，还是20分钟呢？另外，若非必要，请不要提及未来的产品特性。提及可能取消的未来计划将导致维护上的困难。 + +- **保持语句简短具体。**使用标点符号可以便于您的读者跟进说明、理解概念。而且，短句更易于翻译。 + +- **了解您的受众群体。** 在撰写文档之前，请确定好您的受众群体。了解受众群体使您能够明确他们应当熟悉的概念。当撰写面向更高级受众群体的文档时，请在文档前声明，让用户了解这一前提后，再进行阅读。 + +- **使用主动语态。** 请尽可能使用主动语态写作，因为被动语态会使句子模棱两可且难以理解。 下面是一个例子： + - 主动语态：“操作系统运行一个进程。”（The operating system runs a process.）在这种情况下，主语执行动词表示的动作。 + - 被动语态：“一个进程正在被运行。”（A process is being run.）主语不再是“主动的”（_active_），而是被动词作用——它是“被动的”（_passive_）。 + 大多数情况下，如果您使用了“by”，那么您的句子可能仍然是被动语态。 + + +- **若使用首字母缩写词，请您在第一次书写时进行定义。** 例如，looks good to me（LGTM，我觉得看起来很好）。不要认为每个人都理解所有的首字母缩写词。您不需要定义工业标准首字母缩写词，如 TCP/IP。 + + +- **定义技术术语，回避行话。** Fuchsia 文档应当易于各个层次的开发者理解。请避免使用不常用或高度技术性词语而使得文章过于复杂。如果您使用了 Fuchsia 特定的术语，请在[术语表](/glossary/README.md)中对其进行定义。请回避自造词。 + + +- **回避口头表达或地区习语。** 请记住，许多 Fuchsia 用户并非英语母语者。请避免使用难于翻译的习语，例如“that's the way the cookie crumbles.”（生米已成熟饭/覆水难收）虽然对您而言能够理解，但是很难准确地翻译到其他语言中。 + + +- **避免引用专有信息。** 这里指的是任何可能是已注册商标的任何潜在词语或您公司的任何内部信息（API 密钥、机器名等）。 + + +- **使用性别中立代词。** 请不要使用 _he_，_him_，_his_，_she_ 或 _her_，也不要使用 _he/she_ 或 _(s)he_ 等其他类似的符号表达方式。取而代之，请使用单数的 _they_。 + + +- **使用一致的术语。**确保术语在代码、用户界面和文档中是一致的。尽可能使用常见术语，并使用[术语表](/glossary/README.md)来验证用语。 From d9d7adbf435283284dead8e951e0f9f1a6bfba75 Mon Sep 17 00:00:00 2001 From: y2-Whyto Date: Mon, 11 Jul 2022 22:13:03 +0800 Subject: [PATCH 002/112] Update documentation-standards.md --- contribute/docs/documentation-standards.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contribute/docs/documentation-standards.md b/contribute/docs/documentation-standards.md index dc320384..f9f36280 100644 --- a/contribute/docs/documentation-standards.md +++ b/contribute/docs/documentation-standards.md @@ -202,7 +202,7 @@ contains a command with an underscore, then you can include the underscore. - **Keep sentences short and concrete.** Using punctuation allows your reader to follow instructions and understand concepts. Also, short sentences are easier to translate. --> -- **保持语句简短具体。**使用标点符号可以便于您的读者跟进说明、理解概念。而且，短句更易于翻译。 +- **保持语句简短具体。** 使用标点符号可以便于您的读者跟进说明、理解概念。而且，短句更易于翻译。 -- **使用一致的术语。**确保术语在代码、用户界面和文档中是一致的。尽可能使用常见术语，并使用[术语表](/glossary/README.md)来验证用语。 +- **使用一致的术语。** 确保术语在代码、用户界面和文档中是一致的。尽可能使用常见术语，并使用[术语表](/glossary/README.md)来验证用语。 From 1c34d409cce87b76a8b458a7ee3c346cf3fcbd92 Mon Sep 17 00:00:00 2001 From: y2-Whyto Date: Tue, 12 Jul 2022 23:17:31 +0800 Subject: [PATCH 004/112] =?UTF-8?q?=E4=BF=AE=E6=AD=A3=E7=AC=94=E8=AF=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- contribute/docs/documentation-standards.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/contribute/docs/documentation-standards.md b/contribute/docs/documentation-standards.md index c6c9c8be..2e3783e3 100644 --- a/contribute/docs/documentation-standards.md +++ b/contribute/docs/documentation-standards.md @@ -90,7 +90,7 @@ Most documentation can be divided into the following categories: -- [概念性的](documentation-types.md#conceptual-documentation) - 多侧重于教授 Fuchsia，Fuchsia 架构和 Fuchsia 组件的基础性文档 +- [概念性的](documentation-types.md#conceptual-documentation) - 多侧重于教授 Fuchsia、Fuchsia 架构和 Fuchsia 组件的基础性文档 -- **使用简单的美国英语撰写。** 使用清晰、直白的美国英语撰写，以使内容易于理解。使用简单的词汇，保持简洁使用（常见）缩写，如 _it's_ 或 _don't_。 +- **使用简单的美国英语撰写。** 使用清晰、直白的美国英语撰写，以使内容易于理解。请使用简单的词汇，保持简洁，并使用（常见）缩写，如 _it's_ 或 _don't_。 @@ -220,7 +220,7 @@ contains a command with an underscore, then you can include the underscore. In most cases, if you use "by" this indicates that your sentence might be still be in passive voice. --> -- **使用主动语态。** 请尽可能使用主动语态写作，因为被动语态会使句子模棱两可且难以理解。 下面是一个例子： +- **使用主动语态。** 请尽量使用主动语态写作，因为被动语态会使句子模棱两可且难以理解。 下面是一个例子： - 主动语态：“操作系统运行一个进程。”（The operating system runs a process.）在这种情况下，主语执行动词表示的动作。 - 被动语态：“一个进程正在被运行。”（A process is being run.）主语不再是“主动的”（_active_），而是被动词作用——它是“被动的”（_passive_）。 大多数情况下，如果您使用了“by”，那么您的句子可能仍然是被动语态。 From 619ee43565d984429af7a0cbccf25fc0c723ad56 Mon Sep 17 00:00:00 2001 From: y2-Whyto Date: Wed, 13 Jul 2022 19:14:16 +0800 Subject: [PATCH 005/112] =?UTF-8?q?/contribute/docs/documentation-style-gu?= =?UTF-8?q?ide.md=20=E7=BF=BB=E8=AF=91=E5=AE=8C=E6=88=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- contribute/docs/documentation-style-guide.md | 196 ++++++++++++++++++- 1 file changed, 195 insertions(+), 1 deletion(-) diff --git a/contribute/docs/documentation-style-guide.md b/contribute/docs/documentation-style-guide.md index 4c182bb5..9f4f846a 100644 --- a/contribute/docs/documentation-style-guide.md +++ b/contribute/docs/documentation-style-guide.md @@ -1,13 +1,23 @@ + +# 文档风格指南 + +本文档给出了针对 Fuchsia.dev 写作风格的指南。这些方针基于[Google 开发者风格指南][google-dev-doc-style-guide]中的通用指导。 + +注意：本指南重点介绍了为 Fuchsia 编写文档的一些最佳做法。其中的某些主题在以下文档的资源中可能会得到更为广泛的探讨： + +* 要获取关于通用文档标准的信息，包括文件类型、位置和整体语言风格，请参阅 [Fuchsia 文档标准][doc-standard]。 +* 要获取关于措辞、风格和结构的具体指导，请参阅 [Fuchsia 文档风格指南][style-guide]。 + +## 文字和链接 + +### 遵循 80 字符限制 + +在 Fuchsia 项目中，代码的行最大长度为 100 字符，而文档的行最大长度为 80 字符。该规则一个值得注意的例外情况是 URL（即链接），写在一行中，不换行。 + +代码常使用缩进（页面左侧的空格），而英文散文（文档）多形成文字段落。这种差异导致了不同的宽度规格。 + +### 标记外部链接 + +请使用 `{:.external}` 标记任何不属于 `fuchsia.dev`、 +`fuchsia.googlesource.com` 或 `fuchsia-review.googlesource.com` 的链接： + +```none +这是一个[外部](http://example.com){:.external}链接。 ``` + +注意外部链接标志：这是一个[外部][external-link-example]{:.external}链接。 + +### 使用参考风格的链接 + +一般来说，Fuchsia 建议在 Markdown 文件中使用参考风格（reference-style）的链接。 参考风格链接使用与链接相关联的参考标识符，接下来每当您在文档中使用该链接时，即可引用该标识符。这使得文档中的链接易于更新。 + +推荐：请在您需要链接的位置创建标识符。 + + +本例中，链接标识符称为 `fuchsia-home`： + +```none +欢迎来到 [Fuchsia 首页][fuchsia-home]。 ``` + + +接着在文档底部对其定义： + 
[fuchsia-home]: https://fuchsia.dev/
+ + +不推荐：编写如下的行内链接： + +```none +欢迎来到 [Fuchsia 首页](www.fuchsia.dev)。 +``` + +您可以在外部的 [Markdown 指南][markdown-reference-links]中阅读更多与参考风格链接有关的信息。 + +### 对不同的 Fuchsia 内容使用正确链接 + +在 Fuchsia 文档中您可以为三类内容添加链接： + +* `/docs/` - 链接至位于 Fuchsia 源树中 `/docs/` 目录内的文档。这些链接必须关联到具有 `.md` 扩展名的文件。例如，`/concepts/README.md`。 +* 源代码 - 链接至位于 Fuchsia 源树中的源代码文件。这些链接可以关联到任何文件扩展名，但这些文件必须存在于源树中。例如，`/src/sys/sysmgr/main.cc`。 +* 参考文档 - 链接至自动生成的 Fuchsia 参考文档。 + * 大多数 Fuchsia 参考文档不存在于源树内，但在 [fuchsia.dev][fuchsia-dev] 上发布了。这些链接必须使用完整形式的 URL。例如，`https://fuchsia.dev/reference/fidl/fuchsia.io`。 + * 不过，一些 Fuchsia 参考文档存在于源树内。这些文档位于 `/reference/`，并在 `https://fuchsia.dev/fuchsia-src/reference/` 中发布。这些链接必须关联到具有 `.md` 扩展名的文件。例如，`/reference/syscalls/bti_create.md`。 + + +### 测试您的链接后再提交更改 + +一旦创建了有效的 markdown 文件，您应当运行 `doc-checker` 以确保您的文件使用了有效的链接。当您试图提交包含 `.md` 文件的更改时，Gerrit 会运行 `doc-checker`，并会在您的提交中含有损坏链接时进行阻止。 + +要在本地运行 `doc-checker`，请使用 `fx format-code` 工具： ```posix-terminal fx format-code ``` + +## 标头（header） + +### 为页面和章节标题使用句首字母大写格式（sentence case） + +推荐：使用句首字母大写格式（sentence case）： ```none # This title is an example of sentence case ``` + +不推荐：使用标题词首大写格式（title case）： ```none # This Title is an Example of Title Case ``` + +### 为锚点使用连接号（dash），不要使用下划线 + +默认情况下，`fuchsia.dev` 创建锚点时会在在空格处使用下划线（`_`）。不过，当引用一个页面中的章节时，请使用连接号（`-`，dash），使用 `{#section-title}`。同样地，请在文件名中使用连接号。 + +推荐：为锚点使用连接号 + +```none + ## 这是一个章节标题 {#this-is-a-section-header} +``` + +## 代码样例 + +### 为 shell 命令样例使用 posix-terminal 格式化 + +推荐：为 shell 命令在 ``` 后添加 `posix-terminal` 能让读者更容易复制代码块中的内容。 + 
 ```posix-terminal
@@ -149,66 +282,127 @@ fx ota
 ```
+ +该代码块在渲染时，命令前会添加 `$`： ```posix-terminal fx ota ``` + +不推荐：请勿在命令前硬编码一个 `$` 符号。 ```sh $ fx ota ``` + +### 使用 none 以禁用复制功能 + +推荐：对于不需要读者复制内容的代码或输出样例，请在 ``` 后添加 `none {:.devsite-disable-click-to-copy}`。 + +
+```none {:.devsite-disable-click-to-copy}
+$ my_command
+不必复制和粘贴该代码块。
+```
+ +该代码块在渲染时，右上角没有复制标志： + + ```none {:.devsite-disable-click-to-copy} +$ my_command +不必复制和粘贴该代码块。 ``` + +不推荐：为只需查看的内容启用复制功能。如果您在 ``` 之后不指定任何内容，那么复制功能默认是启用的。 + +
+```
+$ my_command
+不必复制和粘贴该代码块。
+```
+ +该代码块渲染为如下形式： + +``` +$ my_command +不必复制和粘贴该代码块。 ``` + +### 引用源代码时使用路径，不要使用 URL + +推荐：任何引用源代码的链接应当仅使用路径指代。否则您将收到静态错误检查（static error check）。 + +
+更新[状态标头][sh]
+[sh]: /zircon/system/ulib/inspect/include/lib/inspect/cpp/vmo/state.h
@@ -220,4 +414,4 @@ Update the [state header][sh] [google-dev-doc-style-guide]: https://developers.google.com/style [markdown-reference-links]: /contribute/docs/markdown.md [external-link-example]: http://example.com -[fuchsia-dev]: https://fuchsia.dev \ No newline at end of file +[fuchsia-dev]: https://fuchsia.dev From 3a4c0b977df84198f1b351da70b8c208cebc1cff Mon Sep 17 00:00:00 2001 From: Xyct <87l46110@gmail.com> Date: Wed, 20 Jul 2022 00:33:50 +0800 Subject: [PATCH 006/112] =?UTF-8?q?=E7=BF=BB=E8=AF=91=20=5Fcommon/intro/?= =?UTF-8?q?=5Fzircon=5Fsyscall.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- get-started/_common/intro/_zircon_syscall.md | 46 ++++++++++++++++++-- 1 file changed, 42 insertions(+), 4 deletions(-) diff --git a/get-started/_common/intro/_zircon_syscall.md b/get-started/_common/intro/_zircon_syscall.md index 0cfc85f5..8fdc6512 100644 --- a/get-started/_common/intro/_zircon_syscall.md +++ b/get-started/_common/intro/_zircon_syscall.md @@ -1,47 +1,85 @@ -## System calls + +## 系统调用 + +用户空间代码使用**系统调用**与内核空间对象交互。Zircon 的系统调用用来执行低层操作，如： + +* 内存管理 +* 任务和进程管理 +* 进程间通信（IPC）与同步 +* 异常处理 +* 硬件支持服务（时钟，熵，设备 I/O） + + + +用户空间进程通过 `libzircon.so` 访问系统调用，这是一个 +[虚拟动态共享对象（virtual Dynamic Shared Object，vDSO）][glossary.virtual-dynamic-shared-object]。 +Zircon vDSO 是 ELF 格式的共享库，它被内核映射到每个新进程的地址空间。 +这个库被称为“虚拟”，是因为它是直接由内核映像暴露，而非从文件加载的。 + +大多数系统调用直接操作一个或多个[句柄][glossary.handle]。 +句柄是进程内部对内核空间对象的引用，表示为32位整数（`zx_handle_t`）。 +每个句柄声明了持有者具有的对句柄自身或引用的对象执行操作的特权，即**权利**（right）。 From 68aca6594deecd9c334b465219bbcc323b401202 Mon Sep 17 00:00:00 2001 From: Xyct <87l46110@gmail.com> Date: Wed, 20 Jul 2022 23:59:22 +0800 Subject: [PATCH 007/112] Update get-started/_common/intro/_zircon_syscall.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 修正“两个‘用’字连着” --- get-started/_common/intro/_zircon_syscall.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/get-started/_common/intro/_zircon_syscall.md b/get-started/_common/intro/_zircon_syscall.md index 8fdc6512..c7128a2a 100644 --- a/get-started/_common/intro/_zircon_syscall.md +++ b/get-started/_common/intro/_zircon_syscall.md @@ -6,7 +6,7 @@ User space code interacts with the objects in kernel space using **system calls**. Zircon has system calls to perform low-level operations such as: --> -用户空间代码使用**系统调用**与内核空间对象交互。Zircon 的系统调用用来执行低层操作，如： +用户空间代码使用**系统调用**与内核空间对象交互。Zircon 有执行低层操作的系统调用，如： -## 文档位置 +## 文档定位 - `/reference/` 目录包含生成的关于 Fuchsia 工具和 API 的参考文档，包括 FIDL 和内核的参考文档。 + `/reference/` 目录包含自动生成的关于 Fuchsia 工具和 API 的参考文档，包括 FIDL 和内核的参考文档。 * contribute: - `/contribute/` 目录包含代码和文档贡献进度以及最佳做法，包含文档准则和风格指南、代码策略以及管理体系。 + `/contribute/` 目录包含代码和文档的贡献进度以及最佳做法，包含文档准则和风格指南、代码策略以及管理体系。 * `images` +## 文档类型 -文件和目录名应当为小写，并使用短横线（hyphen）而非下划线（underscore）来分隔单词。在文件或目录名中请仅使用标准 ASCII 字母数字字符。如果文件名包含带有下划线的命令，那么您可以加入下划线。 +文件和目录名应当为小写，并使用短横线（hyphen）而非下划线（underscore）来分隔单词。在文件或目录名中请仅使用标准 ASCII 字母数字字符。如果文件名包含带有下划线的命令，那么您可以包含下划线。 -- **使用简单的美国英语撰写。** 使用清晰、直白的美国英语撰写，以使内容易于理解。请使用简单的词汇，保持简洁，并使用（常见）缩写，如 _it's_ 或 _don't_。 +- **使用通俗易懂的美国英语撰写。** 使用清晰、直白的美国英语撰写，以使内容易于理解。请使用简单的词汇，保持简洁，并使用（常见）缩写，如 _it's_ 或 _don't_。 From a71d3824ae2e7ac1cb762289f31be59a67029c08 Mon Sep 17 00:00:00 2001 From: y2-Whyto Date: Thu, 21 Jul 2022 14:53:44 +0800 Subject: [PATCH 014/112] Update documentation-standards.md --- contribute/docs/documentation-standards.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contribute/docs/documentation-standards.md b/contribute/docs/documentation-standards.md index 19e3f7d8..fa9319c3 100644 --- a/contribute/docs/documentation-standards.md +++ b/contribute/docs/documentation-standards.md @@ -155,7 +155,7 @@ include the following: All documentation for Fuchsia is written in Markdown (`.md`), and Fuchsia.dev uses the [Hoedown Markdown Parser](https://github.com/hoedown/hoedown). --> -Fuchsia 的所有文档均使用 Markdown（`.md`）撰写，Fuchsia.dev 使用 [Hoedown Markdown Parser](https://github.com/hoedown/hoedown)。 +Fuchsia 的所有文档均使用 Markdown（`.md`）撰写，Fuchsia.dev 使用 [Hoedown Markdown Parser](https://github.com/hoedown/hoedown) 作为 Markdown 文档语法分析器。 +## 沙箱化（sandboxing） + +当一个新进程被创建时，它没有任何能力。 +进程完全依赖于其创建者通过传给它的那些[句柄][glossary.handle]来提供能力。 +我们也可以说，空进程没有**环境权限**（ambient authority）。 + +因此，进程被创建时通常被赋予一些初始资源和能力。 +`fuchsia.process.Launcher` 协议提供了从一个可执行文件和一组内核对象句柄来在系统上创建新进程的低级接口。 +大多数软件使用组件框架，它简化了创建一个有一组标准的初始能力的新进程来执行一些代码的工作。 +您将在稍后更详细地探索组件。 - + +

一些给予进程的初始句柄是被进程挂载到**命名空间**（namespace）中的目录。

[glossary.handle]: /glossary/README.md#handle \ No newline at end of file From 03bee084b8250143ad547caae31db72fb0e37dd2 Mon Sep 17 00:00:00 2001 From: wy Date: Thu, 21 Jul 2022 22:34:28 +0800 Subject: [PATCH 016/112] translate build_fuchsia.md --- get-started/build_fuchsia.md | 197 ++++++++++++++++++++++++++--------- 1 file changed, 149 insertions(+), 48 deletions(-) diff --git a/get-started/build_fuchsia.md b/get-started/build_fuchsia.md index 7e66e119..4cc57f5c 100644 --- a/get-started/build_fuchsia.md +++ b/get-started/build_fuchsia.md @@ -1,167 +1,268 @@ -# Configure and build Fuchsia {#configure-and-build-fuchsia} + +# 配置和编译 Fuchsia {#configure-and-build-fuchsia} +这篇文档将引导你在主机上如何配置并编译 Fuchsia。 + +步骤如下： + +1. [准备](#prerequisites) +1. [配置设置项](#set-your-build-configuration) +1. [编译调优（可选）](#speed-up-the-build) +1. [编译](#build-fuchsia) + +## 1. 准备 {#prerequisites} + +在开始之前，先检查是否满足如下要求： + +* [准备源码](#source-code-setup) +* [硬件要求](#hardware-requirements) + +### 准备源码 {#source-code-setup} + +根据文档 [下载 Fuchsia 源码](/get-started/get_fuchsia_source.md) 指示下载 Fuchsia 的源码，然后在你的机器上设置开发环境。 + +### 硬件要求 {#hardware-requirements} + +Fuchsia 的编译支持如下架构的机器： + +- x86-64 Linux (只支持 Debian 系列的) +- x86-64 macOS + +注意：Windows 和 ARM64 是不支持的。 + +## 2. 配置设置项 {#set-your-build-configuration} + +Fuchsia 的编译设置项告诉编译系统如何编译，以及编译什么架构的文件。 + +设置你的 Fuchsia 编译选项，可以运行 [`fx set`][fx-set-reference] 命令： ```posix-terminal fx set {{ '' }}PRODUCT{{ '' }}.{{ '' }}BOARD{{ '' }} ``` - + +替换以下选项： + +* `PRODUCT`: 编译的目标文件类型, 比如可以设置为： `core` 和 `workstation_eng`. +* `BOARD`: 编译的可执行文件架构，比如：`x64` 和 `qemu-x64` + +下面的示例设置了编译选项为 `core.qemu-x64`: ```posix-terminal fx set core.qemu-x64 ``` - + +在这个示例中： + + * `core` 就是选择了特性最小化的 Fuchsia， 当然包括了常见的网络相关。 + * `qemu-x64` 这个选项设置了编译架构为在开源的虚拟机 （FEMU）中的 x64 架构 [QEMU][qemu]{:.external}. + +在看另一个编译选项示例，下面这个命令配置了 [在设备中安装 Fuchsia 工作站][build-workstation] 中常用的一个架构, `workstation_eng.x64`: ```posix-terminal fx set workstation_eng.x64 ``` - + +如果想查看更详细的编译选项介绍，参考 [配置编译选项](/development/build/fx.md#configure-a-build) + +## 3. 编译调优（可选） {#speed-up-the-build} + +注意：这一步不是必选项，但是建议您设置，因为设置了这一步能节省很多的编译时间。 + +编译调优的话，需要下面的服务： + +* [使用 Goma](#enable-goma) +* [安装 ccache](#install-ccache) + +### 使用 Goma {#enable-goma} + +[Goma](https://chromium.googlesource.com/infra/goma/server/){:.external} 是一个分布式编译服务，常用在一些开源项目中，如 Chrome，Android 以及 Fuchsia。 + +如果你能访问 Goma， 使用下面的命令来开启 Goma 客户端： ```posix-terminal fx goma ``` - + +### 安装 ccache {#install-ccache} + +如果不能访问 Goma，但是想加速本地编译时间，那就使用 [ccache](https://ccache.dev/){:.external} 来缓存来进行增量编译。 * {Linux} - + + 在 Linux 中使用 `ccache`，安装如下安装包： ```posix-terminal sudo apt install ccache ``` * {macOS} - + + 至于 macOS ，参考 [在 Mac 上使用 CCache](https://chromium.googlesource.com/chromium/src.git/+/HEAD/docs/ccache_mac.md){:.external} 中的安装步骤。 + +如果你的 `CCACHE_DIR` 环境变量指向一个存在的路径，`ccache` 就会自动开启。 + +如果想关闭这个特性，可以指定下面的标志为 `fx set`： + +* 强制使用 `ccache`，即使其他的加速项可以使用： 
     fx set PRODUCT.BOARD --ccache
- + +* 关闭 `ccache`： 
     fx set PRODUCT.BOARD --no-ccache
- + +## 4. 编译 {#build-fuchsia} + +[`fx build`][fx-build-reference] 命令可以把源代码编译打包，或者编译成其他的类型。 + +使用如下命令编译 Fuchsia： + +注意：编译时间一般为 90 分钟。 ```posix-terminal fx build ``` - + +当你修改源代码后，要运行命令 `fx build` 来增量编译，或则运行 `fx -i build` 命令来开启一个监视进程，这个监视进程一旦发现源码有更新就会自动编译。 + +想要更多编译 Fuchsia 的相信信息，参考 [开始编译](/development/build/fx.md#execute-a-build)。 + +## 下一步 + +关于如何在你的主机上打开 Fuchsia 模拟器 （FEMU），参考 [开启 Fuchsia 模拟器](/get-started/set_up_femu.md)。 + +如果你无论如何都想要在硬件平台上运行 Fuchsia， 可以参考 [在硬件设备中安装 Fuchsia](/development/hardware/README.md)。 + From 3ee5825602654e7884528278bb9bf35e64f84d65 Mon Sep 17 00:00:00 2001 From: Xyct <87l46110@gmail.com> Date: Thu, 21 Jul 2022 22:44:59 +0800 Subject: [PATCH 017/112] =?UTF-8?q?=E7=BF=BB=E8=AF=91=20=5Fcommon/intro/?= =?UTF-8?q?=5Fsandboxing=5Fnamespaces.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../_common/intro/_sandboxing_namespaces.md | 42 +++++++++++++++---- 1 file changed, 34 insertions(+), 8 deletions(-) diff --git a/get-started/_common/intro/_sandboxing_namespaces.md b/get-started/_common/intro/_sandboxing_namespaces.md index 7fd4a275..af30697b 100644 --- a/get-started/_common/intro/_sandboxing_namespaces.md +++ b/get-started/_common/intro/_sandboxing_namespaces.md @@ -1,11 +1,16 @@ -## Namespaces - + +## 命名空间 + +进程的命名空间包含了进程对外界的私有视图，并且控制了进程能够对 Fuchsia 系统造成多少影响。 +这有效地定义了进程所在的沙箱的规则。 -Namespaces are populated with various resource objects, including: - + +命名空间由各种资源对象填充，包括： + +* **文件**: 包含二进制数据的对象。 +* **目录**: 包含其他对象的对象。 +* **套接字**: 打开时建立连接的对象，如命名管道。 +* **协议和服务**: 打开时提供结构化服务的对象。 +* **设备**: 提供对硬件资源的访问的对象。 + +进程的创建者基于那些所请求的能力，来填充命名空间的内容。 +进程不能向自己的命名空间添加对象，因为这实际上相当于进程在授予自身访问那些对象的权限。 From ac8364b15645d19fb957675cd73963d0fa7f7226 Mon Sep 17 00:00:00 2001 From: cwolf9 <2717232422@qq.com> Date: Fri, 22 Jul 2022 01:47:16 +0800 Subject: [PATCH 018/112] =?UTF-8?q?=E7=BF=BB=E8=AF=91contribute/governance?= =?UTF-8?q?/rfcs/0007=5Fremove=5Fthread=5Fkilling.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../rfcs/0007_remove_thread_killing.md | 194 ++++++++++-------- 1 file changed, 105 insertions(+), 89 deletions(-) diff --git a/contribute/governance/rfcs/0007_remove_thread_killing.md b/contribute/governance/rfcs/0007_remove_thread_killing.md index 35cd59ad..15b5a244 100644 --- a/contribute/governance/rfcs/0007_remove_thread_killing.md +++ b/contribute/governance/rfcs/0007_remove_thread_killing.md @@ -1,89 +1,105 @@ -{% set rfcid = "RFC-0007" %} -{% include "docs/contribute/governance/rfcs/_common/_rfc_header.md" %} -# {{ rfc.name }}: {{ rfc.title }} - - -## Summary - -In the past, `zx_task_kill` allowed usermode to kill individual threads. However, -killing individual threads encourages bad practices and has a high chance of leaving -the process in a bad state. For this reason, the ability to kill individual threads -should be removed. - -## Motivation and problem statement - -There is no reasonable use for usermode to kill individual threads. Exposing such facility -encourages bad practices. - -On Fuchsia, like other systems, killing a thread is done asynchronously; for running threads there -is no practical way to determine the exact place where it is safe to terminate a thread. For a -blocked (waiting) thread, the safer and often simple solution is to add logic so upon wakeup the -thread exits by itself. - -Dangers killing a thread - -* Locks can be left acquired, including global locks like ones controlling the heap. -* Memory can be leaked. At the very least the thread stack, but often many other pieces. -* Runtime left in an inconsistent state. This is at least true for the C and Go runtime. -* Killing a thread in its way to a syscall leaves the process in an unknown state. Kernel is - fine but the process does not have a way to know what happened and what did not happen. -* Defeats RAII wrappers and automatic cleanup. In fact, it defeats most guarantees from the high - level languages Fuchsia uses. - -## Design - -The following syscall will fail with `ZX_ERR_NOT_SUPPORTED` when passed a handle to a thread: - -``` -zx_status_t zx_task_kill(zx_handle_t handle); -``` - -Processes and jobs will still be killable as normal. - -## Implementation - -Luckily, thread killing is not used very much in Fuchsia. The only use cases are in test code -that checks that a thread hits a specific exception. This code is going to be updated so that -the excepting thread exits itself after the exception is handled. For code where the exception -is unrecoverable, the excepting thread's instruction pointer can be set directly to -zx_thread_exit or the runtime's thread exit function before the thread resumes. These tests -may still leak what the excepting thread had stored on the heap, but the runtime is in -a better state, and the leaks will be collected when the test's process exits. - -## Performance - -N/A - -## Security considerations - -N/A - -## Privacy considerations - -N/A - -## Testing - -The zircon core-tests will be updated to ensure that the zx_task_kill syscall behaves as intended. -Some amount of static analysis can be done to find call sites of zx_task_kill that are passed -threads. - -The full Fuchsia Large Scale Change (LSC) process will be followed to ensure this change is -properly tested. - -## Documentation - -The documentation for [zx_task_kill](/reference/syscalls/task_kill.md) will be updated to -reflect that threads are not killable. - -## Drawbacks, Alternatives, and Unknowns - -The alternative to this proposal is the current status quo, which is to allow threads to be -killed. Threads have been killable for the entire history of Fuchsia, but there has not been -any acceptable use cases where programs have relied on this behavior. For this reason, -we believe that thread killing can be safely removed. - -## Prior art and references - -* [Windows Vista tries to remove -TerminateThread](https://devblogs.microsoft.com/oldnewthing/20150814-00/?p=91811) +{% set rfcid = "RFC-0007" %} +{% include "docs/contribute/governance/rfcs/_common/_rfc_header.md" %} +# {{ rfc.name }}: {{ rfc.title }} + + +## Summary + + +过去，`zx_task_kill` 允许在用户态杀死单个线程。 但是，杀死单个线程会为不良做法提供支持，并且很有可能使进程处于不良状态。 出于这个原因，应该删除杀死单个线程的能力。 + +## Motivation and problem statement + + +用户态没有合理的用途来杀死单个线程。 暴露此类能力会为不良做法提供支持。 + + +在 Fuchsia 上，和其他系统一样，杀死一个线程是异步完成的； 对于正在运行的线程，没有实用的方法来确定可以安全终止线程的确切位置。 对于阻塞（等待）状态的线程，通常更安全且简单的解决方案是添加逻辑，以便在唤醒后线程自行退出。(todo) + + +杀死线程的危险 + + +* 锁可以被保持获取，包括像控制堆这样的全局锁。 +* 内存可能会泄漏。 至少线程堆栈可能泄露，但通常还有许多其他部分的内存会泄露。 +* 运行时处于不一致的状态。 至少对于 C 和 Go 运行时来说是这样。 +* 以系统调用的方式杀死一个线程会使进程处于未知状态。 内核没有影响，但该进程无法知道发生了什么以及没有发生什么。 +* 破坏 RAII 包装器和自动清理。 事实上，它破坏了 Fuchsia 使用的高级语言的大多数保证机制。 + +## Design + + +当将句柄被传递给线程时，以下系统调用将失败并返回`ZX_ERR_NOT_SUPPORTED`： + +``` +zx_status_t zx_task_kill(zx_handle_t handle); +``` + + +进程和作业仍然可以正常地被杀死。 + +## Implementation + + +幸运的是，Fuchsia 中并没有太多使用到杀死线程。 唯一的用例是在检查线程是否遇到特定异常的测试代码中。 此代码将被更新，以便异常线程在异常被处理后自行退出。 对于异常无法恢复的代码，可以在线程恢复前，将异常线程的指令指针直接设置为 zx_thread_exit 或运行时的线程退出函数。 这些测试可能仍然会泄漏异常线程存储在堆上的内容，但运行时会处于一个更好的状态，并且会在测试的进程退出时收集泄漏的内容。 + +## Performance + +N/A + +## Security considerations + +N/A + +## Privacy considerations + +N/A + +## Testing + + +Zircon 核心测试将被更新，以确保 zx_task_kill 系统调用按预期运行。可以进行一些静态分析来找到传递线程的 zx_task_kill 的调用点。 + + +将遵循完整的 Fuchsia Large Scale Change (LSC) 流程，以确保这一变化被正确测试。 + +## Documentation + + +[zx_task_kill](/reference/syscalls/task_kill.md) 的文档将被更新以反映线程不可杀死。 + +## Drawbacks, Alternatives, and Unknowns + + +该提议的替代方案是当前的现状，即允许线程被杀死。 在 Fuchsia 的整个历史中，线程都是可以被杀死的，但是没有任何可接受的用例表明程序依赖于这种行为。 出于这个原因，我们相信可以安全地删除线程杀死功能。 + +## Prior art and references + +* [Windows Vista tries to remove +TerminateThread](https://devblogs.microsoft.com/oldnewthing/20150814-00/?p=91811) From a82bfe5c2e74e29b3b1a6c544d36a0aac900c412 Mon Sep 17 00:00:00 2001 From: cwolf9 <2717232422@qq.com> Date: Fri, 22 Jul 2022 20:23:29 +0800 Subject: [PATCH 019/112] =?UTF-8?q?=E7=BF=BB=E8=AF=91=20get-started/=5Fcom?= =?UTF-8?q?mon/components/=5Fdeclaring=5Fintro.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- get-started/_common/components/_declaring_intro.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/get-started/_common/components/_declaring_intro.md b/get-started/_common/components/_declaring_intro.md index 395e91b2..8ee335b4 100644 --- a/get-started/_common/components/_declaring_intro.md +++ b/get-started/_common/components/_declaring_intro.md @@ -1,15 +1,24 @@ + +每个组件（component）都有一个声明，描述组件属性和功能。对于在软件包中分发的组件，其声明使用**组件清单（component manifest）文件**表示，并在**组件解析器**的帮助下加载。 + +![该图显示了如何使用“组件清单”来声明组件。该清单由开发者工具编译，并在运行时解析到设备上。](/get-started/images/components/component-manifest.png){: width="836"} + +请您使用组件清单语言（CML）文件声明组件。在构建时，组件清单编译器（`cmc`）工具会验证清单源并将其编译为二进制格式（`.cm`），并将其存储在组件的软件包中。在运行时，组件解析器将二进制清单文件加载到[组件管理器](/glossary/README.md#Component-Manager)的 [ComponentDecl](https://fuchsia.dev/reference/fidl/fuchsia.component.decl#Component) FIDL 结构中。 From a1f6b86a21d5859719dd1400c56eb1684c129c18 Mon Sep 17 00:00:00 2001 From: cwolf9 <2717232422@qq.com> Date: Fri, 22 Jul 2022 20:42:59 +0800 Subject: [PATCH 020/112] =?UTF-8?q?=E7=BF=BB=E8=AF=91=20get-started/=5Fcom?= =?UTF-8?q?mon/components/=5Fdeclaring=5Fmanifests.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../components/_declaring_manifests.md | 41 ++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/get-started/_common/components/_declaring_manifests.md b/get-started/_common/components/_declaring_manifests.md index dab204a6..6948a95d 100644 --- a/get-started/_common/components/_declaring_manifests.md +++ b/get-started/_common/components/_declaring_manifests.md @@ -1,9 +1,14 @@ -## Component manifests + +## 组件清单（component manifest）文件 + +CML 文件是以 `.cml` 扩展名结尾的 [JSON5](https://json5.org/){: .external} 文件。如下 CML 清单文件示例，描述了一个运行 ELF 二进制文件的简单组件，该文件向系统日志打印一条“Hello, World”信息： + +```json5 +{ + // 有关要运行的程序的信息。 + program: { + // 使用内置的 ELF 运行器。 + runner: "elf", + // 为此组件运行的二进制文件。 + binary: "bin/hello", + // 程序参数 + args: [ + "Hello", + "World!", + ], + }, + + // 此组件使用的能力。 + use: [ + { protocol: "fuchsia.logger.LogSink" }, + ], +} ``` + +该文件声明了关于组件的两个主要部分的信息： + +注意：要获取组件清单的更多详细信息，请参阅[组件清单](/concepts/components/v2/component_manifests.md)。 + +* `program`：描述可执行信息，例如二进制文件、程序参数和相关联的运行时。在此示例中，二进制文件被编译为 ELF 可执行文件并使用内置的 [ELF 运行器](/concepts/components/v2/elf_runner.md)。 + +* `use`：声明此组件运行所需的能力。在此示例中，`fuchsia.logger.LogSink` 协议使该组件能够向系统日志（syslog）写入消息。 From b407d5e9e099ffa453f8aaed08c257ec2c8f09b5 Mon Sep 17 00:00:00 2001 From: cwolf9 <2717232422@qq.com> Date: Fri, 22 Jul 2022 20:45:15 +0800 Subject: [PATCH 021/112] =?UTF-8?q?=E7=BF=BB=E8=AF=91=20get-started/=5Fcom?= =?UTF-8?q?mon/components/=5Fdeclaring=5Fshards.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../_common/components/_declaring_shards.md | 29 ++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/get-started/_common/components/_declaring_shards.md b/get-started/_common/components/_declaring_shards.md index f752add6..84ca7ab4 100644 --- a/get-started/_common/components/_declaring_shards.md +++ b/get-started/_common/components/_declaring_shards.md @@ -1,15 +1,23 @@ -## Manifest shards + +## 清单碎片 (Manifest shard) + +一些能力集合代表了系统中许多组件所共有的用例需求，例如日志记录。为了简化将这些能力纳入组件的过程，本框架将其抽象为**清单碎片**，可将其纳入 CML 源文件中。 + +下面是一个与前面的示例等效的 CML。在这种情况下，通过包含 `diagnostics/syslog/client.shard.cml` 文件，而不是显式地声明 `fuchsia.logger.LogSink` 来提供必要的日志记录功能： + +```json5 +{ + include: [ "syslog/client.shard.cml" ], + + // 有关要运行的程序的信息。 + program: { + // 使用内置的 ELF 运行器。 + runner: "elf", + // 为此组件运行的二进制文件。 + binary: "bin/hello-world", + // 程序参数 + args: [ + "Hello", + "World!", + ], + }, +} +``` From 7cd976794ba3f5d700d97cca6d1cbfda8b6a34d9 Mon Sep 17 00:00:00 2001 From: Xyct <87l46110@gmail.com> Date: Fri, 22 Jul 2022 21:37:04 +0800 Subject: [PATCH 022/112] =?UTF-8?q?=E7=BF=BB=E8=AF=91=20learn/intro/sandbo?= =?UTF-8?q?xing.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- get-started/learn/intro/sandboxing.md | 70 ++++++++++++++++++++++++--- 1 file changed, 63 insertions(+), 7 deletions(-) diff --git a/get-started/learn/intro/sandboxing.md b/get-started/learn/intro/sandboxing.md index 426101cf..219ec044 100644 --- a/get-started/learn/intro/sandboxing.md +++ b/get-started/learn/intro/sandboxing.md @@ -1,5 +1,6 @@ {% import 'docs/_common/_doc_widgets.md' as widgets %} -# Software isolation model + +# 软件隔离模型 <<../../_common/intro/_sandboxing_intro.md>> @@ -7,30 +8,48 @@ <<../../_common/intro/_sandboxing_namespaces.md>> -## Exercise: Namespaces + +## 练习：命名空间（namespace） + +在本练习中，您将使用命令行来更详细地探索组件的命名空间的内容。 <<../_common/_start_femu.md>> -### Find a component in the hub + +### 在 hub 中找到一个组件 + +Fuchsia 提供了 [Hub](/concepts/components/v2/hub.md) 作为诊断接口， +用于获取系统中运行的组件实例的信息。 +您可以使用 hub 的目录结构来探索组件及其命名空间。 + +连接到设备命令行并输入以下 `ls` 命令 +来列出 `/hub-v2/children/core/children` 下的 `core` 领域（realm）的组件: ```posix-terminal fx shell ls /hub-v2/children/core/children @@ -45,10 +64,16 @@ build-info ... ``` + +这是许多核心 Fuchsia 系统组件的一个列表。要查看更多关于特定组件的详细信息，可以列出它的目录内容。 + +对 `http-client` 组件试试这个: ```posix-terminal fx shell ls /hub-v2/children/core/children/network/children/http-client @@ -65,10 +90,14 @@ resolved url ``` -### Explore the namespace and outgoing directory + +### 探索命名空间和出口目录 + +您将在 hub 内部的 `exec/in` 路径下找到运行中组件的**命名空间**。 ```posix-terminal fx shell ls /hub-v2/children/core/children/network/children/http-client/exec/in @@ -80,16 +109,27 @@ pkg svc ``` -Here are some quick highlights of each element: + +对每个元素简单说明如下: + +* `config/`: 组件的配置数据 +* `pkg/`: 组件的包的内容 +* `svc/`: 可供组件使用的系统服务 + +列出 `svc/` 目录的内容。这个目录包含 +[服务节点](https://fuchsia.dev/reference/fidl/fuchsia.io#NodeInfo)， +表示提供给这个组件的系统服务。 ```posix-terminal fx shell ls /hub-v2/children/core/children/network/children/http-client/exec/in/svc @@ -101,13 +141,22 @@ fuchsia.net.name.Lookup fuchsia.posix.socket.Provider ``` + +每个服务都通过一个公有协议访问，其由一个 + [Fuchsia 接口定义语言（Fuchsia Interface Definition Language，FIDL)][glossary.FIDL]接口定义。 +组件通过其**出口目录**（outgoing directory）来提供系统服务， +这个目录被映射到 hub 内部的 `exec/out` 路径。 + +列出 `svc/` 出口目录来查看这个组件提供的系统服务。 ```posix-terminal fx shell ls /hub-v2/children/core/children/network/children/http-client/exec/out/svc @@ -117,11 +166,18 @@ fx shell ls /hub-v2/children/core/children/network/children/http-client/exec/out fuchsia.net.http.Loader ``` + +我们将在以后更详细地探索 FIDL 协议及如何访问各种服务。 From f7f9e74d31bb2c9532dbb189eb59322d0681f915 Mon Sep 17 00:00:00 2001 From: Xyct <87l46110@gmail.com> Date: Sat, 23 Jul 2022 13:14:20 +0800 Subject: [PATCH 023/112] =?UTF-8?q?=E7=BF=BB=E8=AF=91=5Fcommon/intro/=5Fsa?= =?UTF-8?q?ndboxing=5Fintro.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- get-started/_common/intro/_sandboxing_intro.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/get-started/_common/intro/_sandboxing_intro.md b/get-started/_common/intro/_sandboxing_intro.md index 2e22ab62..4978640a 100644 --- a/get-started/_common/intro/_sandboxing_intro.md +++ b/get-started/_common/intro/_sandboxing_intro.md @@ -1,3 +1,7 @@ + +在这一章中，您将学习 Zircon 内核对象如何使 Fuchsia 能够遵循 +**最少特权原则**，隔离进程并只授予他们需要的权限。 \ No newline at end of file From 82ab11d74f569a74e886c77a7be7bea49813ee05 Mon Sep 17 00:00:00 2001 From: cwolf9 <2717232422@qq.com> Date: Sat, 23 Jul 2022 15:03:47 +0800 Subject: [PATCH 024/112] =?UTF-8?q?=E4=BF=AE=E6=94=B9=E6=A0=87=E9=A2=98?= =?UTF-8?q?=E7=AD=89=E6=A0=BC=E5=BC=8F=E9=97=AE=E9=A2=98=200007=5Fremove?= =?UTF-8?q?=5Fthread=5Fkilling.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../rfcs/0007_remove_thread_killing.md | 53 +++++++++++-------- 1 file changed, 32 insertions(+), 21 deletions(-) diff --git a/contribute/governance/rfcs/0007_remove_thread_killing.md b/contribute/governance/rfcs/0007_remove_thread_killing.md index 15b5a244..e038bb49 100644 --- a/contribute/governance/rfcs/0007_remove_thread_killing.md +++ b/contribute/governance/rfcs/0007_remove_thread_killing.md @@ -3,25 +3,27 @@ # {{ rfc.name }}: {{ rfc.title }} -## Summary - + +## 概述 + -过去，`zx_task_kill` 允许在用户态杀死单个线程。 但是，杀死单个线程会为不良做法提供支持，并且很有可能使进程处于不良状态。 出于这个原因，应该删除杀死单个线程的能力。 +过去，`zx_task_kill` 允许在用户态杀死单个线程。但是，杀死单个线程会为不良做法提供支持，并且很有可能使进程处于不良状态。出于这个原因，应该删除杀死单个线程的能力。 -## Motivation and problem statement + +## 动机与问题陈述 -用户态没有合理的用途来杀死单个线程。 暴露此类能力会为不良做法提供支持。 +用户态没有合理的用途来杀死单个线程。暴露此类能力会为不良做法提供支持。 -在 Fuchsia 上，和其他系统一样，杀死一个线程是异步完成的； 对于正在运行的线程，没有实用的方法来确定可以安全终止线程的确切位置。 对于阻塞（等待）状态的线程，通常更安全且简单的解决方案是添加逻辑，以便在唤醒后线程自行退出。(todo) +在 Fuchsia 上，和其他系统一样，杀死一个线程是异步完成的；对于正在运行的线程，没有实用的方法来确定可以安全终止线程的确切位置。对于阻塞（等待）状态的线程，通常更安全且简单的解决方案是添加逻辑，以便在唤醒后线程自行退出。 杀死线程的危险 @@ -34,12 +36,13 @@ thread exits by itself. --> * Defeats RAII wrappers and automatic cleanup. In fact, it defeats most guarantees from the high level languages Fuchsia uses. --> * 锁可以被保持获取，包括像控制堆这样的全局锁。 -* 内存可能会泄漏。 至少线程堆栈可能泄露，但通常还有许多其他部分的内存会泄露。 -* 运行时处于不一致的状态。 至少对于 C 和 Go 运行时来说是这样。 -* 以系统调用的方式杀死一个线程会使进程处于未知状态。 内核没有影响，但该进程无法知道发生了什么以及没有发生什么。 -* 破坏 RAII 包装器和自动清理。 事实上，它破坏了 Fuchsia 使用的高级语言的大多数保证机制。 +* 内存可能会泄漏。至少线程堆栈可能泄露，但通常还有许多其他部分的内存会泄露。 +* 运行时处于不一致的状态。至少对于 C 和 Go 运行时来说是这样。 +* 以系统调用的方式杀死一个线程会使进程处于未知状态。内核没有影响，但该进程无法知道发生了什么以及没有发生什么。 +* 破坏 RAII 包装器和自动清理。事实上，它破坏了 Fuchsia 使用的高级语言的大多数保证机制。 -## Design + +## 设计 当将句柄被传递给线程时，以下系统调用将失败并返回`ZX_ERR_NOT_SUPPORTED`： @@ -51,7 +54,8 @@ zx_status_t zx_task_kill(zx_handle_t handle); 进程和作业仍然可以正常地被杀死。 -## Implementation + +## 实现 -幸运的是，Fuchsia 中并没有太多使用到杀死线程。 唯一的用例是在检查线程是否遇到特定异常的测试代码中。 此代码将被更新，以便异常线程在异常被处理后自行退出。 对于异常无法恢复的代码，可以在线程恢复前，将异常线程的指令指针直接设置为 zx_thread_exit 或运行时的线程退出函数。 这些测试可能仍然会泄漏异常线程存储在堆上的内容，但运行时会处于一个更好的状态，并且会在测试的进程退出时收集泄漏的内容。 +幸运的是，Fuchsia 中并没有太多使用到杀死线程。唯一的用例是在检查线程是否遇到特定异常的测试代码中。此代码将被更新，以便异常线程在异常被处理后自行退出。对于异常无法恢复的代码，可以在线程恢复前，将异常线程的指令指针直接设置为 zx_thread_exit 或运行时的线程退出函数。这些测试可能仍然会泄漏异常线程存储在堆上的内容，但运行时会处于一个更好的状态，并且会在测试的进程退出时收集泄漏的内容。 -## Performance + +## 性能 N/A -## Security considerations + +## 安全性考虑 N/A -## Privacy considerations + +## 隐私问题 N/A -## Testing + +## 测试 将遵循完整的 Fuchsia Large Scale Change (LSC) 流程，以确保这一变化被正确测试。 -## Documentation + +## 文档 [zx_task_kill](/reference/syscalls/task_kill.md) 的文档将被更新以反映线程不可杀死。 -## Drawbacks, Alternatives, and Unknowns + +## 缺点、替代方案和未知因素 -该提议的替代方案是当前的现状，即允许线程被杀死。 在 Fuchsia 的整个历史中，线程都是可以被杀死的，但是没有任何可接受的用例表明程序依赖于这种行为。 出于这个原因，我们相信可以安全地删除线程杀死功能。 +该提议的替代方案是当前的现状，即允许线程被杀死。在 Fuchsia 的整个历史中，线程都是可以被杀死的，但是没有任何可接受的用例表明程序依赖于这种行为。出于这个原因，我们相信可以安全地删除线程杀死功能。 -## Prior art and references + +## 现有技术和参考文献 * [Windows Vista tries to remove TerminateThread](https://devblogs.microsoft.com/oldnewthing/20150814-00/?p=91811) From 3f456b401ad98aa2bdc3f6653c0aadb625ee39f3 Mon Sep 17 00:00:00 2001 From: Xyct <87l46110@gmail.com> Date: Sat, 23 Jul 2022 15:55:35 +0800 Subject: [PATCH 025/112] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E5=8E=9F=E6=96=87?= =?UTF-8?q?=E9=99=84=E6=B3=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- get-started/_common/intro/_sandboxing_namespaces.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/get-started/_common/intro/_sandboxing_namespaces.md b/get-started/_common/intro/_sandboxing_namespaces.md index af30697b..b87d5551 100644 --- a/get-started/_common/intro/_sandboxing_namespaces.md +++ b/get-started/_common/intro/_sandboxing_namespaces.md @@ -50,7 +50,7 @@ capabilities to access those objects. means Fuchsia does not have a concept of chroot environments, since every process effectively has its own private "root". --> -

命名空间是为每个进程定义的。不像其他操作系统，Fuchsia 不存在“全局文件系统”。 +

命名空间是为每个进程定义的。不像其他操作系统，Fuchsia 不存在“全局文件系统（root filesystem）”。 而路径地址“/”则指代进程私有命名空间的根。 这也意味着 Fuchsia 不存在 chroot 环境的概念，因为每个进程都有自己的私有“root”。

这也影响到目录遍历，以及文件系统服务器如何解析包含 ../. 的路径。 - 要获取更多详情，请参阅我们认为双点有害。

+ 要获取更多详情，请参阅我们认为双点（dot-dot）有害。

From 1a3059756bafe26b39fb7b22386630c2a5d23916 Mon Sep 17 00:00:00 2001 From: Xyct <87l46110@gmail.com> Date: Sat, 23 Jul 2022 15:56:39 +0800 Subject: [PATCH 026/112] Update get-started/_common/intro/_sandboxing_sandboxing.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 具有权利 --> 具有的权利 --- get-started/_common/intro/_sandboxing_sandboxing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/get-started/_common/intro/_sandboxing_sandboxing.md b/get-started/_common/intro/_sandboxing_sandboxing.md index 88107709..25f4d7ab 100644 --- a/get-started/_common/intro/_sandboxing_sandboxing.md +++ b/get-started/_common/intro/_sandboxing_sandboxing.md @@ -27,7 +27,7 @@ detail later on. From 2257798a93bd35a53f2cae11772eb464aee5124e Mon Sep 17 00:00:00 2001 From: y2-Whyto Date: Tue, 26 Jul 2022 11:29:09 +0800 Subject: [PATCH 047/112] Update contribute/docs/documentation-style-guide.md Co-authored-by: Xyct <87l46110@gmail.com> --- contribute/docs/documentation-style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contribute/docs/documentation-style-guide.md b/contribute/docs/documentation-style-guide.md index 9f4f846a..40026aa0 100644 --- a/contribute/docs/documentation-style-guide.md +++ b/contribute/docs/documentation-style-guide.md @@ -242,7 +242,7 @@ By default, `fuchsia.dev` creates anchors using underscores (`_`) in place of spaces. When referencing a section in a page, create a custom anchor using dashes (`-`) instead, using `{#section-title}`. Also, use dashes for file names. --> -默认情况下，`fuchsia.dev` 创建锚点时会在在空格处使用下划线（`_`）。不过，当引用一个页面中的章节时，请使用连接号（`-`，dash），使用 `{#section-title}`。同样地，请在文件名中使用连接号。 +默认情况下，`fuchsia.dev` 创建锚点时会在在空格处使用下划线（`_`）。不过，当引用一个页面中的章节时，请使用连接号（`-`，dash），使用 `{#section-title}` 创建自定义锚点。同样地，请在文件名中使用连接号。 -## 标头（header） +## 标题 -### 为页面和章节标题使用句首字母大写格式（sentence case） +### 为页面和章节标题使用句首字母大写格式 -### 为锚点使用连接号（dash），不要使用下划线 +### 为锚点使用连接号，不要使用下划线 * 要获取关于通用文档标准的信息，包括文件类型、位置和整体语言风格，请参阅 [Fuchsia 文档标准][doc-standard]。 * 要获取关于措辞、风格和结构的具体指导，请参阅 [Fuchsia 文档风格指南][style-guide]。 +* 要获取完整的 Markdown 参考指南，请参阅 [Markdown 参考指南][markdown-guide]。 -在 Fuchsia 项目中，代码的行最大长度为 100 字符，而文档的行最大长度为 80 字符。该规则一个值得注意的例外情况是 URL（即链接），写在一行中，不换行。 +在 Fuchsia 项目中，代码的行最大长度为 100 字符，而文档的行最大长度为 80 字符。该规则一个值得注意的例外情况是网址（即链接），写在一行中，不换行。 -不推荐：请勿在命令前硬编码一个 `$` 符号。 +不推荐：请勿在命令里硬编码 `$` 字符。 ```sh $ fx ota From a41e77359c8e822452db7022e926b627199daae0 Mon Sep 17 00:00:00 2001 From: y2-Whyto Date: Tue, 26 Jul 2022 11:42:15 +0800 Subject: [PATCH 052/112] Update contribute/docs/documentation-style-guide.md Co-authored-by: Xyct <87l46110@gmail.com> --- contribute/docs/documentation-style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contribute/docs/documentation-style-guide.md b/contribute/docs/documentation-style-guide.md index dd9bc3ae..a562f78f 100644 --- a/contribute/docs/documentation-style-guide.md +++ b/contribute/docs/documentation-style-guide.md @@ -180,7 +180,7 @@ In the Fuchsia documentation you can link to three types of contents: * `/docs/` - 链接至位于 Fuchsia 源树中 `/docs/` 目录内的文档。这些链接必须关联到具有 `.md` 扩展名的文件。例如，`/concepts/README.md`。 * 源代码 - 链接至位于 Fuchsia 源树中的源代码文件。这些链接可以关联到任何文件扩展名，但这些文件必须存在于源树中。例如，`/src/sys/sysmgr/main.cc`。 * 参考文档 - 链接至自动生成的 Fuchsia 参考文档。 - * 大多数 Fuchsia 参考文档不存在于源树内，但在 [fuchsia.dev][fuchsia-dev] 上发布了。这些链接必须使用完整形式的 URL。例如，`https://fuchsia.dev/reference/fidl/fuchsia.io`。 + * 大多数 Fuchsia 参考文档不存在于源树内，但在 [fuchsia.dev][fuchsia-dev] 上发布了。这些链接必须使用完全限定的网址。例如，`https://fuchsia.dev/reference/fidl/fuchsia.io`。 * 不过，一些 Fuchsia 参考文档存在于源树内。这些文档位于 `/reference/`，并在 `https://fuchsia.dev/fuchsia-src/reference/` 中发布。这些链接必须关联到具有 `.md` 扩展名的文件。例如，`/reference/syscalls/bti_create.md`。 From ccb5f050f71ac7b11721c4bc19418e8033d30981 Mon Sep 17 00:00:00 2001 From: y2-Whyto Date: Tue, 26 Jul 2022 11:44:33 +0800 Subject: [PATCH 053/112] Update contribute/docs/documentation-style-guide.md Co-authored-by: Xyct <87l46110@gmail.com> --- contribute/docs/documentation-style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contribute/docs/documentation-style-guide.md b/contribute/docs/documentation-style-guide.md index a562f78f..95430f84 100644 --- a/contribute/docs/documentation-style-guide.md +++ b/contribute/docs/documentation-style-guide.md @@ -386,7 +386,7 @@ $ my_command -### 引用源代码时使用路径，不要使用 URL +### 引用源代码时使用路径，不要使用网址 -该代码块在渲染时，命令前会添加 `$`： +该代码块在渲染时，命令前会出现 `$`： ```posix-terminal fx ota From 27714f20535f80e8a78fd171b3258e628a0bcc92 Mon Sep 17 00:00:00 2001 From: y2-Whyto Date: Tue, 26 Jul 2022 11:45:28 +0800 Subject: [PATCH 055/112] Update contribute/docs/documentation-style-guide.md Co-authored-by: Xyct <87l46110@gmail.com> --- contribute/docs/documentation-style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contribute/docs/documentation-style-guide.md b/contribute/docs/documentation-style-guide.md index d302c3b2..5b750e55 100644 --- a/contribute/docs/documentation-style-guide.md +++ b/contribute/docs/documentation-style-guide.md @@ -393,7 +393,7 @@ $ my_command code should be referred to by path only. You will get a static error check otherwise. --> -推荐：任何引用源代码的链接应当仅使用路径指代。否则您将收到静态错误检查（static error check）。 +推荐：任何引用源代码的链接应当仅使用路径引用。否则您将收到静态错误检查（static error check）。 -### 对不同的 Fuchsia 内容使用正确链接 +### 为不同的 Fuchsia 内容使用正确链接 -在这一章中，您将学习 Zircon 内核对象如何使 Fuchsia 能够遵循 -**最少特权原则**，隔离进程并只授予他们需要的权限。 \ No newline at end of file +在这一章中，您将学习 Zircon 内核对象如何使 Fuchsia 能够遵循**最少特权原则**，隔离进程并只授予他们需要的权限。 From 7ae974ba5e1fb1ebae8572dc89fafc05bf6ec65d Mon Sep 17 00:00:00 2001 From: y2-Whyto Date: Tue, 26 Jul 2022 12:28:30 +0800 Subject: [PATCH 058/112] build, compile, prerequisites --- glossary-translation.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/glossary-translation.md b/glossary-translation.md index 90251919..1d0893b7 100644 --- a/glossary-translation.md +++ b/glossary-translation.md @@ -22,9 +22,11 @@ | automatic retry | 自动重试 | G | | backoff | 退避 | G | | best practice | 最佳做法 | G & i | +| build | 构建 | G | | caveats | 注意事项 | G | | cleanup | 清理 | G | -| consume | 使用
消耗 | G
后者在结算系统中使用 | +| compile | 编译 | G | +| consume | 使用
消耗 | G
后者在结算系统中使用 | | control plane | 控制层面
控制平面 | G | | data plane | 数据平面
数据层面 | G | | deprecated | 已弃用（的） | G | @@ -53,6 +55,7 @@ | path | 路径 | G | | pave | 铺设 | i | | policy | 政策 | G | +| prerequisites | 前提条件 | G | | proxy | 代理 | | | remote | 远程 | | | robust | 可靠的 | G | From 141b98181f4a1258aa8c1ed6cb9cf8e3eb01fa93 Mon Sep 17 00:00:00 2001 From: y2-Whyto Date: Tue, 26 Jul 2022 12:31:05 +0800 Subject: [PATCH 059/112] source code --- glossary-translation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/glossary-translation.md b/glossary-translation.md index 1d0893b7..94544c98 100644 --- a/glossary-translation.md +++ b/glossary-translation.md @@ -68,6 +68,7 @@ | set up / setup | 设置 | | | settings | 设置 | | | sidecar | Sidecar | 首字母大写，不译
G | +| source code | 源代码 | G | | span | Span
跨 | 作名词时首字母大写，不译
作动词时译为“跨”
G | | strategy | 策略 | G | | suite | 套件 | G | From 44cef1feadd30488a73a2b9767c8469e5507ea19 Mon Sep 17 00:00:00 2001 From: y2-Whyto Date: Tue, 26 Jul 2022 16:28:31 +0800 Subject: [PATCH 060/112] Update documentation-style-guide.md --- contribute/docs/documentation-style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contribute/docs/documentation-style-guide.md b/contribute/docs/documentation-style-guide.md index 07d2fa62..5b750e55 100644 --- a/contribute/docs/documentation-style-guide.md +++ b/contribute/docs/documentation-style-guide.md @@ -151,7 +151,7 @@ You can read more about reference style links in the external -### 为不同的 Fuchsia 内容使用正确链接 +### 对不同的 Fuchsia 内容使用正确链接 -## 标识组件 +## 组件的标记 -组件由 URL 标识。框架借助**组件解析器**将组件 URL 解析为组件声明。解析器本身就是能够处理特定 URL scheme 并获取组件清单、程序和资源的组件。 +组件由 URL 标识。框架借助**组件解析器**将组件 URL 解析为组件声明。解析器本身就是能够处理特定 URL 格式并获取组件清单、程序和资源的组件。 -组件实例由称为 **moniker** 的拓扑路径引用来标识。组件的 moniker 将其在组件实例树中的位置指示为绝对或相对路径。例如，moniker 路径 `/core/system-updater` 指的是存在于 `core` 领域中的 `system-updater` 的实例。 +组件实例由称为 **绰号（moniker）** 的拓扑路径引用来标识。组件的绰号将其在组件实例树中的位置指示为绝对或相对路径。例如，绰号路径 `/core/system-updater` 指的是存在于 `core` 领域中的 `system-updater` 的实例。 From aa3119054f19a36794433fae73c3b0fe34d82d9e Mon Sep 17 00:00:00 2001 From: wy Date: Tue, 26 Jul 2022 20:22:57 +0800 Subject: [PATCH 063/112] get_fuchsia_source.md review --- get-started/get_fuchsia_source.md | 75 ++++++++++++++++--------------- 1 file changed, 38 insertions(+), 37 deletions(-) diff --git a/get-started/get_fuchsia_source.md b/get-started/get_fuchsia_source.md index b3a6e206..085aed85 100644 --- a/get-started/get_fuchsia_source.md +++ b/get-started/get_fuchsia_source.md @@ -7,7 +7,7 @@ This guide provides instructions on how to download the Fuchsia source code and set up the Fuchsia development environment on your machine. --> -这篇文章将指导您下载 Fuchsia 源码以及在您的机器上部署开发环境。 +本指南说明了如何下载 Fuchsia 源码以及在您的机器上部署开发环境。 @@ -19,33 +19,34 @@ The steps are: 4. [Set up environment variables](#set-up-environment-variables). 5. [Configure firewall rules (Optional)](#configure-firewall-rules). --> -1. [前期检查](#perform-a-preflight-check). -2. [安装用到的软件包](#install-prerequisite-packages). +1. [执行预检查](#perform-a-preflight-check). +2. [安装必备软件包](#install-prerequisite-packages). 3. [下载 Fuchsia 源码](#download-the-fuchsia-source-code). 4. [设置环境变量](#set-up-environment-variables). -5. [配置防火墙（可选项）](#configure-firewall-rules). +5. [配置防火墙规则（可选）](#configure-firewall-rules). -## 1. 前期检查 {#perform-a-preflight-check} +## 1. 执行预检查 {#perform-a-preflight-check} -Fuchsia 提供了一个自动检测工具（[`ffx platform preflight`][ffx-platform-preflight]），这个工具可以测试您的机器，并会在发现任何影响您编译 Fuchsia 源码的问题时通知您。 +Fuchsia 提供了一个预检工具（[`ffx platform preflight`][ffx-platform-preflight]），这个工具可以测试您的机器，并会通知您任何在该机器上构建 Fuchsia 源码时会受影响的问题。 -注意：这个检测工具只支持 x64 架构。Fuchsia 目前对其他架构的机器上的编译不做成功担保，比如 Windows 和 ARM64。 +注意：这个预检测工具只支持 x64 架构。目前 Fuchsia 不保证在其他宿主架构上能构建成功，比如 Windows 和 ARM64。 + -运行下面的命令： +运行如下命令： * {Linux} @@ -61,7 +62,7 @@ Run the following command: -## 2. 安装用到的软件包 {#install-prerequisite-packages} +## 2. 安装必备软件包 {#install-prerequisite-packages} - 安装（或更新）下面的软件： + 安装（或更新）下面的软件包： ```posix-terminal sudo apt install curl file git unzip @@ -87,7 +88,7 @@ Fuchsia 要求 `curl`、 `file`、 `unzip` 以及 `git` 等工具是最新版。 --> 安装 Xcode 命令行工具： - 注意：如果 `ffx platform preflight` 工具检测到 Xcode 已经安装，就省去这一步操作。 + 注意：如果 `ffx platform preflight` 检测到 Xcode 工具已经安装，就可以跳过这一步。 ```posix-terminal xcode-select --install @@ -109,7 +110,7 @@ another 80 to 90 GB of space later when you build Fuchsia. Additionally, the download process uses a substantial amount of memory. It is advisible to close non-crucial processes during this time. --> -下载 Fuchsia 源码要求您机器上有 2 GB 的存储空间。之后在编译 Fuchsia 过程中需要另外 80 到 90 GB 的存储空间，这取决于您的编译选项配置。另外，下载过程中也会使用一部分的内存空间。建议您在此过程中关闭其他非必要的程序进程。 +下载 Fuchsia 源码要求您机器上有 2 GB 的存储空间。取决于您的构建配置，之后的构建 Fuchsia 过程则需要额外 80 到 90 GB 的存储空间。另外，下载过程中也会使用大量的内存。建议您在此过程中关闭其他非必要的程序进程。 @@ -120,7 +121,7 @@ To download the Fuchsia source, do the following: Note: You can set up Fuchsia in any directory. This guide selects the `$HOME` directory as an example. --> -1. 选择一个 Fuchsia 源码存储目录，例如： +1. 选择一个 Fuchsia 源码下载目录，例如： 注意：您可以把 Fuchsia 下载到任何路径。本篇教程选择 `$HOME` 作为示例。 @@ -146,10 +147,9 @@ To download the Fuchsia source, do the following: bootstrapping process, see [Authentication error](#authentication-error) for help. --> - 这个脚本会先创建 `fuchsia` 路径，然后下载源码到该路径下。 - - 如果您在脚本运行期间看到了 `Invalid authentication credentials` 错误信息，参考[认证失败](#authentication-error)章节寻求帮助。 + 这个脚本会创建 `fuchsia` 目录，并且下载源码。 + 如果您在脚本运行期间看到了 `Invalid authentication credentials` 错误信息，参考[认证错误](#authentication-error)章节寻求帮助。 -* 添加 `.jiri_root/bin` 路径到您的 `PATH` 环境变量 +* 添加 `.jiri_root/bin` 目录到您的 `PATH` 环境变量 - `.jiri_root/bin` 路径在 Fuchsia 源码中包含了 [`jiri`](https://fuchsia.googlesource.com/jiri) 和 [`fx`](/development/build/fx.md) 工具，这些工具对 Fuchsia 的后续操作起着至关重要的作用。Fuchsia 使用 `jiri` 工具在 Fuchsia 的项目中管理仓库，使用 `fx` 工具帮助配置、编译、运行以及调试 Fuchsia。Fuchsia 的工具链需要可以在您 `PATH` 环境变量中找得到 `jiri` 工具。 + Fuchsia 源码中的 `.jiri_root/bin` 目录包含了 [`jiri`](https://fuchsia.googlesource.com/jiri) 和 [`fx`](/development/build/fx.md) 工具，这些是 Fuchsia 工作流中的必备工具。Fuchsia 使用 `jiri` 工具在 Fuchsia 的项目中管理仓库，使用 `fx` 工具帮助配置、构建、运行以及调试 Fuchsia。Fuchsia 的工具链需要可以在您的 `PATH` 环境变量中找到 `jiri` 工具。 * 导入 `scripts/fx-env.sh` 文件 - 虽然这并不是必须的，导入 [`fx-env.sh`](/scripts/fx-env.sh) 文件可以在您的终端中建立一系列的非常有用的 shell 函数。比如，它会创建给 `fd` 工具用来切换路径时提供自动补全的 `FUCHSIA_DIR` 环境变量（如果想获取更多信息，请参考 `fx-env.sh` 文件）。 + 虽然这并不是必须的，导入 [`fx-env.sh`](/scripts/fx-env.sh) 文件可以在您的终端中启用一系列有用的 shell 函数。比如，它会创建 `FUCHSIA_DIR` 环境变量，以及提供 `fd` 命令用来在目录中导航时提供自动补全 （如果想获取更多信息，请参考 `fx-env.sh` 文件）。 -注意：如果您不想更新您的 shell 配置，在附录中参考[不更新 PATH 变量编译 Fuchsia](#work-on-fuchsia-without-updating-your-path)。 +注意：如果您不想更新您的 shell 配置，参考附录[不更新 PATH 变量的情况下在 Fuchsia 上工作](#work-on-fuchsia-without-updating-your-path)。 -1. 请用文本编辑器打开您的 `~/.bash_profile` 文件（参考如下示例，我们使用 [Nano][nano]{:.external} ） +1. 请用文本编辑器打开您的 `~/.bash_profile` 文件（参考如下示例，我们使用 [Nano][nano]{:.external} 文本编辑器） - 注意：这篇文章使用 `bash` 终端作为示例，如果您使用 `zsh` 的话，在如下步骤中请替换文件 `~/.bash_profile` 为 `~/.zprofile`： + 注意：本指南使用 `bash` 终端作为示例，如果您使用 `zsh` 的话，在如下步骤中请替换 `~/.bash_profile` 为 `~/.zprofile`： ```posix-terminal nano ~/.bash_profile @@ -222,7 +222,7 @@ do the following: --> 1. 在您的 `~/.bash_profile` 文件中添加如下配置： - 注意：如果您的 Fuchsia 源码不在 `~/fuchsia` 路径下，替换 `~/fuchsia` 路径为您的 Fuchsia 路径。 + 注意：如果您的 Fuchsia 源码不在 `~/fuchsia` 目录下，替换 `~/fuchsia` 为您的 Fuchsia 目录。 ```sh export PATH=~/fuchsia/.jiri_root/bin:$PATH @@ -256,7 +256,7 @@ do the following: -## 5. 配置防火墙（可选项） {#configure-firewall-rules} +## 5. 配置防火墙规则（可选） {#configure-firewall-rules} -注意：这一步在您的编译或者运行 Fuchsia 步骤中并不是必须的。但是是被建议的，因为可以用来确保您能在 Linux 中流畅的运行 Fuchsia 虚拟机。 +注意：这一步对构建或者运行 Fuchsia 并不是必须的。但是为了确保 Fuchsia 模拟器实例能在 Linux 上顺利运行是推荐的。 -(**Linux**) 如果您计划在 Linux 中运行 Fuchsia，建议您运行如下命令来允许 Fuchsia 使用一些特殊的特性： +(**仅Linux**) 如果您计划在 Linux 中运行 Fuchsia，建议您运行如下命令在宿主机上允许 Fuchsia 相关的流量： ```posix-terminal fx setup-ufw @@ -285,7 +285,7 @@ firewall rules. (For more information on this script, see [`setup-ufw`][setup-uf To build your first Fuchsia system image, see [Configure and build Fuchsia](/get-started/build_fuchsia.md). --> -编译您第一个 Fuchsia 系统镜像，参考[配置和编译 Fuchsia](/get-started/build_fuchsia.md) 文件。 +构建您第一个 Fuchsia 系统镜像，参考[配置和构建 Fuchsia](/get-started/build_fuchsia.md)。 @@ -293,7 +293,7 @@ To build your first Fuchsia system image, see -### 验证失败 {#authentication-error} +### 认证错误 {#authentication-error} -* 按照屏幕路径的提示为仓库输入密码 -* 删除 `.gitcookies` 文件中不需要的 cookie。 +* 按照屏幕上的指示为特定的仓库获取密码 +* 删除 `.gitcookies` 文件中有问题的 cookie。 -* [把工具复制到可执行文件目录](#copy-the-tool-to-your-binary-directory) -* [为工具添加链接文件到可执行文件目录](#add-a-symlink-to-your-binary-directory) +* [把工具复制到二进制目录](#copy-the-tool-to-your-binary-directory) +* [添加符号链接到二进制目录](#add-a-symlink-to-your-binary-directory) -#### 把工具复制到可执行文件目录 {#copy-the-tool-to-your-binary-directory} +#### 把工具复制到二进制目录 {#copy-the-tool-to-your-binary-directory} -无论如何，您首先需要有不用 `sudo` 命令就可以访问 `~/bin` 路径的权限。如果没有，`jiri` 就不能使它自己保持在最新版本。 +但是，您需要在没有 `sudo` 的情况下对 `~/bin` 有写访问权限。如果没有，`jiri` 就不能保持在最新版本。 -#### 为工具添加链接文件到可执行文件目录 {#add-a-symlink-to-your-binary-directory} +#### 添加符号链接到二进制目录 {#add-a-symlink-to-your-binary-directory} 同样的，如果您想不更新环境变量使用 `fx` 工具，在 `~/bin` 路径中提供您的 `fx` 工具的链接文件，比如： +同样的，如果您想不更新环境变量而使用 `fx` 工具，在 `~/bin` 目录中提供 `fx` 工具的符号链接，比如： 注意：如果您的 Fuchsia 源码不在 `~/fuchsia` 目录中，把 `~/fuchsia` 替换为您的 Fuchsia 目录。 @@ -377,7 +378,7 @@ ln -s ~/fuchsia/scripts/fx ~/bin -相应地，您也可以使用 `fx` 工具的完整路径，比如： +或者，直接用其路径运行 `fx` 工具，比如： ```posix-terminal ./scripts/fx help @@ -385,7 +386,7 @@ Alternatively, run the `fx` tool directly using its path, for example: -另一方面，您需要在 `PATH` 环境变零中设置您的 `jiri` 工具。 +无论哪种情况，您都需要`jiri` 工具在您的 `PATH` 环境变量中。 [ffx-platform-preflight]: https://fuchsia.dev/reference/tools/sdk/ffx#preflight From 6875cc67646c494d3e2bfdf6d0050807341a6e38 Mon Sep 17 00:00:00 2001 From: wy Date: Tue, 26 Jul 2022 20:24:53 +0800 Subject: [PATCH 064/112] =?UTF-8?q?substitute=20=E7=BC=96=E8=AF=91=20with?= =?UTF-8?q?=20=E6=9E=84=E5=BB=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- get-started/build_fuchsia.md | 49 ++++++++++++++++++------------------ 1 file changed, 24 insertions(+), 25 deletions(-) diff --git a/get-started/build_fuchsia.md b/get-started/build_fuchsia.md index 33940dcf..6200e514 100644 --- a/get-started/build_fuchsia.md +++ b/get-started/build_fuchsia.md @@ -1,12 +1,11 @@ - -# 配置和编译 Fuchsia {#configure-and-build-fuchsia} +# 配置和构建 Fuchsia {#configure-and-build-fuchsia} -这篇文档将引导您在主机上如何配置并编译 Fuchsia。 +这篇文档将引导您在主机上如何配置并构建 Fuchsia。 @@ -19,8 +18,8 @@ The steps are: --> 1. [准备](#prerequisites) 1. [配置设置项](#set-your-build-configuration) -1. [编译调优（可选）](#speed-up-the-build) -1. [编译](#build-fuchsia) +1. [构建调优（可选）](#speed-up-the-build) +1. [构建](#build-fuchsia) @@ -54,7 +53,7 @@ environment on your machine. You can build Fuchsia only on a machine with one of the following host architectures: --> -Fuchsia 的编译支持如下架构的机器： +Fuchsia 的构建支持如下架构的机器： -Fuchsia 的编译设置项告诉编译系统如何编译，以及编译什么架构的文件。 +Fuchsia 的构建设置项告诉构建系统如何构建，以及构建什么架构的文件。 -设置您的 Fuchsia 编译选项，可以运行 [`fx set`][fx-set-reference] 命令： +设置您的 Fuchsia 构建选项，可以运行 [`fx set`][fx-set-reference] 命令： ```posix-terminal fx set {{ '' }}PRODUCT{{ '' }}.{{ '' }}BOARD{{ '' }} ``` @@ -91,12 +90,12 @@ Replace the following: `workstation_eng`. * `BOARD`: The architecture of the product; for example, `x64` and `qemu-x64` --> -* `PRODUCT`: 编译的目标文件类型, 比如可以设置为： `core` 和 `workstation_eng`. -* `BOARD`: 编译的可执行文件架构，比如：`x64` 和 `qemu-x64` +* `PRODUCT`: 构建的目标文件类型, 比如可以设置为： `core` 和 `workstation_eng`. +* `BOARD`: 构建的可执行文件架构，比如：`x64` 和 `qemu-x64` -下面的示例设置了编译选项为 `core.qemu-x64`: +下面的示例设置了构建选项为 `core.qemu-x64`: ```posix-terminal fx set core.qemu-x64 @@ -113,13 +112,13 @@ In this example: [QEMU][qemu]{:.external}. --> * `core` 就是选择了特性最小化的 Fuchsia， 当然包括了常见的网络相关。 - * `qemu-x64` 这个选项设置了编译架构为在开源的虚拟机 （FEMU）中的 x64 架构 [QEMU][qemu]{:.external}. + * `qemu-x64` 这个选项设置了构建架构为在开源的虚拟机 （FEMU）中的 x64 架构 [QEMU][qemu]{:.external}. -在看另一个编译选项示例，下面这个命令配置了 [在设备中安装 Fuchsia 工作站][build-workstation] 中常用的一个架构, `workstation_eng.x64`: +在看另一个构建选项示例，下面这个命令配置了 [在设备中安装 Fuchsia 工作站][build-workstation] 中常用的一个架构, `workstation_eng.x64`: ```posix-terminal fx set workstation_eng.x64 @@ -128,20 +127,20 @@ fx set workstation_eng.x64 For more information on the build configuration, see [Configure a build](/development/build/fx.md#configure-a-build). --> -如果想查看更详细的编译选项介绍，参考 [配置编译选项](/development/build/fx.md#configure-a-build) +如果想查看更详细的构建选项介绍，参考 [配置构建选项](/development/build/fx.md#configure-a-build) -## 3. 编译调优（可选） {#speed-up-the-build} +## 3. 构建调优（可选） {#speed-up-the-build} -注意：这一步不是必选项，但是建议您设置，因为设置了这一步能节省很多的编译时间。 +注意：这一步不是必选项，但是建议您设置，因为设置了这一步能节省很多的构建时间。 -编译调优的话，需要下面的服务： +构建调优的话，需要下面的服务： -[Goma](https://chromium.googlesource.com/infra/goma/server/){:.external} 是一个分布式编译服务，常用在一些开源项目中，如 Chrome，Android 以及 Fuchsia。 +[Goma](https://chromium.googlesource.com/infra/goma/server/){:.external} 是一个分布式构建服务，常用在一些开源项目中，如 Chrome，Android 以及 Fuchsia。 @@ -175,7 +174,7 @@ If you do not have access to Goma, but want to accelerate the Fuchsia build locally, use [ccache](https://ccache.dev/){:.external} to cache artifacts from previous builds. --> -如果不能访问 Goma，但是想加速本地编译时间，则可以使用 [ccache](https://ccache.dev/){:.external} 来缓存来进行增量编译。 +如果不能访问 Goma，但是想加速本地构建时间，则可以使用 [ccache](https://ccache.dev/){:.external} 来缓存来进行增量构建。 * {Linux} -## 4. 编译 {#build-fuchsia} +## 4. 构建 {#build-fuchsia} -[`fx build`][fx-build-reference] 命令可以把源代码编译打包，或者编译成其他的类型。 +[`fx build`][fx-build-reference] 命令可以把源代码构建打包，或者构建成其他的类型。 -使用如下命令编译 Fuchsia： +使用如下命令构建 Fuchsia： -注意：编译时间一般为 90 分钟。 +注意：构建时间一般为 90 分钟。 ```posix-terminal fx build @@ -242,12 +241,12 @@ When you modify source code, run the `fx build` command again to perform an incremental build, or run the `fx -i build` command to start a watcher, which automatically builds whenever you update the source code. --> -当您修改源代码后，要运行命令 `fx build` 来增量编译，或者运行 `fx -i build` 命令来开启一个监视进程，这个监视进程一旦发现源码有更新就会自动编译。 +当您修改源代码后，要运行命令 `fx build` 来增量构建，或者运行 `fx -i build` 命令来开启一个监视进程，这个监视进程一旦发现源码有更新就会自动构建。 -要获取关于编译 Fuchsia 的更多信息，请参考参阅[开始编译](/development/build/fx.md#execute-a-build)。 +要获取关于构建 Fuchsia 的更多信息，请参考参阅[开始构建](/development/build/fx.md#execute-a-build)。 From 54acce6729754250419de76c662536d0b24e2a87 Mon Sep 17 00:00:00 2001 From: cwolf9 <2717232422@qq.com> Date: Wed, 27 Jul 2022 04:06:02 +0800 Subject: [PATCH 065/112] =?UTF-8?q?=E7=BF=BB=E8=AF=91=20get-started/=5Fcom?= =?UTF-8?q?mon/fidl/=5Foverview.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- get-started/_common/fidl/_overview.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/get-started/_common/fidl/_overview.md b/get-started/_common/fidl/_overview.md index 1075fdb1..9234dc6a 100644 --- a/get-started/_common/fidl/_overview.md +++ b/get-started/_common/fidl/_overview.md @@ -1,22 +1,34 @@ + +在 **Fuchsia 简介**中了解到，Zircon 提供了内核对象类型来支持 Fuchsia 的进程间通信（IPC）。这些对象类型定义了进程用来交换数据的特定机制。在这个框架内，Zircon 通道提供了一个基于消息的异步传输能力，即支持同时传递数据和一组句柄来授予访问权。 + +Zircon 通道是 **Fuchsia 接口定义语言**（Fuchsia Interface Definition Language，FIDL）所描述的更高层次的交互的基础，FIDL 是用来描述 Fuchsia 程序所使用的 IPC 协议的语言。FIDL 允许不同的客户和服务器相互进行操作，通过强制执行一套语义行为和在通道上操作的持久性格式来实现相互操作。 + +程序通过 **FIDL 编译器**生成的特定语言的 binding 和库与 FIDL 协议进行交互，该编译器是用于隐藏 Zircon IPC 复杂性的一个抽象层。这使得我们可以引入熟悉的编程习惯，如结构化类型和同步执行。编译器为每种支持的语言都生成了 bingding，因此供应商不需要维护客户端库。 + +![图中显示了 Fuchsia 接口定义语言（FIDL）如何通过一个通用接口促进进程间通信（IPC）；与何种编程语言无关。](/get-started/images/fidl/fuchsia-interface.png){: width="870"} From 3027500156a6b0f064351267d378c38d918b15c1 Mon Sep 17 00:00:00 2001 From: cwolf9 <2717232422@qq.com> Date: Wed, 27 Jul 2022 04:09:26 +0800 Subject: [PATCH 066/112] =?UTF-8?q?=E7=BF=BB=E8=AF=91=20get-started/=5Fcom?= =?UTF-8?q?mon/fidl/=5Ffidl=5Fintro.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- get-started/_common/fidl/_fidl_intro.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/get-started/_common/fidl/_fidl_intro.md b/get-started/_common/fidl/_fidl_intro.md index 33d69954..2905c3fb 100644 --- a/get-started/_common/fidl/_fidl_intro.md +++ b/get-started/_common/fidl/_fidl_intro.md @@ -1,11 +1,17 @@ + +Fuchsia 接口定义语言（FIDL）是用来描述 Fuchsia 程序使用的进程间通信（IPC）协议的语言。FIDL 提供了一种简化的声明语法，供供应商将接口定义为一种**协议**。支持的数据类型包括整数、浮点数、布尔运算、字符串和[句柄][glossary.handle]。这些可以被组织成更复杂的数组、向量、结构体、表格和联合体。 + +考虑以下用于 `Echo` 接口的 FIDL 协议的示例。 ```fidl library fuchsia.examples; @@ -15,27 +21,45 @@ library fuchsia.examples; {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/echo.test.fidl" region_tag="echo" adjust_indentation="auto" %} ``` + +FIDL 协议描述了一组**方法**，在通过通道发送消息时被调用。通道消息本身是异步的，发送方和接收方彼此可以独立操作。FIDL 方法引入了更高层次的语义，使 FIDL 交易的客户端和服务器端的编程更加符合传统习惯。 + +FIDL支持以下方法类型： + +* **双向方法**：一个典型的方法调用是，接受可选的参数，其返回类型定义在 `->` 操作符之后。双向方法会阻塞调用方直到收到响应。在 `Echo` 的例子中，`EchoString()` 方法是一个双向的方法。 + +* **单向方法**：异步方法调用，立即返回而不等待响应。没有声明返回类型的方法被认为是客户端的单向方法。在 `Echo` 的例子中，`SendString()` 方法是一个单向的方法。 + +* **事件**：必要时，服务器端可以向客户端发送非请求信息，称之为事件。事件在 `->` 操作符的返回端声明其方法名称。在 `Echo` 的例子中，`OnString()` 方法是一个事件。 + +注意：要获取 FIDL 语言语法和支持的类型的更多细节，请参阅 [FIDL 语言规范](/reference/fidl/language/language.md)。 [glossary.handle]: /glossary/README.md#handle From 11305e485a61bb5047a1d697bb5f0804a69a0907 Mon Sep 17 00:00:00 2001 From: y2-Whyto Date: Wed, 27 Jul 2022 09:56:49 +0800 Subject: [PATCH 067/112] product, board --- glossary-translation.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/glossary-translation.md b/glossary-translation.md index 94544c98..75b4c9dc 100644 --- a/glossary-translation.md +++ b/glossary-translation.md @@ -22,6 +22,7 @@ | automatic retry | 自动重试 | G | | backoff | 退避 | G | | best practice | 最佳做法 | G & i | +| board | 板型 | i | | build | 构建 | G | | caveats | 注意事项 | G | | cleanup | 清理 | G | @@ -56,6 +57,7 @@ | pave | 铺设 | i | | policy | 政策 | G | | prerequisites | 前提条件 | G | +| product | 产品 | i & G | | proxy | 代理 | | | remote | 远程 | | | robust | 可靠的 | G | From a36f14f0a9d28ca43f6d854c283b6652258e7ac8 Mon Sep 17 00:00:00 2001 From: cwolf9 <2717232422@qq.com> Date: Wed, 27 Jul 2022 22:10:28 +0800 Subject: [PATCH 068/112] =?UTF-8?q?=E4=BF=AE=E6=94=B9=E6=BC=8F=E7=BF=BB?= =?UTF-8?q?=E5=8F=8A=E7=BF=BB=E8=AF=91=E7=BB=86=E8=8A=82=20=5Foverview.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- get-started/_common/fidl/_overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/get-started/_common/fidl/_overview.md b/get-started/_common/fidl/_overview.md index 9234dc6a..3e6be97e 100644 --- a/get-started/_common/fidl/_overview.md +++ b/get-started/_common/fidl/_overview.md @@ -5,7 +5,7 @@ define specific mechanisms that processes use to exchange data. Within this framework, **Zircon channels** provide an asynchronous message-based transport capable of passing both data and a set of handles to grant access rights. --> -在 **Fuchsia 简介**中了解到，Zircon 提供了内核对象类型来支持 Fuchsia 的进程间通信（IPC）。这些对象类型定义了进程用来交换数据的特定机制。在这个框架内，Zircon 通道提供了一个基于消息的异步传输能力，即支持同时传递数据和一组句柄来授予访问权。 +您已经在 **Fuchsia 简介**中了解到，Zircon 提供了内核对象类型来支持 Fuchsia 的进程间通信（IPC）。这些对象类型定义了进程用来交换数据的特定机制。在这个框架内，Zircon 通道提供了一个基于消息的异步传输能力，即支持同时传递数据和一组句柄来授予访问权。 -程序通过 **FIDL 编译器**生成的特定语言的 binding 和库与 FIDL 协议进行交互，该编译器是用于隐藏 Zircon IPC 复杂性的一个抽象层。这使得我们可以引入熟悉的编程习惯，如结构化类型和同步执行。编译器为每种支持的语言都生成了 bingding，因此供应商不需要维护客户端库。 +程序通过 **FIDL 编译器**生成的特定语言的绑定（binding）和库与 FIDL 协议进行交互，该编译器是用于隐藏 Zircon IPC 复杂性的一个抽象层。这使得我们可以引入熟悉的编程习惯，如结构化类型和同步执行。编译器为每种支持的语言都生成了绑定，因此供应商不需要维护客户端库。 -Fuchsia 接口定义语言（FIDL）是用来描述 Fuchsia 程序使用的进程间通信（IPC）协议的语言。FIDL 提供了一种简化的声明语法，供供应商将接口定义为一种**协议**。支持的数据类型包括整数、浮点数、布尔运算、字符串和[句柄][glossary.handle]。这些可以被组织成更复杂的数组、向量、结构体、表格和联合体。 +Fuchsia 接口定义语言（FIDL）是用来描述 Fuchsia 程序使用的进程间通信（IPC）协议的语言。FIDL 为供应商提供了一种简化的声明语法，以便将接口定义为一种**协议**。支持的数据类型包括整数、浮点数、布尔运算、字符串和[句柄][glossary.handle]。这些可以被组织成更复杂的数组、向量、结构体、表格和联合体。 -FIDL支持以下方法类型： +FIDL 支持以下方法类型： -* **事件**：必要时，服务器端可以向客户端发送非请求信息，称之为事件。事件在 `->` 操作符的返回端声明其方法名称。在 `Echo` 的例子中，`OnString()` 方法是一个事件。 +* **事件**：必要时，服务器端可以向客户端发送非请求信息，这种消息称为事件。事件在 `->` 操作符的返回端声明其方法名称。在 `Echo` 的例子中，`OnString()` 方法是一个事件。 -如果您在脚本运行期间看到了 `Invalid authentication credentials` 报错信息，您的 `~/.gitcookies` 文件中可能包含了一些引导脚本想要自动检测的来自 `googlesource.com` 的 cookie 信息。 +如果您在引导脚本运行过程中看到了 `Invalid authentication credentials` 报错信息，您的 `~/.gitcookies` 文件中可能包含了来自 `googlesource.com` 中的一些仓库的 cookie，引导脚本想要匿名检出。 @@ -386,7 +386,7 @@ Alternatively, run the `fx` tool directly using its path, for example: -无论哪种情况，您都需要`jiri` 工具在您的 `PATH` 环境变量中。 +无论哪种情况，您都需要 `jiri` 工具在您的 `PATH` 环境变量中。 [ffx-platform-preflight]: https://fuchsia.dev/reference/tools/sdk/ffx#preflight From b42fd3fd01cc083b7e16f0180d4a4f3209c18d06 Mon Sep 17 00:00:00 2001 From: wy Date: Fri, 29 Jul 2022 20:00:54 +0800 Subject: [PATCH 071/112] build_fuchsia.md file review --- get-started/build_fuchsia.md | 78 ++++++++++++++++++------------------ 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/get-started/build_fuchsia.md b/get-started/build_fuchsia.md index 6200e514..e044f36a 100644 --- a/get-started/build_fuchsia.md +++ b/get-started/build_fuchsia.md @@ -5,7 +5,7 @@ on a host machine. --> # 配置和构建 Fuchsia {#configure-and-build-fuchsia} -这篇文档将引导您在主机上如何配置并构建 Fuchsia。 +这篇文档将引导您在主机上配置并构建 Fuchsia。 @@ -16,9 +16,9 @@ The steps are: 1. [Speed up the build (Optional)](#speed-up-the-build). 1. [Build Fuchsia](#build-fuchsia). --> -1. [准备](#prerequisites) +1. [前提条件](#prerequisites) 1. [配置设置项](#set-your-build-configuration) -1. [构建调优（可选）](#speed-up-the-build) +1. [提升构建速度（可选）](#speed-up-the-build) 1. [构建](#build-fuchsia) -* [准备源码](#source-code-setup) +* [源代码设置](#source-code-setup) * [硬件要求](#hardware-requirements) -### 准备源码 {#source-code-setup} +### 源代码设置 {#source-code-setup} -根据文档 [下载 Fuchsia 源码](/get-started/get_fuchsia_source.md) 指示下载 Fuchsia 的源码，然后在您的机器上设置开发环境。 +根据文档[下载 Fuchsia 源代码](/get-started/get_fuchsia_source.md)指示下载 Fuchsia 的源代码，然后在您的计算机上设置开发环境。 @@ -53,7 +53,7 @@ environment on your machine. You can build Fuchsia only on a machine with one of the following host architectures: --> -Fuchsia 的构建支持如下架构的机器： +您只能在具有下列主机架构之一的计算机上构建 Fuchsia： -注意：Windows 和 ARM64 是不支持的。 +注意：不支持 Windows 和 ARM64。 -## 2. 配置设置项 {#set-your-build-configuration} +## 2. 设置构建配置 {#set-your-build-configuration} -Fuchsia 的构建设置项告诉构建系统如何构建，以及构建什么架构的文件。 +Fuchsia 的构建配置告诉构建系统进行构建的产品，以及构建面向的平台。 -设置您的 Fuchsia 构建选项，可以运行 [`fx set`][fx-set-reference] 命令： +要设置您的 Fuchsia 构建配置，请运行 [`fx set`][fx-set-reference] 命令： ```posix-terminal fx set {{ '' }}PRODUCT{{ '' }}.{{ '' }}BOARD{{ '' }} ``` -替换以下选项： +请替换以下选项： -* `PRODUCT`: 构建的目标文件类型, 比如可以设置为： `core` 和 `workstation_eng`. -* `BOARD`: 构建的可执行文件架构，比如：`x64` 和 `qemu-x64` +* `PRODUCT`（产品）：您想要构建的 Fuchsia 产品，比如：`core` 和 `workstation_eng`。 +* `BOARD`（板型）：编译的可执行文件架构，比如：`x64` 和 `qemu-x64`。 -下面的示例设置了构建选项为 `core.qemu-x64`: +下面的示例将一项构建配置设置为 `core.qemu-x64`： ```posix-terminal fx set core.qemu-x64 @@ -111,14 +111,14 @@ In this example: emulator (FEMU), which is based on the open source emulator [QEMU][qemu]{:.external}. --> - * `core` 就是选择了特性最小化的 Fuchsia， 当然包括了常见的网络相关。 - * `qemu-x64` 这个选项设置了构建架构为在开源的虚拟机 （FEMU）中的 x64 架构 [QEMU][qemu]{:.external}. + * `core` 是 Fuchsia 具备最小功能集的产品，包括常用的网络功能。 + * `qemu-x64` 是 Fuchsia 模拟器（FEMU）的 x64 架构这一板型，FEMU 基于开源模拟器 [QEMU][qemu]{:.external}。 -在看另一个构建选项示例，下面这个命令配置了 [在设备中安装 Fuchsia 工作站][build-workstation] 中常用的一个架构, `workstation_eng.x64`: +另外，下面的例子将一项编译配置设置为 `workstation_eng.x64`，这常用于[在设备上安装 Fuchsia 工作站][build-workstation]： ```posix-terminal fx set workstation_eng.x64 @@ -127,40 +127,40 @@ fx set workstation_eng.x64 For more information on the build configuration, see [Configure a build](/development/build/fx.md#configure-a-build). --> -如果想查看更详细的构建选项介绍，参考 [配置构建选项](/development/build/fx.md#configure-a-build) +要获取关于构建配置的更多信息，请参阅[配置构建](/development/build/fx.md#configure-a-build)。 -## 3. 构建调优（可选） {#speed-up-the-build} +## 3. 提升构建速度（可选） {#speed-up-the-build} -注意：这一步不是必选项，但是建议您设置，因为设置了这一步能节省很多的构建时间。 +注意：这一步对于构建 Fuchsia 而言并不是必需的，但是可以在您构建 Fuchsia 时节省很多时间，因此建议您完成该步骤。 -构建调优的话，需要下面的服务： +要提升 Fuchsia 构建速度，您可以使用下列服务之一： -* [使用 Goma](#enable-goma) +* [启用 Goma](#enable-goma) * [安装 ccache](#install-ccache) -### 使用 Goma {#enable-goma} +### 启用 Goma {#enable-goma} -[Goma](https://chromium.googlesource.com/infra/goma/server/){:.external} 是一个分布式构建服务，常用在一些开源项目中，如 Chrome，Android 以及 Fuchsia。 +[Goma](https://chromium.googlesource.com/infra/goma/server/){:.external} 是一个分布式编译器服务，适用于 Chrome、Android 和 Fuchsia 等开源项目。 -如果您能访问 Goma， 那么请使用下面的命令来开启 Goma 客户端： +如果您能访问 Goma， 请在您的计算机上 Goma 客户端： ```posix-terminal fx goma @@ -174,13 +174,13 @@ If you do not have access to Goma, but want to accelerate the Fuchsia build locally, use [ccache](https://ccache.dev/){:.external} to cache artifacts from previous builds. --> -如果不能访问 Goma，但是想加速本地构建时间，则可以使用 [ccache](https://ccache.dev/){:.external} 来缓存来进行增量构建。 +如果您无法访问 Goma，但想在本地加速构建，则可以使用 [ccache](https://ccache.dev/){:.external} 缓存之前构建的产物。 * {Linux} - 在 Linux 中使用 `ccache`，安装如下安装包： + 要在 Linux 上使用 `ccache`，请安装如下安装包： ```posix-terminal sudo apt install ccache ``` @@ -190,20 +190,20 @@ artifacts from previous builds. [Using CCache on Mac](https://chromium.googlesource.com/chromium/src.git/+/HEAD/docs/ccache_mac.md){:.external} for installation instructions. --> - 对于 macOS ，参考 [在 Mac 上使用 CCache](https://chromium.googlesource.com/chromium/src.git/+/HEAD/docs/ccache_mac.md){:.external} 中的安装步骤。 + 对于 macOS ，请参阅[在 Mac 上使用 CCache](https://chromium.googlesource.com/chromium/src.git/+/HEAD/docs/ccache_mac.md){:.external} 中的安装步骤。 -如果您的 `CCACHE_DIR` 环境变量指向一个存在的路径，`ccache` 就会自动开启。 +如果您的 `CCACHE_DIR` 环境变量指向已有路径，那么 `ccache` 就会自动开启。 -如果想关闭这个特性，可以指定下面的标志为 `fx set`： +要覆盖此默认行为，请为 `fx set` 指定以下标志： -* 强制使用 `ccache`，即使其他的加速项可以使用： +* 即使其他的加速项可用，也要强制使用 `ccache`，则： 
     fx set PRODUCT.BOARD --ccache
@@ -211,7 +211,7 @@ To override this default behavior, specify the following flags to `fx set`:
 
-*   关闭 `ccache`：
+*   要禁用 `ccache`：
     
     fx set PRODUCT.BOARD --no-ccache
     

@@ -227,7 +227,7 @@ source code into packages and other build artifacts.
 
-使用如下命令构建 Fuchsia：
+要构建 Fuchsia，请运行以下命令：
 
@@ -241,26 +241,26 @@ When you modify source code, run the `fx build` command again to perform an
 incremental build, or run the `fx -i build` command to start a watcher, which
 automatically builds whenever you update the source code.
 -->
-当您修改源代码后，要运行命令 `fx build` 来增量构建，或者运行 `fx -i build` 命令来开启一个监视进程，这个监视进程一旦发现源码有更新就会自动构建。
+当您修改源代码后，请再次运行命令 `fx build` 进行增量构建，或者运行 `fx -i build` 命令来开启一个监视进程，这个监视进程会在发现源代码更新时自动构建。
 
-要获取关于构建 Fuchsia 的更多信息，请参考参阅[开始构建](/development/build/fx.md#execute-a-build)。
+要获取关于构建 Fuchsia 的更多信息，请参阅[执行构建](/development/build/fx.md#execute-a-build)。
 
-## 下一步
+## 后续步骤
 
-关于如何在您的主机上打开 Fuchsia 模拟器 （FEMU），参考 [开启 Fuchsia 模拟器](/get-started/set_up_femu.md)。
+要在您的计算机上启动 Fuchsia 模拟器 （FEMU），请参阅[开启 Fuchsia 模拟器](/get-started/set_up_femu.md)。
 
-如果您无论如何都想要在硬件平台上运行 Fuchsia， 可以参考 [在硬件设备中安装 Fuchsia](/development/hardware/README.md)。
+不过，如果您想在硬件设备上运行 Fuchsia，请参阅[在设备上安装 Fuchsia](/development/hardware/README.md)。
 
 
 

From 7795077fa5d5fb4db8beb479d6bd4049f64d7abf Mon Sep 17 00:00:00 2001
From: "user: wy" <101500325+user-wy@users.noreply.github.com>
Date: Fri, 29 Jul 2022 20:04:32 +0800
Subject: [PATCH 072/112] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20next=20steps=20?=
 =?UTF-8?q?=E6=9C=AF=E8=AF=AD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

添加 next steps 术语
---
 glossary-translation.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/glossary-translation.md b/glossary-translation.md
index 75b4c9dc..f8c7d45a 100644
--- a/glossary-translation.md
+++ b/glossary-translation.md
@@ -77,6 +77,7 @@
 | traffic                        | 流量                   | G                                                     |
 | unmount                        | 卸载                   | G                                                     |
 | validate                       | 验证                   | G                                                     |
+| Next steps                     | 后续步骤                   | G                                                     |
 
 ## 文档中未出现术语的翻译参考表
 

From 6654362fc3f67cc761e41ec5a4c63eefbab6de5d Mon Sep 17 00:00:00 2001
From: wy 
Date: Sun, 31 Jul 2022 22:22:34 +0800
Subject: [PATCH 073/112] build_fuchsia.md file review

---
 get-started/build_fuchsia.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/get-started/build_fuchsia.md b/get-started/build_fuchsia.md
index e044f36a..42057111 100644
--- a/get-started/build_fuchsia.md
+++ b/get-started/build_fuchsia.md
@@ -17,13 +17,13 @@ The steps are:
 1. [Build Fuchsia](#build-fuchsia).
 -->
 1. [前提条件](#prerequisites)
-1. [配置设置项](#set-your-build-configuration)
+1. [设置构建配置](#set-your-build-configuration)
 1. [提升构建速度（可选）](#speed-up-the-build)
-1. [构建](#build-fuchsia)
+1. [构建 Fuchsia](#build-fuchsia)
 
-## 1. 准备 {#prerequisites}
+## 1. 前提条件 {#prerequisites}
 
@@ -91,7 +91,7 @@ Replace the following:
 * `BOARD`: The architecture of the product; for example, `x64` and `qemu-x64`
 -->
 * `PRODUCT`（产品）：您想要构建的 Fuchsia 产品，比如：`core` 和 `workstation_eng`。
-* `BOARD`（板型）：编译的可执行文件架构，比如：`x64` 和 `qemu-x64`。
+* `BOARD`（板型）：产品的可执行文件架构，比如：`x64` 和 `qemu-x64`。
 
@@ -118,7 +118,7 @@ On the other hand, the example below sets the build configuration to
 `workstation_eng.x64`, which is commonly used to
 [install Fuchsia's Workstation product on a device][build-workstation]:
 -->
-另外，下面的例子将一项编译配置设置为 `workstation_eng.x64`，这常用于[在设备上安装 Fuchsia 工作站][build-workstation]：
+另外，下面的例子将一项构建配置设置为 `workstation_eng.x64`，这常用于[在设备上安装 Fuchsia 工作站][build-workstation]：
 
 ```posix-terminal
 fx set workstation_eng.x64
@@ -218,7 +218,7 @@ To override this default behavior, specify the following flags to `fx set`:
 
-## 4. 构建 {#build-fuchsia}
+## 4. 构建 Fuchsia {#build-fuchsia}
 
-注意：这一步对构建或者运行 Fuchsia 并不是必须的。但是为了确保 Fuchsia 模拟器实例能在 Linux 上顺利运行是推荐的。
+注意：这一步对构建或者运行 Fuchsia 并不是必需的。但是为了确保 Fuchsia 模拟器实例能在 Linux 上顺利运行是推荐的。
 
-(**仅Linux**) 如果您计划在 Linux 中运行 Fuchsia，建议您运行如下命令在宿主机上允许 Fuchsia 相关的流量：
+(**仅限 Linux**) 如果您计划在 Linux 中运行 Fuchsia，建议您运行如下命令在宿主机上允许 Fuchsia 相关的流量：
 
 ```posix-terminal
 fx setup-ufw
@@ -279,13 +279,13 @@ firewall rules. (For more information on this script, see [`setup-ufw`][setup-uf
 
-## 下一步
+## 后续步骤
 
 
-构建您第一个 Fuchsia 系统镜像，参考[配置和构建 Fuchsia](/get-started/build_fuchsia.md)。
+要构建您第一个 Fuchsia 系统镜像，请参考[配置和构建 Fuchsia](/get-started/build_fuchsia.md)。
 
@@ -299,11 +299,11 @@ If you see the `Invalid authentication credentials` error during the bootstrap
 process, your `~/.gitcookies` file may contain cookies from some repositories in
 `googlesource.com` that the bootstrap script wants to check out anonymously.
 -->
-如果您在引导脚本运行过程中看到了 `Invalid authentication credentials` 报错信息，您的 `~/.gitcookies` 文件中可能包含了来自 `googlesource.com` 中的一些仓库的 cookie，引导脚本想要匿名检出。
+如果您在引导脚本运行过程中看到了 `Invalid authentication credentials` 报错信息，那么您的 `~/.gitcookies` 文件中可能包含了来自 `googlesource.com` 中一些仓库的 cookie，引导脚本想要匿名检出。
 
-为了解决这个问题，使用以下任何一个方式：
+要解决该错误，请使用以下方式之一：
 
 
 
-*  按照屏幕上的指示为特定的仓库获取密码
+*  按照屏幕上的指示为特定的仓库获取密码。
 *  删除 `.gitcookies` 文件中有问题的 cookie。
 
 
+系统中的所有组件组成一个有根的**组件实例树**。树中的父组件负责将其他组件的实例声明为其子组件并为它们提供功能。同时，子组件可以向父组件公开功能。这些组件实例和功能关系构成了**组件拓扑**。
 
+
+任何父组件及其所有子组件在树中形成一个称为**领域**的组。领域使父级能够控制哪些功能流入和流出其组件的子树，从而创建功能边界。这种封装允许领域在内部进行重组，而不会影响依赖于其公开功能的外部组件。
 
+
+![图表展示了组件实例被组织成一个树，父组件通过“功能路由”确定每个子组件可用的功能。](/get-started/images/components/component-topology.png){: width="616"}
 
+
+在上图中，`fuchsia.example.Foo` 协议功能通过组件实例树从提供者路由到客户端。组件使用 `use` 关键字声明它们**需要**的功能：
 
+
+```json5
+{
+    // 程序运行的有关信息。
+    program: {
+        // 使用内置的 ELF 运行程序来运行二进制文件。
+        runner: "elf",
+        // 运行该组件的二进制文件。
+        binary: "bin/client",
+    },
+
+    // 此组件所需的功能。
+    use: [
+        { protocol: "fuchsia.example.Foo" },
+    ],
+}
 ```
 
+
+组件使用组件清单中的 `capabilities` 部分声明它们实现或**提供**的功能。这使得组件框架知道该功能和它的提供者。请查看下面的 `provider.cml` 示例：
 
+
+```json5
+{
+    // 程序运行的有关信息。
+    program: {
+        // 使用内置的 ELF 运行程序来运行二进制文件。
+        runner: "elf",
+        // 运行该组件的二进制文件。
+        binary: "bin/provider",
+    },
 
+    // 此组件提供的功能。
+    capabilities: [
+        { protocol: "fuchsia.example.Foo" },
+    ],
+    // 通过此组件路由的功能。
+    expose: [
+        {
+            protocol: "fuchsia.example.Foo",
+            from: "self",
+        },
+    ],
+}
+```
+
+
+`expose` 关键字使这个组件的功能通过它的父组件向其他领域提供，这也可能包括这个组件的子组件提供的功能。在这种情况下，功能的来源是 `self`，因为这个组件是提供者。
 
+
+父组件控制领域内的**功能路由**，创建从客户端组件到提供者的显式路径。请查看以下 `parent.cml` 清单示例：
 
 ```json5
 {
@@ -96,18 +160,28 @@ example `parent.cml` manifest:
 }
 ```
 
+
+
 
+
+父组件在领域中声明一组子组件，并使用 `offer` 关键字将功能路由到它们。用这种方法，父组件就决定了每个子组件功能的范围和来源。这也使拓扑中的多个组件能够提供相同的功能，因为组件框架依赖于显式路由来确定如何解析来自每个客户端的请求。
 
+
+注意：要获取关于组件组织的更多详细信息，请参阅[组件拓扑](/concepts/components/v2/topology.md).

From 8924986cd3f836215a994655f848d50389c57f9e Mon Sep 17 00:00:00 2001
From: cwolf9 <2717232422@qq.com>
Date: Thu, 4 Aug 2022 21:23:35 +0800
Subject: [PATCH 076/112] =?UTF-8?q?=E7=BF=BB=E8=AF=91=20get-started/=5Fcom?=
 =?UTF-8?q?mon/components/=5Ftests=5Fintro.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 get-started/_common/components/_tests_intro.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/get-started/_common/components/_tests_intro.md b/get-started/_common/components/_tests_intro.md
index 9b994c64..eac6dac3 100644
--- a/get-started/_common/components/_tests_intro.md
+++ b/get-started/_common/components/_tests_intro.md
@@ -1,19 +1,31 @@
+
+Fuchsia **测试运行器框架**（Test Runner Framework）使开发者能够使用各种语言和运行时为组件构建测试，并在目标设备上执行它们。该框架提供了实现 `fuchsia.test.Suite` 协议的**测试运行器**组件，并与通用的特定语言的测试框架（如 GoogleTest (C++)）集成。
 
+
+`test_manager` 组件负责在 Fuchsia 设备上运行测试。它检查实现测试套件协议的组件,并将它们作为子组件启动。这意味着 `test_manager` 也负责为每个测试套件提供能力，即创建通常称为**测试领域**的东西。
 
+
+![图中显示了测试运行器框架如何为开发者提供接口来公开测试套件，以及开发者工具如何在 Fuchsia 设备上执行测试。](/get-started/images/components/test-realm.png){: width="714"}
 
+
+`ffx test` 等开发者工具与设备上的 `test_manager` 进行通信，以执行测试套件并检索结果。

From ba1347427fe1ce1dd7e60eb533aeb44e7b99908d Mon Sep 17 00:00:00 2001
From: cwolf9 <2717232422@qq.com>
Date: Thu, 4 Aug 2022 21:24:52 +0800
Subject: [PATCH 077/112] =?UTF-8?q?=E7=BF=BB=E8=AF=91=20get-started/=5Fcom?=
 =?UTF-8?q?mon/fidl/=5Ftesting=5Fintro.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 get-started/_common/fidl/_testing_intro.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/get-started/_common/fidl/_testing_intro.md b/get-started/_common/fidl/_testing_intro.md
index b1611972..159e3aa8 100644
--- a/get-started/_common/fidl/_testing_intro.md
+++ b/get-started/_common/fidl/_testing_intro.md
@@ -1,3 +1,4 @@
+
+[集成测试](https://en.wikipedia.org/wiki/Integration_testing){:.external} 侧重于验证组件的行为，因为它会与系统上其他组件进行交互。正因为如此，集成测试通常与主组件分开构建，并且可以将被测组件和其他依赖组件声明为子组件。根据测试的性质，依赖组件可以作为模拟或存根提供，以促进测试用例保持封闭性。

From 816cda46c4b8b3da3b1d199526edd1e695b07ba0 Mon Sep 17 00:00:00 2001
From: Xyct <87l46110@gmail.com>
Date: Fri, 5 Aug 2022 13:57:42 +0800
Subject: [PATCH 078/112] =?UTF-8?q?=E7=BF=BB=E8=AF=91=5Fcommon/intro/=5Far?=
 =?UTF-8?q?chitecture.md=E5=92=8Cget-started/learn/intro/architecture.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 get-started/_common/intro/_architecture.md | 27 +++++++++++++++++++++-
 get-started/learn/intro/architecture.md    |  3 ++-
 2 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/get-started/_common/intro/_architecture.md b/get-started/_common/intro/_architecture.md
index 522c93d6..aee80ff5 100644
--- a/get-started/_common/intro/_architecture.md
+++ b/get-started/_common/intro/_architecture.md
@@ -1,29 +1,54 @@
+
+![展示整个 Fuchsia 系统架构的高层图表的数据表，强调了核心组件和子系统]
 (/get-started/images/intro/fuchsia-architecture.png){: width="1080"}
 
-The following architectural principles guide Fuchsia's design and development:
+
 
+以下架构性原则指导了 Fuchsia 的设计与开发：
+
 
+* [**简单：**][simple]Fuchsia 让创建、维护和集成软件与硬件在广范的设备中都变得容易。
+
 
+* [**安全：**][secure]Fuchsia 有着为现代计算设计的内核和软件模型。
+
 
+* [**可升级：**][updatable]作为模块化操作系统，Fuchsia 允许内核、驱动和软件组件独立升级。
+
+* [**高性能：**][performant]Fuchsia 为真实世界产品需求设计，并为性能优化。
 
+
 
+系统的核心是 [Zircon][glossary.zircon]，它是处理系统启动与引导的内核和一组库。其他所有系统组件都实现于用户空间并被隔离，再次强化了**最小特权原则**。这些组件包括：
+
+*   设备驱动
+*   文件系统
+*   网络栈
 
 [glossary.zircon]: /glossary/README.md#zircon
 [simple]: /concepts/principles/simple.md
diff --git a/get-started/learn/intro/architecture.md b/get-started/learn/intro/architecture.md
index aab7cae8..fb7f06da 100644
--- a/get-started/learn/intro/architecture.md
+++ b/get-started/learn/intro/architecture.md
@@ -1,3 +1,4 @@
-# Fuchsia architecture
+
+# Fuchsia 架构
 
 <<../../_common/intro/_architecture.md>>

From 4a9f66bd86586871167a2077b102f325792323dc Mon Sep 17 00:00:00 2001
From: Xyct <87l46110@gmail.com>
Date: Fri, 5 Aug 2022 18:00:02 +0800
Subject: [PATCH 079/112] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E7=BF=BB=E8=AF=91?=
 =?UTF-8?q?=E6=9C=AF=E8=AF=AD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 glossary-translation.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/glossary-translation.md b/glossary-translation.md
index f8c7d45a..1c5049f6 100644
--- a/glossary-translation.md
+++ b/glossary-translation.md
@@ -39,6 +39,7 @@
 | escalate                       | 上报                   | G                                                     |
 | execute-only memory            | 只执行内存             | G                                                     |
 | fault injection                | 故障注入               | G                                                     |
+| fully qualified URL            | 完全限定的网址         | G                                                     |
 | get stared                     | 使用入门 
 入门     | G 
 前者更常用                                     |
 | get started with               | 开始使用 
 使用入门 | G 
 二者均常用                                     |
 | guidance                       | 指导                   |                                                       |
@@ -50,6 +51,7 @@
 | infrastructure                 | 基础架构               | G                                                     |
 | inspect                        | 审视                   | Fuchsia 专有名词 
 i                               |
 | just-in-time (JIT) compilation | 即时（JIT）编译        | G                                                     |
+| moniker                        | 代称                   | i                                                     |
 | mount                          | 装载                   | G                                                     |
 | namespace                      | 命名空间               | G                                                     |
 | out-of-tree                    | 树外                   | G 
 此处指源码树                                   |
@@ -76,6 +78,7 @@
 | suite                          | 套件                   | G                                                     |
 | traffic                        | 流量                   | G                                                     |
 | unmount                        | 卸载                   | G                                                     |
+| URL                            | 网址                   | G                                                     |
 | validate                       | 验证                   | G                                                     |
 | Next steps                     | 后续步骤                   | G                                                     |
 

From 9e71d4abbfea78743616f52ba7f36d2362dd368e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=97=85=E7=AB=8B=E3=81=A1=E3=81=AE=E9=A2=A8?=
 <36873309+tabidachinokaze@users.noreply.github.com>
Date: Fri, 5 Aug 2022 21:53:23 +0800
Subject: [PATCH 080/112] Update
 get-started/_common/components/_organizing_intro.md

Co-authored-by: y2-Whyto 
---
 get-started/_common/components/_organizing_intro.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/get-started/_common/components/_organizing_intro.md b/get-started/_common/components/_organizing_intro.md
index 8be5db0c..d22ce23c 100644
--- a/get-started/_common/components/_organizing_intro.md
+++ b/get-started/_common/components/_organizing_intro.md
@@ -15,7 +15,7 @@ out of its sub-tree of components, creating a capability boundary. This
 encapsulation allows the realm to be reorganized internally without affecting
 external components dependent on its exposed capabilities.
  -->
-任何父组件及其所有子组件在树中形成一个称为**领域**的组。领域使父级能够控制哪些功能流入和流出其组件的子树，从而创建功能边界。这种封装允许领域在内部进行重组，而不会影响依赖于其公开功能的外部组件。
+任何父组件及其所有子组件在树中形成一个称为**领域**的组。领域使父级能够控制那些功能流入和流出其组件的子树，从而创建功能边界。这种封装允许领域在内部进行重组，而不会影响依赖于其公开功能的外部组件。
 
 
-Fuchsia 是谷歌从内核创建的一种新的开源操作系统，旨在满足当今不断增长的连接设备生态系统的需求。
+Fuchsia 是谷歌从内核创建的一种新的开源操作系统，旨在满足当今不断增长的互联设备生态系统的需求。
+
 
 
-在本培训模块中，您将了解这一新操作系统背后的核心原理，
-并探索 Fuchsia 如何为开发人员在各种设备上创建经久耐用的产品和体验奠定基础。
+在本培训模块中，您将了解这一新操作系统背后的核心原理，并探索 Fuchsia 如何为开发人员在各种设备上创建经久耐用的产品和体验奠定基础。

From 8a5128a72624baead30126d4edd9e4c82799d5fd Mon Sep 17 00:00:00 2001
From: Eric X 
Date: Sat, 6 Aug 2022 17:52:36 +0800
Subject: [PATCH 082/112] =?UTF-8?q?=E5=9B=9E=E9=80=80build=5Ffuchsia?=
 =?UTF-8?q?=E6=96=87=E4=BB=B6=E5=88=B0=E6=9C=AA=E7=BF=BB=E8=AF=91=E7=89=88?=
 =?UTF-8?q?=E6=9C=AC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 get-started/build_fuchsia.md | 15 ++++++---------
 1 file changed, 6 insertions(+), 9 deletions(-)

diff --git a/get-started/build_fuchsia.md b/get-started/build_fuchsia.md
index 58964b9d..7e66e119 100644
--- a/get-started/build_fuchsia.md
+++ b/get-started/build_fuchsia.md
@@ -1,17 +1,14 @@
-
-# 配置和构建 Fuchsia 
+# Configure and build Fuchsia {#configure-and-build-fuchsia}
 
-
-本指南提供如何在宿主机上配置和构建 Fuchsia 的指令。
+This guide provide instructions on how to configure and build Fuchsia
+on a host machine.
 
-
-步骤如下：
+The steps are:
 
-
+1. [Build Fuchsia](#build-fuchsia).
 
 ## 1. Prerequisites {#prerequisites}
 

From 1e84ad4db836476362a8107d613d16f180594ad8 Mon Sep 17 00:00:00 2001
From: Eric X 
Date: Sat, 6 Aug 2022 17:57:04 +0800
Subject: [PATCH 083/112] =?UTF-8?q?=E5=9B=9E=E9=80=80=E5=85=B6=E4=BB=96?=
 =?UTF-8?q?=E6=96=87=E4=BB=B6=E5=88=B0=E6=9C=AA=E7=BF=BB=E8=AF=91=E7=89=88?=
 =?UTF-8?q?=E6=9C=AC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 get-started/_common/components/_overview.md   | 34 ++++++-------------
 .../_common/components/_product_driver.md     | 21 ++++--------
 .../_common/components/_product_intro.md      | 12 ++-----
 .../_common/components/_product_session.md    | 22 ++++--------
 4 files changed, 28 insertions(+), 61 deletions(-)

diff --git a/get-started/_common/components/_overview.md b/get-started/_common/components/_overview.md
index 26934923..fd829dc0 100644
--- a/get-started/_common/components/_overview.md
+++ b/get-started/_common/components/_overview.md
@@ -1,40 +1,28 @@
-
-一个组件是一个运行在 Fuchsia 沙盒中的程序。每个组件都是一个可组合的模块，依据各自功能与其它组件交互。
-Fuchsia 中的所有软件都被定义为一个个组件，除了内核、引导进程以及组件管理器。
+except for the kernel image, bootstrapping processes, and the Component Manager.
 
-
-Fuchsia 的组件框架致力于让系统可以运行几乎所有的用户空间软件。
-组件管理器是一个系统进程，负责协调各个组件实例的执行和生命周期，维护组件拓扑，给组件提供相应功能，并使它们彼此隔离。
+from one another.
 
-
-组件通过功能获得访问更广泛系统的各个部分的特权。 
-每个组件都可以声明它们提供给系统的新功能以及需要其他组件（或框架）提供的功能。
-组件管理器解析并验证组件之间的所有功能请求，以确保它们与组件已被正确授予的功能相匹配。
+has been properly granted.
 
 
diff --git a/get-started/_common/components/_product_driver.md b/get-started/_common/components/_product_driver.md
index 7271df4f..e56a8b82 100644
--- a/get-started/_common/components/_product_driver.md
+++ b/get-started/_common/components/_product_driver.md
@@ -1,20 +1,13 @@
-
-## 驱动框架
+## Driver framework
 
-
-与 session 类似，Fuchsia 驱动框架使开发人员能够将产品特定的设备驱动程序实现为组件。
-一些驱动程序组件代表硬件接口控制器，例如 PCI 或 USB，而其他驱动程序组件则与终端设备交互，
-例如以太网控制器或键盘。
+interact with end devices, such as an ethernet controller or keyboard.
 
-
-当设备被发现或连接到系统时，`driver_manager` 平台组件启动必要的驱动程序组件，
-将它们绑定到硬件接口，并管理它们的生命周期。
+hardware interfaces, and manages their lifecycle.
 
-
-注：有关驱动框架的细节，参考[Fuchsia 驱动框架](/development/drivers/concepts/fdf.md).
+Note: For more details on the driver framework, see
+[Fuchsia Driver Framework](/development/drivers/concepts/fdf.md).
diff --git a/get-started/_common/components/_product_intro.md b/get-started/_common/components/_product_intro.md
index 186ceaa7..cc748e6a 100644
--- a/get-started/_common/components/_product_intro.md
+++ b/get-started/_common/components/_product_intro.md
@@ -1,16 +1,10 @@
-
-组件构成了在 Fuchsia 用户空间中运行的软件的基础。 
-到目前为止，您探索的组件是运行 Fuchsia 的所有产品通用的核心平台的一部分。
-Fuchsia 产品由平台组件和产品特定元素组成，以满足设备硬件和用户体验的独特需求。 
-在本节中，您将探索 Fuchsia 如何构建组件以实现产品级定制。
+Fuchsia builds on components to enable product-level customization.
 
-
-![数据表展现了 Fuchsia 通过会话框架和驱动框架让产品在核心平台上的定制成为可能.]
 (/get-started/images/components/product.png){: width="582"}
diff --git a/get-started/_common/components/_product_session.md b/get-started/_common/components/_product_session.md
index 4e78ca99..d776e8c1 100644
--- a/get-started/_common/components/_product_session.md
+++ b/get-started/_common/components/_product_session.md
@@ -1,23 +1,15 @@
-
-## Session 框架
+## Session framework
 
-
-会话是一系列封装了产品用户体验的组件。会话框架充当 Fuchsia 平台和产品级用户交互之间的边界。 
-每个 Fuchsia 产品都将单个会话实例定义为产品体验的根，并可能管理其他子组件。
+additional child components.
 
-
-
-`session_manager` 平台组件在启动时打开会话组件，并为其提供一组固定的功能，以支持诸如窗口管理、
-输入事件处理或可访问元素的会话框架 API.
+accessibility.
 
-
-注: 有关会话框架的更多细节，请参考
-[会话框架介绍](/concepts/session/introduction.md).
+Note: For more details on the session framework, see
+[Introduction to the session framework](/concepts/session/introduction.md).

From a50c8f9a0c1de013e360b4abb40b6b7debb172e3 Mon Sep 17 00:00:00 2001
From: tabidachinokaze 
Date: Sat, 6 Aug 2022 22:04:24 +0800
Subject: [PATCH 084/112] =?UTF-8?q?=E7=BF=BB=E8=AF=91=20get-started/=5Fcom?=
 =?UTF-8?q?mon/components/=5Forganizing=5Flifecycle.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../components/_organizing_lifecycle.md       | 30 ++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/get-started/_common/components/_organizing_lifecycle.md b/get-started/_common/components/_organizing_lifecycle.md
index 7ae52f80..a797afff 100644
--- a/get-started/_common/components/_organizing_lifecycle.md
+++ b/get-started/_common/components/_organizing_lifecycle.md
@@ -1,37 +1,65 @@
-## Component lifecycle
+
+## 组件生命周期
 
+
+在组件拓扑中添加和移除组件实例时，会创建和销毁组件实例。这可以通过以下两种方式之一发生：
 
+
+* **静态地**：该实例在组件清单中被声明为树中另一个组件的子组件。静态组件仅当一个更新更改组件拓扑时才会创建和销毁。
+
+* **动态地**：实例在运行时使用 `fuchsia.component.Realm` 协议在组件 `collection` 中添加或移除。动态组件在系统关闭时销毁。
 
+
+一旦组件被销毁，框架就会移除它的持久状态（比如本地存储）。
 
+
+框架会启动一个组件实例当另一个组件尝试打开一个通道到该组件实例时——这称为**绑定**。当连接到一个由组件公开的能力时，绑定会**隐式**发生。绑定到已经启动的组件会连接到当前运行的实例。
 
+
+
 
+
+组件可能会通过退出程序（由组件的 `runner` 定义）自行停止，或者框架可能会在系统关闭时停止组件。在被销毁之前，框架将组件移动到**关闭**状态以指示它不能再次启动。
 
+
+![该图显示了组件如何具有两种不同的状态：实例和执行。这些状态描述了“组件生命周期”。](/get-started/images/components/component-lifecycle.png){: width="662"}
 
+
+注意：要获取关于组件状态和执行的更多详细信息，请参阅[组件生命周期](/concepts/components/v2/lifecycle.md)。

From 67336c9d54dad4cff62bb00464546e646048d498 Mon Sep 17 00:00:00 2001
From: Eric X 
Date: Sun, 7 Aug 2022 12:00:20 +0800
Subject: [PATCH 085/112] =?UTF-8?q?=E5=88=86=E6=8B=86=E5=88=B0=E5=8D=95?=
 =?UTF-8?q?=E7=8B=AC=E5=88=86=E6=94=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../_common/intro/_components_intro.md        |  24 ++--
 get-started/explore_fuchsia.md                | 109 ++++++------------
 2 files changed, 49 insertions(+), 84 deletions(-)

diff --git a/get-started/_common/intro/_components_intro.md b/get-started/_common/intro/_components_intro.md
index fbdc8fe7..f4aef32b 100644
--- a/get-started/_common/intro/_components_intro.md
+++ b/get-started/_common/intro/_components_intro.md
@@ -1,20 +1,28 @@
-**Components** are the foundational building blocks of software running in
+
+**组件**是 Fuchsia 中运行的软件的基石。每一个组件都是可以组合的沙盒模块，相互之间通过功能交互。这提高了系统安全性并在各个组件之间建立了清晰的接口，使它们更容易更新或替换。
 
-In Fuchsia, **everything is a component** (almost). Recall from the previous
+
+Fuchsia 中**一切都是组件**（几乎）。回想一下之前对 Zircon 的讨论，内核有意设计得很小，大多数核心服务都是在用户空间中实现。这意味着在 Fuchsia 上运行的大多数软件都是采用组件框架实现的，包括：
 
-*   User-facing applications
+
+* 面向用户的应用
+* 设备驱动
+* 文件系统
+* 媒体编解码器
+* 网络栈
 
-Outside the kernel there are only a few low-level exceptions not using the
-component framework, such as bootloaders and the `userboot` process.
+
+内核之外只有少数不使用组件框架的底层例外，如引导程序和 `userboot` 进程。
diff --git a/get-started/explore_fuchsia.md b/get-started/explore_fuchsia.md
index 7a9d302c..c1e32ae8 100644
--- a/get-started/explore_fuchsia.md
+++ b/get-started/explore_fuchsia.md
@@ -1,119 +1,85 @@
-
-# 探索 Fuchsia {#explore-fuchsia}
+# Explore Fuchsia {#explore-fuchsia}
 
-
-在设备或模拟器上启动并运行 Fuchsia 后，请查看以下资源：
+Once you have Fuchsia up and running on a device or emulator,
+check out the following resources:
 
-
-*  [运行 ffx 命令](#run-ffx-commands).
-*  [运行示例程序](#run-examples).
-*  [创建 Fuchsia 组件](#create-fuchsia-components).
-*  [贡献修订](#contribute-changes).
+*  [Contribute changes](#contribute-changes).
 
-
-## 运行 ffx 命令 {#run-ffx-commands}
+## Run ffx commands {#run-ffx-commands}
 
-
-[`ffx`][ffx-overview] 是 Fuchsia 目标工作流的主机工具，为所有 Fuchsia 环境和主机平台上提供一致的开发体验。
+and host platforms.
 
-
-以下是一些 `ffx` 命令示例：
+The following are some of `ffx` command examples:
 
-
-* 显示设备列表：
+*   Display the list of devices:
 
     ```posix-terminal
     ffx target list
     ```
 
-
-* 显示设备信息：
+*   Display the device information:
 
     ```posix-terminal
     ffx target show
     ```
 
-
-* 输出设备日志：
+*   Print the device logs:
 
     ```posix-terminal
     ffx log
     ```
 
-
-* 重启设备：
+*   Reboot the device:
 
     ```posix-terminal
     ffx target reboot
     ```
 
-
-## 运行示例
+## Run examples {#run-examples}
 
-
-要试用 Fuchsia 的样例程序，请参考如下指南：
+To try out Fuchsia's sample software, check out the guides below:
 
-
-*   [运行样例组件](/development/run/run-examples.md)
-*   [运行测试组件](/development/run/run-test-component.md)
-*   [运行端到端测试](/development/testing/run_an_end_to_end_test.md)
+*   [Run an end-to-end test](/development/testing/run_an_end_to_end_test.md)
 
-
-## 创建 Fuchsia 组件 {#create-fuchsia-components}
+## Create Fuchsia components {#create-fuchsia-components}
 
-
-Fuchsia 中最小可运行软件单元是[组件](/concepts/components/v2)，这些组件通过
-[FIDL](/concepts/fidl/overview.md)（Fuchsia 接口定义语言）协议彼此交互。
+(Fuchsia Interface Definition Language) protocols.
 
-
-要想了解更多有关 Fuchsia 组件和 FIDL 的信息，参考如下指南：
+To learn more about Fuchsia components and FIDL, check out the guides below:
 
-
-*   [构建组件](/development/components/build.md)
-*   [FIDL 概览](/development/languages/fidl/README.md)
-*   [FIDL 教程](/development/languages/fidl/tutorials/overview.md)
+*   [FIDL tutorials](/development/languages/fidl/tutorials/overview.md)
 
-
-## 贡献更改 {#contribute-changes}
+## Contribute changes {#contribute-changes}
 
-
-当您准备好为 Fuchsia 项目做出贡献时，请参阅[贡献更改][contribute-changes]。
+When you're ready to contribute to the Fuchsia project,
+see [Contribute changes][contribute-changes].
 
-
-## 参阅
+## See also
 
-
-要获取关于 Fuchsia 开发流程的更多信息，请参阅下列资源：
+For more information on Fuchsia's development workflows,
+check out the following resources:
 
-
-*   [fx 工作流程](/development/build/fx.md)
-*   [工作流程技巧和问题](/development/source_code/workflow_tips_and_faq.md)
-*   [配置编辑器](/development/editors/)
-*   [源码规划](/development/source_code/layout.md)
-*   [构建系统](/development/build/build_system/index.md)
+*   [Build system](/development/build/build_system/index.md)
 
 
 
-
 [fidl-concepts]: /concepts/fidl/overview.md
 [run-fuchsia-tests]: /development/testing/run_fuchsia_tests.md
 [scenic]: /concepts/ui/scenic/index.md
-[contribute-changes]: /development/source_code/contribute_changes.md -->
-[组件]: /concepts/components/v2
-[运行示例程序]: /development/run/run-examples.md
-[ffx 命令概览]: /development/tools/ffx/overview.md
-[fidl]: /development/languages/fidl
-[fidl 指南]: /development/languages/fidl/tutorials/overview.md
-[fidl 概念]: /concepts/fidl/overview.md
-[运行 fuchsia 测试]: /development/testing/run_fuchsia_tests.md
-[scenic]: /concepts/ui/scenic/index.md
-[贡献更改]: /development/source_code/contribute_changes.md
+[contribute-changes]: /development/source_code/contribute_changes.md

From c585fb14786838a41c560eb6ccf21c4bbc522c46 Mon Sep 17 00:00:00 2001
From: y2-Whyto 
Date: Mon, 8 Aug 2022 12:30:25 +0800
Subject: [PATCH 086/112] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20capability?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 glossary-translation.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/glossary-translation.md b/glossary-translation.md
index 1c5049f6..6b08568d 100644
--- a/glossary-translation.md
+++ b/glossary-translation.md
@@ -24,6 +24,7 @@
 | best practice                  | 最佳做法               | G & i                                                 |
 | board                          | 板型                   | i                                                     |
 | build                          | 构建                   | G                                                     |
+| capability                     | 能力                   | i                                                     |
 | caveats                        | 注意事项               | G                                                     |
 | cleanup                        | 清理                   | G                                                     |
 | compile                        | 编译                   | G                                                     |
@@ -80,7 +81,7 @@
 | unmount                        | 卸载                   | G                                                     |
 | URL                            | 网址                   | G                                                     |
 | validate                       | 验证                   | G                                                     |
-| Next steps                     | 后续步骤                   | G                                                     |
+| Next steps                     | 后续步骤               | G                                                     |
 
 ## 文档中未出现术语的翻译参考表
 

From daa955a9cccad29a9ddfbd82fd3151e69222ab57 Mon Sep 17 00:00:00 2001
From: y2-Whyto 
Date: Mon, 8 Aug 2022 17:22:16 +0800
Subject: [PATCH 087/112] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20accessibility?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 glossary-translation.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/glossary-translation.md b/glossary-translation.md
index 6b08568d..4a774ebf 100644
--- a/glossary-translation.md
+++ b/glossary-translation.md
@@ -12,6 +12,7 @@
 
 | 英文原文                       | 中文翻译对应词         | 备注                                                  |
 | ------------------------------ | ---------------------- | ----------------------------------------------------- |
+| accessibility                  | 无障碍功能             | G                                                     |
 | application                    | 应用 
 应用程序     |                                                       |
 | ArchiveAccessor                | 档案访问器             | i                                                     |
 | archivist                      | 归档器                 | i                                                     |

From eb8f6591c9415bf87e3354fd3d22eeffd0593e0b Mon Sep 17 00:00:00 2001
From: wwvm <51313548+wwvm@users.noreply.github.com>
Date: Mon, 8 Aug 2022 19:08:47 +0800
Subject: [PATCH 088/112] Update
 get-started/_common/components/_product_session.md

Co-authored-by: y2-Whyto 
---
 get-started/_common/components/_product_session.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/get-started/_common/components/_product_session.md b/get-started/_common/components/_product_session.md
index 9c87a511..83726bc2 100644
--- a/get-started/_common/components/_product_session.md
+++ b/get-started/_common/components/_product_session.md
@@ -6,7 +6,7 @@ session framework serves as a boundary between the Fuchsia platform and the
 product-level user interaction. Each Fuchsia product defines a single session
 instance as the root of the product experience, which may or may not manage
 additional child components. -->
-会话是一系列封装了产品用户体验的组件。会话框架充当 Fuchsia 平台和产品级用户交互之间的边界。每个 Fuchsia 产品都将单个会话实例定义为产品体验的根，并可能管理其他子组件。
+会话是一系列封装了产品用户体验的组件。会话框架充当 Fuchsia 平台和产品级用户之间交流的边界。每个 Fuchsia 产品都将单个会话实例定义为产品体验的根，它可能管理，也可能不管理其他子组件。
 
 
 
 and offers it a fixed set of capabilities necessary to support the session
 framework APIs for elements such as window management, input event handling, or
 accessibility. -->
-`session_manager` 平台组件在启动时打开会话组件，并为其提供一组固定的功能，以支持诸如窗口管理、输入事件处理或可访问元素的会话框架 API。
+`session_manager` 平台组件在启动时打开会话组件，并为其提供一组固定的功能，以支持诸如窗口管理、输入事件处理或无障碍功能等元素的会话框架 API。
 
 

From a8e09fc0183713af52321b0e29781fb7ddeaf9e6 Mon Sep 17 00:00:00 2001
From: tabidachinokaze 
Date: Tue, 9 Aug 2022 00:55:08 +0800
Subject: [PATCH 090/112] =?UTF-8?q?capability=20/=20capabilities=20?=
 =?UTF-8?q?=E7=BF=BB=E8=AF=91=E6=9B=BF=E6=8D=A2=E4=B8=BA=E8=83=BD=E5=8A=9B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../_common/components/_organizing_intro.md   | 22 +++++++++----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/get-started/_common/components/_organizing_intro.md b/get-started/_common/components/_organizing_intro.md
index 8be5db0c..b23dbc34 100644
--- a/get-started/_common/components/_organizing_intro.md
+++ b/get-started/_common/components/_organizing_intro.md
@@ -6,7 +6,7 @@ with capabilities. At the same time, child components can expose capabilities
 back to the parent. These component instance and capability relationships make
 up the **component topology**.
  -->
-系统中的所有组件组成一个有根的**组件实例树**。树中的父组件负责将其他组件的实例声明为其子组件并为它们提供功能。同时，子组件可以向父组件公开功能。这些组件实例和功能关系构成了**组件拓扑**。
+系统中的所有组件组成一个有根的**组件实例树**。树中的父组件负责将其他组件的实例声明为其子组件并为它们提供能力。同时，子组件可以向父组件公开能力。这些组件实例和能力关系构成了**组件拓扑**。
 
 
-任何父组件及其所有子组件在树中形成一个称为**领域**的组。领域使父级能够控制哪些功能流入和流出其组件的子树，从而创建功能边界。这种封装允许领域在内部进行重组，而不会影响依赖于其公开功能的外部组件。
+任何父组件及其所有子组件在树中形成一个称为**领域**的组。领域使父级能够控制那些能力流入和流出其组件的子树，从而创建能力边界。这种封装允许领域在内部进行重组，而不会影响依赖于其公开能力的外部组件。
 
 
-![图表展示了组件实例被组织成一个树，父组件通过“功能路由”确定每个子组件可用的功能。](/get-started/images/components/component-topology.png){: width="616"}
+![图表展示了组件实例被组织成一个树，父组件通过“能力路由”确定每个子组件可用的能力。](/get-started/images/components/component-topology.png){: width="616"}
 
 
-在上图中，`fuchsia.example.Foo` 协议功能通过组件实例树从提供者路由到客户端。组件使用 `use` 关键字声明它们**需要**的功能：
+在上图中，`fuchsia.example.Foo` 协议能力通过组件实例树从提供者路由到客户端。组件使用 `use` 关键字声明它们**需要**的能力：
 
 
-组件使用组件清单中的 `capabilities` 部分声明它们实现或**提供**的功能。这使得组件框架知道该功能和它的提供者。请查看下面的 `provider.cml` 示例：
+组件使用组件清单中的 `capabilities` 部分声明它们实现或**提供**的能力。这使得组件框架知道该能力和它的提供者。请查看下面的 `provider.cml` 示例：
 
 
-`expose` 关键字使这个组件的功能通过它的父组件向其他领域提供，这也可能包括这个组件的子组件提供的功能。在这种情况下，功能的来源是 `self`，因为这个组件是提供者。
+`expose` 关键字使这个组件的能力通过它的父组件向其他领域提供，这也可能包括这个组件的子组件提供的能力。在这种情况下，能力的来源是 `self`，因为这个组件是提供者。
 
 
-父组件控制领域内的**功能路由**，创建从客户端组件到提供者的显式路径。请查看以下 `parent.cml` 清单示例：
+父组件控制领域内的**能力路由**，创建从客户端组件到提供者的显式路径。请查看以下 `parent.cml` 清单示例：
 
 ```json5
 {
@@ -178,7 +178,7 @@ enables multiple components in the topology to provide the same capability, as
 the component framework relies on explicit routes to determine how to resolve
 the requests from each client.
  -->
-父组件在领域中声明一组子组件，并使用 `offer` 关键字将功能路由到它们。用这种方法，父组件就决定了每个子组件功能的范围和来源。这也使拓扑中的多个组件能够提供相同的功能，因为组件框架依赖于显式路由来确定如何解析来自每个客户端的请求。
+父组件在领域中声明一组子组件，并使用 `offer` 关键字将能力路由到它们。用这种方法，父组件就决定了每个子组件能力的范围和来源。这也使拓扑中的多个组件能够提供相同的能力，因为组件框架依赖于显式路由来确定如何解析来自每个客户端的请求。
 
 
-* **静态地**：该实例在组件清单中被声明为树中另一个组件的子组件。静态组件仅当一个更新更改组件拓扑时才会创建和销毁。
+* **静态地**：该实例在组件清单中被声明为树中另一个组件的子组件。静态组件仅当一个更新改变了组件拓扑时才会创建和销毁。
 
-框架会启动一个组件实例当另一个组件尝试打开一个通道到该组件实例时——这称为**绑定**。当连接到一个由组件公开的能力时，绑定会**隐式**发生。绑定到已经启动的组件会连接到当前运行的实例。
+当一个组件尝试打开到另一组件的通道时（这称为**绑定**（binding）），框架会启动后者的一个组件实例。当连接到由组件所暴露的能力时，绑定会**隐式**发生。对已经启动的组件进行绑定，会连接到其当前运行的实例。
 
 
-组件可能会通过退出程序（由组件的 `runner` 定义）自行停止，或者框架可能会在系统关闭时停止组件。在被销毁之前，框架将组件移动到**关闭**状态以指示它不能再次启动。
+组件可能会通过退出程序（由组件的 `runner` 定义）自行停止，或者可能由框架在系统关闭时停止。在被销毁之前，框架将组件移动到**关闭**状态以表示它不能再次启动。
 
 
-`test_manager` 组件负责在 Fuchsia 设备上运行测试。它检查实现测试套件协议的组件,并将它们作为子组件启动。这意味着 `test_manager` 也负责为每个测试套件提供能力，即创建通常称为**测试领域**的东西。
+`test_manager` 组件负责在 Fuchsia 设备上运行测试。它检查实现测试套件协议的组件，并将它们作为子组件启动。这意味着 `test_manager` 也负责为每个测试套件提供能力，即创建通常所谓的**测试领域**。
 
 
-`ffx test` 等开发者工具与设备上的 `test_manager` 进行通信，以执行测试套件并检索结果。
+`ffx test` 等开发者工具与设备上的 `test_manager` 进行通信，以执行测试套件并取回结果。

From b2e6dc6fc135d1aee34749b8bec5528ae00d2723 Mon Sep 17 00:00:00 2001
From: cwolf9 <2717232422@qq.com>
Date: Tue, 9 Aug 2022 09:18:14 +0800
Subject: [PATCH 093/112] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E4=B8=8D=E5=B8=B8?=
 =?UTF-8?q?=E8=A7=81=E5=8D=95=E8=AF=8D=E7=9A=84=E7=BF=BB=E8=AF=91=E6=A0=87?=
 =?UTF-8?q?=E6=B3=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 get-started/_common/fidl/_testing_intro.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/get-started/_common/fidl/_testing_intro.md b/get-started/_common/fidl/_testing_intro.md
index 159e3aa8..20be291d 100644
--- a/get-started/_common/fidl/_testing_intro.md
+++ b/get-started/_common/fidl/_testing_intro.md
@@ -7,4 +7,4 @@ and other dependencies as children. Depending on the nature of the test,
 dependency components may be provided as mocks or stubs to promote that the test
 cases remain hermetic.
 -->
-[集成测试](https://en.wikipedia.org/wiki/Integration_testing){:.external} 侧重于验证组件的行为，因为它会与系统上其他组件进行交互。正因为如此，集成测试通常与主组件分开构建，并且可以将被测组件和其他依赖组件声明为子组件。根据测试的性质，依赖组件可以作为模拟或存根提供，以促进测试用例保持封闭性。
+[集成测试](https://en.wikipedia.org/wiki/Integration_testing){:.external} 侧重于验证组件的行为，因为它会与系统上其他组件进行交互。正因为如此，集成测试通常与主组件分开构建，并且可能将被测组件和其他依赖组件声明为子组件。根据测试的性质，依赖组件可以作为模拟（mock）或存根（stub）提供，以促进测试用例保持封闭性。

From d6d26aa755b5eec72208c70acedb3505c4e9a40a Mon Sep 17 00:00:00 2001
From: y2-Whyto 
Date: Tue, 9 Aug 2022 20:21:50 +0800
Subject: [PATCH 094/112] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20job?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

https://developer.android.com/kotlin/coroutines/coroutines-adv
---
 glossary-translation.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/glossary-translation.md b/glossary-translation.md
index 4a774ebf..4d0bf7a0 100644
--- a/glossary-translation.md
+++ b/glossary-translation.md
@@ -52,6 +52,7 @@
 | in-tree                        | 树内                   | G 
 此处指源码树                                   |
 | infrastructure                 | 基础架构               | G                                                     |
 | inspect                        | 审视                   | Fuchsia 专有名词 
 i                               |
+| job                            | 作业                   | G                                                     |
 | just-in-time (JIT) compilation | 即时（JIT）编译        | G                                                     |
 | moniker                        | 代称                   | i                                                     |
 | mount                          | 装载                   | G                                                     |

From efb6573aaa588b2a2179570a755bf7a59d3503ec Mon Sep 17 00:00:00 2001
From: y2-Whyto 
Date: Tue, 9 Aug 2022 20:38:04 +0800
Subject: [PATCH 095/112] parse, parser

---
 glossary-translation.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/glossary-translation.md b/glossary-translation.md
index 4d0bf7a0..cd8b978c 100644
--- a/glossary-translation.md
+++ b/glossary-translation.md
@@ -58,6 +58,8 @@
 | mount                          | 装载                   | G                                                     |
 | namespace                      | 命名空间               | G                                                     |
 | out-of-tree                    | 树外                   | G 
 此处指源码树                                   |
+| parse                          | 解析                   | G                                                     |
+| parser                         | 解析器                 | G                                                     |
 | path                           | 路径                   | G                                                     |
 | pave                           | 铺设                   | i                                                     |
 | policy                         | 政策                   | G                                                     |

From a2574ef4db918e04f84e51257fc84393f1314864 Mon Sep 17 00:00:00 2001
From: y2-Whyto 
Date: Tue, 9 Aug 2022 21:13:37 +0800
Subject: [PATCH 096/112] realm

---
 glossary-translation.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/glossary-translation.md b/glossary-translation.md
index cd8b978c..89755e05 100644
--- a/glossary-translation.md
+++ b/glossary-translation.md
@@ -66,6 +66,7 @@
 | prerequisites                  | 前提条件               | G                                                     |
 | product                        | 产品                   | i & G                                                 |
 | proxy                          | 代理                   |                                                       |
+| realm                          | 领域                   | i                                                     |
 | remote                         | 远程                   |                                                       |
 | robust                         | 可靠的                 | G                                                     |
 | sandbox                        | 沙盒                   | G                                                     |

From 6c4d45e0adeed37d66a305b2f3481437f462ea79 Mon Sep 17 00:00:00 2001
From: y2-Whyto 
Date: Tue, 9 Aug 2022 21:45:58 +0800
Subject: [PATCH 097/112] expose

https://support.google.com/cloudidentity/answer/9167101?hl=zh-Hans
https://support.google.com/tagmanager/answer/7683362?hl=zh-Hans
---
 glossary-translation.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/glossary-translation.md b/glossary-translation.md
index 89755e05..ced0929b 100644
--- a/glossary-translation.md
+++ b/glossary-translation.md
@@ -40,6 +40,7 @@
 | ergonomics                     | 工效学                 | i & G                                                 |
 | escalate                       | 上报                   | G                                                     |
 | execute-only memory            | 只执行内存             | G                                                     |
+| expose                         | 公开 
 显示         | G 
 具体选择取决于语境，亦有“公开显示”译法         |
 | fault injection                | 故障注入               | G                                                     |
 | fully qualified URL            | 完全限定的网址         | G                                                     |
 | get stared                     | 使用入门 
 入门     | G 
 前者更常用                                     |

From f74220f76f74148e3da368df56280dcd3322302f Mon Sep 17 00:00:00 2001
From: tabidachinokaze 
Date: Wed, 10 Aug 2022 03:01:30 +0800
Subject: [PATCH 098/112] update

---
 get-started/_common/components/_organizing_intro.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/get-started/_common/components/_organizing_intro.md b/get-started/_common/components/_organizing_intro.md
index b23dbc34..8ef85e7c 100644
--- a/get-started/_common/components/_organizing_intro.md
+++ b/get-started/_common/components/_organizing_intro.md
@@ -184,4 +184,4 @@ the requests from each client.
 Note: For more details on component organization, see
 [Component topology](/concepts/components/v2/topology.md).
  -->
-注意：要获取关于组件组织的更多详细信息，请参阅[组件拓扑](/concepts/components/v2/topology.md).
+注意：要获取关于组件组织的更多详细信息，请参阅[组件拓扑](/concepts/components/v2/topology.md)。

From ebe0f88a3775212371c1b96035b77618e69cf71a Mon Sep 17 00:00:00 2001
From: wy 
Date: Wed, 10 Aug 2022 22:24:20 +0800
Subject: [PATCH 099/112] get_fuchsia_source.md file review

---
 get-started/get_fuchsia_source.md | 88 +++++++++++++++++--------------
 1 file changed, 48 insertions(+), 40 deletions(-)

diff --git a/get-started/get_fuchsia_source.md b/get-started/get_fuchsia_source.md
index 4ad24397..cd7212b3 100644
--- a/get-started/get_fuchsia_source.md
+++ b/get-started/get_fuchsia_source.md
@@ -1,13 +1,13 @@
 
-# 下载 Fuchsia 源码
+# 下载 Fuchsia 源代码
 
-本指南说明了如何下载 Fuchsia 源码以及在您的机器上部署开发环境。
+本指南说明了如何下载 Fuchsia 源代码以及在您的机器上部署开发环境。
 
@@ -21,7 +21,7 @@ The steps are:
 -->
 1. [执行预检查](#perform-a-preflight-check).
 2. [安装必备软件包](#install-prerequisite-packages).
-3. [下载 Fuchsia 源码](#download-the-fuchsia-source-code).
+3. [下载 Fuchsia 源代码](#download-the-fuchsia-source-code).
 4. [设置环境变量](#set-up-environment-variables).
 5. [配置防火墙规则（可选）](#configure-firewall-rules).
 
@@ -35,13 +35,13 @@ Fuchsia provides a preflight check tool
 that examines your machine and informs you of any issues that may
 affect building Fuchsia from source on the machine.
 -->
-Fuchsia 提供了一个预检工具（[`ffx platform preflight`][ffx-platform-preflight]），这个工具可以测试您的机器，并会通知您任何在该机器上构建 Fuchsia 源码时会受影响的问题。
+Fuchsia 提供了一个预检查工具（[`ffx platform preflight`][ffx-platform-preflight]），这个工具可以测试您的机器，并会通知您在该机器上可能会影响从源代码构建 Fuchsia 的任何问题。
 
-注意：这个预检测工具只支持 x64 架构。目前 Fuchsia 不保证在其他宿主架构上能构建成功，比如 Windows 和 ARM64。
+注意：这个预检查工具只支持 x64 架构。目前 Fuchsia 不保证在其他宿主架构上能构建成功，比如 Windows 和 ARM64。
 
 
@@ -67,19 +68,21 @@ Run the following command:
 Fuchsia requires `curl`, `file`, `unzip`, and `git` to be up to date. The version
 of `git` needs to be 2.28 or higher.
 -->
-Fuchsia 要求 `curl`、 `file`、 `unzip` 以及 `git` 等工具是最新版。 `git` 版本要求 2.28 或以上。
+Fuchsia 要求 `curl`、 `file`、 `unzip` 以及 `git` 等工具是最新版。 `git` 版本需为 2.28 或以上。
 
 * {Linux}
+
 
-  安装（或更新）下面的软件包：
+  安装（或更新）以下软件包：
 
   ```posix-terminal
   sudo apt install curl file git unzip
   ```
 
 * {macOS}
+
 
   安装 Xcode 命令行工具：
 
-  注意：如果 `ffx platform preflight` 检测到 Xcode 工具已经安装，就可以跳过这一步。
+  注意：如果 `ffx platform preflight` 显示 Xcode 工具已经安装，则请跳过这一步。
 
   ```posix-terminal
   xcode-select --install
   ```
+
 
-## 3. 下载 Fuchsia 源码 {#download-the-fuchsia-source-code}
+## 3. 下载 Fuchsia 源代码 {#download-the-fuchsia-source-code}
 
-Fuchsia 提供了一个[引导脚本](/scripts/bootstrap)，这个脚本会创建一个 `fuchsia` 的文件夹并把 Fuchsia 源码下载到这里。
+Fuchsia 提供了一个[引导脚本](/scripts/bootstrap)，这个脚本会创建一个名为 `fuchsia` 的文件夹，并把 Fuchsia 源码下载到这里。
 
-下载 Fuchsia 源码要求您机器上有 2 GB 的存储空间。取决于您的构建配置，之后的构建 Fuchsia 过程则需要额外 80 到 90 GB 的存储空间。另外，下载过程中也会使用大量的内存。建议您在此过程中关闭其他非必要的程序进程。
+下载 Fuchsia 源码要求您机器上有大约 2 GB 的存储空间。根据您的构建配置，之后在构建 Fuchsia 时，您还额外需要 80 到 90 GB 的存储空间。另外，下载过程中也会使用大量的内存。建议您在此过程中关闭其他非必要的进程。
 
-下载 Fuchsia 源码，请按如下步骤：
+要下载 Fuchsia 源代码，请执行如下步骤：
 
-1. 选择一个 Fuchsia 源码下载目录，例如：
+1. 选择一个 Fuchsia 源代码下载目录，例如：
     
-    注意：您可以把 Fuchsia 下载到任何路径。本篇教程选择 `$HOME` 作为示例。
+    注意：您可以在任何目录下设置 Fuchsia。本指南选择 `$HOME` 作为示例。
 
     ```posix-terminal
     cd $HOME
     ```
+
 
 1.  运行引导脚本：
     
-    注意：下载 Fuchsia 源码可能需要 60 分钟。
+    注意：下载 Fuchsia 源代码可能需要 60 分钟。
 
     ```posix-terminal
     curl -s "https://fuchsia.googlesource.com/fuchsia/+/HEAD/scripts/bootstrap?format=TEXT" | base64 --decode | bash
@@ -147,9 +152,9 @@ To download the Fuchsia source, do the following:
     bootstrapping process, see [Authentication error](#authentication-error) for
     help.
 -->
-    这个脚本会创建 `fuchsia` 目录，并且下载源码。
+    这个脚本会创建 `fuchsia` 目录，并且下载源代码。
 
-    如果您在脚本运行期间看到了 `Invalid authentication credentials` 错误信息，参考[认证错误](#authentication-error)章节寻求帮助。
+    如果您在脚本运行期间看到了 `Invalid authentication credentials` 错误信息，请参考[认证错误](#authentication-error)章节寻求帮助。
 
 
-Fuchsia 建议您在 shell 的配置文件中添加如下几个配置：
+Fuchsia 建议您按照如下操作更新 shell 配置文件：
 
 *  添加 `.jiri_root/bin` 目录到您的 `PATH` 环境变量
     
-   Fuchsia 源码中的 `.jiri_root/bin` 目录包含了 [`jiri`](https://fuchsia.googlesource.com/jiri) 和 [`fx`](/development/build/fx.md) 工具，这些是 Fuchsia 工作流中的必备工具。Fuchsia 使用 `jiri` 工具在 Fuchsia 的项目中管理仓库，使用 `fx` 工具帮助配置、构建、运行以及调试 Fuchsia。Fuchsia 的工具链需要可以在您的 `PATH` 环境变量中找到 `jiri` 工具。
+   Fuchsia 源码中的 `.jiri_root/bin` 目录包含了 [`jiri`](https://fuchsia.googlesource.com/jiri) 和 [`fx`](/development/build/fx.md) 工具，这些是 Fuchsia 工作流中的必备工具。Fuchsia 使用 `jiri` 工具在 Fuchsia 的项目中管理仓库，而 `fx` 工具能够帮助配置、构建、运行以及调试 Fuchsia。Fuchsia 的工具链需要可以在您的 `PATH` 环境变量中找到 `jiri` 工具。
 
-注意：如果您不想更新您的 shell 配置，参考附录[不更新 PATH 变量的情况下在 Fuchsia 上工作](#work-on-fuchsia-without-updating-your-path)。
+注意：如果您不想更新您的 shell 配置，则请参阅[在不更新 PATH 变量的情况下处理 Fuchsia](#work-on-fuchsia-without-updating-your-path)。
 
-为了更新您的 shell 配置文件来设置 Fuchsia 的环境变量，请按如下步骤：
+要更新您的 shell 配置文件来设置 Fuchsia 的环境变量，请执行如下步骤：
 
-1.  请用文本编辑器打开您的 `~/.bash_profile` 文件（参考如下示例，我们使用 [Nano][nano]{:.external} 文本编辑器）
+1.  使用文本编辑器打开您的 `~/.bash_profile` 文件（在以下示例中，我们使用 [Nano][nano]{:.external} 文本编辑器）：
 
-    注意：本指南使用 `bash` 终端作为示例，如果您使用 `zsh` 的话，在如下步骤中请替换 `~/.bash_profile` 为 `~/.zprofile`：
+    注意：本指南使用 `bash` 终端作为示例，如果您使用 `zsh`，请在后续步骤中请替换 `~/.bash_profile` 为 `~/.zprofile`：
 
     ```posix-terminal
     nano ~/.bash_profile
     ```
+
 
 1.  在您的 `~/.bash_profile` 文件中添加如下配置：
 
-    注意：如果您的 Fuchsia 源码不在 `~/fuchsia` 目录下，替换 `~/fuchsia` 为您的 Fuchsia 目录。
+    注意：如果您的 Fuchsia 源码不在 `~/fuchsia` 目录下，则请替换 `~/fuchsia` 为您的 Fuchsia 目录。
+
 
     ```sh
     export PATH=~/fuchsia/.jiri_root/bin:$PATH
     source ~/fuchsia/scripts/fx-env.sh
     ```
+
 
@@ -235,16 +243,17 @@ do the following:
 
-1.  更新环境变量，请运行如下命令：
+1.  要更新环境变量，请运行如下命令：
 
     ```posix-terminal
     source ~/.bash_profile
     ```
+
 
-1.  验证您是否可以运行如下命令且没有报错：
+1.  验证您可以在您的 `fuchsia` 目录内运行如下命令且没有报错：
 
     ```posix-terminal
     jiri help
@@ -264,9 +273,9 @@ recommended to ensure that Fuchsia's emulator instances run smoothly on Linux.
 (**Linux only**) If you're planning on running Fuchsia on Linux, it is advised to
 run the following command to allow Fuchsia-specific traffic on the host machine:
 -->
-注意：这一步对构建或者运行 Fuchsia 并不是必需的。但是为了确保 Fuchsia 模拟器实例能在 Linux 上顺利运行是推荐的。
+注意：这一步对构建或者运行 Fuchsia 并不是必需的。但是推荐您进行该步骤，以确保 Fuchsia 模拟器实例能在 Linux 上流畅运行。
 
-(**仅限 Linux**) 如果您计划在 Linux 中运行 Fuchsia，建议您运行如下命令在宿主机上允许 Fuchsia 相关的流量：
+(**仅限 Linux**) 如果您计划在 Linux 中运行 Fuchsia，那么建议您运行如下命令，在宿主机上允许 Fuchsia 特定流量：
 
 ```posix-terminal
 fx setup-ufw
@@ -275,7 +284,7 @@ fx setup-ufw
 This script requires `sudo` (which asks for your password) to set the appropriate
 firewall rules. (For more information on this script, see [`setup-ufw`][setup-ufw].)
 -->
-这个脚本需要 `sudo` （会提示您输入密码）权限来设置防火墙规则。（更多关于脚本的的信息，参考 [`setup-ufw`][setup-ufw] 文件）。
+该脚本需要 `sudo` 权限（会要求您输入密码）来设置适当的防火墙规则。（要获取关于该脚本的更多信息，请参考 [`setup-ufw`][setup-ufw]）。
 
@@ -285,7 +294,7 @@ firewall rules. (For more information on this script, see [`setup-ufw`][setup-uf
 To build your first Fuchsia system image, see
 [Configure and build Fuchsia](/get-started/build_fuchsia.md).
 -->
-要构建您第一个 Fuchsia 系统镜像，请参考[配置和构建 Fuchsia](/get-started/build_fuchsia.md)。
+要构建您第一个 Fuchsia 系统镜像，请参阅[配置和构建 Fuchsia](/get-started/build_fuchsia.md)。
 
@@ -299,7 +308,7 @@ If you see the `Invalid authentication credentials` error during the bootstrap
 process, your `~/.gitcookies` file may contain cookies from some repositories in
 `googlesource.com` that the bootstrap script wants to check out anonymously.
 -->
-如果您在引导脚本运行过程中看到了 `Invalid authentication credentials` 报错信息，那么您的 `~/.gitcookies` 文件中可能包含了来自 `googlesource.com` 中一些仓库的 cookie，引导脚本想要匿名检出。
+如果您在引导脚本运行过程中看到了 `Invalid authentication credentials`（无效的认证凭据）错误信息，那么您的 `~/.gitcookies` 文件中可能含有来自 `googlesource.com` 中一些仓库的 cookie，引导脚本想要匿名检查。
 
@@ -311,7 +320,7 @@ To resolve this error, do one of the following:
 *   Delete the offending cookies from the `.gitcookies` file.
 -->
 
-*  按照屏幕上的指示为特定的仓库获取密码。
+*  按照屏幕上的指示为指定仓库获取密码。
 *  删除 `.gitcookies` 文件中有问题的 cookie。
 
 
-下面的章节为[设置环境变量](#set-up-environment-variables)章节提供了替代选项：
+下面的章节为[设置环境变量](#set-up-environment-variables)章节提供了替代方法：
 
-如果您不想更新您的环境变量，但是您想在任何目录中使用 `jiri` 工具，把 `jiri` 工具复制到 `~/bin` 目录中，比如：
+如果您不想更新您的环境变量，但是想在任何目录中使用 `jiri` 工具，那么请把 `jiri` 工具复制到 `~/bin` 目录中，比如：
 
-注意：如果您的 Fuchsia 源码不在 `~/fuchsia` 目录中，把 `~/fuchsia` 替换为您的 Fuchsia 目录。
+注意：如果您的 Fuchsia 源码不在 `~/fuchsia` 目录中，则请把 `~/fuchsia` 替换为您的 Fuchsia 目录。
 
 ```posix-terminal
 cp ~/fuchsia/.jiri_root/bin/jiri ~/bin
@@ -354,7 +363,7 @@ cp ~/fuchsia/.jiri_root/bin/jiri ~/bin
 However, you must have write access to the `~/bin` directory without `sudo`. If
 you don't, `jiri` cannot keep itself up-to-date.
 -->
-但是，您需要在没有 `sudo` 的情况下对 `~/bin` 有写访问权限。如果没有，`jiri` 就不能保持在最新版本。
+但是，您必须在没有 `sudo` 的情况下对 `~/bin` 有写访问权限。否则，`jiri` 无法自动保持最新版本。
 
@@ -367,10 +376,9 @@ example:
 Note: If your Fuchsia source code is not located in the `~/fuchsia` directory,
 replace `~/fuchsia` with your Fuchsia directory.
 -->
-同样的，如果您想不更新环境变量使用 `fx` 工具，在 `~/bin` 路径中提供您的 `fx` 工具的链接文件，比如：
-同样的，如果您想不更新环境变量而使用 `fx` 工具，在 `~/bin` 目录中提供 `fx` 工具的符号链接，比如：
+同样地，如果您想在不更新环境变量的情况下使用 `fx` 工具，则请在 `~/bin` 路径中添加您 `fx` 工具的链接文件，比如：
 
-注意：如果您的 Fuchsia 源码不在 `~/fuchsia` 目录中，把 `~/fuchsia` 替换为您的 Fuchsia 目录。
+注意：如果您的 Fuchsia 源码不在 `~/fuchsia` 目录中，则请把 `~/fuchsia` 替换为您的 Fuchsia 目录。
 
 ```posix-terminal
 ln -s ~/fuchsia/scripts/fx ~/bin
@@ -378,7 +386,7 @@ ln -s ~/fuchsia/scripts/fx ~/bin
 
-或者，直接用其路径运行 `fx` 工具，比如：
+或者，请直接使用 `fx` 工具的路径来运行，比如：
 
 ```posix-terminal
 ./scripts/fx help

From bf555589879a1641cd20f9c10fe5276f7896d1b8 Mon Sep 17 00:00:00 2001
From: Xyct <87l46110@gmail.com>
Date: Thu, 11 Aug 2022 14:46:46 +0800
Subject: [PATCH 100/112] Update get-started/_common/intro/_architecture.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

广泛的 --> 各种

Co-authored-by: y2-Whyto 
---
 get-started/_common/intro/_architecture.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/get-started/_common/intro/_architecture.md b/get-started/_common/intro/_architecture.md
index aee80ff5..9455f7c9 100644
--- a/get-started/_common/intro/_architecture.md
+++ b/get-started/_common/intro/_architecture.md
@@ -14,7 +14,7 @@ architecture, highlighting core components and subsystems.]
   Fuchsia makes it easy to create, maintain, and integrate software and hardware across a wide range of devices.
  -->
 
-* [**简单：**][simple]Fuchsia 让创建、维护和集成软件与硬件在广范的设备中都变得容易。
+* [**简单：**][simple]Fuchsia 让创建、维护和集成软件与硬件在各种设备中都变得容易。
 
+## 驱动框架
 
+
+与会话类似，Fuchsia 驱动框架使开发人员能够将产品特定的设备驱动程序实现为组件。一些驱动程序组件代表硬件接口控制器，例如 PCI 或 USB，而其他驱动程序组件则与终端设备交互，例如以太网控制器或键盘。
 
+
+当设备被发现或连接到系统时，`driver_manager` 平台组件启动必要的驱动程序组件，将它们绑定到硬件接口，并管理它们的生命周期。
 
+
+注：要获取关于驱动框架的更多细节，请参阅[Fuchsia 驱动框架](/development/drivers/concepts/fdf.md)。

From 273d0837a8f5ee7c3e991641b6986a2c8afb366a Mon Sep 17 00:00:00 2001
From: y2-Whyto 
Date: Thu, 11 Aug 2022 21:07:29 +0800
Subject: [PATCH 103/112] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=20#184?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 get-started/_common/components/_product_driver.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/get-started/_common/components/_product_driver.md b/get-started/_common/components/_product_driver.md
index 991bec91..814fc730 100644
--- a/get-started/_common/components/_product_driver.md
+++ b/get-started/_common/components/_product_driver.md
@@ -22,4 +22,4 @@ hardware interfaces, and manages their lifecycle.
 Note: For more details on the driver framework, see
 [Fuchsia Driver Framework](/development/drivers/concepts/fdf.md).
 -->
-注：要获取关于驱动框架的更多细节，请参阅[Fuchsia 驱动框架](/development/drivers/concepts/fdf.md)。
+注：要获取关于驱动框架的更多细节，请参阅 [Fuchsia 驱动框架](/development/drivers/concepts/fdf.md)。

From b6d89702e5bb49319560de844ba9f3e3351a139d Mon Sep 17 00:00:00 2001
From: y2-Whyto 
Date: Fri, 12 Aug 2022 12:47:42 +0800
Subject: [PATCH 104/112] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E5=87=A0=E4=B8=AA=20?=
 =?UTF-8?q?#165=20=E4=B8=AD=E7=9A=84=E4=BF=AE=E6=94=B9=E5=BB=BA=E8=AE=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 get-started/get_fuchsia_source.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/get-started/get_fuchsia_source.md b/get-started/get_fuchsia_source.md
index cd7212b3..4f744d1f 100644
--- a/get-started/get_fuchsia_source.md
+++ b/get-started/get_fuchsia_source.md
@@ -189,16 +189,16 @@ Fuchsia 建议您按照如下操作更新 shell 配置文件：
     navigating directories with auto-completion. (For more information, see
     comments in `fx-env.sh`.)
 -->
-*   导入 `scripts/fx-env.sh` 文件
+*   使用“source”命令导入 `scripts/fx-env.sh` 文件
     
-    虽然这并不是必须的，导入 [`fx-env.sh`](/scripts/fx-env.sh) 文件可以在您的终端中启用一系列有用的 shell 函数。比如，它会创建 `FUCHSIA_DIR` 环境变量，以及提供 `fd` 命令用来在目录中导航时提供自动补全 （如果想获取更多信息，请参考 `fx-env.sh` 文件）。
+    虽然这并不是必须的，但是使用“source”命令导入 [`fx-env.sh`](/scripts/fx-env.sh) 文件可以在您的终端中启用一系列有用的 shell 函数。比如，它会创建 `FUCHSIA_DIR` 环境变量，以及提供 `fd` 命令用来在目录中导航时提供自动补全 （要获取更多信息，请参阅 `fx-env.sh` 中的注释）。
 
 
-注意：如果您不想更新您的 shell 配置，则请参阅[在不更新 PATH 变量的情况下处理 Fuchsia](#work-on-fuchsia-without-updating-your-path)。
+注意：如果您不想更新您的 shell 配置，则请参阅[在不更新 PATH 变量的情况下准备 Fuchsia](#work-on-fuchsia-without-updating-your-path)。
 
-###  不更新 PATH 变量编译 Fuchsia {#work-on-fuchsia-without-updating-your-path}
+###  在不更新 PATH 变量的情况下准备 Fuchsia {#work-on-fuchsia-without-updating-your-path}
 
+协议句柄是一个很常见的对象，它提供了一个 FIDL 协议的实现，FIDL 协议可以通过组件命名空间找到。组件框架使用能力促进了[组件](/glossary/README.md#component)之间的协议发现。能力路由描述了哪个组件应该作为任何给定客户端的提供者。一旦确定了适当的组件，[组件管理器](/glossary/README.md#component-manager)就会使用每个组件命名空间中的句柄来启动组件之间的连接。
 
+
+请看以下 `fuchsia.example.Foo` 协议的示例：
 
+
+![图中显示了如何连接组件，组件是能力路由和协议服务的结合。组件必须为它们提供给其他组件的协议的实现来提供服务。](/get-started/images/fidl/protocol-serving.png){: width="629"}
 
+
+该图强调了执行连接所涉及的主要元素：
 
+
+1.  提供者组件在清单的 `capabilities` 部分中静态地**声明**协议。这使组件框架能够执行能力路由。
+
+2.  客户端组件在清单（manifest）的 `use` 部分静态地**请求**协议。如果能力路由成功，这将在客户端的命名空间中创建 `/svc/fuchsia.example.Foo` 协议项。
+
+3.  提供者代码在运行时**发布**实现。这将在提供者传出目录中的 `/svc/fuchsia.example.Foo` 处创建一个协议项。
+
+4.  客户端代码在运行时**连接**到协议句柄。这将与运行在提供者组件中的实现打开一个 FIDL 连接。

From 4b2a013788239c52ade76344e8e60e135ffd8891 Mon Sep 17 00:00:00 2001
From: Cwolf9 <35797478+Cwolf9@users.noreply.github.com>
Date: Sat, 13 Aug 2022 10:23:43 +0800
Subject: [PATCH 106/112] Update _connecting_intro.md

---
 get-started/_common/fidl/_connecting_intro.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/get-started/_common/fidl/_connecting_intro.md b/get-started/_common/fidl/_connecting_intro.md
index 0ac40657..d1eecf71 100644
--- a/get-started/_common/fidl/_connecting_intro.md
+++ b/get-started/_common/fidl/_connecting_intro.md
@@ -14,7 +14,7 @@ component's namespace.
 
-请看以下 `fuchsia.example.Foo` 协议的示例：
+请参考以下 `fuchsia.example.Foo` 协议的示例：
 
 
 
 
-注: 要获取关于会话框架的更多细节，请参阅[会话框架介绍](/concepts/session/introduction.md).
+注: 要获取关于会话框架的更多细节，请参阅[会话框架介绍](/concepts/session/introduction.md)。

From 084a4391318f07b05c91ff2d35691399ed7b57f6 Mon Sep 17 00:00:00 2001
From: y2-Whyto 
Date: Wed, 17 Aug 2022 10:28:42 +0800
Subject: [PATCH 108/112] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E5=B8=83=E5=B1=80?=
 =?UTF-8?q?=E9=94=99=E8=AF=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 get-started/get_fuchsia_source.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/get-started/get_fuchsia_source.md b/get-started/get_fuchsia_source.md
index 4f744d1f..43caa1dc 100644
--- a/get-started/get_fuchsia_source.md
+++ b/get-started/get_fuchsia_source.md
@@ -19,11 +19,11 @@ The steps are:
 4. [Set up environment variables](#set-up-environment-variables).
 5. [Configure firewall rules (Optional)](#configure-firewall-rules).
 -->
-1. [执行预检查](#perform-a-preflight-check).
-2. [安装必备软件包](#install-prerequisite-packages).
-3. [下载 Fuchsia 源代码](#download-the-fuchsia-source-code).
-4. [设置环境变量](#set-up-environment-variables).
-5. [配置防火墙规则（可选）](#configure-firewall-rules).
+1. [执行预检查](#perform-a-preflight-check)。
+2. [安装必备软件包](#install-prerequisite-packages)。
+3. [下载 Fuchsia 源代码](#download-the-fuchsia-source-code)。
+4. [设置环境变量](#set-up-environment-variables)。
+5. [配置防火墙规则（可选）](#configure-firewall-rules)。
 
 
-1. 选择一个 Fuchsia 源代码下载目录，例如：
+1.  选择一个 Fuchsia 源代码下载目录，例如：
     
     注意：您可以在任何目录下设置 Fuchsia。本指南选择 `$HOME` 作为示例。
 
@@ -161,11 +161,13 @@ To download the Fuchsia source, do the following:
 ## 4. Set up environment variables {#set-up-environment-variables}
 -->
 ## 4. 设置环境变量 {#set-up-environment-variables}
+
 
 Fuchsia 建议您按照如下操作更新 shell 配置文件：
+
 
-*  添加 `.jiri_root/bin` 目录到您的 `PATH` 环境变量
+*   添加 `.jiri_root/bin` 目录到您的 `PATH` 环境变量
     
-   Fuchsia 源码中的 `.jiri_root/bin` 目录包含了 [`jiri`](https://fuchsia.googlesource.com/jiri) 和 [`fx`](/development/build/fx.md) 工具，这些是 Fuchsia 工作流中的必备工具。Fuchsia 使用 `jiri` 工具在 Fuchsia 的项目中管理仓库，而 `fx` 工具能够帮助配置、构建、运行以及调试 Fuchsia。Fuchsia 的工具链需要可以在您的 `PATH` 环境变量中找到 `jiri` 工具。
+    Fuchsia 源码中的 `.jiri_root/bin` 目录包含了 [`jiri`](https://fuchsia.googlesource.com/jiri) 和 [`fx`](/development/build/fx.md) 工具，这些是 Fuchsia 工作流中的必备工具。Fuchsia 使用 `jiri` 工具在 Fuchsia 的项目中管理仓库，而 `fx` 工具能够帮助配置、构建、运行以及调试 Fuchsia。Fuchsia 的工具链需要可以在您的 `PATH` 环境变量中找到 `jiri` 工具。
+
 
 注意：如果您不想更新您的 shell 配置，则请参阅[在不更新 PATH 变量的情况下准备 Fuchsia](#work-on-fuchsia-without-updating-your-path)。
+
 
 要更新您的 shell 配置文件来设置 Fuchsia 的环境变量，请执行如下步骤：
+
 
 1.  保存文件并退出。
+
 
@@ -263,10 +268,12 @@ do the following:
     ```posix-terminal
     fx help
     ```
+
 
 ## 5. 配置防火墙规则（可选） {#configure-firewall-rules}
+
 
 该脚本需要 `sudo` 权限（会要求您输入密码）来设置适当的防火墙规则。（要获取关于该脚本的更多信息，请参考 [`setup-ufw`][setup-ufw]）。
+
 
@@ -296,20 +305,24 @@ To build your first Fuchsia system image, see
 [Configure and build Fuchsia](/get-started/build_fuchsia.md).
 -->
 要构建您第一个 Fuchsia 系统镜像，请参阅[配置和构建 Fuchsia](/get-started/build_fuchsia.md)。
+
 
 ## 附录
+
 
 ### 认证错误 {#authentication-error}
+
 
 如果您在引导脚本运行过程中看到了 `Invalid authentication credentials`（无效的认证凭据）错误信息，那么您的 `~/.gitcookies` 文件中可能含有来自 `googlesource.com` 中一些仓库的 cookie，引导脚本想要匿名检查。
+
 
@@ -321,18 +334,20 @@ To resolve this error, do one of the following:
 *   Delete the offending cookies from the `.gitcookies` file.
 -->
 
-*  按照屏幕上的指示为指定仓库获取密码。
-*  删除 `.gitcookies` 文件中有问题的 cookie。
+*   按照屏幕上的指示为指定仓库获取密码。
+*   删除 `.gitcookies` 文件中有问题的 cookie。
 
 
-###  在不更新 PATH 变量的情况下准备 Fuchsia {#work-on-fuchsia-without-updating-your-path}
+### 在不更新 PATH 变量的情况下准备 Fuchsia {#work-on-fuchsia-without-updating-your-path}
+
 
 下面的章节为[设置环境变量](#set-up-environment-variables)章节提供了替代方法：
+
 
-####  把工具复制到二进制目录 {#copy-the-tool-to-your-binary-directory}
+#### 把工具复制到二进制目录 {#copy-the-tool-to-your-binary-directory}
+
 
 但是，您必须在没有 `sudo` 的情况下对 `~/bin` 有写访问权限。否则，`jiri` 无法自动保持最新版本。
+
 
 #### 添加符号链接到二进制目录 {#add-a-symlink-to-your-binary-directory}
+
 
 注意：这一步对构建或者运行 Fuchsia 并不是必需的。但是推荐您进行该步骤，以确保 Fuchsia 模拟器实例能在 Linux 上流畅运行。
 
-(**仅限 Linux**) 如果您计划在 Linux 中运行 Fuchsia，那么建议您运行如下命令，在宿主机上允许 Fuchsia 特定流量：
+（**仅限 Linux**）如果您计划在 Linux 中运行 Fuchsia，那么建议您运行如下命令，在宿主机上允许 Fuchsia 特定流量：
 
 ```posix-terminal
 fx setup-ufw

From 1a4cdeffe92820b745e25478be4b1ee53d0a3d4a Mon Sep 17 00:00:00 2001
From: y2-Whyto 
Date: Wed, 17 Aug 2022 16:25:39 +0800
Subject: [PATCH 111/112] =?UTF-8?q?installer=EF=BC=8Clegacy?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

https://support.google.com/chrome/answer/95346?hl=zh-Hans&co=GENIE.Platform%3DDesktop#zippy=,windows,mac

https://support.google.com/google-ads/answer/10514212?hl=zh-Hans
---
 glossary-translation.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/glossary-translation.md b/glossary-translation.md
index a2feb9e9..9394f686 100644
--- a/glossary-translation.md
+++ b/glossary-translation.md
@@ -54,8 +54,10 @@
 | in-tree                        | 树内                   | G 
 此处指源码树                                   |
 | infrastructure                 | 基础架构               | G                                                     |
 | inspect                        | 审视                   | Fuchsia 专有名词 
 i                               |
+| installer                      | 安装程序               | G                                                     |
 | job                            | 作业                   | G                                                     |
 | just-in-time (JIT) compilation | 即时（JIT）编译        | G                                                     |
+| legacy                         | 旧版                   | G                                                     |
 | moniker                        | 代称                   | i                                                     |
 | mount                          | 装载                   | G                                                     |
 | namespace                      | 命名空间               | G                                                     |

From f11690711a26af7a867017fd5a8c02997db0a375 Mon Sep 17 00:00:00 2001
From: y2-Whyto 
Date: Wed, 17 Aug 2022 16:36:25 +0800
Subject: [PATCH 112/112] =?UTF-8?q?=E5=AF=B9=20PR=20=E6=8F=90=E4=BA=A4?=
 =?UTF-8?q?=E8=A6=81=E6=B1=82=E5=81=9A=E4=BA=86=E6=9B=B4=E5=8A=A0=E7=B2=BE?=
 =?UTF-8?q?=E7=A1=AE=E7=9A=84=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 2af2bd9d..8b10ddf1 100644
--- a/README.md
+++ b/README.md
@@ -46,7 +46,6 @@
 ## PR 提交要求
 
  1. 多个翻译请**分文件提交 PR**，即新建分支（branch），在每个分支中只更改一个文件并提交；
- 1. PR 提交时请在**标题区域包含文件名**，以便进行记录；
+ 1. PR 提交时请在**标题区域包含文件的绝对路径**，以便进行查找、核对和记录；
  1. PR 的标题和内容最好使用中文；
- 1. 为避免做重复性工作，请在翻译时**先试译若干节**，并将 PR **[以草稿形式提交](https://docs.github.com/cn/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests)**（[创建草稿 PR](https://docs.github.com/cn/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) 或[提交 PR 后进入并在右侧选择转换为草稿](https://docs.github.com/cn/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#converting-a-pull-request-to-a-draft)），以便校对人员提前开始校对，及时修正当前翻译中存在的可能会在下文中重复出现的格式或内容问题。
- 
+ 1. 为避免做重复性工作，最好在翻译时**先试译若干节**，并将 PR **[以草稿形式提交](https://docs.github.com/cn/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests)**（[创建草稿 PR](https://docs.github.com/cn/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) 或[提交 PR 后进入并在右侧选择转换为草稿](https://docs.github.com/cn/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#converting-a-pull-request-to-a-draft)），以便校对人员提前开始校对，及时修正当前翻译中存在的可能会在下文中重复出现的格式或内容问题。