Merge pull request #1396 from espressif/docs/translate_indedx_docs

docs: Provide CN translation for five index docs
espressif · Jan 7, 2025 · 608af67 · 608af67
2 parents 20c6beb + 271ae50
commit 608af67
Show file tree

Hide file tree

Showing 14 changed files with 302 additions and 122 deletions.
diff --git a/docs_espressif/en/buildproject.rst b/docs_espressif/en/buildproject.rst
@@ -1,25 +1,26 @@
-Build the Project
-===============================
+.. _build the project:
 
-1. Build the project:
+Build Your Project
+==================
 
-- Navigate to **View** > **Command Palette**.
+:link_to_translation:`zh_CN:[中文]`
 
-- Type **ESP-IDF: Build your Project** and select the command to build the project.
+1.  Build your project: Go to ``View`` > ``Command Palette``, enter ``ESP-IDF: Build your Project`` and choose the command to build the project.
 
-2. A new terminal being launched with the build output and a notification bar with Building Project message until it is done then a Build done message when finished. 
+2.  A new terminal will open with the build output. A notification bar will display the "Building project" message, followed by a "Building done" message when the process is complete.
 
-.. image:: ../../media/tutorials/basic_use/build.png
+    .. image:: ../../media/tutorials/basic_use/build.png
 
-.. note::
-  There is a **idf.notificationMode** configuration setting if you do not want to see the output automatically. Please review `ESP-IDF Settings <settings>` to see how to modify this configuration setting.
+    .. note::
 
-You could modify the behavior of the build task with **idf.cmakeCompilerArgs** for Cmake configure step and **idf.ninjaArgs** for Ninja step. For example, using ``idf.ninjaArgs: [-j N]`` where N is the number of jobs run in parallel.
+        There is an ``idf.notificationMode`` configuration setting if you prefer not to see the output automatically. Please refer to :ref:`ESP-IDF Settings <settings>` to learn how to modify this configuration.
 
-3. After building the application, the size analysis task will be executed in a terminal, showing the binaries size analysis results. You can enable or disable this task being executed with **idf.enableSizeTaskAfterBuildTask** in your settings.json.
+    You can adjust the behavior of the build task with ``idf.cmakeCompilerArgs`` for the Cmake configure step and ``idf.ninjaArgs`` for the Ninja step. For example, use ``idf.ninjaArgs: [-j N]`` where **N** is the number of jobs to run in parallel.
 
-.. image:: ../../media/tutorials/basic_use/size_terminal.png
+3.  After building the application, the size analysis task will run in a terminal, showing the binary size analysis results. You can enable or disable this task with ``idf.enableSizeTaskAfterBuildTask`` in the ``settings.json``.
 
-ESP-IDF build output will try to suggest hints to solve errors that can be shown using the :ref:`Hints viewer <hints viewer>`.
+    .. image:: ../../media/tutorials/basic_use/size_terminal.png
 
-Next step is to :ref:`Flash onto the device <flash the device>`.
+The ESP-IDF build output will provide hints to resolve errors, which can be viewed using the :ref:`Hints Viewer <hints viewer>`.
+
+Next, proceed to :ref:`Flash onto the Device <flash the device>`.
diff --git a/docs_espressif/en/configureproject.rst b/docs_espressif/en/configureproject.rst
@@ -1,57 +1,63 @@
+.. _configure_your_project:
+
 Configure Your Project
-===============================
+======================
+
+:link_to_translation:`zh_CN:[中文]`
 
-Select an Espressif target (esp32, esp32s2, etc.) by selecting menu **View** > **Command Palette** and typing **ESP-IDF: Set Espressif Device Target** command.
+Select an Espressif target (esp32, esp32s2, etc.) by going to ``View`` > ``Command Palette`` and entering ``ESP-IDF: Set Espressif Device Target`` command.
 
-Select menu **View** > **Command Palette** and type the **ESP-IDF: Select OpenOCD Board Configuration** to choose the openOCD configuration files for the extension openOCD server.
+Go to ``View`` > ``Command Palette`` and enter ``ESP-IDF: Select OpenOCD Board Configuration`` to choose the openOCD configuration files for the extension openOCD server.
 
 .. note::
-  * Please review `Configuration of OpenOCD for Specific Target <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/tips-and-quirks.html#jtag-debugging-tip-openocd-configure-target>`_ to understand which board or configuration to use for your specific hardware.
 
-Next configure your project. Select menu **View** > **Command Palette** and type **ESP-IDF: SDK Configuration Editor** command ESP-IDF project settings.
+    Please refer to `Configuration of OpenOCD for Specific Target <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/tips-and-quirks.html#jtag-debugging-tip-openocd-configure-target>`_ to select the appropriate OpenOCD configuration file based on your hardware.
+
+Next, configure your project. Go to ``View`` > ``Command Palette`` and enter ``ESP-IDF: SDK Configuration Editor`` to adjust ESP-IDF project settings.
 
 .. image:: ../../media/tutorials/basic_use/gui_menuconfig.png
 
