docs: Provide Chinese translation for template.rst and platformio.rst

docs/en/api-reference/template.rst

@@ -1,12 +1,14 @@
 API Documentation Template
 ==========================
 
+:link_to_translation:`zh_CN:[中文]`
+
 .. note::
 
     *INSTRUCTIONS*
 
     1. Use this file (:idf_file:`docs/en/api-reference/template.rst`) as a template to document API.
-    2. Change the file name to the name of the header file that represents documented API.
+    2. Change the file name to the name of the header file that represents the documented API.
     3. Include respective files with descriptions from the API folder using ``..include::``
 
         * README.rst
@@ -24,15 +26,15 @@ Overview
     *INSTRUCTIONS*
 
     1. Provide overview where and how this API may be used.
-    2. Where applicable include code snippets to illustrate functionality of particular functions.
+    2. Include code snippets to illustrate functionality of particular functions when applicable.
     3. To distinguish between sections, use the following `heading levels <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections>`_:
 
         * ``#`` with overline, for parts
         * ``*`` with overline, for chapters
-        * ``=``, for sections
+        * ``=`` for sections
-        * ``-``, for subsections
+        * ``-`` for subsections
-        * ``^``, for subsubsections
+        * ``^`` for subsubsections
-        * ``"``, for paragraphs
+        * ``"`` for paragraphs
 
 Application Example
 -------------------
@@ -43,9 +45,9 @@ Application Example
 
     1. Prepare one or more practical examples to demonstrate functionality of this API.
     2. Each example should follow pattern of projects located in ``esp-idf/examples/`` folder.
-    3. Place example in this folder complete with ``README.md`` file.
+    3. Place example in this folder, and add ``README.md`` file.
     4. Provide overview of demonstrated functionality in ``README.md``.
-    5. With good overview reader should be able to understand what example does without opening the source code.
+    5. With good overview readers should be able to understand what example does without opening the source code.
     6. Depending on complexity of example, break down description of code into parts and provide overview of functionality of each part.
     7. Include flow diagram and screenshots of application output if applicable.
     8. Finally add in this section synopsis of each example together with link to respective folder in ``esp-idf/examples/``.
@@ -59,9 +61,9 @@ API Reference
 
     *INSTRUCTIONS*
 
-    1. This repository provides for automatic update of API reference documentation using :doc:`code markup retrieved by Doxygen from header files <../contribute/documenting-code>`.
+    1. ESP-IDF repository provides automatic update of API reference documentation using :doc:`code markup retrieved by Doxygen from header files <../contribute/documenting-code>`.
 
