Merge branch 'docs/translate_kconfig' into 'master'

docs: translate kconfig.rst

Closes DOC-4574

See merge request espressif/esp-idf!22624

docs/en/api-reference/kconfig.rst

@@ -1,12 +1,13 @@
 Project Configuration
 *********************
+:link_to_translation:`zh_CN:[中文]`
 
 Introduction
 ============
 
-ESP-IDF uses the esp-idf-kconfig_ package based on kconfiglib_ which is a Python-based extension to the Kconfig_ system. Kconfig provides a compile-time project configuration mechanism and is based around options of several types: integer, string, boolean. Kconfig files specify dependencies between options, default values of the options, the way the options are grouped together, etc.
+The esp-idf-kconfig_ package that ESP-IDF uses is based on kconfiglib_, which is a Python extension to the Kconfig_ system. Kconfig provides a compile-time project configuration mechanism and offers configuration options of several types (e.g., integers, strings, and boolens). Kconfig files specify dependencies between options, default values of options, the way options are grouped together, etc.
 
-For the complete list of available features please see Kconfig_ and `kconfiglib extentions`_.
+For the full list of available features, please see Kconfig_ and `kconfiglib extentions`_.
 
 .. _project-configuration-menu:
 
@@ -15,50 +16,45 @@ Project Configuration Menu
 
 Application developers can open a terminal-based project configuration menu with the ``idf.py menuconfig`` build target.
 
-After being updated, this configuration is saved inside ``sdkconfig`` file in the project root directory. Based on ``sdkconfig``, application build targets will generate ``sdkconfig.h`` file in the build directory, and will make sdkconfig options available to the project build system and source files.
+After being updated, this configuration is saved in the ``sdkconfig`` file under the project root directory. Based on ``sdkconfig``, application build targets will generate the ``sdkconfig.h`` file under the build directory, and will make the ``sdkconfig`` options available to the project build system and source files.
 
 Using sdkconfig.defaults
 ========================
 
-In some cases, such as when ``sdkconfig`` file is under revision control, the fact that ``sdkconfig`` file gets changed by the build system may be inconvenient. The build system offers a way to avoid this, in the form of ``sdkconfig.defaults`` file. This file is never touched by the build system, and can be created manually or automatically. It can contain all the options which matter for the given application and are different from the default ones. The format is the same as that of the ``sdkconfig`` file. ``sdkconfig.defaults`` can be created manually when one remembers all the changed configurations. Otherwise, the file can be generated automatically by running the ``idf.py save-defconfig`` command.
+In some cases, for example, when the ``sdkconfig`` file is under revision control, it may be inconvenient for the build system to change the ``sdkconfig`` file. The build system offers a solution to prevent it from happening, which is to create the ``sdkconfig.defaults`` file. This file is never touched by the build system, and can be created manually or automatically. It contains all the options which matter to the given application and are different from the default ones. The format is the same as that of the ``sdkconfig`` file. ``sdkconfig.defaults`` can be created manually when one remembers all the changed configuration, or it can be generated automatically by running the ``idf.py save-defconfig`` command.
 
-Once ``sdkconfig.defaults`` is created, ``sdkconfig`` can be deleted and added to the ignore list of the revision control system (e.g. ``.gitignore`` file for ``git``). Project build targets will automatically create ``sdkconfig`` file, populated with the settings from ``sdkconfig.defaults`` file, and the rest of the settings will be set to their default values. Note that the build process will not override settings that are already in ``sdkconfig`` by ones from ``sdkconfig.defaults``. For more information, see :ref:`custom-sdkconfig-defaults`.
+Once ``sdkconfig.defaults`` is created, ``sdkconfig`` can be deleted or added to the ignore list of the revision control system (e.g., the ``.gitignore`` file for ``git``). Project build targets will automatically create the ``sdkconfig`` file, populate it with the settings from the ``sdkconfig.defaults`` file, and configure the rest of the settings to their default values. Note that during the build process, settings from ``sdkconfig.defaults`` will not override those already in ``sdkconfig``. For more information, see :ref:`custom-sdkconfig-defaults`.
 
-Kconfig Formatting Rules
-========================
+Kconfig Format Rules
+====================
 
-The following attributes of ``Kconfig`` files are standardized:
+Format rules for Kconfig files are as follows:
 
