Merge branch 'main' into translate-async-await

Author: rosekc

.github/pull_request_template.md

@@ -1,22 +1,23 @@
 <!--
-Before opening a PR, make sure you have claimed to translate a file by
-adding your username after the file entry in the README.
+如果这个 PR 是认领某个要翻译的章节，那么可以删除这个 PR 模板的所有内容。
 -->
 
 <!--
-Link to relevant issues or previous PRs, one per line. Use "fixes" to
-automatically close an issue.
+如果有不确定的翻译，请在这里逐条注明并替换这个注释。你也可以在 Discussion 创建讨论。
 -->
 
-- fixes #<issue number>
 
 <!--
-Ensure each step in the "Contrubuting Guide" of the README is complete by
-adding an "x" to each box below.
+如果你的 PR 是要处理某个 issue，请把下面的 `<issue number>` 替换为对应的 issue 编号。如果没有的话，可以删除下面这一行。
 -->
 
-Checklist:
+- fixes #<issue number>
+
+<!--
+对于翻译 PR，确保你已经完整阅读 README.md 里的《Contrubuting Guide》小节和置顶 issue《翻译要求与建议》。完成并勾选下面的检查清单（把方括号里的空格替换为 `x`）。
+-->
 
-- [ ] Fill the checkbox of the related file entry in the README with an "x".
-- [ ] Run `pre-commit` hooks and fix any issues.
-- [ ] Build docs locally, no warnings or errors.
+- [ ] 在 README.md 中勾选翻译的章节条目（把方括号里的空格替换为 `x`）.
+- [ ] 在本地生成文档并预览输出，处理所有错误和异常。
+- [ ] 运行 `pre-commit` 钩子，处理所有问题。
+- [ ] 更新 `.po` 文件顶部的 `Last-Translator` 字段。

.github/workflows/sync.yaml

@@ -0,0 +1,66 @@
+name: Sync
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 19 * * *" # Run at 3am UTF+8 every day
+
+jobs:
+  sync:
+    name: Sync with upstream docs
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
+
+      - name: Fetch upstream changes
+        id: fetch-changes
+        run: |
+          git config --local user.email "[email protected]"
+          git config --local user.name "GitHub Action"
+          git remote add upstream https://github.com/pallets/flask.git
+          git fetch upstream
+          git merge upstream/2.0.x -m "Merge upstream changes into 'main' by GitHub Actions"
+          # If docs/ has changes, continue below steps otherwise abort
+          git diff --name-only origin/main HEAD | grep -q -e '^docs/'
+
+      - name: Generate Translation
+        run: |
+          pip install -r requirements/docs.txt
+          pip install PyGithub
+          pip install -e .
+          cd docs
+          make gettext
+          sphinx-intl update -p _build/gettext
+          cd ..
+          git add docs/
+          git commit -m "Update po files by GitHub Actions"
+
+      - name: Push changes
+        uses: ad-m/github-push-action@master
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create issue
+        shell: python
+        run: |
+          import subprocess, os
+          from datetime import datetime
+          from github import Github
+          current_date = datetime.today().strftime(' %Y-%m-%d')
+          g = Github(os.getenv('GITHUB_TOKEN'))
+          changed = subprocess.check_output("git diff --name-only HEAD~1 HEAD | grep -e '^docs/locales/'", shell=True, text=True)
+          body = "## Changed po files\n\n" + "\n".join(f"- [ ] {line}" for line in changed.splitlines() if line.strip())
+          repo = g.get_repo(os.getenv('REPO'))
+          label = repo.get_label('sync')
+          issue = repo.create_issue(title=os.getenv('ISSUE_TITLE') + current_date, body=body, labels=[label])
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          ISSUE_TITLE: Sync translation for upstream updates

.gitignore

@@ -24,3 +24,6 @@ htmlcov/
 .coverage
 .coverage.*
 *,cover
+
+# Translation
+*.mo

CHANGES.rst

@@ -13,6 +13,12 @@ Version 2.0.2
 
 Unreleased
 
+-   Fix type annotation for ``teardown_request``. :issue:`4093`
+-   Fix type annotation for ``before_request`` and ``before_app_request``
+    decorators. :issue:`4104`
+-   Fixed the issue where typing requires template global
+    decorators to accept functions with no arguments. :issue:`4098`
+
 
 Version 2.0.1
 -------------

README.md

@@ -1,10 +1,14 @@
-# Flask Docs Translation
+# Flask 中文文档
 