-After all changes are made, click save and close this window.
+After making changes, click ``save`` and close the window.
 
-Next step is to :ref:`Build the project <build the project>`.
+Next, proceed to :ref:`Build Your project <build the project>`.
 
-C and C++ Code navigation and syntax highlight
------------------------------------------------------
+C and C++ Code Navigation and Syntax Highlighting
+-------------------------------------------------
 
 .. note::
-  * C and C++ code navigation doesn't need to be configured if you create the project as described in :ref:`Configure your project <configure your project>` as these commands will create the ``{PROJECT_DIRECTORY_PATH}/.vscode/c_cpp_properties.json`` file.
 
-For code navigation and C/C++ syntax highlight you could use either the `Microsoft C/C++ Extension <https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools>`_, `LLVM CLangd extension <https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd>`_ or any other extension you desire.
+    C and C++ code navigation is automatically configured if you create the project as described in :ref:`Configure Your Project <configure_your_project>`. Those commands generate the ``{PROJECT_DIRECTORY_PATH}/.vscode/c_cpp_properties.json`` file.
+
+For code navigation and C/C++ syntax highlighting, you can use `Microsoft C/C++ extension <https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools>`_, `LLVM clangd extension <https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd>`_, or any other preferred extension.
 
-Usually C/C++ language extensions rely on a file called ``compile_commands.json`` which is located on your project build directory. You can generate this file using the **ESP-IDF: Run idf.py reconfigure task**.
+Usually C/C++ language extensions rely on a file called ``compile_commands.json``, which is located in your project build directory. You can generate this file using the ``ESP-IDF: Run idf.py reconfigure task``.
 
-For LLVM CLangd extension, only the compile_commands.json is needed. For Microsoft C/C++ extension, a configuration file is located in ``{PROJECT_DIRECTORY_PATH}/.vscode/c_cpp_properties.json`` and can be generated by creating a project using **ESP-IDF: New Project**, **ESP-IDF: Show Examples Projects** command or using the **ESP-IDF: Add .vscode Configuration Folder** command on an existing ESP-IDF projects.
+For LLVM clangd extension, only ``compile_commands.json`` is needed. For Microsoft C/C++ extension, a configuration file is located at ``{PROJECT_DIRECTORY_PATH}/.vscode/c_cpp_properties.json``. This file can be generated by creating a project using ``ESP-IDF: New Project``, ``ESP-IDF: Show Example Projects`` command, or by using the ``ESP-IDF: Add .vscode Configuration Folder`` command on an existing ESP-IDF projects.
 
-The file looks like this:
+The file structure is as follows:
 
 .. code-block:: JSON
 
-  {
-    "configurations": [
-      {
-        "name": "ESP-IDF",
-        "compilerPath": "/path/to/toolchain-gcc",
-        "compileCommands": "${workspaceFolder}/build/compile_commands.json",
-        "includePath": [
-          "${config:idf.espIdfPath}/components/**",
-          "${config:idf.espIdfPathWin}/components/**",
-          "${workspaceFolder}/**"
-        ],
-        "browse": {
-          "path": [
-            "${config:idf.espIdfPath}/components",
-            "${config:idf.espIdfPathWin}/components",
-            "${workspaceFolder}"
-          ]
-        }
-      }
-    ]
-  }
-
-If ``compile_commands.json`` is not defined, the Microsoft C/C++ extension will browse the provided ESP-IDF path to provide code navigation resolution.
+    {
+        "configurations": [
+            {
+                "name": "ESP-IDF",
+                "compilerPath": "/path/to/toolchain-gcc",
+                "compileCommands": "${workspaceFolder}/build/compile_commands.json",
+                "includePath": [
+                    "${config:idf.espIdfPath}/components",
+                    "${config:idf.espIdfPathWin}/components/",
+                    "${workspaceFolder}/"
+                ],
+                "browse": {
+                    "path": [
+                        "${config:idf.espIdfPath}/components",
+                        "${config:idf.espIdfPathWin}/components",
+                        "${workspaceFolder}"
+                    ]
+                }
+            }
+        ]
+    }
+
+If ``compile_commands.json`` is not defined, Microsoft C/C++ extension will browse the provided ESP-IDF path to resolve code navigation.
diff --git a/docs_espressif/en/connectdevice.rst b/docs_espressif/en/connectdevice.rst
@@ -1,10 +1,12 @@
 .. _connectdevice:
 
 Connect Your Device
-===============================
+===================
 