-- Within any menu, option names should have a consistent prefix. The prefix length is currently set to at least 3
-  characters.
-- The indentation style is 4 characters created by spaces. All sub-items belonging to a parent item are indented by
-  one level deeper. For example, ``menu`` is indented by 0 characters, the ``config`` inside of the menu by 4
-  characters, the help of the ``config`` by 8 characters and the text of the ``help`` by 12 characters.
+- Option names in any menus should have consistent prefixes. The prefix currently should have at least 3 characters.
+- The unit of indentation should be 4 spaces. All sub-items belonging to a parent item are indented by one level deeper. For example, ``menu`` is indented by 0 spaces, ``config``  ``menu`` by 4 spaces, ``help`` in ``config`` by 8 spaces, and the text under ``help`` by 12 spaces.
 - No trailing spaces are allowed at the end of the lines.
-- The maximum length of options is set to 40 characters.
-- The maximum length of lines is set to 120 characters.
+- The maximum length of options is 40 characters.
+- The maximum length of lines is 120 characters.
+
+.. note::
 
-Format checker
+    The ``help`` section of each config in the menu is treated as reStructuredText to generate the reference documentation for each option.
+
+Format Checker
 --------------
 
-``tools/ci/check_kconfigs.py`` is provided for checking the ``Kconfig`` formatting rules. The checker checks all ``Kconfig`` and ``Kconfig.projbuild`` files in the ESP-IDF directory and generates a new file with suffix ``.new`` with some recommendations how to fix issues (if there are any). Please note that the checker cannot correct all rules and the responsibility of the developer is to check and make final corrections in order to pass the tests. For example, indentations will be corrected if there isn't some misleading previous formatting but it cannot come up with a common prefix for options inside a menu.
+``tools/ci/check_kconfigs.py`` is provided for checking Kconfig files against the above format rules. The checker checks all Kconfig and ``Kconfig.projbuild`` files in the ESP-IDF directory, and generates a new file with suffix ``.new`` with some suggestions about how to fix issues (if there are any). Please note that the checker cannot correct all format issues and the responsibility of the developer is to final check and make corrections in order to pass the tests. For example, indentations will be corrected if there isn't any misleading formatting, but it cannot come up with a common prefix for options inside a menu.
 
 .. _configuration-options-compatibility:
 
 Backward Compatibility of Kconfig Options
 =========================================
 
-The standard Kconfig_ tools ignore unknown options in ``sdkconfig``. So if a developer has custom settings for options which are renamed in newer ESP-IDF releases then the given setting for the option would be silently ignored. Therefore, several features have been adopted to avoid this:
-
-1. ``kconfgen`` is used by the tool chain to pre-process ``sdkconfig`` files before anything else, for example
-   ``menuconfig``, would read them. As the consequence, the settings for old options will be kept and not ignored.
-2. ``kconfgen`` recursively finds all ``sdkconfig.rename`` files in ESP-IDF directory which contain old and new
-   ``Kconfig`` option names. Old options are replaced by new ones in the ``sdkconfig`` file. Renames that should only appear for a single target can be placed in a target specific rename file: `sdkconfig.rename.TARGET`, where `TARGET` is the target name, e.g. `sdkconfig.rename.esp32s2`.
-3. ``kconfgen`` post-processes ``sdkconfig`` files and generates all build
-   outputs (``sdkconfig.h``, ``sdkconfig.cmake``, ``auto.conf``) by adding a list
-   of compatibility statements, i.e. value of the old option is set the value of
-   the new option (after modification). This is done in order to not break
-   customer codes where old option might still be used.
+The standard Kconfig_ tools ignore unknown options in ``sdkconfig``. So if a developer has custom settings for options which are renamed in newer ESP-IDF releases, then the given setting for the option would be silently ignored. Therefore, several features have been adopted to avoid this:
+
+1. ``kconfgen`` is used by the tool chain to pre-process ``sdkconfig`` files before anything else. For example, ``menuconfig`` would read them, so the settings for old options will be kept and not ignored.
+2. ``kconfgen`` recursively finds all ``sdkconfig.rename`` files in ESP-IDF directory which contain old and new ``Kconfig`` option names. Old options are replaced by new ones in the ``sdkconfig`` file. Renames that should only appear for a single target can be placed in a target-specific rename file ``sdkconfig.rename.TARGET``, where ``TARGET`` is the target name, e.g. ``sdkconfig.rename.esp32s2``.
+3. ``kconfgen`` post-processes ``sdkconfig`` files and generates all build outputs (``sdkconfig.h``, ``sdkconfig.cmake``, and ``auto.conf``) by adding a list of compatibility statements, i.e., the values of old options are set for new options after modification. If users still use old options in their code, this will prevent it from breaking.
 4. :ref:`configuration-deprecated-options` are automatically generated by ``kconfgen``.
 
 .. _configuration-options-reference:
