Skip to content

Commit eba7ecd

Browse files
committed
Improve project documentation and contributor workflow
1 parent 8fb8f25 commit eba7ecd

4 files changed

Lines changed: 286 additions & 75 deletions

File tree

‎.github/pull_request_template.md‎

Lines changed: 70 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,27 @@
11
# Pull Request
22

3-
## Summary
3+
Thank you for contributing to the Punjabi (`pa`) translation of the Python documentation.
44

5-
Provide a brief summary of your changes.
5+
Please complete the sections below to help reviewers understand and validate your contribution.
66

77
---
88

9-
## Type of Change
9+
# Summary
10+
11+
Provide a brief description of your changes.
12+
13+
-
14+
15+
---
16+
17+
# Type of Change
1018

1119
Please check all that apply.
1220

1321
- [ ] New translation
1422
- [ ] Translation improvement
23+
- [ ] Translation review
24+
- [ ] Terminology update
1525
- [ ] Documentation update
1626
- [ ] Contributor documentation
1727
- [ ] Validation workflow
@@ -22,20 +32,38 @@ Please check all that apply.
2232

2333
---
2434

25-
## Files Changed
35+
# Documentation Area
2636

27-
List the files modified in this pull request.
37+
If this pull request modifies translations, specify the affected documentation area(s).
38+
39+
Examples:
40+
41+
- Tutorial
42+
- Using Python
43+
- Standard Library
44+
- HOWTO
45+
- FAQ
46+
- Reference
47+
- C API
48+
- What's New
49+
- Repository documentation
50+
51+
Documentation area(s):
2852

2953
-
3054

3155
---
3256

33-
## Translation Details (if applicable)
57+
# Files Changed
3458

35-
Documentation area:
59+
List the files modified in this pull request.
3660

3761
-
3862

63+
---
64+
65+
# Translation Details (if applicable)
66+
3967
Language:
4068

4169
- Punjabi (`pa`)
@@ -44,34 +72,58 @@ Approximate number of translated strings:
4472

4573
-
4674

75+
Description of translated content:
76+
77+
-
78+
4779
---
4880

49-
## Validation
81+
# Validation
5082

5183
Confirm that the following checks have been completed before submitting this pull request.
5284

5385
- [ ] `msgfmt --check`
5486
- [ ] `sphinx-lint`
5587
- [ ] HTML documentation build completed successfully
56-
- [ ] Nitpicky (`-n`) build completed successfully (if applicable)
57-
- [ ] No untranslated or fuzzy messages introduced
88+
- [ ] Nitpicky (`-n`) documentation build completed successfully (if applicable)
89+
- [ ] No untranslated messages introduced
90+
- [ ] No fuzzy messages introduced
5891
- [ ] Terminology follows `GLOSSARY.md`
5992
- [ ] Translation follows `STYLE_GUIDE.md`
93+
- [ ] reStructuredText and Sphinx markup have been preserved
6094

6195
---
6296

63-
## Additional Notes
97+
# Review Notes
6498

65-
Include any additional information reviewers should know.
99+
Provide any information that may help reviewers.
100+
101+
Examples:
102+
103+
- terminology decisions
104+
- intentionally untranslated text
105+
- known limitations
106+
- areas requiring additional review
66107

67108
-
68109

69110
---
70111

71-
## Checklist
112+
# Related Issues or Discussions
113+
114+
Reference any related issue, discussion, or Python Documentation Translation conversation.
115+
116+
-
117+
118+
---
119+
120+
# Contributor Checklist
121+
122+
Please confirm the following before requesting review.
72123

73-
- [ ] I have read the project's `CONTRIBUTING.md`.
74-
- [ ] My changes follow the project's Style Guide.
75-
- [ ] I have validated my changes locally.
76-
- [ ] I have updated documentation where necessary.
77-
- [ ] This pull request is ready for review.
124+
- [ ] I have read `CONTRIBUTING.md`.
125+
- [ ] I followed `STYLE_GUIDE.md`.
126+
- [ ] I followed `GLOSSARY.md`.
127+
- [ ] I validated my changes locally where applicable.
128+
- [ ] I updated documentation where necessary.
129+
- [ ] My contribution is ready for review.

‎CONTRIBUTING.md‎

Lines changed: 71 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,28 @@ Whether you are fixing a typo, translating a new document, reviewing terminology
3232

3333
The Punjabi (`pa`) translation project is actively maintained and follows the official Python Documentation Translation workflow.
3434

35+
## Project Team
36+
37+
The Punjabi (`pa`) translation project is maintained collaboratively by a team of coordinators and contributors through the official Python Documentation Translation project on Transifex.
38+
39+
### Coordinators
40+
41+
The project is currently coordinated by:
42+
43+
- Bhuvansh Kataria (@BHUVANSH855)
44+
- Mohit Yadav (@mohityadav8)
45+
- Yashraj Jangra (@jangrayash1505)
46+
47+
The coordinators are responsible for:
48+
49+
- Managing the translation project.
50+
- Maintaining translation quality.
51+
- Coordinating contributors and reviewers.
52+
- Ensuring consistency across translated documentation.
53+
- Overseeing validation and synchronization workflows.
54+
55+
---
56+
3557
### Current Highlights
3658