-In Visual Studio Code, select menu **View** > **Command Palette** and type **ESP-IDF: Select Port to Use:** and choose the serial port that your device is connected.
+:link_to_translation:`zh_CN:[中文]`
 
-Please review `Establish serial communication <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/establish-serial-connection.html>`_ if you are not sure about the serial port name.
+In Visual Studio Code, go to ``View`` > ``Command Palette``, enter ``ESP-IDF: Select Port to Use``, and choose the serial port that your device is connected.
 
-Next step is to :ref:`Configure your project <configure your project>`.
+If you are not sure about the serial port name, refer to `Establish Serial Communication <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/establish-serial-connection.html>`_.
+
+Next, proceed to :ref:`Configure your project <configure_your_project>`.
diff --git a/docs_espressif/en/debugproject.rst b/docs_espressif/en/debugproject.rst
@@ -4,7 +4,7 @@ Debug Your Project
 :link_to_translation:`zh_CN:[中文]`
 
 Table of Contents
-==================
+-----------------
 
 .. contents::
    :depth: 2
@@ -18,15 +18,15 @@ Before debugging the project, you need to specify the serial port of the device:
 
 1. Select the serial port
 
-- Navigate to ``View`` > ``Command Palette``.
+- Go to ``View`` > ``Command Palette``
 
-- Type **ESP-IDF: Select Port to Use** and select the command to specify the serial port of your device.
+- Enter ``ESP-IDF: Select Port to Use`` and choose the command to specify the serial port of your device
 
 2. Make sure that OpenOCD configuration files are correct
 
-- Navigate to ``View`` > ``Command Palette``.
+- Go to ``View`` > ``Command Palette``
 
-- Type **ESP-IDF: Select OpenOCD Board Configuration** and select the command to choose the OpenOCD configuration files for the extension OpenOCD server.
+- Enter ``ESP-IDF: Select OpenOCD Board Configuration`` and choose the command to specify the OpenOCD configuration files for the extension OpenOCD server
 
 .. note::
 
@@ -211,5 +211,5 @@ Post-mortem Debugging Use Cases
 
 You can start a monitor session to capture fatal error events with **ESP-IDF: Launch IDF Monitor for Core Dump Mode/GDB Stub Modec** command. If configured in your project's sdkconfig, it can trigger the start of a debug session for GDB remote protocol server (GDBStub) or `ESP-IDF Core Dump <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/core_dump.html#core-dump>`_ when an error occurrs. For more information, see `Panic Handler <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/fatal-errors.html#panic-handler>`_.
 
-- **Core Dump** is configured when **Core Dump's Data Destination** is set to either ``UART`` or ``FLASH`` using the **ESP-IDF: SDK Configuration Editor** extension command or ``idf.py menuconfig`` in a terminal.
-- **GDB Stub** is configured when ``Panic Handler Behaviour`` is set to ``Invoke GDBStub`` using the **ESP-IDF: SDK Configuration Editor** extension command or ``idf.py menuconfig`` in a terminal.
+- **Core Dump** is configured when **Core Dump's Data Destination** is set to either ``UART`` or ``FLASH`` using the ``ESP-IDF: SDK Configuration Editor`` extension command or ``idf.py menuconfig`` in a terminal.
+- **GDB Stub** is configured when **Panic Handler Behaviour** is set to ``Invoke GDBStub`` using the ``ESP-IDF: SDK Configuration Editor`` extension command or ``idf.py menuconfig`` in a terminal.
diff --git a/docs_espressif/en/flashdevice.rst b/docs_espressif/en/flashdevice.rst
@@ -1,58 +1,48 @@
 .. _flash the device:
 
 Flash onto the Device
-===============================
+=====================
 
-1. Select the Serial Port:
+:link_to_translation:`zh_CN:[中文]`
 
-- Navigate to **View** > Command Palette.
+1.  **Select the serial port**: Go to ``View`` > ``Command Palette``, enter ``ESP-IDF: Select Port to Use``, and choose the command to specify the serial port of your device.
 
-- Type **ESP-IDF: Select Port to Use** and select the command to specify the serial port of your device.
+2.  **Start flashing the device**: Go to ``View`` > ``Command Palette``, enter ``ESP-IDF: Flash your Project``, and choose the command to start flashing your device. You can choose ``UART``, ``JTAG`` or ``DFU`` flashing method.
 
-2. Start flashing the device:
+    .. note::
 
-- Go to **View** > **Command Palette**.
+        * ``UART`` is the most common option for most Espressif devices.
+        * If you are using ``JTAG``, ensure OpenOCD is properly configured. Go to ``View`` > ``Command Palette`` and enter ``ESP-IDF: Select OpenOCD Board Configuration`` to select the correct configuration for your board.
 
-- Type **ESP-IDF: Flash your Project** and select the command to start flashing your device.
+    .. note::
 