@@ -66,9 +62,9 @@ The standard Kconfig_ tools ignore unknown options in ``sdkconfig``. So if a dev
 Configuration Options Reference
 ===============================
 
-Subsequent sections contain the list of available ESP-IDF options, automatically generated from Kconfig files. Note that depending on the options selected, some options listed here may not be visible by default in the interface of menuconfig.
+Subsequent sections contain the list of available ESP-IDF options automatically generated from Kconfig files. Note that due to dependencies between options, some options listed here may not be visible by default in ``menuconfig``.
 
-By convention, all option names are upper case with underscores. When Kconfig generates sdkconfig and sdkconfig.h files, option names are prefixed with ``CONFIG_``. So if an option ``ENABLE_FOO`` is defined in a Kconfig file and selected in menuconfig, then sdkconfig and sdkconfig.h files will have ``CONFIG_ENABLE_FOO`` defined. In this reference, option names are also prefixed with ``CONFIG_``, same as in the source code.
+By convention, all option names are upper-case letters with underscores. When Kconfig generates ``sdkconfig`` and ``sdkconfig.h`` files, option names are prefixed with ``CONFIG_``. So if an option ``ENABLE_FOO`` is defined in a Kconfig file and selected in ``menuconfig``, then the ``sdkconfig`` and ``sdkconfig.h`` files will have ``CONFIG_ENABLE_FOO`` defined. In the following sections, option names are also prefixed with ``CONFIG_``, same as in the source code.
 
 
 .. include-build-file:: inc/kconfig.inc

docs/zh_CN/api-reference/kconfig.rst

