docs: make Chinese README the default

README.md

@@ -1,231 +1,189 @@
+<!-- WEHUB_ZH_README -->
+> [!NOTE]
+> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
+> [English](./README.en.md) · [原始项目](https://github.com/psf/black) · [上游 README](https://github.com/psf/black/blob/HEAD/README.md)  
+> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
+
 [![Black Logo](https://raw.githubusercontent.com/psf/black/main/docs/_static/logo2-readme.png)](https://black.readthedocs.io/en/stable/)
 
-<h2 align="center">The Uncompromising Code Formatter</h2>
+<h2 align="center">毫不妥协的代码格式化工具</h2>
 
 <p align="center">
-<a href="https://github.com/psf/black/actions"><img alt="Actions Status" src="https://github.com/psf/black/workflows/Test/badge.svg"></a>
-<a href="https://black.readthedocs.io/en/stable/?badge=stable"><img alt="Documentation Status" src="https://readthedocs.org/projects/black/badge/?version=stable"></a>
-<a href="https://coveralls.io/github/psf/black?branch=main"><img alt="Coverage Status" src="https://coveralls.io/repos/github/psf/black/badge.svg?branch=main"></a>
+<a href="https://github.com/psf/black/actions"><img alt="Actions 状态" src="https://github.com/psf/black/workflows/Test/badge.svg"></a>
+<a href="https://black.readthedocs.io/en/stable/?badge=stable"><img alt="文档状态" src="https://readthedocs.org/projects/black/badge/?version=stable"></a>
+<a href="https://coveralls.io/github/psf/black?branch=main"><img alt="覆盖率状态" src="https://coveralls.io/repos/github/psf/black/badge.svg?branch=main"></a>
 <a href="https://github.com/psf/black/blob/main/LICENSE"><img alt="License: MIT" src="https://black.readthedocs.io/en/latest/_static/license.svg"></a>
 <a href="https://pypi.org/project/black/"><img alt="PyPI" src="https://img.shields.io/pypi/v/black"></a>
-<a href="https://pypi.org/project/black"><img alt="Supported Python Versions" src="https://img.shields.io/pypi/pyversions/black?color=brightgreen"></a>
-<a href="https://pepy.tech/project/black"><img alt="Downloads" src="https://static.pepy.tech/badge/black"></a>
+<a href="https://pypi.org/project/black"><img alt="支持的 Python 版本" src="https://img.shields.io/pypi/pyversions/black?color=brightgreen"></a>
+<a href="https://pepy.tech/project/black"><img alt="下载量" src="https://static.pepy.tech/badge/black"></a>
 <a href="https://anaconda.org/conda-forge/black/"><img alt="conda-forge" src="https://img.shields.io/conda/dn/conda-forge/black.svg?label=conda-forge"></a>
-<a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
+<a href="https://github.com/psf/black"><img alt="代码风格：black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
 </p>
 
-> “Any color you like.”
+> “随你喜欢什么颜色。”
 
-_Black_ is the uncompromising Python code formatter. By using it, you agree to cede
-control over minutiae of hand-formatting. In return, _Black_ gives you speed,
-determinism, and freedom from `pycodestyle` nagging about formatting. You will save time
-and mental energy for more important matters.
+_Black_ 是一款毫不妥协的 Python 代码格式化工具。使用它即表示你同意将手工格式化的琐碎细节交由它处理。作为回报，_Black_ 为你带来速度、确定性，以及不再被 `pycodestyle` 唠叨格式的自由。你将节省时间和精力，投入到更重要的事情上。
 
-Blackened code looks the same regardless of the project you're reading. Formatting
-becomes transparent after a while and you can focus on the content instead.
+格式化后的代码无论你在阅读哪个项目，看起来都一样。久而久之，格式化会变得透明，你可以专注于内容本身。
 
-_Black_ makes code review faster by producing the smallest diffs possible.
+_Black_ 通过生成尽可能小的 diff，让代码审查更快。
 
-Watch the [PyCon 2019 talk](https://youtu.be/esZLCuWs_2Y) to learn more.
+观看 [PyCon 2019 演讲](https://youtu.be/esZLCuWs_2Y) 了解更多。
 
 ---
 
-**[Read the documentation on ReadTheDocs!](https://black.readthedocs.io/en/stable)**
+**[在 ReadTheDocs 上阅读文档！](https://black.readthedocs.io/en/stable)**
 
 ---
 
-## Installation and usage
+## 安装与使用
 
-### Installation
+### 安装
 
-_Black_ can be installed by running `pip install black`. It requires Python 3.10+ to
-run. If you want to format Jupyter Notebooks, install with
-`pip install "black[jupyter]"`.
+_Black_ 可通过运行 `pip install black` 安装。运行需要 Python 3.10+。若要格式化 Jupyter Notebook，请使用 `pip install "black[jupyter]"` 安装。
 
-If you want to run _Black_ without installing Python, download one of the
-PyInstaller-built standalone executables from the
-[latest GitHub release](https://github.com/psf/black/releases/latest).
+若不想安装 Python 就想运行 _Black_，可从 [最新 GitHub 发布版本](https://github.com/psf/black/releases/latest). 下载 PyInstaller 构建的独立可执行文件之一。
 
-### Usage
+### 用法
 
-To get started right away with sensible defaults:
+若要立即以合理的默认配置开始使用：
 
 ```sh
 black {source_file_or_directory}
 ```
 
-You can run _Black_ as a package if running it as a script doesn't work:
+若以脚本方式运行无效，可将 _Black_ 作为包运行：
 
 ```sh
 python -m black {source_file_or_directory}
 ```
 
-Further information can be found in our docs:
+更多信息请参阅我们的文档：
 
-- [Usage and Configuration](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html)
+- [用法与配置](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html)
 
-_Black_ is already [successfully used](https://github.com/psf/black#used-by) by many
-projects, small and big. _Black_ has a comprehensive test suite, with efficient parallel
-tests, and our own auto formatting and parallel Continuous Integration runner. Now that
-we have become stable, you should not expect large formatting changes in the future.
-Stylistic changes will mostly be responses to bug reports and support for new Python
-syntax. For more information please refer to
-[The Black Code Style](https://black.readthedocs.io/en/stable/the_black_code_style/index.html).
+_Black_ 已被众多大小项目 [成功采用](https://github.com/psf/black#used-by)。_Black_ 拥有全面的测试套件，包含高效的并行测试，以及自有的自动格式化与并行持续集成（Continuous Integration）运行器。既然我们已趋于稳定，未来你不应再期待大规模格式变更。风格上的变化将主要针对 bug 报告和新 Python 语法支持。更多信息请参阅 [The Black Code Style](https://black.readthedocs.io/en/stable/the_black_code_style/index.html).
 
-Also, as a safety measure which slows down processing, _Black_ will check that the
-reformatted code still produces a valid AST that is effectively equivalent to the
-original (see the
-[Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#ast-before-and-after-formatting)
-section for details). If you're feeling confident, use `--fast`.
+此外，作为一项会减慢处理速度的安全措施，_Black_ 会检查重新格式化后的代码仍能生成与原始代码在语义上等价的有效 AST（详见 [Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#ast-before-and-after-formatting) 一节）。若你很有把握，可使用 `--fast`。
 
-## The _Black_ code style
+## _Black_ 代码风格
 
-_Black_ is a PEP 8 compliant opinionated formatter. _Black_ reformats entire files in
-place. Style configuration options are deliberately limited and rarely added. It doesn't
-take previous formatting into account (see
-[Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#pragmatism)
-for exceptions).
+_Black_ 是一款符合 PEP 8 的 opinionated（有主见）格式化工具。_Black_ 会就地重新格式化整个文件。风格配置选项被刻意限制，很少新增。它不会考虑先前的格式化（例外见 [Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#pragmatism)）。
 
-Our documentation covers the current _Black_ code style, but planned changes to it are
-also documented. They're both worth taking a look at:
+我们的文档涵盖当前 _Black_ 代码风格，也记录了计划中的变更。两者都值得一看：
 
-- [The _Black_ Code Style: Current style](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html)
-- [The _Black_ Code Style: Future style](https://black.readthedocs.io/en/stable/the_black_code_style/future_style.html)
+- [_Black_ 代码风格：当前风格](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html)
+- [_Black_ 代码风格：未来风格](https://black.readthedocs.io/en/stable/the_black_code_style/future_style.html)
 
-Changes to the _Black_ code style are bound by the Stability Policy:
+_Black_ 代码风格的变更受稳定性政策（Stability Policy）约束：
 
-- [The _Black_ Code Style: Stability Policy](https://black.readthedocs.io/en/stable/the_black_code_style/index.html#stability-policy)
+- [_Black_ 代码风格：稳定性政策](https://black.readthedocs.io/en/stable/the_black_code_style/index.html#stability-policy)
 
-Please refer to this document before submitting an issue. What seems like a bug might be
-intended behaviour.
+提交 issue 前请先查阅本文档。看似 bug 的行为可能是预期行为。
 
-### Pragmatism
+### 实用主义（Pragmatism）
 
-Early versions of _Black_ used to be absolutist in some respects. They took after its
-initial author. This was fine at the time as it made the implementation simpler and
-there were not many users anyway. Not many edge cases were reported. As a mature tool,
-_Black_ does make some exceptions to rules it otherwise holds.
+_Black_ 早期版本在某些方面曾是绝对主义者，沿袭了其最初作者的风格。这在当时并无大碍，因为实现更简单，而且用户也不多，报告的边界情况很少。作为成熟工具，_Black_ 会对它一贯坚持的规则做出一些例外。
 
-- [The _Black_ code style: Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#pragmatism)
+- [_Black_ 代码风格：实用主义](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#pragmatism)
 
-Please refer to this document before submitting an issue just like with the document
-above. What seems like a bug might be intended behaviour.
+提交 issue 前请先查阅本文档，与上文文档一样。看似 bug 的行为可能是预期行为。
 
-## Configuration
+## 配置
 
-_Black_ is able to read project-specific default values for its command line options
-from a `pyproject.toml` file. This is especially useful for specifying custom
-`--include` and `--exclude`/`--force-exclude`/`--extend-exclude` patterns for your
-project.
+_Black_ 可从 `pyproject.toml` 文件读取项目特定的命令行选项默认值。这对于为项目指定自定义 `--include` 以及 `--exclude`/`--force-exclude`/`--extend-exclude` 模式尤其有用。
 
-You can find more details in our documentation:
+更多细节请参阅我们的文档：
 
-- [The basics: Configuration via a file](https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#configuration-via-a-file)
+- [基础：通过文件配置](https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#configuration-via-a-file)
 
-And if you're looking for more general configuration documentation:
+若你需要更通用的配置文档：
 
-- [Usage and Configuration](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html)
+- [用法与配置](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html)
 
-**Pro-tip**: If you're asking yourself "Do I need to configure anything?" the answer is
-"No". _Black_ is all about sensible defaults. Applying those defaults will have your
-code in compliance with many other _Black_ formatted projects.
+**专业提示**：若你在想「我需要配置什么吗？」答案是「不需要」。_Black_ 的核心就是合理默认。应用这些默认即可让你的代码与许多其他 _Black_ 格式化项目保持一致。
 
-## Used by
+## 使用者
 
-The following notable open-source projects trust _Black_ with enforcing a consistent
-code style: pytest, tox, Pyramid, Django, Django Channels, Hypothesis, attrs,
-SQLAlchemy, Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv),
-pandas, Pillow, Twisted, LocalStack, every Datadog Agent Integration, Home Assistant,
-Zulip, Kedro, OpenOA, FLORIS, ORBIT, WOMBAT, and many more.
+以下知名开源项目信任 _Black_ 来强制执行一致的代码风格：pytest、tox、Pyramid、Django、Django Channels、Hypothesis、attrs、SQLAlchemy、Poetry、PyPA 应用（Warehouse、Bandersnatch、Pipenv、virtualenv）、pandas、Pillow、Twisted、LocalStack、所有 Datadog Agent Integration、Home Assistant、Zulip、Kedro、OpenOA、FLORIS、ORBIT、WOMBAT，以及更多。
 
-The following organizations use _Black_: Dropbox, KeepTruckin, Lyft, Mozilla, Quora,
-Duolingo, QuantumBlack, Tesla, Archer Aviation.
+以下组织使用 _Black_：Dropbox、KeepTruckin、Lyft、Mozilla、Quora、Duolingo、QuantumBlack、Tesla、Archer Aviation。
 
-Are we missing anyone? Let us know.
+有遗漏吗？请告知我们。
 
-## Testimonials
+## 用户评价
 
-**Mike Bayer**, creator of [`SQLAlchemy`](https://www.sqlalchemy.org/):
+**Mike Bayer**，[`SQLAlchemy`](https://www.sqlalchemy.org/): 的创建者：
 
-> I can't think of any single tool in my entire programming career that has given me a
-> bigger productivity increase by its introduction. I can now do refactorings in about
-> 1% of the keystrokes that it would have taken me previously when we had no way for
-> code to format itself.
+> 回想我整个编程生涯，我想不出还有哪一款工具，仅凭引入就给我带来了如此巨大的生产力提升。如今我们做重构，大约只需过去没有自动格式化时 1% 的按键量。
 
-**Dusty Phillips**,
-[writer](https://www.amazon.com/stores/Dusty-Phillips/author/B00HSYG5BO):
+**Dusty Phillips**，[作家](https://www.amazon.com/stores/Dusty-Phillips/author/B00HSYG5BO):：
 
-> _Black_ is opinionated so you don't have to be.
+> _Black_ 替你做了主见选择，你就不必再纠结。
 
-**Hynek Schlawack**, creator of [`attrs`](https://www.attrs.org/), core developer of
-Twisted and CPython:
+**Hynek Schlawack**，[`attrs`](https://www.attrs.org/), 的创建者，Twisted 与 CPython 核心开发者：
 
-> An auto-formatter that doesn't suck is all I want for Xmas!
+> 我圣诞节唯一想要的，就是一款不烂的垃圾自动格式化工具！
 
-**Carl Meyer**, [Django](https://www.djangoproject.com/) core developer:
+**Carl Meyer**，[Django](https://www.djangoproject.com/) 核心开发者：
 
-> At least the name is good.
+> 至少名字起得好。
 
-**Kenneth Reitz**, creator of [`requests`](https://requests.readthedocs.io/en/stable/)
-and [pipenv](https://pipenv.pypa.io/en/stable/):
+**Kenneth Reitz**，[`requests`](https://requests.readthedocs.io/en/stable/) 与 [pipenv](https://pipenv.pypa.io/en/stable/): 的创建者：
 
-> This vastly improves the formatting of our code. Thanks a ton!
+> 这极大地改善了我们代码的格式。非常感谢！
 
-## Show your style
+## 展示你的风格
 
-Use the badge in your project's README.md:
+在你的项目 README.md 中使用徽章：
 
 ```md
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 ```
 
-Using the badge in README.rst:
+在 README.rst 中使用徽章：
 
 ```rst
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
     :target: https://github.com/psf/black
 ```
 
-Looks like this:
+效果如下：
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
-## License
+## 许可证
 
 MIT
 
-## Contributing
+## 贡献
 
-Welcome! Happy to see you willing to make the project better. You can get started by
-reading this:
+欢迎！很高兴看到你愿意让项目变得更好。你可以从阅读以下内容开始：
 
 - [Contributing: The basics](https://black.readthedocs.io/en/latest/contributing/the_basics.html)
 
-You can also take a look at the rest of the contributing docs or talk with the
-developers:
+你也可以查看其余贡献文档，或与开发者交流：
 
 - [Contributing documentation](https://black.readthedocs.io/en/latest/contributing/index.html)
 - [Chat on Discord](https://discord.gg/RtVdv86PrH)
 
-## Change log
+## 更新日志
 
-The log has become rather long. It moved to its own file.
+日志已经变得相当长了，因此已移至单独的文件。
 
-See [CHANGES](https://black.readthedocs.io/en/latest/change_log.html).
+参见 [CHANGES](https://black.readthedocs.io/en/latest/change_log.html).
 
-## Authors
+## 作者
 
-The author list is quite long nowadays, so it lives in its own file.
+作者名单如今已相当长，因此它存放在单独的文件中。
 
-See [AUTHORS.md](./AUTHORS.md)
+参见 [AUTHORS.md](./AUTHORS.md)
 
-## Code of Conduct
+## 行为准则
 
-Everyone participating in the _Black_ project, and in particular in the issue tracker,
-pull requests, and social media activity, is expected to treat other people with respect
-and more generally to follow the guidelines articulated in the
+参与 _Black_ 项目的每个人，尤其是在 issue tracker、pull requests 和社交媒体活动中，都应以尊重的态度对待他人，并更普遍地遵循
 [Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/).
+中所述的准则。
 
-At the same time, humor is encouraged. In fact, basic familiarity with Monty Python's
-Flying Circus is expected. We are not savages.
+同时，我们鼓励幽默。事实上，我们期望大家基本熟悉 Monty Python's Flying Circus（《巨蟒剧团》）。我们不是野蛮人。
 
-And if you _really_ need to slap somebody, do it with a fish while dancing.
+而如果你 _真的_ 需要扇某人耳光，那就一边跳舞一边用鱼来打。