-- Choose ``UART``, ``JTAG`` or ``DFU`` flash mode. 
+        There is an ``idf.flashBaudRate`` configuration setting to modify the flashing baud rate.
 
-3. The flashing task will beign on the previously selected serial port, launching a new terminal displaying the flash task output. While flashing is in progress, a notification bar will display ``ESP-IDF: Flashing project`` Once the process is complete, the message will change to ``Flash Done ⚡️``.
+3.  The flashing task will begin on the selected serial port, launching a new terminal displaying the flashing task output. While flashing is in progress, a notification bar will display ``ESP-IDF: Flashing project``. Once the process is complete, the message will change to ``Flash Done ⚡️``.
 
-.. note::
-  ``UART`` is the most common option for most Espressif devices.
+    .. image:: ../../media/tutorials/basic_use/flash.png
 
-.. note::
-  * If you are using ``JTAG`` make sure to have OpenOCD properly configured using menu **View** > **Command Palette** and type **ESP-IDF: Select OpenOCD Board Configuration** to select the right configuration for your board.
-  * Please review `Configuration of OpenOCD for Specific Target <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/tips-and-quirks.html#jtag-debugging-tip-openocd-configure-target>`_ to understand which board or configuration to use for your specific hardware.
-  * Make sure to configure your drivers as mentioned in ESP-IDF `Configure JTAG Interface <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/configure-ft2232h-jtag.html>`_ documentation.
+Please refer to `Configuration of OpenOCD for Specific Target <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/tips-and-quirks.html#jtag-debugging-tip-openocd-configure-target>`_ to select the appropriate OpenOCD configuration file based on your hardware.
 
-.. image:: ../../media/tutorials/basic_use/flash.png
+Make sure to configure your drivers as mentioned in `Configure JTAG Interface <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/configure-ft2232h-jtag.html>`_.
 
-.. note::
-  * There is an **idf.flashBaudRate** configuration settings to modify the flashing baud rate.
+Next, proceed to :ref:`Monitor the Output <monitor_the_output>`.
 
-Next step is to :ref:`Monitor the output <monitor the output>`.
+Other Flashing Commands
+-----------------------
 
-Other flashing commands
---------------------------
+You can also choose the flashing method ``UART``, ``JTAG``, or ``DFU`` (ESP32-S2 or ESP32-S3) based on your hardware connection.
 
-You can also choose the flashing type ``UART``, ``JTAG`` or ``DFU`` (esp32s2 or esp32s3) based on your hardware connection.
+- Go to ``View`` > ``Command Palette``, enter ``ESP-IDF: Select Flash Method``, and select the flashing method for your device. The selected choice will be saved in the ``idf.flashType`` configuration setting.
+- You can also use the following commands to flash with a specific flashing method:
 
-- Go to **View** > **Command Palette**.
+    1. ``ESP-IDF: Flash (UART) your Project`` for UART flashing
+    2. ``ESP-IDF: Flash (DFU) your Project`` to flash using DFU (only for ESP32-S2 and ESP32-S3)
+    3. ``ESP-IDF: Flash (with JTAG)`` to flash using JTAG and OpenOCD
 
-- Type **ESP-IDF: Select Flash Method and Flash** and select the flashing type for your device.
-- Selected choice will be saved in the **idf.flashType** configuration setting.
+Related Documentation
+---------------------
 
-You can also use these commands to flash with an specific flash type:
-
-1. **ESP-IDF: Flash (UART) your Project** for UART flashing.
-2. **ESP-IDF: Flash (DFU) your Project**  to flash using DFU (only for ESP32-S2 and ESP32-S3).
-3. **ESP-IDF: Flash (with JTag)** to flash using JTAG and OpenOCD. 
-
-Links
--------------------
-
-* `ESP-PROG guide <https://docs.espressif.com/projects/espressif-esp-iot-solution/en/latest/hw-reference/ESP-Prog_guide.html>`_ for hardware connection and configuration.
-* `Configuration of OpenOCD for Specific Target <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/tips-and-quirks.html#jtag-debugging-tip-openocd-configure-target>`_ to understand which board or configuration to use for your specific hardware.
-* `Establishing serial connection <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/establish-serial-connection.html>`_ with Espressif serial device.
+* `ESP-PROG Guide <https://docs.espressif.com/projects/espressif-esp-iot-solution/en/latest/hw-reference/ESP-Prog_guide.html>`_ for hardware connection and configuration
+* `Configuration of OpenOCD for Specific Target <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/tips-and-quirks.html#jtag-debugging-tip-openocd-configure-target>`_ to select the appropriate OpenOCD configuration file based on your hardware
+* `Establishing Serial Connection <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/establish-serial-connection.html>`_ with Espressif serial device