-    2. Update is done on each documentation build by invoking Sphinx extension :`esp_extensions/run_doxygen.py` for all header files listed in the ``INPUT`` statement of :idf_file:`docs/doxygen/Doxyfile`.
+    2. Update is done on each documentation build by invoking Sphinx extension ``esp_extensions/run_doxygen.py`` for all header files listed in the ``INPUT`` statement of :idf_file:`docs/doxygen/Doxyfile`.
 
     3. Each line of the ``INPUT`` statement  (other than a comment that begins with ``##``) contains a path to header file ``*.h`` that is used to generate corresponding ``*.inc`` files::
 
@@ -71,9 +73,9 @@ API Reference
         ../components/esp32/include/esp_wifi.h \
         ../components/esp32/include/esp_smartconfig.h \
 
-    4. When the headers are expanded, any macros defined by default in ``sdkconfig.h`` as well as any macros defined in SOC-specific ``include/soc/*_caps.h`` headers will be expanded. This allows the headers to include/exclude material based on the ``IDF_TARGET`` value.
+    4. When the headers are expanded, any macros defined by default in ``sdkconfig.h`` as well as any macros defined in SOC-specific ``include/soc/*_caps.h`` headers will be expanded. This allows the headers to include or exclude material based on the ``IDF_TARGET`` value.
 
-    5. The ``*.inc`` files contain formatted reference of API members generated automatically on each documentation build. All ``*.inc`` files are placed in Sphinx ``_build`` directory. To see directives generated for e.g., ``esp_wifi.h``, run ``python gen-dxd.py esp32/include/esp_wifi.h``.
+    5. The ``*.inc`` files contain formatted reference of API members generated automatically on each documentation build. All ``*.inc`` files are placed in Sphinx ``_build`` directory. To see directives generated, e.g., ``esp_wifi.h``, run ``python gen-dxd.py esp32/include/esp_wifi.h``.
 
     6. To show contents of ``*.inc`` file in documentation, include it as follows::
 
@@ -100,4 +102,4 @@ API Reference
 
     8. In any case, to generate API reference, the file :idf_file:`docs/doxygen/Doxyfile` should be updated with paths to ``*.h`` headers that are being documented.
 
-    9. When changes are committed and documentation is build, check how this section has been rendered. :doc:`Correct annotations <../contribute/documenting-code>` in respective header files, if required.
+    9. When changes are committed and documentation is built, check how this section has been rendered. :doc:`Correct annotations <../contribute/documenting-code>` in respective header files, if required.

docs/en/third-party-tools/platformio.rst

@@ -3,6 +3,8 @@
 PlatformIO
 ##########
 
+:link_to_translation:`zh_CN:[中文]`
+
 .. image:: ../../_static/platformio-logo.png
   :target: https://platformio.org/?utm_source=docs.espressif.com
 
@@ -16,23 +18,15 @@ What is PlatformIO?
 is a cross-platform embedded development environment with out-of-the-box support
 for ESP-IDF.
 
-Since ESP-IDF support within PlatformIO is not maintained by the Espressif team,
+Since ESP-IDF support within PlatformIO is not maintained by the Espressif team, please report any issues with PlatformIO directly to its developers in `the official PlatformIO repositories <https://github.com/platformio>`_.
-please report any issues with PlatformIO directly to its developers in
-`the official PlatformIO repositories <https://github.com/platformio>`_.
 
-A detailed overview of the PlatformIO ecosystem and its philosophy can be
+A detailed overview of the PlatformIO ecosystem and its philosophy can be found in `the official PlatformIO documentation <https://docs.platformio.org/en/latest/what-is-platformio.html?utm_source=docs.espressif.com>`_.
-found in `the official PlatformIO documentation <https://docs.platformio.org/en/latest/what-is-platformio.html?utm_source=docs.espressif.com>`_.
 
 Installation
 ~~~~~~~~~~~~
 
-* `PlatformIO IDE <https://platformio.org/platformio-ide?utm_source=docs.espressif.com>`_
+* `PlatformIO IDE <https://platformio.org/platformio-ide?utm_source=docs.espressif.com>`_ is a toolset for embedded C/C++ development available on Windows, macOS and Linux platforms.
-  is a toolset for embedded C/C++ development available on Windows, macOS and Linux
+* `PlatformIO Core (CLI) <https://docs.platformio.org/en/latest/core/index.html?utm_source=docs.espressif.com>`_ is a command-line tool that consists of multi-platform build system, platform and library managers and other integration components. It can be used with a variety of code development environments and allows integration with cloud platforms and web
-  platforms
-* `PlatformIO Core (CLI) <https://docs.platformio.org/en/latest/core/index.html?utm_source=docs.espressif.com>`_
-  is a command-line tool that consists of multi-platform build system, platform and
-  library managers and other integration components. It can be used with a variety of
-  code development environments and allows integration with cloud platforms and web
   services
 
 Configuration
@@ -43,8 +37,7 @@ Please go through `the official PlatformIO configuration guide for ESP-IDF <http
 Tutorials
 ~~~~~~~~~
 
-- `ESP-IDF and ESP32-DevKitC: debugging, unit testing, project analysis
+- `ESP-IDF and ESP32-DevKitC: debugging, unit testing, project analysis <https://docs.platformio.org/en/latest/tutorials/espressif32/espidf_debugging_unit_testing_analysis.html?utm_source=docs.espressif.com>`__
-  <https://docs.platformio.org/en/latest/tutorials/espressif32/espidf_debugging_unit_testing_analysis.html?utm_source=docs.espressif.com>`__
 
 Project Examples
 ~~~~~~~~~~~~~~~~
@@ -56,5 +49,5 @@ Next Steps
 
 Here are some useful links for exploring the PlatformIO ecosystem:
 
-- Learn more about `integrations with other IDEs/Text Editors <https://docs.platformio.org/en/latest/integration/ide/index.html?utm_source=docs.espressif.com>`_
+- Learn more about `integrations with other IDEs or Text Editors <https://docs.platformio.org/en/latest/integration/ide/index.html?utm_source=docs.espressif.com>`_
-- Get help from `PlatformIO community <https://community.platformio.org/?utm_source=docs.espressif.com>`_
+- Get help from `PlatformIO community <https://community.platformio.org/?utm_source=docs.espressif.com>`_

docs/zh_CN/api-reference/template.rst

@@ -1 +1,105 @@
-.. include:: ../../en/api-reference/template.rst
+API 文档模板
+==========================
+
+:link_to_translation:`en:[English]`
+
+.. note::
+
+    *说明*
+
+    1. 使用此文件 (:idf_file:`docs/zh_CN/api-reference/template.rst`) 作为 API 参考文档模板。
+    2. API 参考文档需和 API 的头文件名称保持一致。
+    3. 使用 ``..include::`` 从 API 文件夹中添加相应的说明文件。
+
+        * README.rst
+        * example.rst
+        * ...
+
+    4. 可选择在此文件中直接提供描述。
+    5. 完成后，删除所有的说明信息（类似本说明）和多余的头部信息。
+
+概述
+--------
+
+.. note::
+
+    *撰写说明*
+
+    1. 提供概述，简要说明 API 的用途和使用方法。
+    2. 必要时提供代码片段，以说明特定函数的功能。
+    3. 用此 `文档 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections>`_ 中介绍的方式区分不同的章节标题：
+
+        * ``#`` 用于设置各部分，标题上下同时标记
+        * ``*`` 用于设置章标题，标题上下同时标记
+        * ``=`` 用于设置节标题
+        * ``-`` 用于设置小节标题
+        * ``^`` 用于设置小小节标题
+        * ``"`` 用于设置段落标题
+
+应用示例
+-------------------
+
+.. note::
+
+    *撰写说明*
+
+    1. 准备一个或多个实际示例，展示此 API 的功能。
+    2. 每个示例应遵循 ``esp-idf/examples/`` 文件夹中项目的模式。
+    3. 将示例放在此文件夹中，添加 ``README.md`` 文件。
+    4. 在 ``README.md`` 中对展示的功能进行概述。
+    5. 良好的概述让读者能够充分理解示例，而无需参考源代码。
+    6. 按照示例的复杂程度，将代码描述分解成几个部分，并对每部分的功能进行概述。
+    7. 必要时，添加流程图和应用程序的输出截图。
+    8. 最后为本章节的每个示例添加对应链接，示例文件夹应位于 ``esp-idf/examples/`` 中。
+
+API 参考
+-------------
+
+.. highlight:: none
+
+.. note::
+
+    *撰写说明*
+
+    1. ESP-IDF 仓库通过 :doc:`用 Doxygen 从头文件中检索代码标记 <../contribute/documenting-code>` 的方式自动更新 API 参考文档。
+
+    2. 通过调用 Sphinx 扩展工具 ``esp_extensions/run_doxygen.py``，对 :idf_file:`docs/doxygen/Doxyfile` 中 ``INPUT`` 语句列出的所有头文件进行更新。
+
+    3. ``INPUT`` 语句的每一行（以 ``##`` 开头的注释除外）都包含一个到头文件 ``*.h`` 的路径，用于生成相应的 ``*.inc`` 文件::
+
+        ##
+        ## Wi-Fi - API Reference
+        ##
+        ../components/esp32/include/esp_wifi.h \
+        ../components/esp32/include/esp_smartconfig.h \
+
+    4. 头文件被展开时， ``sdkconfig.h`` 中默认定义的宏以及在 SOC 特定 ``include/soc/*_caps.h`` 头文件中定义的宏都会被展开。这样，头文件就可以根据 ``IDF_TARGET`` 的值来添加或排除相关内容。
+
+    5.  ``*.inc`` 文件中包含每次文档构建时自动生成的 API 成员格式化参考。所有 ``*.inc`` 文件都位于 Sphinx 的 ``_build`` 路径下。如需查看生成指令，以 ``esp_wifi.h`` 为例，运行 ``python gen-dxd.py esp32/include/esp_wifi.h``。
+
+    6. 用以下语句在文档中显示 ``*.inc`` 文件的内容::
+
+       .. include-build-file:: inc/esp_wifi.inc
+
+       参考示例：:idf_file:`docs/en/api-reference/network/esp_wifi.rst`
+
+    7. 你也可以不用 ``*.inc`` 文件，而使用自己的方式描述 API。参考示例：:idf_file:`docs/en/api-reference/storage/fatfs.rst`。
+
+       以下为常见的 ``.. doxygen...::`` 指令：
+
+        * 函数 - ``.. doxygenfunction:: name_of_function``
+        * 联合体 - ``.. doxygenunion:: name_of_union``
+        * 结构体 - ``.. doxygenstruct:: name_of_structure`` 和 ``:members:``
+        * 宏 - ``.. doxygendefine:: name_of_define``
+        * 类定义 - ``.. doxygentypedef:: name_of_type``
+        * 枚举 - ``.. doxygenenum:: name_of_enumeration``
+
+       如需更多信息，请参考 `Breathe 文档 <https://breathe.readthedocs.io/en/latest/directives.html>`_。
+
+       使用 `link custom role` 指令添加指向头文件的链接，如下所示::
+
+       * :component_file:`path_to/header_file.h`
+
+    8. 在任何情况下，要生成 API 参考文档，应该更新文件 :idf_file:`docs/doxygen/Doxyfile` 并将其中的路径更新为正在添加文档的 ``*.h`` 头文件的路径。
+
+    9. 更改提交并构建文档后，可以查看文档的渲染效果。如有需要，为相应的头文件 :doc:`纠正注释 <../contribute/documenting-code>`。

docs/zh_CN/third-party-tools/platformio.rst

@@ -1 +1,53 @@
-.. include:: ../../en/third-party-tools/platformio.rst
+.. _platformio:
+
+PlatformIO
+##########
+
+:link_to_translation:`en:[English]`
+
+.. image:: ../../_static/platformio-logo.png
+  :target: https://platformio.org/?utm_source=docs.espressif.com
+
+.. contents::
+    :local:
+
+什么是 PlatformIO？
+~~~~~~~~~~~~~~~~~~~
+
+`PlatformIO <https://platformio.org/?utm_source=docs.espressif.com>`__
+是一个跨平台的嵌入式开发环境，能直接支持 ESP-IDF。
+
+由于 PlatformIO 对 ESP-IDF 的支持并非由 Espressif 团队维护，
+如果遇到 PlatformIO 相关的问题，请通过 `官方 PlatformIO 库 <https://github.com/platformio>`_ 联系其开发人员。
+
+要了解关于 PlatformIO 生态系统及其理念的详细概述，请参考
+`官方 PlatformIO 文档 <https://docs.platformio.org/en/latest/what-is-platformio.html?utm_source=docs.espressif.com>`_。
+
+安装
+~~~~~~~~~~~~
+
+* `PlatformIO IDE <https://platformio.org/platformio-ide?utm_source=docs.espressif.com>`_ 是一个可在 Windows，macOS 和 Linux 平台上使用的嵌入式 C/C++ 开发工具集。
+* `PlatformIO Core (CLI) <https://docs.platformio.org/en/latest/core/index.html?utm_source=docs.espressif.com>`_ 是一个命令行工具，包含多平台编译系统，平台和库管理器以及其他集成组件。它可以与各种代码开发环境一起使用，还可以集成云平台和网络服务。
+
+配置
+~~~~~~~~~~~~~
+
+请参阅 `PlatformIO 官方的 ESP-IDF 配置指南 <https://docs.platformio.org/en/latest/frameworks/espidf.html?utm_source=docs.espressif.com#configuration>`_。
+
+教程
+~~~~~~~~~
+
+- `ESP-IDF and ESP32-DevKitC: debugging, unit testing, project analysis <https://docs.platformio.org/en/latest/tutorials/espressif32/espidf_debugging_unit_testing_analysis.html?utm_source=docs.espressif.com>`__
+
+项目示例
+~~~~~~~~~~~~~~~~
+
+请参阅 `PlatformIO 官方文档 <https://docs.platformio.org/en/latest/frameworks/espidf.html?utm_source=docs.espressif.com#examples>`__ 中 ESP-IDF 相关内容。
+
+更多内容
+~~~~~~~~~~
+
+访问以下链接探索 PlatformIO 生态系统：
+
+- 了解更多 `与其他 IDE 或文本编辑器集成 <https://docs.platformio.org/en/latest/integration/ide/index.html?utm_source=docs.espressif.com>`_ 的信息。
+- 从 `PlatformIO 社区 <https://community.platformio.org/?utm_source=docs.espressif.com>`__ 获取帮助。