@@ -1 +1,75 @@
-.. include:: ../../en/api-reference/kconfig.rst
+项目配置
+********
+:link_to_translation:`en:[English]`
+
+简介
+=====
+
+ESP-IDF 使用基于 kconfiglib_ 的 esp-idf-kconfig_ 包，而 kconfiglib_ 是 Kconfig_ 系统的 Python 扩展。 Kconfig 提供了编译时的项目配置机制，以及多种类型的配置选项（如整数、字符串和布尔值等）。Kconfig 文件指定了选项之间的依赖关系、默认值、组合方式等。
+
+了解所有可用功能，请查看 Kconfig_ 和 `kconfiglib 扩展`_。
+
+.. _project-configuration-menu:
+
+项目配置菜单
+============
+
+应用程序开发人员可以通过 ``idf.py menuconfig`` 构建目标，在终端中打开项目配置菜单。
+
+更新后，此配置将保存在项目根目录的 ``sdkconfig`` 文件中。借助 ``sdkconfig``，应用程序构建目标将在构建目录中生成 ``sdkconfig.h`` 文件，并使得 ``sdkconfig`` 选项可用于项目构建系统和源文件。
+
+使用 sdkconfig.defaults
+==============================
+
+在某些情况下，例如 ``sdkconfig`` 文件处于版本控制状态时，构建系统可能会不便于更改 ``sdkconfig`` 文件。在构建系统中创建 ``sdkconfig.defaults`` 文件可以避免上述情况发生。该文件可以手动或自动创建，且永远不会被构建系统更改。该文件包含所有不同于默认选项的重要选项，其格式与 ``sdkconfig`` 文件格式相同。如果用户记得所有已更改的配置则可以手动创建 ``sdkconfig.defaults``，或者运行 ``idf.py save-defconfig`` 命令来自动生成此文件。
+
+``sdkconfig.defaults`` 创建后，用户可以删除 ``sdkconfig`` 或将其添加到版本控制系统的忽略列表中（例如 ``git`` 的 ``.gitignore`` 文件）。项目构建目标将自动创建 ``sdkconfig`` 文件，填充 ``sdkconfig.defaults`` 文件中的设置，并将其他设置配置为默认值。请注意，构建时 ``sdkconfig.defaults`` 中的设置不会覆盖 ``sdkconfig`` 的已有设置。了解更多信息，请查看 :ref:`custom-sdkconfig-defaults`。
+
+Kconfig 格式规定
+====================
+
+Kconfig 文件的格式规定如下：
+
+- 在所有菜单中，选项名称的前缀需保持一致。目前，前缀长度应为至少 3 个字符。
+- 每级采用 4 个空格的缩进方式，子项需比父项多缩进一级。例如， ``menu`` 缩进 0 个空格， ``menu`` 中的 ``config`` 则缩进 4 个空格， ``config`` 中的 ``help`` 缩进 8 个空格， ``help`` 下的文本缩进 12 个空格。
+- 行末不得出现尾随空格。
+- 选项最长为 40 个字符。
+- 每行最长为 120 个字符。
+
+.. note::
+
+    菜单中不同配置的 ``help`` 小节将被视为 reStructuredText 格式，以便生成相应选项的参考文档。
+
+格式检查器
+--------------
+
+``tools/ci/check_kconfigs.py`` 可以检查 Kconfig 文件是否符合上述格式规定。检查器会检查 ESP-IDF 目录下的所有 Kconfig 和 ``Kconfig.projbuild`` 文件，如有格式错误，会生成后缀为 ``.new`` 的新文件以提供修改建议。请注意，检查器不能解决所有格式问题，开发人员仍需终审和修改文件使其通过测试。例如，在没有其他误导性格式的情况下，检查器能够更正缩进，但无法提供菜单内选项的常用前缀。
+
+.. _configuration-options-compatibility:
+
+Kconfig 选项的向后兼容性
+================================
+
+标准 Kconfig_ 工具会忽略 ``sdkconfig`` 中的未知选项。因此，如果开发人员对某些选项进行了自定义设置，但这些选项在 ESP-IDF 新版本中被重命名，原有设置将被忽略。以下功能可以避免上述情况发生：
+
+1. 工具链使用 ``kconfgen`` 预处理 ``sdkconfig`` 文件。例如， ``menuconfig`` 会读取这些文件，从而保留旧选项设置。
+2. ``kconfgen`` 递归查找 ESP-IDF 目录中所有包含新旧 Kconfig 选项名称的 ``sdkconfig.rename`` 文件。在 ``sdkconfig`` 文件中，新选项将替换旧选项。针对单个目标的重命名可以放在特定目标的重命名文件 ``sdkconfig.rename.TARGET`` 中，其中 ``TARGET`` 是目标名称，例如 ``sdkconfig.rename.esp32s2``。
+3. ``kconfgen`` 通过添加兼容性语句列表（即经过修改后，将旧选项的值设置为新选项的值），后处理 ``sdkconfig`` 文件，并生成所有构建结果（ ``sdkconfig.h``、 ``sdkconfig.cmake`` 以及 ``auto.conf``）。如果用户在其代码中仍然使用旧选项，此举可以防止用户代码出现问题。
+4. ``kconfgen`` 会自动生成 :ref:`configuration-deprecated-options`。
+
+.. _configuration-options-reference:
+
+配置选项参考
+==================
+
+以下小节包含由 Kconfig 文件自动生成的 ESP-IDF 可用选项列表。请注意，由于所选选项不同，下列某些选项可能在 ``menuconfig`` 界面中默认不可见。
+
+按照惯例，所有选项名称均为大写字母加下划线。当 Kconfig 生成 ``sdkconfig`` 和 ``sdkconfig.h`` 文件时，选项名称会以 ``CONFIG_`` 为前缀。因此，如果 Kconfig 文件定义了 ``ENABLE_FOO`` 选项且 ``menuconfig`` 中选择了该选项，则 ``sdkconfig`` 和 ``sdkconfig.h`` 文件也将定义 ``CONFIG_ENABLE_FOO``。在以下小节中，选项名称也以 ``CONFIG_`` 为前缀，与源代码相同。
+
+
+.. include-build-file:: inc/kconfig.inc
+
+.. _Kconfig: https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt
+.. _esp-idf-kconfig: https://pypi.org/project/esp-idf-kconfig/
+.. _kconfiglib: https://github.com/ulfalizer/Kconfiglib
+.. _kconfiglib 扩展: https://pypi.org/project/kconfiglib/#kconfig-extensions