-这里是 Flask 文档中文翻译项目，欢迎参与！在开始翻译之前，请务必阅读下面的 Contributing Guide 了解贡献流程，然后阅读[这个 Issue](https://github.com/greyli/flask-docs-zh/issues/11) 了解翻译基本要求和建议，并在[这个 Dicussion](https://github.com/greyli/flask-docs-zh/discussions/12) 投票选出你认为合适的翻译词汇。
+这里是 Flask 文档中文翻译项目，欢迎参与！
 
-如果有其他问题和相关想法，请[创建 Discussion](https://github.com/greyli/flask-docs-zh/discussions/new) 发起讨论；如果对翻译流程和项目设置有改进建议，或是发现了翻译错误和笔误，请[创建 Issue](https://github.com/greyli/flask-docs-zh/issues/new) 反馈。
+1. 在开始翻译之前，请务必阅读下面的 Contributing Guide 了解翻译流程，然后阅读[这个 issue](https://github.com/greyli/flask-docs-zh/issues/11) 了解翻译要求，并在[这些 discussions](https://github.com/greyli/flask-docs-zh/discussions/categories/vote) 中分别投票选出最佳翻译词汇、中文 logo 字体和中文标语。
+2. 需要强调的是，完成一章的翻译要提交两个 PR：第一个 PR 在对应的章节条目后添加自己的用户名以认领章节；第二个 PR 翻译对应的 `.po` 文件并勾选完成的章节条目。先认领，再翻译，一次只认领一章。
+3. 不要改动任何 ReStructuredText 标记、变量/类/函数/方法名称、URL 等。
 
-这个项目在后期会转移到 [Flask Community Work Group](https://github.com/flaskcwg) 组织，并链接到 Flask 官方文档作为官方中文翻译。
+如果有其他问题和相关想法，请[创建 discussion](https://github.com/greyli/flask-docs-zh/discussions/new) 发起讨论；如果对翻译流程和项目设置有改进建议，或是发现了翻译错误和笔误，请[创建 issue](https://github.com/greyli/flask-docs-zh/issues/new) 反馈。
+
+这个项目在后期会转移到 [FlaskCWG](https://github.com/flaskcwg) 组织，并在翻译完成后链接到 Flask 官方文档。
 
 
 ## Contributing Guide
@@ -87,7 +91,7 @@ An example of one such file, from docs/.../index.po, is given below.
 ```po
 #: ../../index.rst:4
 msgid "Welcome to Flask"
-msgstr "<FILL HERE BY TARGET LANGUAGE>"
+msgstr "欢迎来到 Flask 的世界"
 ```
 
 Another case, msgid is multi-line text and contains reStructuredText syntax:
@@ -98,11 +102,12 @@ msgid ""
 "Welcome to Flask's documentation. Get started with :doc:`installation` "
 "and then get an overview with the :doc:`quickstart`."
 msgstr ""
-"FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE :doc:`installation` "
-"FILL HERE BY TARGET LANGUAGE :doc:`quickstart`."
+"欢迎来到 Flask 的文档。你可以从 :doc:`installation` 入手"
+"然后阅读 :doc:`quickstart` 来了解基本概念。"
 ```
 
-Please be careful not to break reST notation. Most po-editors will help you with that.
+Please be careful not to break reST notation. Most
+[po-editors](https://www.gnu.org/software/trans-coord/manual/web-trans/html_node/PO-Editors.html) will help you with that.
 
 - Mark the chapter as finished (fill the checkbox with "x"):
 
@@ -147,20 +152,6 @@ the new branch. Click the "Compare & pull request" button to create a PR.
 - The translation coordinator will review your PR very soon. Thank you!
 
 
-### Tips
-
-**If you use translator.** Do not put the whole content of a file into the
-translator, this can cause problems with code snippets, reserved words of the
-programming language, special ReStructuredText tags and so on, the best way is to
-translate paragraph by paragraph, header by header.
-
-**Maintaining the essence.** Although the translator does a large part of the work,
-sometimes the resulting translation does not match the meaning of the original
-resource. It is important to correct this so that the original meaning is not lost.
-Do not change names of functions, classes, variables methods etc in the codes, it
-is possible that they will stop working.
-
-
 ## Translation To-do List
 
 Be sure only mark one chapter at a time, mark another one when the former
@@ -171,29 +162,29 @@ if you doesn't finish the translation in ten days.
 ### docs/
 
 - [ ] advanced_foreword (reserved)
-- [ ] appcontext
+- [ ] appcontext [@rosekc](https://github.com/rosekc) rosekc
 - [x] async-await [@rosekc](https://github.com/rosekc) rosekc
 - [ ] becomingbig
-- [ ] blueprints
+- [x] blueprints [@frostming](https://github.com/frostming) Frost Ming
 - [ ] changes
 - [ ] cli
-- [ ] config
+- [ ] config [@guiqiqi](https://github.com/guiqiqi) Doge-GUI
 - [ ] contributing
 - [ ] debugging
 - [ ] design
-- [ ] errorhandling
+- [ ] errorhandling [@qiufengyu](https://github.com/qiufengyu) Fengyu
 - [ ] extensiondev
 - [ ] extensions
 - [ ] foreword (reserved)
 - [ ] htmlfaq
-- [ ] index (reserved)
-- [ ] installation (reserved)
+- [x] index [@greyli](https://github.com/greyli) Grey Li
+- [x] installation [@greyli](https://github.com/greyli) Grey Li
 - [ ] logging
 - [ ] quickstart (reserved)
-- [ ] reqcontext
+- [ ] reqcontext [@rosekc](https://github.com/rosekc) rosekc
 - [ ] security
 - [ ] server
-- [ ] shell
+- [ ] shell [@LTakamori](https://github.com/LTakamori) LTakamori
 - [ ] signals
 - [ ] templating
 - [ ] testing
@@ -206,7 +197,7 @@ if you doesn't finish the translation in ten days.
 - [ ] database
 - [ ] deploy
 - [ ] factory
-- [ ] index
+- [x] index [@greyli](https://github.com/greyli) Grey Li
 - [ ] install
 - [ ] layout
 - [ ] next
@@ -221,7 +212,7 @@ if you doesn't finish the translation in ten days.
 - [ ] asgi
 - [ ] cgi
 - [ ] fastcgi
-- [ ] index
+- [ ] index [@180909](https://github.com/180909) 180909
 - [ ] mod_wsgi
 - [ ] uwsgi
 - [ ] wsgi-standalone

docs/_static/flask-logo.png

@@ -7,7 +7,8 @@ Using ``async`` and ``await``
 
 Routes, error handlers, before request, after request, and teardown
 functions can all be coroutine functions if Flask is installed with the
-``async`` extra (``pip install flask[async]``). This allows views to be
+``async`` extra (``pip install flask[async]``). It requires Python 3.7+
+where ``contextvars.ContextVar`` is available. This allows views to be
 defined with ``async def`` and use ``await``.
 
 .. code-block:: python

docs/async-await.rst

@@ -39,13 +39,14 @@
 html_theme_options = {"index_sidebar_logo": False}
 html_context = {
     "project_links": [
-        ProjectLink("Donate", "https://palletsprojects.com/donate"),
+        ProjectLink("捐赠", "https://palletsprojects.com/donate"),
         ProjectLink("PyPI Releases", "https://pypi.org/project/Flask/"),
-        ProjectLink("Source Code", "https://github.com/pallets/flask/"),
+        ProjectLink("源码", "https://github.com/pallets/flask/"),
         ProjectLink("Issue Tracker", "https://github.com/pallets/flask/issues/"),
-        ProjectLink("Website", "https://palletsprojects.com/p/flask/"),
+        ProjectLink("网站", "https://palletsprojects.com/p/flask/"),
         ProjectLink("Twitter", "https://twitter.com/PalletsTeam"),
-        ProjectLink("Chat", "https://discord.gg/pallets"),
+        ProjectLink("聊天", "https://discord.gg/pallets"),
+        ProjectLink("参与翻译", "https://github.com/greyli/flask-docs-zh"),
     ]
 }
 html_sidebars = {
@@ -56,7 +57,7 @@
 html_static_path = ["_static"]
 html_favicon = "_static/flask-icon.png"
 html_logo = "_static/flask-icon.png"
-html_title = f"Flask Documentation ({version})"
+html_title = f"Flask 文档 ({version})"
 html_show_sourcelink = False
 
 # LaTeX ----------------------------------------------------------------
@@ -100,7 +101,7 @@ def setup(app):
 
 # Translation ----------------------------------------------------------
 
-locale_dirs = ['locales']   # path is example but recommended.
-gettext_compact = False     # optional.
-# see https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language
-language = ''  # update this
+locale_dirs = ["locales"]
+gettext_compact = False
+language = "zh_CN"
+html_search_language = "zh"

docs/conf.py

@@ -8,6 +8,8 @@ Python Version
 We recommend using the latest version of Python. Flask supports Python
 3.6 and newer.
 
+``async`` support in Flask requires Python 3.7+ for ``contextvars.ContextVar``.
+
 
 Dependencies
 ------------

docs/installation.rst

@@ -11,7 +11,7 @@ msgstr ""
 "POT-Creation-Date: 2021-05-25 19:31+0800\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
-"Language-Team: LANGUAGE <[email protected]>\n"
+"Language-Team: zh_CN <[email protected]>\n"
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=utf-8\n"
 "Content-Transfer-Encoding: 8bit\n"