Skip to content

Commit 906bfa5

Browse files
greyligreyli
committed
Move contributing guide to separate file & add reviewers section
1 parent b1d2206 commit 906bfa5

File tree

2 files changed

+151
-147
lines changed

2 files changed

+151
-147
lines changed

‎CONTRIBUTING.md

+139
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
## Contributing Guide
2+
3+
4+
### Installation
5+
6+
- Click the [Fork](https://github.com/greyli/flask-docs-zh/fork) button to fork this repository on GitHub.
7+
- Clone your fork repository locally (replace `{username}` with your username):
8+
9+
```
10+
$ git clone https://github.com/{username}/flask-docs-zh
11+
$ cd flask-docs-zh
12+
$ git remote add upstream https://github.com/greyli/flask-docs-zh
13+
```
14+
15+
- Create a virtual environment and install requirements:
16+
17+
For Linux/macOS:
18+
19+
```
20+
$ python3 -m venv env
21+
$ source env/bin/activate
22+
$ python -m pip install --upgrade pip setuptools
23+
$ pip install -r requirements/dev.txt
24+
$ pip install -e .
25+
$ pre-commit install
26+
```
27+
28+
For Windows:
29+
30+
```
31+
> python -m venv env
32+
> env\Scripts\activate
33+
> python -m pip install --upgrade pip setuptools
34+
> pip install -r .\requirements\dev.txt
35+
> pip install -e .
36+
> pre-commit install
37+
```
38+
39+
40+
### Self-Assignment
41+
42+
- Open your fork repository on GitHub.
43+
- Click the "Fetch upstream" button to update your fork.
44+
- Click the edit button (a pencil icon in the upper right corner of the README)
45+
to edit the README.
46+
- Find the "Translation To-do List" section, mark the chapter you want to
47+
translate in following format:
48+
49+
```
50+
- [ ] example @your_username Your Name
51+
```
52+
53+
You can link the username to your GitHub profile:
54+
55+
```
56+
- [ ] example [@your_username](https://github.com/your_username) Your Name
57+
```
58+
59+
- Leave a commit message (e.g., "Assign example to @your_username"), then select
60+
"Create a new branch for this commit and start a pull request" and click the
61+
"Commit changes" button to create a PR.
62+
63+
64+
### Translation
65+
66+
- When the self-assignment PR is merged, create a new branch locally
67+
(be sure to update the example branch name, for example, `translate-cli`):
68+
69+
```
70+
$ git fetch upstream
71+
$ git checkout -b your-branch-name upstream/main
72+
```
73+
74+
- Translate the `.po` file in the `docs/locales/zh_CN/LC_MESSAGES` directory.
75+
76+
An example of one such file, from docs/.../index.po, is given below.
77+
78+
```po
79+
#: ../../index.rst:4
80+
msgid "Welcome to Flask"
81+
msgstr "欢迎来到 Flask 的世界"
82+
```
83+
84+
Another case, msgid is multi-line text and contains reStructuredText syntax:
85+
86+
```po
87+
#: ../../index.rst:11
88+
msgid ""
89+
"Welcome to Flask's documentation. Get started with :doc:`installation` "
90+
"and then get an overview with the :doc:`quickstart`."
91+
msgstr ""
92+
"欢迎来到 Flask 的文档。你可以从 :doc:`installation` 入手"
93+
"然后阅读 :doc:`quickstart` 来了解基本概念。"
94+
```
95+
96+
Please be careful not to break reST notation. Most
97+
[po-editors](https://www.gnu.org/software/trans-coord/manual/web-trans/html_node/PO-Editors.html) will help you with that.
98+
99+
- Mark the chapter as finished (fill the checkbox with "x"):
100+
101+
```
102+
- [x] example @your_username Your Name
103+
```
104+
105+
- Update the `Last-Translator` field at the top of the `.po` file.
106+
- Commit the changes:
107+
108+
```
109+
$ git add docs/locales/zh_CN/LC_MESSAGES/example.po README.md
110+
$ git commit -m "Translate docs/example"
111+
```
112+
113+
- Build the docs and preview the changes:
114+
115+
For Linux/macOS:
116+
117+
```
118+
$ cd docs
119+
$ make html
120+
```
121+
122+
For Windows:
123+
124+
```
125+
> cd docs
126+
> .\make.bat html
127+
```
128+
129+
Open `{project_location}/docs/_build/html/index.html` in your browser to view the docs.
130+
131+
- If everything is working as expected, push the changes to GitHub:
132+
133+
```
134+
$ git push origin your-branch-name
135+
```
136+
137+
- Open the home page of your forked repository, you will see a notice about
138+
the new branch. Click the "Compare & pull request" button to create a PR.
139+
- The translation coordinator will review your PR very soon. Thank you!

‎README.md

+12-147
Original file line numberDiff line numberDiff line change
@@ -1,162 +1,27 @@
1-
# Flask 中文文档
1+
# The Chinese Translation of Flask's Documentation
22

33
这里是 Flask 文档中文翻译项目，欢迎参与！
44

5-
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 字体和中文标语。
6-
2. 需要强调的是，完成一章的翻译要提交两个 PR：第一个 PR 在对应的章节条目后添加自己的用户名以认领章节；第二个 PR 翻译对应的 `.po` 文件并勾选完成的章节条目。先认领，再翻译，一次只认领一章。
7-
3. 不要改动任何 ReStructuredText 标记、变量/类/函数/方法名称、URL 等。
5+
参与前请完成以下任务：
86

9-
如果有其他问题和相关想法，请[创建 discussion](https://github.com/greyli/flask-docs-zh/discussions/new) 发起讨论；如果对翻译流程和项目设置有改进建议，或是发现了翻译错误和笔误，请[创建 issue](https://github.com/greyli/flask-docs-zh/issues/new) 反馈。
10-
11-
这个项目在后期会转移到 [FlaskCWG](https://github.com/flaskcwg) 组织，并在翻译完成后链接到 Flask 官方文档。
12-
13-
14-
## Contributing Guide
15-
16-
17-
### Installation
18-
19-
- Click the "Fork" button to fork this repository on GitHub.
20-
- Clone your fork repository locally (replace `{username}` with your username):
21-
22-
```
23-
$ git clone https://github.com/{username}/flask-docs-zh
24-
$ cd flask-docs-zh
25-
$ git remote add upstream https://github.com/greyli/flask-docs-zh
26-
```
27-
28-
- Create a virtual environment and install requirements:
29-
30-
For Linux/macOS:
31-
32-
```
33-
$ python3 -m venv env
34-
$ source env/bin/activate
35-
$ python -m pip install --upgrade pip setuptools
36-
$ pip install -r requirements/dev.txt
37-
$ pip install -e .
38-
$ pre-commit install
39-
```
40-
41-
For Windows:
42-
43-
```
44-
> python -m venv env
45-
> env\Scripts\activate
46-
> python -m pip install --upgrade pip setuptools
47-
> pip install -r .\requirements\dev.txt
48-
> pip install -e .
49-
> pre-commit install
50-
```
51-
52-
53-
### Self-Assignment
54-
55-
- Open your fork repository on GitHub.
56-
- Click the "Fetch upstream" button to update your fork.
57-
- Click the edit button (a pencil icon in the upper right corner of the README)
58-
to edit the README.
59-
- Find the "Translation To-do List" section, mark the chapter you want to
60-
translate in following format:
61-
62-
```
63-
- [ ] example @your_username Your Name
64-
```
65-
66-
You can link the username to your GitHub profile:
67-
68-
```
69-
- [ ] example [@your_username](https://github.com/your_username) Your Name
70-
```
71-
72-
- Leave a commit message (e.g., "Assign example to @your_username"), then select
73-
"Create a new branch for this commit and start a pull request" and click the
74-
"Commit changes" button to create a PR.
7+
1. 阅读《[贡献指南](https://github.com/greyli/flask-docs-zh/blob/main/CONTRIBUTING.md)》了解翻译贡献流程。
8+
2. 阅读《[翻译要求与建议](https://github.com/greyli/flask-docs-zh/issues/11)》了解翻译要求。
9+
3. 在[这些讨论](https://github.com/greyli/flask-docs-zh/discussions/categories/vote)中分别投票选出你喜欢的中文 logo 字体、中文标语翻译和词汇翻译。
7510

11+
**需要强调的是，完成一章的翻译要提交两个 PR：第一个 PR 在对应的章节条目后添加自己的用户名以认领章节（[示例 PR](https://github.com/greyli/flask-docs-zh/pull/20/files)）；第二个 PR 翻译对应的 `.po` 文件并勾选完成的章节条目（[示例 PR](https://github.com/greyli/flask-docs-zh/pull/43/files)）。先认领，再翻译，一次只认领一章。**
7612

77-
### Translation
78-
79-
- When the self-assignment PR is merged, create a new branch locally
80-
(be sure to update the example branch name, for example, `translate-cli`):
81-
82-
```
83-
$ git fetch upstream
84-
$ git checkout -b your-branch-name upstream/main
85-
```
86-
87-
- Translate the `.po` file in the `docs/locales/zh_CN/LC_MESSAGES` directory.
88-
89-
An example of one such file, from docs/.../index.po, is given below.
90-
91-
```po
92-
#: ../../index.rst:4
93-
msgid "Welcome to Flask"
94-
msgstr "欢迎来到 Flask 的世界"
95-
```
96-
97-
Another case, msgid is multi-line text and contains reStructuredText syntax:
98-
99-
```po
100-
#: ../../index.rst:11
101-
msgid ""
102-
"Welcome to Flask's documentation. Get started with :doc:`installation` "
103-
"and then get an overview with the :doc:`quickstart`."
104-
msgstr ""
105-
"欢迎来到 Flask 的文档。你可以从 :doc:`installation` 入手"
106-
"然后阅读 :doc:`quickstart` 来了解基本概念。"
107-
```
108-
109-
Please be careful not to break reST notation. Most
110-
[po-editors](https://www.gnu.org/software/trans-coord/manual/web-trans/html_node/PO-Editors.html) will help you with that.
111-
112-
- Mark the chapter as finished (fill the checkbox with "x"):
113-
114-
```
115-
- [x] example @your_username Your Name
116-
```
117-
118-
- Update the `Last-Translator` field at the top of the `.po` file.
119-
- Commit the changes:
120-
121-
```
122-
$ git add docs/locales/zh_CN/LC_MESSAGES/example.po README.md
123-
$ git commit -m "Translate docs/example"
124-
```
125-
126-
- Build the docs and preview the changes:
127-
128-
For Linux/macOS:
129-
130-
```
131-
$ cd docs
132-
$ make html
133-
```
134-
135-
For Windows:
136-
137-
```
138-
> cd docs
139-
> .\make.bat html
140-
```
141-
142-
Open `{project_location}/docs/_build/html/index.html` in your browser to view the docs.
13+
如果有其他问题和相关想法，请[创建 discussion](https://github.com/greyli/flask-docs-zh/discussions/new) 发起讨论；如果对翻译流程和项目设置有改进建议，或是发现了翻译错误和笔误，请[创建 issue](https://github.com/greyli/flask-docs-zh/issues/new) 反馈。
14314

144-
- If everything is working as expected, push the changes to GitHub:
15+
这个项目在后期会转移到 [FlaskCWG](https://github.com/flaskcwg) 组织，并在翻译完成后链接到 Flask 官方文档。
14516

146-
```
147-
$ git push origin your-branch-name
148-
```
14917

150-
- Open the home page of your forked repository, you will see a notice about
151-
the new branch. Click the "Compare & pull request" button to create a PR.
152-
- The translation coordinator will review your PR very soon. Thank you!
18+
## Reviewers
15319

20+
- Grey Li ([@greyli](https://github.com/greyli))
21+
- Frost Ming ([@frostming](https://github.com/frostming))
15422

155-
## Translation To-do List
15623

157-
Be sure only mark one chapter at a time, mark another one when the former
158-
PR is created. Unless it's a long chapter, we may reset the assignment
159-
if you doesn't finish the translation in ten days.
24+
## Translators (Translation To-do List)
16025

16126

16227
### docs/

0 commit comments

Comments
 (0)