3759
- ✅ Officially listed in the Python Developer Guide Translation Coordinators (PR #1843)
@@ -64,21 +86,21 @@ The Punjabi (`pa`) translation project is actively maintained and follows the of
6486
| Metric | Value |
6587
|--------|------:|
6688
| Verified Translated Strings | **7,668** |
67-
| Tutorial Files | 17 |
68-
| Using Python Files | 9 |
69-
| Completed Core Library Files | 5 |
70-
| Completed HOWTO Files | 2 |
71-
| Root Translation Files | 2 |
89+
| Tutorial Files Completed | 17 |
90+
| Using Python Files Completed | 9 |
91+
| Core Library Files Completed | 5 |
92+
| HOWTO Files Completed | 2 |
93+
| Root Translation Files Completed | 2 |
7294

7395
### Current Priorities
7496

7597
Current development focuses on:
7698

77-
- Expanding translations across additional Standard Library modules.
78-
- Continuing HOWTO, FAQ, Reference, C API, and What's New documentation.
79-
- Maintaining terminology consistency through community review.
99+
- Reviewing existing translations for terminology consistency and technical accuracy.
100+
- Expanding translations across additional Standard Library, HOWTO, FAQ, Reference, C API, and What's New documentation.
101+
- Maintaining consistency with `GLOSSARY.md` and `STYLE_GUIDE.md`.
80102
- Keeping translations synchronized with upstream CPython documentation.
81-
- Preparing the project for future integration with Python's documentation build infrastructure.
103+
- Growing the Punjabi translation community and onboarding new contributors and reviewers.
82104

83105
---
84106

@@ -146,11 +168,11 @@ The Punjabi (`pa`) translation project follows the standard Python Documentation
146168
```text
147169
Translate in Transifex
148170
↓
149-
Community Review
171+
Follow GLOSSARY.md
150172
↓
151-
Terminology Verification (GLOSSARY.md)
173+
Follow STYLE_GUIDE.md
152174
↓
153-
Translation Style Review (STYLE_GUIDE.md)
175+
Peer Review
154176
↓
155177
Automated Synchronization to GitHub
156178
↓
@@ -176,6 +198,7 @@ Contributors can help in several ways:
176198
- Translate untranslated documentation.
177199
- Review existing translations.
178200
- Improve terminology consistency.
201+
- Validate translations locally.
179202
- Fix formatting or reStructuredText issues.
180203
- Correct validation errors.
181204
- Improve documentation quality.
@@ -230,6 +253,10 @@ After creating a new `.po` file:
230253

231254
Every completed translation should pass all validation checks before submission.
232255

256+
> **Validation and translation review are separate processes.**
257+
>
258+
> Automated validation verifies translation syntax, markup preservation, and documentation build correctness. Human review focuses on terminology consistency, language quality, technical accuracy, and adherence to the project's glossary and style guide.
259+
233260
## Validation Pipeline
234261

235262
```text
@@ -298,6 +325,23 @@ All commands should complete successfully before submitting a contribution.
298325

299326
---
300327

328+
## Review Guidelines
329+
330+
Review is a collaborative process intended to improve translation quality rather than simply identify errors. Contributors and reviewers are encouraged to discuss terminology, phrasing, and technical accuracy to achieve consistent, high-quality translations.
331+
332+
Automated validation confirms that a translation is technically valid, but it does not verify translation quality.
333+
334+
During review, contributors and reviewers should check:
335+
336+
- Technical accuracy.
337+
- Consistency with `GLOSSARY.md`.
338+
- Compliance with `STYLE_GUIDE.md`.
339+
- Natural Punjabi wording.
340+
- Preservation of reStructuredText and Sphinx markup.
341+
- Correct handling of cross-references, directives, and code examples.
342+
343+
---
344+
301345
# Translation Rules
302346

303347
Maintaining consistency is one of the most important goals of this project.
@@ -433,6 +477,20 @@ Avoid literal word-for-word translations when a more natural Punjabi expression
433477

434478
---
435479

480+
## Reviewer Responsibilities
481+
482+
Reviewers help ensure that translations are technically accurate, linguistically natural, and consistent across the project.
483+
484+
A reviewer should:
485+
486+
- Verify terminology against `GLOSSARY.md`.
487+
- Check compliance with `STYLE_GUIDE.md`.
488+
- Preserve original meaning and technical intent.
489+
- Ensure all Sphinx and reStructuredText markup remains unchanged.
490+
- Report inconsistencies or suggest improvements through GitHub or Transifex.
491+
492+
---
493+
436494
# Quality Checklist
437495

438496
Before submitting your contribution, ensure that:
@@ -512,7 +570,7 @@ Contributors should:
512570
- Preserve all reStructuredText roles, directives, hyperlinks, and formatting.
513571
- Keep code examples identical to the original documentation.
514572
- Preserve indentation and whitespace where required.
515-
- Review completed translations before submission.
573+
- Review completed translations for technical accuracy, terminology consistency, and natural Punjabi wording before submission.
516574
- Follow translation patterns established in completed project files whenever appropriate.
517575

518576
When uncertain about a translation, prioritize consistency with existing project terminology rather than introducing new wording.

0 commit comments

Comments
 (0)