docs: Provide CN translation for 3 additionalfeatures docs (#1357)

Shen7436 · web-flow · commit 8c628ac2c863 · 2025-11-27T11:54:26.000+08:00
diff --git a/docs/en/additionalfeatures/clangtoolchain.rst b/docs/en/additionalfeatures/clangtoolchain.rst
@@ -1,15 +1,18 @@
-Configuring Clang Toolchain
-===========================
+Clang Toolchain Configuration
+=============================
+
+:link_to_translation:`zh_CN:[中文]`
 
 1. After creating a new project, edit the project configuration.
    
    .. image:: https://user-images.githubusercontent.com/24419842/194882285-9faadb5d-0fe2-4012-bb6e-bc23dedbdbd2.png
       :alt: Project Configuration
 
-2. Go to the ``Build Settings`` tab and select the clang toolchain:
+2. Go to the ``Build Settings`` tab and select the Clang toolchain.
    
    .. image:: https://user-images.githubusercontent.com/24419842/194882462-3c0fd660-b223-4caf-964d-58224d91b518.png
       :alt: Clang Toolchain Selection
 
 .. note:: 
-   Clang toolchain is currently an experimental feature, and you may encounter build issues due to incompatibility with ESP-IDF. The following describes how to address the most common build issues on the current ESP-IDF master (ESP-IDF v5.1-dev-992-gaf28c1fa21-dirty). To work around clang build errors, please refer to `this workaround guide <https://github.com/espressif/idf-eclipse-plugin/blob/master/WORKAROUNDS.md#clang-toolchain-buid-errors>`_.
+
+   The Clang toolchain is currently an experimental feature, and you may encounter build issues due to incompatibility with ESP-IDF. The following describes how to address the most common build issues on the current ESP-IDF master (ESP-IDF v5.1-dev-992-gaf28c1fa21-dirty). For additional Clang-related build errors, please refer to the `workaround guide <https://github.com/espressif/idf-eclipse-plugin/blob/master/WORKAROUNDS.md#clang-toolchain-buid-errors>`_.
diff --git a/docs/en/additionalfeatures/esp-terminal.rst b/docs/en/additionalfeatures/esp-terminal.rst
@@ -1,14 +1,16 @@
 ESP-IDF Terminal
-===============================
+================
 
-This would launch a local terminal with all the environment variables set under ``Preferences`` > ``C/C++`` > ``Build`` > ``Environment``. The default working directory would be either the currently selected project or ``IDF_PATH`` if there is no project selected.
+:link_to_translation:`zh_CN:[中文]`
+
+This launches a local terminal with all environment variables configured under ``Preferences`` > ``C/C++`` > ``Build`` > ``Environment``. The default working directory would be either the currently selected project or ``IDF_PATH`` if no project selected.
 
 The terminal ``PATH`` is also configured with ``esptool``, ``espcoredump``, ``partition_table``, and ``app_update`` component paths, so it is convenient to access them directly from the ESP-IDF terminal.
 
 To launch the ESP-IDF Terminal:
 
-- Click on the ``Open a Terminal`` icon from the toolbar.
-- Choose ``ESP-IDF Terminal`` from the terminal drop-down and click ``OK`` to launch a terminal.
+1. Click on the ``Open a Terminal`` icon from the toolbar.
+2. Choose ``ESP-IDF Terminal`` from the terminal drop-down and click ``OK`` to launch a terminal.
 
 .. image:: ../../../media/idf_terminal.png
    :alt: ESP-IDF Terminal
diff --git a/docs/en/additionalfeatures/heaptracing.rst b/docs/en/additionalfeatures/heaptracing.rst
@@ -3,85 +3,93 @@
 Heap Tracing
 ============
 
-Heap tracing enables you to monitor memory usage over time by generating and analyzing a `svdat` dump file. The IDF Eclipse Plugin supports generating heap trace files through special breakpoints. For more information on SDK-level configuration and tracing features, refer to the official `ESP-IDF documentation <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/heap_debug.html>`_.
+:link_to_translation:`zh_CN:[中文]`
+
+Heap tracing allows you to monitor memory usage over time by generating and analyzing a ``svdat`` dump file. The IDF Eclipse Plugin supports generating heap trace files by setting special breakpoints. For more information on SDK-level configuration and tracing features, refer to the official `ESP-IDF documentation <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/heap_debug.html>`_.
 
 Generating Dump File
 --------------------
-1. **Open the sysview\_heap\_log.c file**
+
+1. **Open the sysview_heap_log.c File**
    
-   From the Project Explorer, locate and open the `sysview_heap_log.c` file from the **system** templates project.
+   From the Project Explorer, locate and open the ``sysview_heap_log.c`` file from the **system** templates project.
 
    .. image:: ../../../media/HeapTracing/sysview_heap_log_file.PNG
       :alt: sysview_heap_log.c file
 
 2. **Add a Breakpoint and Configure Properties**
    
-   Add a breakpoint at the desired line, then right-click on the breakpoint icon in the editor and select `Breakpoint Properties…`.
+   Add a breakpoint at the desired line, then right-click on the breakpoint icon in the editor and select ``Breakpoint Properties``.
 
    .. image:: ../../../media/HeapTracing/breakpoint_properties_popup.png
       :alt: Breakpoint Properties
 
 3. **Define Heap Tracing Action**
 
-   In the Breakpoint Properties window, go to `Actions`, click `New`, and select `Heap Tracing` from the `Action Type` dropdown. 
-   - For the initial breakpoint, set the action to **Start Heap Trace** and specify the save location for the dump file (recommended to store in the project directory). Name the action meaningfully, then click OK.
+   In the ``Breakpoint Properties`` window, go to ``Actions``, click ``New``, and select ``Heap Tracing`` from the ``Action Type`` dropdown. 
+
+   For the initial breakpoint, set the ``Action`` to ``Start Heap Trace`` and specify the save location for the dump file (it is recommended to store it in the project directory). Name the action meaningfully, then click ``OK``.
 
    .. image:: ../../../media/HeapTracing/heap_tracing_action.png
       :alt: Heap Tracing Action
 
 4. **Attach the Action to the Breakpoint**
 
-   After creating the action, click `Attach` to link it to the breakpoint, which will display it under the Actions for this breakpoint section.
+   After creating the action, click ``Attach`` to link it to the breakpoint, which will display the action under the ``Actions for this breakpoint`` section.
 
    .. image:: ../../../media/HeapTracing/breakpoint_properties_actions_start_attached.png
       :alt: Attach Action
 
 5. **Apply and Create Additional Breakpoint**
 
-   Now you have a breakpoint that will start tracing and generate a dump file. To stop the tracing, create another breakpoint (e.g., at line 102), set its properties, and choose the **Stop Heap Trace** option in the action settings. Attach this action to the breakpoint as shown below.
+   Now you have a breakpoint that will start tracing and generate a dump file. To stop the tracing, create another breakpoint (e.g., at line 102), set its properties, and choose the ``Stop Heap Trace`` option in the action settings. Attach this action to the breakpoint as shown below.
 
    .. image:: ../../../media/HeapTracing/breakpoint_properties_actions_stop_attached.png
       :alt: Stop Heap Trace Action
 
 6. **Launch Debug Configuration**
 
-   Launch the debug configuration for your ESP32 board. When the program hits the breakpoints, the IDE will prompt you to switch to the debugger perspective. Continue execution for each breakpoint to start and stop tracing. Refresh the project in the Project Explorer to view the dump file in the specified location.
+   Launch the debug configuration for your ESP32 board. When a breakpoint is hit, the IDE will prompt you to switch to the debugger perspective. Continue execution at each breakpoint to start or stop tracing, then refresh the project in the Project Explorer to view the dump file at the specified location.
 
 Analyzing the Dump File
 -----------------------
 
-The IDF Eclipse Plugin allows you to analyze generated `svdat` dump files. Right-click on the dump file and select `Heap Dump Analysis` from the context menu.
+The IDF Eclipse Plugin allows you to analyze generated ``svdat`` dump files. Right-click on the dump file and select ``ESP-IDF: Heap Dump Analysis`` from the context menu.
 
-**Note:** Ensure the project is built with the appropriate symbols file to enable analysis.
+.. note::
+
+   Ensure the project is built with the appropriate symbols file to enable analysis.
 
 .. image:: ../../../media/HeapTracing/analysis_context_menu.png
    :alt: Heap Dump Analysis Context Menu
 
-Overview Tab
--------------
-The Overview Tab displays memory consumption over time in a graph format. By default, all contexts are shown; you can select specific contexts corresponding to heap events.
+``Overview`` Tab
+----------------
+
+The ``Overview`` Tab displays memory consumption over time in a graph format. By default, all contexts are shown, but you can select specific contexts corresponding to heap events.
 
 .. image:: ../../../media/HeapTracing/overview_tab_tracing.png
    :alt: Memory Consumption Graph
 
-For example, selecting multiple contexts displays them separately on the graph.
+For example, selecting multiple contexts displays each of them separately on the graph.
 
 .. image:: ../../../media/HeapTracing/overview_tab_tracing_contexts.png
    :alt: Selected Contexts in Graph
 
-Details Tab
--------------
-The Details Tab provides further insights, showing each event in the heap trace. Rows highlighted in light orange indicate potential memory leaks (since the trace may have ended before a free event was detected). Green rows show free heap events.
+``Details`` Tab
+---------------
+
+The ``Details`` Tab provides further insights by showing each event in the heap trace. Rows highlighted in light orange indicate potential memory leaks, as the trace may have ended before a corresponding free event was detected. Rows highlighted in green indicate free heap events.
 
 .. image:: ../../../media/HeapTracing/details_tab_tracing.png
    :alt: Details Tab
 
-To filter entries for possible memory leaks, check the `View Possible Memory Leaks` box. Right-clicking on any entry allows you to view callers, opening the `Callers View` to display the call stack for the heap event.
+To filter entries for possible memory leaks, check the ``View Possible Memory Leaks`` box. Right-clicking on any entry allows you to view its callers by opening the ``Callers View``, which displays the call stack for the heap event.
 
 .. image:: ../../../media/HeapTracing/show_callers_context_menu.png
    :alt: Show Callers
 
-Clicking on an entry in the `Callers View` will navigate to the corresponding line in the source file.
+Clicking on an entry in the ``Callers View`` will navigate to the corresponding line in the source file.
 
 .. image:: ../../../media/HeapTracing/callers_view.png
-   :alt: Callers View
+   :alt: Callers View
diff --git a/docs/zh_CN/additionalfeatures/clangtoolchain.rst b/docs/zh_CN/additionalfeatures/clangtoolchain.rst
@@ -1 +1,18 @@
-.. include:: ../../en/additionalfeatures/clangtoolchain.rst
+配置 Clang 工具链
+=================
+
+:link_to_translation:`en:[English]`
+
+1. 创建新项目后，编辑项目配置。
+   
+   .. image:: https://user-images.githubusercontent.com/24419842/194882285-9faadb5d-0fe2-4012-bb6e-bc23dedbdbd2.png
+      :alt: 项目配置
+
+2. 前往 ``Build Settings`` 选项卡并选择 Clang 工具链。
+   
+   .. image:: https://user-images.githubusercontent.com/24419842/194882462-3c0fd660-b223-4caf-964d-58224d91b518.png
+      :alt: 选择 Clang 工具链
+
+.. note:: 
+
+   Clang 工具链目前处于实验阶段，使用时可能会因为与 ESP-IDF 不兼容而遇到构建问题。以下内容说明了如何解决当前 ESP-IDF master 分支 (ESP-IDF v5.1-dev-992-gaf28c1fa21-dirty) 上最常见的构建问题。若遇到 Clang 构建错误，请参考此 `变通方法指南 <https://github.com/espressif/idf-eclipse-plugin/blob/master/WORKAROUNDS_CN.md>`_。
diff --git a/docs/zh_CN/additionalfeatures/esp-terminal.rst b/docs/zh_CN/additionalfeatures/esp-terminal.rst
@@ -1 +1,16 @@
-.. include:: ../../en/additionalfeatures/esp-terminal.rst
+ESP-IDF 终端
+============
+
+:link_to_translation:`en:[English]`
+
+该功能会启动一个本地终端，其中配置了在 ``Preferences`` > ``C/C++`` > ``Build`` > ``Environment`` 下的所有环境变量。默认工作目录为当前选中的项目；如果没有选中项目，则为 ``IDF_PATH``。
+
+该终端的 ``PATH`` 还配置了 ``esptool``、``espcoredump``、``partition_table`` 和 ``app_update`` 组件的路径，便于在 ESP-IDF 终端中直接访问这些组件。
+
+可参照下列步骤启动 ESP-IDF 终端：
+
+1. 在工具栏中点击 ``Open a Terminal`` 图标。
+2. 在终端下拉菜单中选择 ``ESP-IDF Terminal``，然后点击 ``OK`` 启动终端。
+
+.. image:: ../../../media/idf_terminal.png
+   :alt: ESP-IDF 终端
diff --git a/docs/zh_CN/additionalfeatures/heaptracing.rst b/docs/zh_CN/additionalfeatures/heaptracing.rst
@@ -1 +1,95 @@
-.. include:: ../../en/additionalfeatures/heaptracing.rst
+.. _heap_tracing:
+
+堆跟踪
+======
+
+:link_to_translation:`en:[English]`
+
+你可以使用堆跟踪生成并分析 ``svdat`` 转储文件，持续监控内存使用情况。IDF Eclipse 插件支持通过设置特定断点来生成堆跟踪文件。有关 SDK 级配置和跟踪功能的更多信息，请参阅官方 `ESP-IDF 文档 <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-reference/system/heap_debug.html>`_。
+
+生成转储文件
+------------
+
+1. **打开 sysview_heap_log.c 文件**
+   
+   在资源管理器中找到并打开 **系统** 模板项目中的 ``sysview_heap_log.c`` 文件。
+
+   .. image:: ../../../media/HeapTracing/sysview_heap_log_file.PNG
+      :alt: sysview_heap_log.c 文件
+
+2. **添加断点并配置属性**
+   
+   在所需的代码行添加一个断点，然后在编辑器中右键单击断点图标，选择 ``Breakpoint Properties``。
+
+   .. image:: ../../../media/HeapTracing/breakpoint_properties_popup.png
+      :alt: 断点属性
+
+3. **定义堆跟踪操作**
+
+   在 ``Breakpoint Properties`` 窗口中，前往 ``Actions``，单击 ``New``，并在 ``Action Type`` 下拉列表中选择 ``Heap Tracing``。 
+
+   对于初始断点，在 ``Action`` 一栏选择 ``Start Heap Trace``，并指定转储文件的保存位置（建议存放在项目目录）。为该操作设置一个有意义的名称，然后单击 ``OK``。
+
+   .. image:: ../../../media/HeapTracing/heap_tracing_action.png
+      :alt: 堆跟踪操作
+
+4. **将该操作附加至断点**
+
+   创建操作后，单击 ``Attach`` 将其链接至断点。绑定成功后，该操作会显示在 ``Actions for this breakpoint`` 一栏。
+
+   .. image:: ../../../media/HeapTracing/breakpoint_properties_actions_start_attached.png
+      :alt: 附加操作
+
+5. **应用并创建另一个断点**
+
+   现在你已有一个会开始跟踪并生成转储文件的断点。要停止跟踪，请再创建一个断点（例如在代码的第 102 行），设置其属性，并在操作设置中选择 ``Stop Heap Trace`` 选项。按下图所示，将此操作附加至断点。
+
+   .. image:: ../../../media/HeapTracing/breakpoint_properties_actions_stop_attached.png
+      :alt: 停止堆跟踪操作
+
+6. **启动调试配置**
+
+   在 IDE 中启动开发板的调试配置。当程序运行至断点时，IDE 会提示你切换到调试器视图。在每个断点处继续执行程序，以开始或停止跟踪。然后在资源管理器中刷新项目，即可在指定位置查看生成的转储文件。
+
+分析转储文件
+------------
+
+IDF Eclipse 插件可用于分析生成的 ``svdat`` 转储文件。右键单击该转储文件，并在上下文菜单中选择 ``ESP-IDF: Heap Dump Analysis``。
+
+.. note::
+
+   确保项目使用合适的符号文件进行构建，以便启用分析。
+
+.. image:: ../../../media/HeapTracing/analysis_context_menu.png
+   :alt: 堆转储分析的上下文菜单
+
+``Overview`` 标签页
+-------------------
+
+``Overview`` 标签页以曲线图形式显示内存消耗的变化情况。默认情况下，图表会显示所有上下文的内存信息，你也可以选择只显示与特定堆事件相关的上下文。
+
+.. image:: ../../../media/HeapTracing/overview_tab_tracing.png
+   :alt: 内存消耗图
+
+例如，选择多个上下文时，曲线图会分别显示每个上下文的内存使用情况。
+
+.. image:: ../../../media/HeapTracing/overview_tab_tracing_contexts.png
+   :alt: 图表中已选的上下文
+
+``Details`` 标签页
+------------------
+
+``Details`` 标签页提供更详细的信息，显示堆跟踪中的每个事件。浅橙色高亮的行表示潜在的内存泄漏，因为跟踪可能在释放事件被检测到之前就已结束。绿色高亮的行表示已释放的堆事件。
+
+.. image:: ../../../media/HeapTracing/details_tab_tracing.png
+   :alt: 详细信息标签页
+
+要筛选可能的内存泄漏条目，请勾选 ``View Possible Memory Leaks`` 复选框。右键单击任意条目可查看其调用者，这会打开 ``Callers View``，显示该堆事件的调用栈。
+
+.. image:: ../../../media/HeapTracing/show_callers_context_menu.png
+   :alt: 显示调用者
+
+在 ``Callers View`` 中单击某个条目将跳转到源文件中的相应代码行。
+
+.. image:: ../../../media/HeapTracing/callers_view.png
+   :alt: 调用者视图
