From c8f230750d5641f234311fd5c49a504a4661c1a2 Mon Sep 17 00:00:00 2001 From: Bhuvansh Kataria Date: Thu, 22 Oct 2026 17:16:57 +0000 Subject: [PATCH 01/12] Add Punjabi README with an English version --- README.en.md | 42 ++++++ README.md | 351 ++++----------------------------------------------- 2 files changed, 69 insertions(+), 324 deletions(-) create mode 100644 README.en.md diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..8dedd9a --- /dev/null +++ b/README.en.md @@ -0,0 +1,42 @@ +# Python Documentation Translation — Punjabi (ਪੰਜਾਬੀ) + +[ਪੰਜਾਬੀ](README.md) + +Punjabi (Gurmukhi, `pa`) translation of the [Python documentation](https://docs.python.org/). + +- **Read it:** +- **Progress:** (updated automatically) +- **Translate and review:** [Transifex](https://explore.transifex.com/python-doc/python-newest/), language Punjabi (`pa`) +- **Contribute:** see [CONTRIBUTING.md](CONTRIBUTING.md) + +## How do we translate? + +1. Open the [Python Documentation project](https://explore.transifex.com/python-doc/python-newest/) on Transifex. +2. Click "Join this project". Create a Transifex account if you don't have one. +3. Select Punjabi (`pa`) on the project page. +4. After a coordinator approves your request, pick a resource and follow [Transifex_Setup.md](Transifex_Setup.md). +5. A reviewer approves your translations, and the daily sync brings them to this repository. You don't need to open a pull request for translations. + +## How does it work? + +Translations are written and reviewed in Transifex. A GitHub Actions workflow pulls the **reviewed** translations into this repository every day, into the `3.13`, `3.14` and `3.15` branches. Strings that are translated but not yet reviewed stay in Transifex until they are reviewed, so they are not in the repository yet. + +Every push and pull request runs `msgfmt --check` on all `.po` files. The Python documentation build uses this repository to publish the Punjabi site. + +## Guides + +| File | Contents | +|------|----------| +| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute, validate and submit changes | +| [Transifex_Setup.md](Transifex_Setup.md) | First steps in Transifex | +| [STYLE_GUIDE.md](STYLE_GUIDE.md) | Translation style and conventions | +| [RULES.md](RULES.md) | Detailed rules for markup, placeholders and `.po` files | +| [GLOSSARY.md](GLOSSARY.md) | Preferred Punjabi terminology | + +## Coordinators + +[@BHUVANSH855](https://github.com/BHUVANSH855), [@mohityadav8](https://github.com/mohityadav8) and [@Yashraj-Jangra](https://github.com/Yashraj-Jangra). + +## License + +Translations are contributed under the [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/) license. diff --git a/README.md b/README.md index 8513131..aa65c71 100644 --- a/README.md +++ b/README.md @@ -1,339 +1,42 @@ -# Translation of the Python Documentation — pa +# Python ਦਸਤਾਵੇਜ਼ੀਕਰਨ ਦਾ ਪੰਜਾਬੀ ਅਨੁਵਾਦ -[![Python Version](https://img.shields.io/badge/Python-3.15-blue.svg)](https://www.python.org/) -[![Language](https://img.shields.io/badge/Language-Punjabi%20(pa)-green.svg)](https://devguide.python.org/documentation/translations/) -[![License](https://img.shields.io/badge/License-CC0-lightgrey.svg)](https://creativecommons.org/publicdomain/zero/1.0/) +[English](README.en.md) -Punjabi (Gurmukhi) translation of the Python documentation. +[Python ਦਸਤਾਵੇਜ਼ੀਕਰਨ](https://docs.python.org/) ਦਾ ਪੰਜਾਬੀ (ਗੁਰਮੁਖੀ, `pa`) ਅਨੁਵਾਦ। -This project aims to translate Python's official documentation into Punjabi (Gurmukhi) and make Python learning resources more accessible to Punjabi-speaking developers, students, and educators. +- **ਪੜ੍ਹੋ:** +- **ਪ੍ਰਗਤੀ:** (ਆਪਣੇ-ਆਪ ਅੱਪਡੇਟ ਹੁੰਦੀ ਹੈ) +- **ਅਨੁਵਾਦ ਅਤੇ ਸਮੀਖਿਆ:** [Transifex](https://explore.transifex.com/python-doc/python-newest/), ਭਾਸ਼ਾ ਪੰਜਾਬੀ (`pa`) +- **ਯੋਗਦਾਨ ਪਾਓ:** [CONTRIBUTING.md](CONTRIBUTING.md) ਵੇਖੋ (ਅੰਗਰੇਜ਼ੀ ਵਿੱਚ) -## Contents +## ਅਨੁਵਾਦ ਕਿਵੇਂ ਕਰੀਏ? -- [Status](#status) -- [Current Progress](#current-progress) -- [Validation Status](#validation-status) -- [Recent Milestones](#recent-milestones) -- [Infrastructure](#infrastructure) -- [Transifex](#transifex) -- [Next Steps](#next-steps) -- [Goals](#goals) -- [Repository Structure](#repository-structure) -- [Translation Workflow](#translation-workflow) -- [References](#references) -- [Acknowledgements](#acknowledgements) -- [License](#license) +1. Transifex ਉੱਤੇ [Python Documentation ਪ੍ਰੋਜੈਕਟ](https://explore.transifex.com/python-doc/python-newest/) ਖੋਲ੍ਹੋ। +2. "Join this project" ਬਟਨ ਦਬਾਓ। ਜੇ ਤੁਹਾਡਾ Transifex ਖਾਤਾ ਨਹੀਂ ਹੈ, ਤਾਂ ਬਣਾ ਲਓ। +3. ਪ੍ਰੋਜੈਕਟ ਦੇ ਪੰਨੇ ਉੱਤੇ ਪੰਜਾਬੀ (`pa`) ਚੁਣੋ। +4. ਕੋਆਰਡੀਨੇਟਰ ਵੱਲੋਂ ਮਨਜ਼ੂਰੀ ਮਿਲਣ ਤੋਂ ਬਾਅਦ ਕੋਈ ਰਿਸੋਰਸ ਚੁਣੋ ਅਤੇ [Transifex_Setup.md](Transifex_Setup.md) ਵਿੱਚ ਦਿੱਤੇ ਕਦਮਾਂ ਦੀ ਪਾਲਣਾ ਕਰੋ (ਅੰਗਰੇਜ਼ੀ ਵਿੱਚ)। +5. ਸਮੀਖਿਆਕਾਰ ਤੁਹਾਡੇ ਅਨੁਵਾਦਾਂ ਨੂੰ ਮਨਜ਼ੂਰ ਕਰਦੇ ਹਨ, ਅਤੇ ਰੋਜ਼ਾਨਾ ਸਮਕਾਲੀਕਰਨ ਨਾਲ ਉਹ ਇਸ ਰਿਪੋਜ਼ਟਰੀ ਵਿੱਚ ਆ ਜਾਂਦੇ ਹਨ। ਅਨੁਵਾਦਾਂ ਲਈ ਪੁੱਲ ਰਿਕਵੈਸਟ ਬਣਾਉਣ ਦੀ ਲੋੜ ਨਹੀਂ। -## Status +## ਇਹ ਕਿਵੇਂ ਕੰਮ ਕਰਦਾ ਹੈ? -🎉 **Officially recognized** — Punjabi (`pa`) is now listed in the **Python Developer Guide Translation Coordinators** following the merge of **PR #1843**. +ਅਨੁਵਾਦ Transifex ਵਿੱਚ ਲਿਖੇ ਅਤੇ ਸਮੀਖਿਆ ਕੀਤੇ ਜਾਂਦੇ ਹਨ। ਇੱਕ GitHub Actions ਵਰਕਫਲੋ ਹਰ ਰੋਜ਼ **ਸਮੀਖਿਆ ਕੀਤੇ ਗਏ** ਅਨੁਵਾਦਾਂ ਨੂੰ ਇਸ ਰਿਪੋਜ਼ਟਰੀ ਦੀਆਂ `3.13`, `3.14` ਅਤੇ `3.15` ਬ੍ਰਾਂਚਾਂ ਵਿੱਚ ਲਿਆਉਂਦਾ ਹੈ। ਜਿਨ੍ਹਾਂ ਸਤਰਾਂ ਦਾ ਅਨੁਵਾਦ ਹੋ ਚੁੱਕਾ ਹੈ ਪਰ ਸਮੀਖਿਆ ਨਹੀਂ ਹੋਈ, ਉਹ ਸਮੀਖਿਆ ਹੋਣ ਤੱਕ Transifex ਵਿੱਚ ਹੀ ਰਹਿੰਦੀਆਂ ਹਨ, ਇਸ ਲਈ ਉਹ ਅਜੇ ਰਿਪੋਜ਼ਟਰੀ ਵਿੱਚ ਨਹੀਂ ਹਨ। -This repository follows the official Python Documentation Translation workflow and is synchronized with the official Python Documentation Transifex project. +ਹਰ ਪੁਸ਼ ਅਤੇ ਪੁੱਲ ਰਿਕਵੈਸਟ ਉੱਤੇ ਸਾਰੀਆਂ `.po` ਫ਼ਾਈਲਾਂ ਲਈ `msgfmt --check` ਚੱਲਦਾ ਹੈ। Python ਦਸਤਾਵੇਜ਼ੀਕਰਨ ਦੀ ਬਿਲਡ ਪੰਜਾਬੀ ਸਾਈਟ ਪ੍ਰਕਾਸ਼ਿਤ ਕਰਨ ਲਈ ਇਸ ਰਿਪੋਜ਼ਟਰੀ ਦੀ ਵਰਤੋਂ ਕਰਦੀ ਹੈ। -| Property | Value | -|----------|-------| -| Repository Status | Active Development | -| Current Branch | `3.15` | -| Language Tag | `pa` | -| Translation Platform | Official Python Documentation on Transifex | -| Project Team | 3 Coordinators | -| Translation Workflow | Active | +## ਮਾਰਗਦਰਸ਼ਿਕਾਵਾਂ -### Translation Progress - -| Section | Status | Strings | -|---------|--------|--------:| -| Tutorial (17/17 files) | ✅ Complete | 1,327 | -| Using Python (9/9 files) | ✅ Complete | 1,631 | -| `library/stdtypes.po` | ✅ Complete | 1,607 | -| `library/functions.po` | ✅ Complete | 536 | -| `library/exceptions.po` | ✅ Complete | 207 | -| `library/functools.po` | ✅ Complete | 128 | -| `library/string.po` | ✅ Complete | 31 | -| `howto/regex.po` | ✅ Complete | 335 | -| `howto/sorting.po` | ✅ Complete | 90 | -| `glossary.po` | ✅ Complete | 499 | -| `bugs.po` | ✅ Complete | 31 | -| **Verified Translation Total** | | **7,668** | - -### Infrastructure Status - -| Component | Status | -|-----------|--------| -| Python Developer Guide Listing | ✅ PR #1843 Merged | -| Official Transifex Team | ✅ Active | -| Project Coordination Team | ✅ 3 Coordinators | -| Daily Transifex Synchronization | ✅ Running | -| GitHub Actions Validation | ✅ Passing | -| GNU gettext (`msgfmt`) Validation | ✅ Passing | -| `sphinx-lint` | ✅ Passing | -| HTML Documentation Build | ✅ Passing | -| Nitpicky (`-n`) Documentation Build | ✅ Passing | - -## Current Progress - -The Punjabi translation project is maintained collaboratively by a team of coordinators using the official Python Documentation Translation infrastructure. - -Translation quality is ensured through a combination of: - -- shared terminology defined in `GLOSSARY.md` -- translation conventions described in `STYLE_GUIDE.md` -- automated validation -- collaborative review through Transifex -- CPython documentation builds - -The Punjabi translation project continues to expand through the official Python Documentation Translation workflow. - -### Completed Translation Areas - -| Area | Status | -|------|--------| -| Tutorial Documentation (17/17 files) | ✅ Complete | -| Using Python Documentation (9/9 files) | ✅ Complete | -| Core Library Translation Set | ✅ Complete | -| `bugs.po` | ✅ Complete | -| `glossary.po` | ✅ Complete | -| `howto/regex.po` | ✅ Complete | -| `howto/sorting.po` | ✅ Complete | - -### Translation Statistics - -| Metric | Value | -|--------|------:| -| Verified Translated Strings | **7,668** | -| Tutorial Files Completed | 17 | -| Using Python Files Completed | 9 | -| Core Library Files Completed | 5 | -| HOWTO Files Completed | 2 | -| Root Translation Files Completed | 2 | - -Translation work is ongoing, with additional Library, HOWTO, FAQ, Reference, C API, and What's New documentation being translated through the official Python Documentation Transifex project. - -## Validation Status - -> **Validation and translation review are separate processes.** -> -> The validation pipeline 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. - -All completed translations are validated using the same workflow adopted by the Python Documentation Translation community before being merged into the repository. - -### Validation Pipeline - -```text -Translate - ↓ -Transifex - ↓ -GitHub Actions Sync - ↓ -GNU gettext Validation (`msgfmt --check`) - ↓ -sphinx-lint - ↓ -CPython HTML Build - ↓ -Nitpicky (`-n`) Documentation Build -``` - -### Validation Commands - -```bash -msgfmt --check FILE.po -sphinx-lint . -python -m sphinx -b html -D language=pa Doc build/html-pa -python -m sphinx -b html -n -W Doc build/html-pa -``` - -### Validation Summary - -- ✅ GNU gettext (`msgfmt`) validation passing -- ✅ No validation errors -- ✅ GitHub Actions validation passing -- ✅ `sphinx-lint` — No problems found -- ✅ CPython HTML documentation build passing -- ✅ Nitpicky (`-n`) documentation build passing -- ✅ Repository-wide validation passing - -### Validation Scope - -The automated validation pipeline verifies: - -- Translation syntax -- GNU gettext compatibility -- reStructuredText markup preservation -- Sphinx documentation structure -- Documentation build success -- Broken references through nitpicky builds - -Automated validation **does not replace human translation review**. - ---- - -## Recent Milestones - -- ✅ Punjabi (`pa`) officially listed in the Python Developer Guide Translation Coordinators (PR #1843 merged) -- ✅ Repository renamed to `python-docs-pa` -- ✅ Language tag standardized to `pa` -- ✅ Migration to the `3.15` translation branch -- ✅ Translation workflow established -- ✅ Daily Transifex synchronization operational -- ✅ Repository-wide `msgfmt` validation passing -- ✅ Repository-wide `sphinx-lint` validation passing -- ✅ CPython HTML documentation builds passing -- ✅ Nitpicky documentation builds passing -- ✅ Translation team expanded to **3 coordinators** -- ✅ Local validation workflow documented -- ✅ Translation infrastructure established - -## Infrastructure - -The project includes documentation, automation, and validation resources to ensure consistent, high-quality translations. - -| Component | Purpose | -|-----------|---------| -| `STYLE_GUIDE.md` | Translation conventions and style guidelines | -| `GLOSSARY.md` | Standardized Python terminology (English → Punjabi) | -| `CONTRIBUTING.md` | Contributor onboarding and workflow | -| `PROJECT_REPORT.md` | Project history and major milestones | -| GitHub Actions | Automated validation and Transifex synchronization | -| Transifex | Collaborative translation platform | -| GNU gettext (`msgfmt`) | Translation validation | -| `sphinx-lint` | Documentation quality checks | -| CPython HTML Build | Verifies successful documentation builds | -| Nitpicky (`-n`) Build | Detects broken references and documentation issues | - -## Transifex - -The Punjabi (`pa`) translation is maintained through the official Python Documentation project on Transifex. - -### Project Information - -| Item | Value | +| ਫ਼ਾਈਲ | ਵਿਸ਼ਾ | |------|-------| -| Platform | Python Documentation on Transifex | -| Language | Punjabi (`pa`) | -| Branch | `3.15` | -| Repository | `python-docs-pa` | -| Coordinators | [@BHUVANSH855](https://github.com/BHUVANSH855), [@mohityadav8](https://github.com/mohityadav8), [@Yashraj-Jangra](https://github.com/Yashraj-Jangra) | - -Translations are contributed collaboratively through the official Python Documentation Transifex project and synchronized to this repository using automated GitHub Actions workflows. - -All translations are expected to follow the project's glossary, style guide, and validation workflow before being considered ready for publication. - -## Next Steps - -Current priorities: - -1. Continue community review and terminology consistency checks through Transifex. -2. Expand translation coverage across additional Library, HOWTO, FAQ, Reference, C API, and What's New documentation. -3. Continue growing the Punjabi translation community and onboarding new contributors. -4. Maintain glossary and style guide consistency across all translations. -5. Prepare the project for future publication through Python's documentation infrastructure. - -## Goals - -This project supports the Python Documentation Translation initiative by making the official Python documentation accessible to Punjabi speakers while maintaining the same quality standards as the upstream project. - -The primary goals are to: - -- Translate the official Python documentation into Punjabi (Gurmukhi). -- Maintain consistent terminology through a shared glossary. -- Follow the Python documentation translation guidelines and style conventions. -- Ensure translation quality through automated validation, documentation builds, and collaborative review. -- Preserve reStructuredText and Sphinx markup accurately. -- Encourage community contributions and peer review. -- Keep translations synchronized with the upstream Python documentation. - -## Repository Structure - -```text -python-docs-pa/ -├── .github/ # GitHub Actions workflows -├── tutorial/ # Tutorial documentation -├── using/ # Using Python documentation -├── library/ # Standard library reference -├── howto/ # HOWTO guides -├── faq/ # Frequently asked questions -├── reference/ # Language reference -├── c-api/ # Python/C API documentation -├── extending/ # Extending and embedding Python -├── installing/ # Installation documentation -├── distributing/ # Distribution guides -├── deprecations/ # Deprecated features -├── whatsnew/ # What's New documentation -│ -├── README.md -├── CONTRIBUTING.md -├── STYLE_GUIDE.md -├── GLOSSARY.md -├── PROJECT_REPORT.md -│ -├── *.po # Root translation files -└── .gitignore -``` - -## Translation Workflow - -The project follows the standard Python Documentation Translation workflow. - -```text -Translate in Transifex - ↓ -Follow GLOSSARY.md - ↓ -Follow STYLE_GUIDE.md - ↓ -Peer Review - ↓ -Automated synchronization to GitHub - ↓ -GitHub Actions validation - ↓ -GNU gettext validation (`msgfmt`) - ↓ -sphinx-lint - ↓ -CPython HTML Build - ↓ -Nitpicky (`-n`) Build -``` - -### Contributor Checklist - -1. Translate or review `.po` files in Transifex. -2. Follow the terminology defined in `GLOSSARY.md`. -3. Follow the conventions described in `STYLE_GUIDE.md`. -4. Preserve all reStructuredText roles, directives, code blocks, and markup. -5. Validate translations locally when possible. -6. Ensure GitHub Actions complete successfully after synchronization. - -## References - -The following resources are used throughout this project: - -- **Python Developer Guide – Documentation Translations** - - -- **Python Documentation** - - -- **Python Documentation on Transifex** - - -- **Python Documentation Style Guide** - - -- **reStructuredText Primer (Sphinx)** - - -## Acknowledgements - -This project follows the official Python Documentation Translation initiative. +| [CONTRIBUTING.md](CONTRIBUTING.md) | ਯੋਗਦਾਨ ਕਿਵੇਂ ਪਾਉਣਾ ਹੈ, ਜਾਂਚ ਕਿਵੇਂ ਕਰਨੀ ਹੈ ਅਤੇ ਤਬਦੀਲੀਆਂ ਕਿਵੇਂ ਭੇਜਣੀਆਂ ਹਨ | +| [Transifex_Setup.md](Transifex_Setup.md) | Transifex ਵਿੱਚ ਪਹਿਲੇ ਕਦਮ | +| [STYLE_GUIDE.md](STYLE_GUIDE.md) | ਅਨੁਵਾਦ ਦੀ ਸ਼ੈਲੀ ਅਤੇ ਨਿਯਮ | +| [RULES.md](RULES.md) | ਮਾਰਕਅੱਪ, ਪਲੇਸਹੋਲਡਰ ਅਤੇ `.po` ਫ਼ਾਈਲਾਂ ਲਈ ਵਿਸਤ੍ਰਿਤ ਨਿਯਮ | +| [GLOSSARY.md](GLOSSARY.md) | ਪਸੰਦੀਦਾ ਪੰਜਾਬੀ ਸ਼ਬਦਾਵਲੀ | -Special thanks to the Python Documentation community, translation coordinators, reviewers, and contributors whose guidance and infrastructure make community-driven documentation translations possible. +## ਕੋਆਰਡੀਨੇਟਰ -## License +[@BHUVANSH855](https://github.com/BHUVANSH855), [@mohityadav8](https://github.com/mohityadav8) ਅਤੇ [@Yashraj-Jangra](https://github.com/Yashraj-Jangra)। -This repository follows the licensing model of the official Python Documentation Translation project. +## ਲਾਇਸੈਂਸ -Documentation translations are contributed under the CC0 1.0 Universal license. See the Python Documentation Translation project for additional licensing information. +ਅਨੁਵਾਦ [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/) ਲਾਇਸੈਂਸ ਅਧੀਨ ਯੋਗਦਾਨ ਵਜੋਂ ਦਿੱਤੇ ਜਾਂਦੇ ਹਨ। From 57fecbc13b90a6cef80a6a7171dbb7e12f1ff1df Mon Sep 17 00:00:00 2001 From: Bhuvansh Kataria Date: Thu, 22 Oct 2026 17:36:05 +0000 Subject: [PATCH 02/12] Shorten GLOSSARY.md and remove the duplicated status section --- GLOSSARY.md | 244 +++------------------------------------------------- 1 file changed, 12 insertions(+), 232 deletions(-) diff --git a/GLOSSARY.md b/GLOSSARY.md index 4918b0b..a9c13dc 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -1,102 +1,12 @@ # Punjabi (pa) Python Docs Glossary -This glossary defines the preferred Punjabi terminology for translating the official Python documentation into Punjabi (`pa`). - -It complements `README.md`, `CONTRIBUTING.md`, and `STYLE_GUIDE.md` by providing standardized translations for technical terms used throughout the project. - -All contributors should use the terminology defined in this glossary to ensure consistency, technical accuracy, and long-term maintainability across all translated documentation. - ---- - -## Contents - -- [Project Status](#project-status) -- [How to Use This Glossary](#how-to-use-this-glossary) -- [Core Python Terms](#core-python-terms) -- [Data Types](#data-types) -- [Mutability](#mutability) -- [Operators and Operations](#operators-and-operations) -- [Collections and Iteration](#collections-and-iteration) -- [Exceptions and Errors](#exceptions-and-errors) -- [Modules and Libraries](#modules-and-libraries) -- [String and Formatting Terms](#string-and-formatting-terms) -- [Numeric Terms](#numeric-terms) -- [Standard Library Terms](#standard-library-terms) -- [Documentation Terms](#documentation-terms) -- [Documentation Workflow Terms](#documentation-workflow-terms) -- [Terms Commonly Left Untranslated](#terms-commonly-left-untranslated) -- [Common Python Keywords](#common-python-keywords) -- [Language Tag](#language-tag) -- [Consistency Rules](#consistency-rules) -- [Glossary Maintenance](#glossary-maintenance) -- [References](#references) -- [Final Notes](#final-notes) - ---- - -# Project Status - -The Punjabi (`pa`) translation project is actively maintained as part of the official Python Documentation Translation initiative. - -### Current Highlights - -- ✅ Officially listed in the Python Developer Guide Translation Coordinators (PR #1843) -- ✅ Active translation branch: `3.15` -- ✅ Automated synchronization with the official Python Documentation Transifex project -- ✅ GitHub Actions validation passing -- ✅ GNU gettext (`msgfmt`) validation passing -- ✅ `sphinx-lint` validation passing -- ✅ CPython HTML documentation build passing -- ✅ Nitpicky (`-n`) documentation build passing - -### Completed Translation Areas - -| Area | Status | -|------|--------| -| Tutorial Documentation (17/17 files) | ✅ Complete | -| Using Python Documentation (9/9 files) | ✅ Complete | -| `library/stdtypes.po` | ✅ Complete | -| `library/functions.po` | ✅ Complete | -| `library/exceptions.po` | ✅ Complete | -| `library/functools.po` | ✅ Complete | -| `library/string.po` | ✅ Complete | -| `howto/regex.po` | ✅ Complete | -| `howto/sorting.po` | ✅ Complete | -| `glossary.po` | ✅ Complete | -| `bugs.po` | ✅ Complete | - -### Translation Statistics - -| Metric | Value | -|--------|------:| -| Verified Translated Strings | **7,668** | -| Tutorial Files | 17 | -| Using Python Files | 9 | -| Completed Core Library Files | 5 | -| Completed HOWTO Files | 2 | -| Root Translation Files | 2 | - -The terminology defined in this glossary reflects the vocabulary established throughout the completed translations and should be treated as the project's preferred terminology for all future documentation. - ---- +Preferred Punjabi terms for translating the Python documentation. Use them so translations stay consistent. For writing style, see `STYLE_GUIDE.md`. # How to Use This Glossary -This glossary establishes the standard terminology for the Punjabi (`pa`) translation of the Python documentation. - -When translating documentation: - -- Always use glossary-approved terminology whenever a term already exists. -- Do not introduce alternative translations for established technical terms. -- Reuse terminology from previously completed translations whenever possible. -- Follow the writing conventions described in `STYLE_GUIDE.md`. -- Preserve technical accuracy while producing natural and readable Punjabi. - -If a required technical term is not yet included in this glossary: - -1. Check previously completed translation files for an established translation. -2. Use consistent terminology throughout the document. -3. Add the new term to this glossary only after it has been reviewed and adopted as the project's preferred translation. +- Use the listed term whenever one exists. Do not introduce variants. +- For a term that is not listed, reuse the wording from existing translations. If there is none, use one wording consistently in the file and propose it as described under "Adding or Changing a Term". +- Never translate function, module, class and exception names, directives, roles, placeholders or code. --- @@ -208,10 +118,7 @@ If a required technical term is not yet included in this glossary: | English | Preferred Punjabi | |---------|-------------------| -| iterable | ਇਟਰੇਬਲ | -| iterator | ਇਟਰੇਟਰ | | loop | ਲੂਪ | -| iteration | ਇਟਰੇਸ਼ਨ | | membership test | ਮੈਂਬਰਸ਼ਿਪ ਜਾਂਚ | | sequence operations | ਕ੍ਰਮ ਕਾਰਵਾਈਆਂ | | mapping operations | ਮੈਪਿੰਗ ਕਾਰਵਾਈਆਂ | @@ -277,7 +184,6 @@ If a required technical term is not yet included in this glossary: | rounding | ਗੋਲਾਈਕਰਨ | | conversion | ਰੂਪਾਂਤਰਨ | | approximation | ਅਨੁਮਾਨ | -| floating-point | ਫਲੋਟਿੰਗ-ਪੌਇੰਟ | | binary fraction | ਬਾਈਨਰੀ ਭਿੰਨ | | decimal fraction | ਦਸ਼ਮਲਵ ਭਿੰਨ | | representation | ਪ੍ਰਤਿਨਿਧਿਤਾ | @@ -351,145 +257,19 @@ If a required technical term is not yet included in this glossary: # Terms Commonly Left Untranslated -The following terms are widely recognized within the Python ecosystem and should normally remain in English unless there is a strong project-wide reason to translate them. - -```text -Python -API -JSON -XML -HTML -HTTP -HTTPS -URL -Unicode -UTF-8 -ASCII -Git -GitHub -Transifex -Linux -Windows -macOS -POSIX -CPython -PyPI -pip -venv -IDLE -REPL -``` - ---- - -# Common Python Keywords - -Python language keywords must never be translated. - -```text -if -else -elif -for -while -class -def -return -import -from -try -except -finally -raise -pass -with -yield -lambda -and -or -not -global -nonlocal -async -await -match -case -``` - ---- - -# Language Tag - -The project uses the following IETF language tag for Punjabi: - -```text -pa -``` - -This language tag is used throughout the repository, GitHub workflows, Transifex configuration, and CPython documentation builds. - ---- - -# Consistency Rules - -To maintain a consistent translation across the project: - -- Always use glossary-approved terminology whenever an established translation exists. -- Do not introduce alternative translations for existing technical terms. -- Reuse terminology from previously completed translation files whenever possible. -- Function names, module names, class names, exception names, directives, roles, placeholders, and code identifiers must remain unchanged. -- When uncertain, prefer the terminology already used in completed translations rather than creating new variants. -- Follow the conventions described in `STYLE_GUIDE.md` for formatting, punctuation, and writing style. - -Consistency across the entire documentation is more important than individual translation preferences. - ---- - -# Glossary Maintenance - -This glossary is a living document and should evolve as the Punjabi translation project continues to grow. - -New terminology should be added only when: - -- A previously untranslated technical term appears in the documentation. -- Contributors agree on a preferred translation. -- The terminology has been reviewed for consistency with existing translations. -- The term is expected to be reused across multiple documentation files. - -When updating the glossary: - -1. Verify that the term does not already exist under a different translation. -2. Use the same wording consistently across all translated files. -3. Update existing translations if a project-wide terminology change is adopted. -4. Review the glossary after major translation milestones to keep terminology current. +These widely used terms normally stay in English: Python, API, JSON, XML, HTML, HTTP, HTTPS, URL, Unicode, UTF-8, ASCII, Git, GitHub, Transifex, Linux, Windows, macOS, POSIX, CPython, PyPI, pip, venv, IDLE, REPL. --- -# References - -Useful resources for contributors: +# Python Keywords -- **Python Developer Guide – Documentation Translations** - - -- **Python Documentation** - - -- **Python Documentation Style Guide** - - -- **Python Documentation on Transifex** - - -- **reStructuredText Primer (Sphinx)** - +Python keywords (`if`, `else`, `for`, `class`, `def`, `async`, `await`, `match` and so on) are never translated. --- -# Final Notes - -This glossary defines the preferred terminology for the Punjabi (`pa`) translation of the Python documentation. - -All contributors are encouraged to consult this glossary before translating new documentation and to update it whenever new project-approved terminology is established. +# Adding or Changing a Term -Using consistent terminology across the repository improves readability, simplifies reviews, reduces translation inconsistencies, and provides a high-quality documentation experience for Punjabi-speaking Python users. +1. Check that the term is not already listed under a different translation. +2. Agree on the wording with the other contributors in the pull request or an issue, and check it against existing translations. +3. Add the term to the right table here and use it consistently in all translated files. +4. If you change an existing term, update the translations that use it. From 3c06f6eca52748fd005d468becf5ad68c8bbbec8 Mon Sep 17 00:00:00 2001 From: Bhuvansh Kataria Date: Thu, 22 Oct 2026 17:41:47 +0000 Subject: [PATCH 03/12] Shorten STYLE_GUIDE.md and move markup rules to RULES.md --- STYLE_GUIDE.md | 794 +++---------------------------------------------- 1 file changed, 35 insertions(+), 759 deletions(-) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 6e67a2e..0439ab0 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -1,778 +1,54 @@ -# Punjabi (pa) Python Docs Style Guide +# Style Guide -This guide defines translation conventions for the Punjabi (`pa`) translation of the Python documentation. +This guide explains how we write the Punjabi (`pa`) translation of the Python documentation. Rules for markup, code, placeholders and `.po` files are in [RULES.md](RULES.md). Approved terms are in [GLOSSARY.md](GLOSSARY.md). -It complements `README.md`, `CONTRIBUTING.md`, and `GLOSSARY.md` by describing the writing style, terminology, formatting rules, and validation practices contributors should follow when translating Python documentation. +## Principles -All contributors should follow these guidelines to ensure consistency, technical accuracy, and long-term maintainability across the project. +- We translate the meaning, not the words. The Punjabi must say exactly what the English says. +- Technical accuracy comes first, then consistency, then style. +- We write clear, natural Punjabi (Gurmukhi) that a Punjabi-speaking programmer can read easily. +- We never change the meaning of a technical term. ---- +## Tone -## Contents +- Formal, educational and clear, like the English documentation. +- No slang, no regional dialect, and no word-for-word translation that sounds unnatural. +- When in doubt: clarity over literal wording, consistency over personal preference, accuracy over style. -- [Project Status](#project-status) -- [General Principles](#general-principles) -- [Translation Philosophy](#translation-philosophy) -- [Never Translate](#never-translate) -- [Variable Names](#variable-names) -- [PO File Rules](#po-file-rules) -- [Placeholder Preservation](#placeholder-preservation) -- [RST Markup Preservation](#rst-markup-preservation) -- [Inline Markup Preservation](#inline-markup-preservation) -- [Directives](#directives) -- [Code Blocks](#code-blocks) -- [Interactive Python Sessions](#interactive-python-sessions) -- [URLs](#urls) -- [Version Information](#version-information) -- [Technical Terms](#technical-terms) -- [Terminology Consistency](#terminology-consistency) -- [Batch Translation Workflow](#batch-translation-workflow) -- [Machine Translation Policy](#machine-translation-policy) -- [Translation Quality Checklist](#translation-quality-checklist) -- [Validation Commands](#validation-commands) -- [Repository-Wide Validation](#repository-wide-validation) -- [Transifex Synchronization](#transifex-synchronization) -- [Commit Message Conventions](#commit-message-conventions) -- [Contributor Expectations](#contributor-expectations) -- [Tone and Writing Style](#tone-and-writing-style) -- [Translation Review](#translation-review) -- [Final Rule](#final-rule) +## Terminology ---- +For every technical term we follow this order: -# Project Status +1. Use the term from [GLOSSARY.md](GLOSSARY.md). Do not create an alternative, and do not switch wording between files. +2. If the term is not listed, use a Punjabi word only when it has exactly the same technical meaning. +3. If there is no such Punjabi word, write the English word in Gurmukhi (transliteration). +4. Proper names, code and UI button labels stay in Latin script. So do the terms listed under "Terms Commonly Left Untranslated" in the glossary. -The Punjabi (`pa`) translation project is actively maintained as part of the official Python Documentation Translation initiative. +Then add the new term to the glossary, as described under "Adding or Changing a Term" there. -### Current Highlights +Please also: -- ✅ Officially listed in the Python Developer Guide Translation Coordinators (PR #1843) -- ✅ Active translation branch: `3.15` -- ✅ Automated synchronization with the official Python Documentation Transifex project -- ✅ GitHub Actions validation passing -- ✅ GNU gettext (`msgfmt`) validation passing -- ✅ `sphinx-lint` validation passing -- ✅ CPython HTML documentation build passing -- ✅ Nitpicky (`-n`) documentation build passing +- Check the context. The same English word can be a technical term, an ordinary word or part of code. Never run a find-and-replace for a term over many files. +- Look at other Python translations (for example Chinese, Japanese or Korean) to see how they handle a term, but do not copy their wording. +- Do not rewrite an existing translation only because you prefer another wording. Change it only for a clear language, technical or consistency reason. -### Completed Translation Areas +## Machine translation -| Area | Status | -|------|--------| -| Tutorial Documentation (17/17 files) | ✅ Complete | -| Using Python Documentation (9/9 files) | ✅ Complete | -| `library/stdtypes.po` | ✅ Complete | -| `library/functions.po` | ✅ Complete | -| `library/exceptions.po` | ✅ Complete | -| `library/functools.po` | ✅ Complete | -| `library/string.po` | ✅ Complete | -| `howto/regex.po` | ✅ Complete | -| `howto/sorting.po` | ✅ Complete | -| `glossary.po` | ✅ Complete | -| `bugs.po` | ✅ Complete | +We use machine translation only as a first draft. A person must read and correct every string. Watch for unnatural word order, wrong technical meanings, inconsistent terms and unexplained switching between English and Punjabi. -### Translation Statistics +## Review -| Metric | Value | -|--------|------:| -| Verified Translated Strings | **7,668** | -| Tutorial Files | 17 | -| Using Python Files | 9 | -| Completed Core Library Files | 5 | -| Completed HOWTO Files | 2 | -| Root Translation Files | 2 | +Reviewers in Transifex check each string for: -Contributors should review previously completed translations before introducing new terminology or translation patterns. +- **Meaning:** it says the same as the English. +- **Terminology:** it uses the glossary term. +- **Punjabi:** it is natural, with correct grammar and spelling. +- **Markup:** roles, links, placeholders and code are intact (see [RULES.md](RULES.md)). ---- +Only reviewed strings reach this repository, so approve a string only when it passes all four. -# General Principles +## References -The following principles apply to every translation in this repository, regardless of the document or subject area. - -* Translate meaning, not individual words. -* Use natural and clear Punjabi (Gurmukhi). -* Preserve technical accuracy. -* Prefer consistency over stylistic variation. -* Follow terminology defined in `GLOSSARY.md`. -* Reuse existing translations whenever possible. -* Match the tone of official Python documentation. - ---- - -# Translation Philosophy - -The goal is not literal translation. - -The goal is to produce documentation that feels natural to Punjabi-speaking developers while remaining technically identical to the English original. - -Good translation: - -```text -Clear -Accurate -Consistent -Natural -``` - -Poor translation: - -```text -Word-for-word -Ambiguous -Inconsistent -Artificial sounding -``` - ---- - -# Never Translate - -## Python Keywords - -```text -if -else -elif -for -while -class -def -return -import -from -try -except -finally -raise -pass -with -yield -lambda -and -or -not -global -nonlocal -async -await -match -case -``` - ---- - -## Built-in Names - -```text -print -len -range -list -dict -tuple -set -frozenset -bytes -bytearray -str -int -float -complex -bool -object -type -property -classmethod -staticmethod -``` - ---- - -## Exception Names - -```text -Exception -ValueError -TypeError -KeyError -IndexError -ImportError -RuntimeError -AttributeError -StopIteration -``` - ---- - -## Standard Library Names - -```text -os -sys -json -pathlib -re -typing -collections -itertools -asyncio -``` - -These identifiers must remain unchanged. - ---- - -# Variable Names - -Never translate variable names. - -Examples: - -```python -x -y -count -index -user_name -my_list -self -cls -``` - -Correct: - -```python -count = 5 -``` - -Incorrect: - -```python -ਗਿਣਤੀ = 5 -``` - ---- - -# PO File Rules - -Never modify: - -```text -msgid -#: source references -#, flags -``` - -Translate only: - -```text -msgstr -``` - ---- - -# Placeholder Preservation - -Placeholders must remain exactly unchanged. - -Examples: - -```text -%s -%d -%i -%r -%f -%s%.*f -``` - -```text -{} -{0} -{name} -{value} -``` - -```text -%(name)s -%(count)d -``` - -Correct: - -```text -"%s ਆਈਟਮ ਮਿਲੇ" -``` - -Incorrect: - -```text -"%d ਆਈਟਮ ਮਿਲੇ" -``` - -unless the original uses `%d`. - ---- - -# RST Markup Preservation - -Never modify reStructuredText roles. - -Examples: - -```rst -:func:`print` -:class:`list` -:class:`dict` -:mod:`os` -:meth:`append` -:attr:`name` -:exc:`ValueError` -:term:`iterator` -:ref:`section` -``` - -Translate only surrounding text. - -Correct: - -```rst -ਇਹ :func:`print` ਫੰਕਸ਼ਨ ਦੀ ਵਰਤੋਂ ਕਰਦਾ ਹੈ। -``` - -Incorrect: - -```rst -ਇਹ :func:`ਛਾਪੋ` ਫੰਕਸ਼ਨ ਦੀ ਵਰਤੋਂ ਕਰਦਾ ਹੈ। -``` - ---- - -# Inline Markup Preservation - -Keep inline markup unchanged. - -Examples: - -```rst -*italic* -**bold** -``code`` -``` - -Do not modify formatting syntax. - ---- - -# Directives - -Never modify Sphinx directives. - -Examples: - -```rst -.. note:: -.. warning:: -.. important:: -.. tip:: -.. versionadded:: -.. versionchanged:: -.. deprecated:: -.. code-block:: python -``` - -Translate the directive content only. - ---- - -# Code Blocks - -Translate: - -* Comments -* Explanatory text - -Do not translate: - -* Python code -* Keywords -* Identifiers -* Module names -* Function names -* Class names -* Exception names - -Example: - -```python -# Calculate the square of a number -x = 5 -print(x * x) -``` - -Only the comment may be translated. - ---- - -# Interactive Python Sessions - -Examples: - -```python ->>> x = 5 ->>> print(x) -5 -``` - -Do not translate: - -* Code -* Output -* Tracebacks -* Exception names - -Translate only surrounding explanations. - ---- - -# URLs - -Never translate URLs. - -Examples: - -```text -https://docs.python.org/ -https://devguide.python.org/ -https://github.com/python/cpython -``` - ---- - -# Version Information - -Never modify version numbers. - -Examples: - -```text -Python 3.13 -Python 3.14 -Changed in version 3.12 -Deprecated since version 3.11 -``` - -Translate surrounding text only. - ---- - -# Technical Terms - -Some technical terms are widely recognized in English within the Python ecosystem and should normally remain untranslated unless the project glossary specifies an approved Punjabi equivalent. - -Examples: - -```text -Python -API -Unicode -JSON -XML -HTML -HTTP -URL -ASCII -UTF-8 -``` - -Use glossary-approved Punjabi translations where available. - ---- - -# Terminology Consistency - -Always consult: - -```text -GLOSSARY.md -``` - -before introducing new terminology. - -If a term already exists in the glossary: - -* Use the glossary translation. -* Do not create alternatives. -* Do not switch wording between files. - -Consistency is more important than personal preference. - ---- - -# Batch Translation Workflow - -For large files, translations should be performed in reviewable batches. - -Recommended format: - -```text -Replace this block: - -msgid "example" -msgstr "" - -With: - -msgid "example" -msgstr "ਉਦਾਹਰਨ" -``` - -For multiple consecutive entries: - -```text -Replace these consecutive blocks: -... -``` - -This workflow was successfully used for: - -```text -library/functions.po -library/stdtypes.po -library/functools.po -library/exceptions.po -``` - -and is recommended for future large files. - ---- - -# Machine Translation Policy - -Machine translation may be used only as a drafting aid. - -Every translation must be manually reviewed. - -Contributors remain responsible for: - -* Accuracy -* Technical correctness -* Terminology consistency -* Markup preservation -* Natural Punjabi wording - -No untranslated machine output should be committed. - ---- - -# Translation Quality Checklist - -Before committing: - -* Verify all intended strings are translated. -* Verify placeholders remain unchanged. -* Verify markup remains unchanged. -* Verify code examples remain executable. -* Verify glossary terminology is followed. -* Verify formatting matches the source. -* Verify the documentation builds successfully. -* Verify `sphinx-lint` reports no issues. -* Verify the translation reads naturally in Punjabi. -* Complete a manual review. - ---- - -# Validation Commands - -Validate a file: - -```bash -msgfmt --check FILE.po -``` - -Show statistics: - -```bash -msgfmt --statistics FILE.po -``` - -Show untranslated entries: - -```bash -msgattrib --untranslated FILE.po -``` - -Show translated entries: - -```bash -msgattrib --translated FILE.po -``` - ---- - -# Repository-Wide Validation - -Validate translation files: - -```bash -msgfmt --check FILE.po -``` - -Run documentation linting: - -```bash -sphinx-lint . -``` - -Build the Punjabi documentation: - -```bash -python -m sphinx -b html -D language=pa Doc build/html-pa -``` - -Run the strict ("nitpicky") documentation build: - -```bash -python -m sphinx -b html -n -W Doc build/html-pa -``` - -A completed translation should: - -- Pass GNU gettext validation. -- Preserve all reStructuredText markup. -- Produce no `sphinx-lint` errors. -- Build successfully with CPython's HTML documentation builder. -- Pass the nitpicky (`-n`) documentation build. - ---- - -# Transifex Synchronization - -Translations may be maintained through the official Python Documentation -Transifex project. - -Before uploading translations: - -* Validate all files with msgfmt -* Ensure glossary terminology is consistent -* Verify RST markup remains unchanged -* Review all machine-assisted translations manually - -Only validated translations should be uploaded. - ---- - -# Commit Message Conventions - -Commit messages should be concise, descriptive, and focused on a single logical change whenever possible. - -Use descriptive commit messages. - -Examples: - -```text -Translate tutorial/classes.po to Punjabi -Translate tutorial/floatingpoint.po to Punjabi -Translate tutorial/venv.po to Punjabi -Translate library/functions.po to Punjabi -Translate library/stdtypes.po to Punjabi -Translate library/functools.po to Punjabi -Translate library/exceptions.po to Punjabi -Translate glossary.po to Punjabi -Update glossary terminology -Update README statistics -Update project documentation -``` - ---- - -# Contributor Expectations - -Before starting a new file: - -1. Review `GLOSSARY.md` -2. Review this Style Guide -3. Review completed translations -4. Validate frequently -5. Commit in logical batches -6. Keep terminology consistent - ---- - -# Tone and Writing Style - -Documentation should be: - -* Formal -* Educational -* Clear -* Consistent -* Professional - -Avoid: - -* Slang -* Regional dialect variations -* Excessively literal translations -* Unnecessary English/Punjabi mixing - -When in doubt: - -```text -Clarity > Literal Translation -Consistency > Personal Preference -Accuracy > Style -``` - ---- - -# Translation Review - -Every completed translation should be reviewed before submission. - -Review each completed translation for: - -- Technical accuracy. -- Natural and idiomatic Punjabi wording. -- Consistent terminology. -- Correct grammar and spelling. -- Preservation of placeholders. -- Preservation of reStructuredText markup. -- Formatting consistency. -- Successful validation with the project's tooling. - ---- - -# References - -Useful resources for contributors: - -- **Python Developer Guide – Documentation Translations** - - -- **Python Documentation** - - -- **Python Documentation Style Guide** - - -- **Python Documentation on Transifex** - - -- **reStructuredText Primer (Sphinx)** - - ---- - -# Final Rule - -Every translation should satisfy three requirements: - -```text -Technically accurate -Consistent with the project glossary -Natural and readable for Punjabi users -``` - -If any of these requirements are not met, revise the translation before committing. +- [Python Developer's Guide: Translating](https://devguide.python.org/documentation/translations/translating/) +- [Python Developer's Guide: Style guide](https://devguide.python.org/documentation/style-guide/) +- [CPython glossary](https://docs.python.org/3/glossary.html) From 4366a7813b3227b588d17793889b06e0f00c36f1 Mon Sep 17 00:00:00 2001 From: Bhuvansh Kataria Date: Thu, 22 Oct 2026 17:44:43 +0000 Subject: [PATCH 04/12] Shorten RULES.md to markup, code and .po rules --- RULES.md | 1186 ++---------------------------------------------------- 1 file changed, 38 insertions(+), 1148 deletions(-) diff --git a/RULES.md b/RULES.md index f0305dc..2dc9491 100644 --- a/RULES.md +++ b/RULES.md @@ -1,1172 +1,62 @@ -# Punjabi Python Documentation Translation Rules +# Rules for Markup, Code and `.po` Files -This document defines the rules contributors must follow before translating +These rules keep the translation valid and the documentation build working. For language and terminology, see [STYLE_GUIDE.md](STYLE_GUIDE.md) and [GLOSSARY.md](GLOSSARY.md). -or editing Punjabi (`pa`) Python documentation. +We translate in Transifex (see [Transifex_Setup.md](Transifex_Setup.md)). The same rules apply to any `.po` file edited in this repository. -The purpose of these rules is to keep the translation technically accurate, +## Keep unchanged -natural for Punjabi-speaking Python users, consistent across the repository, +Keep these exactly as in the English source: -and compatible with the official Python documentation tooling. +- Python keywords, built-in names, and names of modules, packages, classes, functions, methods, attributes, exceptions and constants +- Variable, argument and parameter names in code +- C API names, command names, environment variables, file and directory names +- PEP numbers and version numbers (`3.12`, `Python 3.15`) +- URLs, anchors and reference identifiers +- Placeholders such as `%s`, `%d`, `%(name)s`, `{}`, `{0}`, `{name}` and `` -The primary reference for translation policy is the Python Developer Guide +A name stays as it is even when a Punjabi spelling is possible. The words around a name are translated as usual. -documentation translation guidance: +## Code -https\://devguide.python.org/documentation/translations/translating/ +- Do not change Python code: indentation, names, operators, imports, arguments or syntax. +- Do not change output, tracebacks or interactive sessions (the `>>>` and `...` prompts). +- Comments inside code may be translated if the meaning stays the same. +- Translate a string literal only when the English text clearly means the literal itself to be translated. It may also be data, output, an API value or an identifier. -Other official Python documentation translations may be consulted as +## reStructuredText and Sphinx markup -references for translation methodology and terminology. - ---- - -## 1. Core Translation Principles - -### 1.1 Translate meaning, not words - -Translate the meaning of the English documentation into natural Punjabi. - -Do not perform word-for-word translation when that produces unnatural, - -ambiguous, misleading, or technically incorrect Punjabi. - -The final translation should communicate the same technical meaning as the - -English source. - -### 1.2 Preserve technical accuracy - -Never simplify, generalize, reinterpret, or alter a technical statement merely - -to make the Punjabi sentence easier to write. - -Technical behavior described by the English documentation must remain - -technically equivalent in Punjabi. - -### 1.3 Punjabi should be natural - -Use Punjabi that a Punjabi-speaking programmer can read naturally. - -Avoid: - -- machine-translation artifacts - -- unnecessarily complicated Punjabi - -- unnatural literal translations - -- excessive Sanskritized vocabulary - -- unnecessary English words when a familiar Punjabi technical form exists - -- forced Punjabi translations of technical terms that programmers normally - -  know in English - -### 1.4 Do not translate every technical word automatically - -Technical terminology must be decided using context. - -For a technical term: - -1\. Check existing Punjabi programming/documentation usage. - -2\. Check previously approved terminology in this project. - -3\. Check established terminology in mature Python documentation translations. - -4\. Consider whether Punjabi programmers normally use the English term. - -5\. Prefer an established community convention over an invented translation. - -6\. A hybrid Punjabi + English form is acceptable when it is natural and - -   commonly understood. - -7\. English may remain unchanged when it is the clearest or most familiar - -   technical form. - -8\. Once terminology is approved for this project, record it in the glossary - -   and use it consistently. - -Do not invent a Punjabi technical term simply because a dictionary provides - -a possible translation. - ---- - -## 2. Technical Terminology Policy - -### 2.1 Use the glossary consistently - -`GLOSSARY.md` is the project's terminology record. - -When a term has an approved project translation, use that translation - -consistently unless there is a strong technical or contextual reason not to. - -Do not introduce competing translations for the same technical concept. - -### 2.2 Glossary entries require review - -A new terminology choice must not be added to `GLOSSARY.md` merely because - -one contributor prefers it. - -Before adding a new term: - -1\. Check existing project translations. - -2\. Check Punjabi programming/documentation usage. - -3\. Check mature Python translations for translation methodology. - -4\. Confirm that the proposed term accurately represents the Python concept. - -5\. Prefer a form that will remain understandable to Punjabi programmers. - -6\. Use the same term throughout the project after approval. - -### 2.3 Context takes priority - -The same English word may require different Punjabi wording in different - -contexts. - -For example, an English word may be: - -- a Python technical concept - -- an ordinary English word - -- an identifier - -- a class name - -- a function name - -- part of a Sphinx role - -- part of a code example - -Do not translate based only on string matching. - -### 2.4 Do not perform blind global replacements - -Never run a repository-wide replacement such as: - -```text - -method -> Punjabi equivalent - -object -> Punjabi equivalent - -string -> Punjabi equivalent - -``` - -without checking the context. - -A word may occur inside code, identifiers, Sphinx markup, API names, or - -other structures where changing it would be incorrect. - ---- - -## 3. Python Names and Identifiers - -The following must remain unchanged unless the English source itself changes: - -- Python keywords - -- function names - -- method names - -- class names - -- module names - -- package names - -- exception names - -- attribute names - -- variable names in code - -- argument names in code - -- parameter names in code - -- constants - -- API names - -- C API names - -- command names - -- environment variable names - -- file names - -- directory names - -- protocol names - -- PEP numbers - -- Python version numbers - -Examples: - -```text - -def - -class - -return - -async - -await - -__init__ - -__name__ - -PyObject - -Py_INCREF - -StopIteration - -Python - -CPython - -asyncio - -``` - -must not be translated. - ---- - -## 4. Code Examples - -### 4.1 Preserve executable code - -Do not alter executable Python code unless the English source itself has - -changed. - -Preserve: - -- indentation - -- variable names - -- function names - -- class names - -- method names - -- operators - -- syntax - -- imports - -- module names - -- arguments - -- parameters - -- strings that are required for program behavior - -### 4.2 Comments may be translated - -Comments inside code examples may be translated when doing so does not change - -their meaning. - -Example: - -```python - -\# create a list - -``` - -may have its comment translated, while: - -```python - -items = [] - -``` - -must remain unchanged. - -### 4.3 String literals require context - -Do not automatically translate every string literal. - -A string may be: - -- explanatory example text - -- command output - -- expected program output - -- an API value - -- a protocol value - -- an identifier - -- data used by the example - -Only translate it when the source documentation intends the literal itself - -to be translated. - ---- - -## 5. reStructuredText and Sphinx Markup - -Python documentation uses reStructuredText and Sphinx extensively. - -Translation must preserve documentation markup. - -### 5.1 Preserve Sphinx roles - -Do not modify the role itself. - -Examples: - -```text - -\:func:`print` - -\:class:`list` - -\:meth:`str.format` - -\:keyword:`while` - -\:exc:`ValueError` - -\:mod:`asyncio` - -\:ref:`some-reference` - -\:pep:`703` - -``` - -must retain their role syntax. - -### 5.2 Preserve role targets - -The target of a Sphinx role is normally an internal documentation identifier - -and must remain unchanged. - -For example: - -```text - -\:ref:`function` - -``` - -must not become: - -```text - -\:ref:`ਫੰਕਸ਼ਨ` - -``` - -when `function` is the reference target. - -### 5.3 Explicit display text may be translated - -When a Sphinx role contains separate display text and target, the display - -text may be translated while the target remains unchanged. - -Example: - -```text - -\:ref:`Function definitions ` - -``` - -may translate the visible label while preserving: - -```text - - - -``` - -### 5.4 Preserve directives - -Do not translate directive names or their technical arguments. - -Examples: - -```text - -.. code-block:: - -.. note:: - -.. warning:: - -.. seealso:: - -.. versionadded:: - -.. versionchanged:: - -``` - -### 5.5 Preserve links - -Do not change: - -- URLs - -- URL targets - -- anchors - -- reference identifiers - -Only translate visible link text where appropriate. - ---- - -## 6. Placeholders and Formatting - -Placeholders must remain unchanged. - -Examples include: - -```text - -%s - -%d - -{value} - -{foo} - -%(name)s - - - - - -``` - -Do not rename or translate placeholders. - -Preserve: - -- backticks - -- double backticks - -- asterisks used for emphasis - -- underscores used by reStructuredText - -- quotation marks where technically significant - -- escaped characters - -- newline structure where required - -- code formatting - ---- - -## 7. PO File Rules - -### 7.1 English source strings are read-only - -Never intentionally modify the English source strings in `msgid` during -translation, review, cleanup, or terminology work. - -The `msgid` is the upstream English source and must be treated as read-only. - -Do not: - -- rewrite English wording -- fix English grammar -- change English punctuation -- change English capitalization -- alter the English meaning -- translate the English source -- change source text merely to make the Punjabi translation easier -- make formatting-only edits to `msgid` content as part of translation work - -Translation and cleanup work must be performed on `msgstr`. - -The only exception is a legitimate upstream source update. If the upstream -Python documentation changes the English source, the PO files may receive the -new `msgid` through the normal source/template synchronization process. That -is not a translation edit. - -A translation-quality change must contain no intentional `msgid` changes. - -### 7.2 `msgstr` is the translation side - -All normal Punjabi translation work belongs in `msgstr`. - -When reviewing an entry: - -1. Read the `msgid` only to understand the source meaning. -2. Decide the correct Punjabi wording. -3. Modify only `msgstr`. -4. Preserve any required source-side markup, identifiers, URLs, placeholders, - and other technical content. - -If the English source itself appears incorrect, do not silently fix it in the -Punjabi PO file. Report or address the upstream source separately. - -### 7.3 Preserve PO syntax - -Every PO entry must remain valid gettext syntax. - -Before committing: - -```bash -msgfmt --check -o /dev/null path/to/file.po -``` - -For repository-wide validation: - -```bash -find . -name "*.po" -print0 | xargs -0 -n1 msgfmt --check -o /dev/null -``` - -### 7.4 Preserve multiline structure - -When editing multiline `msgstr` entries: - -- preserve valid quoting -- preserve escaped characters -- preserve newline characters -- do not accidentally merge or split content in a way that changes meaning -- ensure the final PO file remains syntactically valid - -Do not rewrap or otherwise rewrite `msgid` lines during translation work. - -### 7.5 Never leave accidental fuzzy translations - -A translation should not be marked fuzzy merely to bypass review. - -Uncertain translations should be reviewed and corrected before being treated -as final. - -Do not remove a legitimate fuzzy marker without reviewing the translation first. - -### 7.6 Do not change unrelated entries - -A translation commit should not contain unrelated formatting, source-text, -metadata, or code changes. - -In particular, do not use a translation cleanup as an excuse to modify English -`msgid` strings elsewhere in the file. - ---- - -## 8. Translation Quality - -Every translated entry should be checked for: - -### Meaning - -Does the Punjabi text communicate the same information? - -### Terminology - -Does it use the project's approved term where one exists? - -### Naturalness - -Would a Punjabi-speaking programmer naturally understand the sentence? - -### Grammar - -Is the Punjabi grammatically and stylistically acceptable? - -### Technical precision - -Could the wording cause a reader to misunderstand Python behavior? - -### Consistency - -Is the same concept translated consistently elsewhere? - -### Markup - -Are all roles, references, links, placeholders, and formatting intact? - ---- - -## 9. Technical English and Hybrid Forms - -English technical terminology is allowed and sometimes preferred. - -Use English when: - -- the word is commonly used by programmers - -- a Punjabi translation is uncommon or confusing - -- the word is a proper technical name - -- the English form is clearer - -- the term is normally used in English in Punjabi programming material - -Hybrid wording is also acceptable when it is natural. - -For example: - -```text - -Python interpreter - -CPython interpreter - -runtime environment - -Python API - -``` - -may remain partly English when that is the clearest terminology for the - -intended audience. - -Do not force an artificial Punjabi translation merely for the sake of having - -every word translated. - ---- - -## 10. Consistency Policy - -Once a technical term has been approved: - -- use it consistently across the repository - -- update the glossary - -- use it in new translations - -- correct inconsistent completed translations where appropriate - -- do not introduce another spelling or translation without review - -Consistency applies to: - -- terminology - -- spelling - -- transliteration - -- punctuation - -- capitalization - -- technical names - -- recurring documentation phrases - ---- - -## 11. Terminology Review Procedure - -When encountering a technical term without an approved project translation: - -### Step 1 - -Check `GLOSSARY.md`. - -### Step 2 - -Search completed Punjabi translations in this repository. - -### Step 3 - -Check Punjabi programming resources and established usage. - -### Step 4 - -Consult mature Python translation projects such as: - -- Simplified Chinese - -- Traditional Chinese - -- Japanese - -- Korean - -- other established Python documentation translations - -These are references for terminology methodology and translation practice, - -not sources to copy literally. - -### Step 5 - -Check the meaning in the official Python documentation or CPython glossary. - -### Step 6 - -Choose the form that is: - -- technically accurate - -- understandable - -- natural in Punjabi - -- appropriate for Python programmers - -- consistent with existing project terminology - -### Step 7 - -Record the approved terminology in `GLOSSARY.md`. - ---- - -## 12. Do Not Copy Other Languages Literally - -Other Python translations are useful references, but their terminology is - -language-specific. - -A Chinese, Japanese, Korean, Spanish, or French translation must not be - -copied mechanically into Punjabi. - -Use other translations to understand: - -- how technical terms are handled - -- when English is retained - -- how terminology dictionaries are organized - -- how Sphinx markup is preserved - -- how translators maintain consistency - -The Punjabi translation must follow Punjabi language conventions. - ---- - -## 13. Review Existing Translations - -A previously translated entry is not automatically considered correct. - -When reviewing old translations: - -- check the English source again - -- verify technical meaning - -- check terminology against the current glossary - -- check consistency with current project rules - -- check Sphinx markup - -- check code examples - -- improve awkward or misleading Punjabi when necessary - -However, do not rewrite translations merely because another wording is - -personally preferred. - -There must be a clear linguistic, technical, or consistency reason for a - -change. - ---- - -## 14. Avoid Machine-Translation Artifacts - -Do not submit translations that appear to have been copied directly from an - -automatic translation system without human review. - -Watch for: - -- unnatural word order - -- incorrect technical meanings - -- inconsistent terminology - -- unexplained English/Punjabi switching - -- incorrect punctuation - -- literal translations of idioms - -- incorrect grammatical agreement - -- mistranslated code terminology - -Machine translation may be used as a drafting aid, but every final translation - -must be reviewed by a human. - ---- - -## 15. Do Not Translate Names - -The following should normally remain unchanged: - -```text - -Python - -CPython - -PyPI - -GitHub - -Transifex - -Unicode - -UTF-8 - -PEP - -PEP 703 - -Linux - -Windows - -macOS - -POSIX - -JSON - -XML - -HTTP - -HTTPS - -URL - -API - -``` - -Do not translate a proper name merely because a Punjabi transliteration exists. - -Transliteration may be used in explanatory prose only when it is appropriate - -and does not alter the actual technical name. - ---- - -## 16. Version and Release Information - -Never alter technical version information. - -Preserve values such as: - -```text - -Python 3.15 - -Python 3.14 - -3.13 - -PEP 703 - -``` - -exactly when they identify a version, release, or specification. - -Do not translate version identifiers. - ---- - -## 17. Punctuation and Formatting - -Punjabi prose should use consistent punctuation. - -Be careful with: - -- commas - -- full stops - -- colons - -- semicolons - -- parentheses - -- quotation marks - -- hyphens - -- dashes - -- apostrophes - -- code delimiters - -Do not introduce formatting changes that are unrelated to translation. - ---- - -## 18. Source Meaning Has Priority Over Style Preference - -When choosing between two valid Punjabi formulations: - -1\. Prefer the one that preserves technical meaning most precisely. - -2\. Prefer natural Punjabi. - -3\. Prefer established project terminology. - -4\. Prefer consistency with surrounding documentation. - -5\. Do not change wording merely because it sounds more personally preferred. - ---- - -## 19. Core Switcher Files - -The following files are especially important for the Python documentation - -translation infrastructure: +- Keep roles and their targets: `:func:`, `:class:`, `:meth:`, `:exc:`, `:mod:`, `:ref:`, `:pep:` and so on. +- To show a Punjabi label, use the form with an explicit target and translate only the label. The target between `<` and `>` stays as in the English. +- Keep directives and their arguments (`.. note::`, `.. warning::`, `.. versionadded:: 3.12`, `.. code-block:: python`). Translate only the text inside them. +- Keep inline markup: `*italic*`, `**bold**`, ` ``code`` `, backticks, underscores and escaped characters. +- Keep the structure of the text (line breaks, lists, tables) as in the source. ```text - -bugs.po - -tutorial/\*.po - -builtins/functions.po - +English: :ref:`function` +Wrong: :ref:`ਫੰਕਸ਼ਨ` +Right: :ref:`ਫੰਕਸ਼ਨ ` ``` -These files require particularly careful review because their translation - -status is relevant to the documentation language switcher. - -Do not sacrifice translation quality merely to increase completion - -percentages. - ---- +## `.po` files -## 20. Validation Before Commit +- Translate `msgstr` only. Never change `msgid`, the `#:` source references, the `#,` flags or the header. They come from the English source and are updated by the sync. +- If the English looks wrong, report it upstream. Do not fix it in the `.po` file. +- Keep the quoting, escapes and line breaks of multi-line strings valid. +- Do not add or remove `fuzzy` to skip a review. Check an uncertain translation and fix it first. +- Do not mix unrelated changes (formatting, metadata, other files) into a translation commit. -At minimum, run: +## Checks -```bash - -find . -name "\*.po" -print0 | xargs -0 -n1 msgfmt --check -o /dev/null - -``` - -Then: +Before sending a change, run: ```bash - +msgfmt --check FILE.po +find . -name "*.po" -print0 | xargs -0 -n1 msgfmt --check -o /dev/null git diff --check - -``` - -Review the actual changes: - -```bash - git diff - -``` - -Before committing, confirm: - -- no unintended `msgid` changes - -- no code changes - -- no broken Sphinx markup - -- no altered URLs - -- no altered placeholders - -- no accidental whitespace damage - -- no unrelated changes - -- no incorrect terminology introduced - -Where available, also run the repository's documentation and linting checks. - ---- - -## 21. Commit Discipline - -Keep commits focused. - -Good examples: - -```text - -Update Punjabi documentation translations - -Fix Punjabi terminology consistency - -Improve Punjabi glossary terminology - -Fix Punjabi translation markup - -Add Punjabi translation contributor rules - -``` - -Avoid mixing unrelated changes into a translation-quality commit. - ---- - -## 22. Review Checklist - -Before submitting a translation change, confirm: - -```text - -[ ] Meaning preserved - -[ ] Punjabi is natural and readable - -[ ] Approved terminology is used - -[ ] No unnecessary technical English was introduced - -[ ] No required English technical term was incorrectly translated - -[ ] Python/API names preserved - -[ ] Code preserved - -[ ] Sphinx roles preserved - -[ ] Sphinx role targets preserved - -[ ] URLs preserved - -[ ] Placeholders preserved - -[ ] PO syntax valid - -[ ] No fuzzy translation accidentally introduced - -[ ] No unrelated changes - -[ ] Translation reviewed by a human - ``` ---- - -## 23. Golden Rule - -> Translate the documentation, not the program. - -The goal is not to replace every English word. - -The goal is to produce accurate, natural, consistent, maintainable Punjabi - -documentation for Python users while preserving the technical structure of - -the official Python documentation. - -When language preference, terminology preference, and technical correctness - -conflict, technical correctness and preservation of the source meaning take - -priority. - ---- - -## 24. References - -Primary guidance: - -- Python Developer Guide — Documentation Translations - -  https\://devguide.python.org/documentation/translations/translating/ - -- Python Documentation - -  https\://docs.python.org/ - -- Python Developer Guide — Documentation Style Guide - -  https\://devguide.python.org/documentation/style-guide/ - -- CPython Glossary - -  https\://docs.python.org/3/glossary.html - -Useful translation references: - -- Python Simplified Chinese Documentation - -  https\://github.com/python/python-docs-zh-cn - -- Python Traditional Chinese Documentation - -  https\://github.com/python/python-docs-zh-tw - -- Python Japanese Documentation - -  https\://github.com/python/python-docs-ja - -These projects should be used as references for translation practice and +The first two commands run `msgfmt` on one file and on all files. In `git diff`, confirm that no `msgid`, code, URL or placeholder changed and that there are no unrelated changes. -terminology methodology, not as sources for literal Punjabi translations. +Optional: run `sphinx-lint FILE.po`, or build the HTML documentation locally as described in the [Developer's Guide](https://devguide.python.org/documentation/translations/translating/). From b09b7c3a4593f5258522e4f4456413b57c51b7ac Mon Sep 17 00:00:00 2001 From: Bhuvansh Kataria Date: Thu, 22 Oct 2026 17:45:32 +0000 Subject: [PATCH 05/12] Shorten CONTRIBUTING.md and point to the other guides --- CONTRIBUTING.md | 630 +++--------------------------------------------- 1 file changed, 31 insertions(+), 599 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index baee336..e0e4d3b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,622 +1,54 @@ -# Contributing to Python Documentation — Punjabi (`pa`) +# Contributing -Thank you for your interest in contributing to the Punjabi (Gurmukhi) translation of the Python documentation. +Thank you for helping translate the Python documentation into Punjabi. Typo fixes, new translations and reviews are all welcome. -This project is part of the official Python Documentation Translation initiative and follows the translation workflow adopted by the Python Documentation community. Our goal is to make the official Python documentation accessible to Punjabi-speaking developers, students, educators, and the broader open-source community while maintaining the same quality standards as the upstream documentation. +## Ways to help -Whether you are fixing a typo, translating a new document, reviewing terminology, or improving translation quality, your contributions are welcome. +- **Translate or review** in [Transifex](https://explore.transifex.com/python-doc/python-newest/). Most of the work happens there, and you do not need a pull request. See [Transifex_Setup.md](Transifex_Setup.md). +- **Improve this repository** (guides, workflows, templates) with a pull request. See "Pull requests" below. +- **Report a problem** by opening an issue. ---- +## Before you start -## Contents +Read [STYLE_GUIDE.md](STYLE_GUIDE.md) and [GLOSSARY.md](GLOSSARY.md). [RULES.md](RULES.md) has the detailed rules for markup, placeholders and `.po` files. Use the glossary terms, and keep code, identifiers and reStructuredText markup unchanged. -- [Project Status](#project-status) -- [Before You Start](#before-you-start) -- [Repository Structure](#repository-structure) -- [Translation Workflow](#translation-workflow) -- [Getting Started](#getting-started) -- [Creating New Translation Files](#creating-a-new-translation-file) -- [Validation](#validation) -- [Translation Rules](#translation-rules) -- [Quality Checklist](#quality-checklist) -- [Pull Request Guidelines](#pull-request-guidelines) -- [Commit Message Examples](#commit-message-examples) -- [Translation Standards](#translation-standards) -- [Getting Help](#getting-help) -- [References](#references) -- [License](#license) +## Translations ---- +Translate and review in Transifex. Reviewed translations are pulled into this repository every day (see the [README](README.en.md)). -# Project Status +Please do not edit translations in the `.po` files here. The daily sync takes them from Transifex, so direct edits can be overwritten. If a `.po` file needs a fix that cannot be made in Transifex, ask a coordinator. -The Punjabi (`pa`) translation project is actively maintained and follows the official Python Documentation Translation workflow. +## Pull requests -## Project Team +For changes to the guides, workflows or templates: -The Punjabi (`pa`) translation project is maintained collaboratively by a team of coordinators and contributors through the official Python Documentation Translation project on Transifex. +1. Fork the repository, clone your fork and create a branch from `3.15`. +2. Make your change. Keep each pull request about one topic. +3. If you touched a `.po` file, run `msgfmt --check FILE.po`. +4. Push the branch and open a pull request against `3.15` with a clear description. -### Coordinators +## Checks -The project is currently coordinated by: - -- Bhuvansh Kataria [@BHUVANSH855](https://github.com/BHUVANSH855) -- Mohit Yadav [@mohityadav8](https://github.com/mohityadav8) -- Yashraj Jangra [@Yashraj-Jangra](https://github.com/Yashraj-Jangra) - -The coordinators are responsible for: - -- Managing the translation project. -- Maintaining translation quality. -- Coordinating contributors and reviewers. -- Ensuring consistency across translated documentation. -- Overseeing validation and synchronization workflows. - ---- - -### Current Highlights - -- ✅ Officially listed in the Python Developer Guide Translation Coordinators (PR #1843) -- ✅ Active translation branch: `3.15` -- ✅ Automated synchronization with the official Python Documentation Transifex project -- ✅ GitHub Actions validation passing -- ✅ GNU gettext (`msgfmt`) validation passing -- ✅ `sphinx-lint` validation passing -- ✅ CPython HTML documentation build passing -- ✅ Nitpicky (`-n`) documentation build passing - -### Completed Translation Areas - -| Area | Status | -|------|--------| -| Tutorial Documentation (17/17 files) | ✅ Complete | -| Using Python Documentation (9/9 files) | ✅ Complete | -| `library/stdtypes.po` | ✅ Complete | -| `library/functions.po` | ✅ Complete | -| `library/exceptions.po` | ✅ Complete | -| `library/functools.po` | ✅ Complete | -| `library/string.po` | ✅ Complete | -| `howto/regex.po` | ✅ Complete | -| `howto/sorting.po` | ✅ Complete | -| `glossary.po` | ✅ Complete | -| `bugs.po` | ✅ Complete | - -### Translation Statistics - -| Metric | Value | -|--------|------:| -| Verified Translated Strings | **7,668** | -| Tutorial Files Completed | 17 | -| Using Python Files Completed | 9 | -| Core Library Files Completed | 5 | -| HOWTO Files Completed | 2 | -| Root Translation Files Completed | 2 | - -### Current Priorities - -Current development focuses on: - -- Reviewing existing translations for terminology consistency and technical accuracy. -- Expanding translations across additional Standard Library, HOWTO, FAQ, Reference, C API, and What's New documentation. -- Maintaining consistency with `GLOSSARY.md` and `STYLE_GUIDE.md`. -- Keeping translations synchronized with upstream CPython documentation. -- Growing the Punjabi translation community and onboarding new contributors and reviewers. - ---- - -# Before You Start - -Before contributing, please ensure you have: - -- A GitHub account. -- A Transifex account (recommended for translation work). -- Basic familiarity with Git and GitHub. -- Basic understanding of Python documentation and reStructuredText (RST). -- GNU gettext utilities installed (`msgfmt`, `msgattrib`, `msginit`). -- Python and Sphinx installed if you intend to perform local documentation builds. - -Although many translations are performed through Transifex, contributors may also work directly with `.po` files when appropriate. - -Before beginning any translation work, please read: - -- `README.md` -- `STYLE_GUIDE.md` -- `GLOSSARY.md` - -These documents describe the project's workflow, terminology, and translation conventions. - ---- - -# Repository Structure - -The repository is organized similarly to the upstream CPython documentation. - -```text -python-docs-pa/ -├── .github/ # GitHub Actions workflows -├── tutorial/ # Tutorial documentation -├── using/ # Using Python documentation -├── library/ # Standard Library documentation -├── howto/ # HOWTO guides -├── faq/ # Frequently Asked Questions -├── reference/ # Language Reference -├── c-api/ # Python/C API documentation -├── extending/ # Extending and Embedding Python -├── installing/ # Installation documentation -├── distributing/ # Distribution documentation -├── deprecations/ # Deprecated features -├── whatsnew/ # What's New documentation -│ -├── README.md -├── CONTRIBUTING.md -├── STYLE_GUIDE.md -├── GLOSSARY.md -├── PROJECT_REPORT.md -│ -├── *.po # Root translation files -└── .gitignore -``` - -Each directory contains translation files (`.po`) corresponding to the official CPython documentation. - -Whenever possible, contributors should work on one document or one logical translation area at a time to simplify review and maintain consistency. - -# Translation Workflow - -The Punjabi (`pa`) translation project follows the standard Python Documentation Translation workflow. - -```text -Translate in Transifex - ↓ -Follow GLOSSARY.md - ↓ -Follow STYLE_GUIDE.md - ↓ -Peer Review - ↓ -Automated Synchronization to GitHub - ↓ -GitHub Actions Validation - ↓ -GNU gettext Validation (`msgfmt`) - ↓ -sphinx-lint - ↓ -CPython HTML Build - ↓ -Nitpicky (`-n`) Documentation Build -``` - -Every completed translation should successfully pass the validation pipeline before being considered ready. - ---- - -# Getting Started - -Contributors can help in several ways: - -- Translate untranslated documentation. -- Review existing translations. -- Improve terminology consistency. -- Validate translations locally. -- Fix formatting or reStructuredText issues. -- Correct validation errors. -- Improve documentation quality. - -For external contributors, the recommended GitHub workflow is: - -1. Fork the repository. -2. Clone your fork locally. -3. Create a new branch. -4. Make your changes. -5. Validate your work. -6. Commit your changes. -7. Push the branch. -8. Open a Pull Request. - -If you are translating through Transifex, translations will be synchronized automatically through the repository's GitHub Actions workflow. - ---- - -# Creating a New Translation File - -When a new CPython documentation template (`.pot`) becomes available, a corresponding Punjabi translation file can be created using GNU gettext. - -Example: - -```bash -msginit \ - --locale=pa \ - --input=PATH_TO_TEMPLATE.pot \ - --output-file=PATH_TO_OUTPUT.po -``` - -For example: - -```bash -msginit \ - --locale=pa \ - --input=library/functions.pot \ - --output-file=library/functions.po -``` - -After creating a new `.po` file: - -- Preserve the original metadata. -- Translate progressively. -- Validate frequently. -- Submit only well-tested translations. - ---- - -# Validation - -Every completed translation should pass all validation checks before submission. - -> **Validation and translation review are separate processes.** -> -> 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. - -## Validation Pipeline - -```text -Translation - ↓ -msgfmt - ↓ -sphinx-lint - ↓ -CPython HTML Build - ↓ -Nitpicky Build -``` - ---- - -## GNU gettext Validation - -Check for syntax errors: - -```bash -msgfmt --check FILE.po -``` - -Display translation statistics: - -```bash -msgfmt --statistics FILE.po -``` - -List untranslated messages: - -```bash -msgattrib --untranslated FILE.po -``` - -List translated messages: - -```bash -msgattrib --translated FILE.po -``` - ---- - -## Documentation Validation - -Run documentation linting: - -```bash -sphinx-lint . -``` - -Build the Punjabi documentation: - -```bash -python -m sphinx -b html -D language=pa Doc build/html-pa -``` - -Run the strict ("nitpicky") documentation build: +CI runs `msgfmt --check` on every `.po` file for each push and pull request. It must pass. ```bash -python -m sphinx -b html -n -W Doc build/html-pa -``` - -All commands should complete successfully before submitting a contribution. - ---- - -## Review Guidelines - -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. - -Automated validation confirms that a translation is technically valid, but it does not verify translation quality. - -During review, contributors and reviewers should check: - -- Technical accuracy. -- Consistency with `GLOSSARY.md`. -- Compliance with `STYLE_GUIDE.md`. -- Natural Punjabi wording. -- Preservation of reStructuredText and Sphinx markup. -- Correct handling of cross-references, directives, and code examples. - ---- - -# Translation Rules - -Maintaining consistency is one of the most important goals of this project. - -Always preserve: - -- Technical accuracy -- Existing terminology -- Formatting -- Documentation structure -- reStructuredText markup - ---- - -## Never Translate - -### Python Keywords - -```text -if -else -elif -for -while -class -def -return -import -from -try -except -finally -raise -pass -with -yield -lambda -``` - ---- - -### Python Identifiers - -Do **not** translate: - -- Function names -- Class names -- Module names -- Exception names -- Variable names -- Package names - -Examples: - -```text -print -len -range -list -dict -tuple -set -ValueError -TypeError -KeyError -ImportError -os -sys -json -pathlib -``` - ---- - -### reStructuredText and Sphinx Markup - -Never modify or translate documentation roles or directives such as: - -```rst -:func: -:class: -:mod: -:meth: -:attr: -:exc: -:term: -:ref: -``` - -Likewise, preserve: - -- Code blocks -- Inline code -- Hyperlinks -- File names -- Anchors -- Cross-references - ---- - -### Other Items - -Do not translate: - -- URLs -- Python version numbers -- Command-line options -- File extensions -- Package names -- Environment variables - ---- - -## Translate - -Translate: - -- Titles -- Section headings -- Paragraphs -- Explanatory text -- Notes -- Warnings -- Tips -- Comments inside code examples -- Table content -- User-facing descriptions -- Documentation narratives - -Translate naturally while preserving the original meaning. - -Avoid literal word-for-word translations when a more natural Punjabi expression communicates the same concept accurately. - ---- - -## Reviewer Responsibilities - -Reviewers help ensure that translations are technically accurate, linguistically natural, and consistent across the project. - -A reviewer should: - -- Verify terminology against `GLOSSARY.md`. -- Check compliance with `STYLE_GUIDE.md`. -- Preserve original meaning and technical intent. -- Ensure all Sphinx and reStructuredText markup remains unchanged. -- Report inconsistencies or suggest improvements through GitHub or Transifex. - ---- - -# Quality Checklist - -Before submitting your contribution, ensure that: - -- [ ] All intended entries have been translated or reviewed. -- [ ] GNU gettext (`msgfmt`) validation passes. -- [ ] No reStructuredText markup has been modified accidentally. -- [ ] Code examples remain unchanged. -- [ ] Terminology follows `GLOSSARY.md`. -- [ ] Translation style follows `STYLE_GUIDE.md`. -- [ ] Translation has been reviewed for natural Punjabi wording. -- [ ] `sphinx-lint` reports no problems. -- [ ] CPython HTML documentation builds successfully. -- [ ] Nitpicky (`-n`) documentation build passes. -- [ ] GitHub Actions validation completes successfully. - -# Pull Request Guidelines - -Before opening a Pull Request, please ensure that your contribution is complete, focused, and ready for review. - -### Before You Submit - -- Sync your branch with the latest `3.15` branch. -- Keep each Pull Request focused on a single topic or documentation area whenever possible. -- Validate your translations locally before submitting. -- Ensure GitHub Actions complete successfully. -- Provide a clear description of your changes. -- Reference related issues or discussions when applicable. - -Large translation efforts should be split into multiple smaller Pull Requests whenever practical to simplify review. - ---- - -# Commit Message Examples - -Use concise, descriptive commit messages. - -Examples: - -```text -Translate tutorial/modules.po to Punjabi - -Translate library/functions.po - -Translate library/stdtypes.po - -Update glossary terminology - -Improve translation consistency - -Fix validation issues in tutorial translations - -Correct formatting in reference documentation - -Update Punjabi translations for Python 3.15 +msgfmt --check FILE.po # required +sphinx-lint FILE.po # optional, for larger changes ``` ---- - -# Translation Standards - -High-quality translations should be: - -- Technically accurate. -- Natural and easy to read in Punjabi. -- Consistent with existing project terminology. -- Consistent with the official Python documentation. -- Free from grammatical and spelling errors. -- Valid according to GNU gettext and Sphinx validation tools. - -Contributors should: - -- Prefer natural Punjabi over literal word-for-word translations. -- Preserve the original meaning and technical intent. -- Follow the terminology defined in `GLOSSARY.md`. -- Follow the conventions described in `STYLE_GUIDE.md`. -- Preserve all reStructuredText roles, directives, hyperlinks, and formatting. -- Keep code examples identical to the original documentation. -- Preserve indentation and whitespace where required. -- Review completed translations for technical accuracy, terminology consistency, and natural Punjabi wording before submission. -- Follow translation patterns established in completed project files whenever appropriate. - -When uncertain about a translation, prioritize consistency with existing project terminology rather than introducing new wording. - ---- - -# Getting Help - -If you have questions about terminology, translation style, or project workflow, consult the following project documentation first: - -- `README.md` -- `STYLE_GUIDE.md` -- `GLOSSARY.md` -- `PROJECT_REPORT.md` - -For project discussions, suggestions, bug reports, or translation questions, please use GitHub Issues and Pull Requests. - -Constructive feedback, terminology discussions, and translation reviews are always welcome. - ---- - -# References - -Useful resources for contributors: - -- **Python Developer Guide – Documentation Translations** - - -- **Python Documentation** - - -- **Python Documentation on Transifex** - - -- **Python Documentation Style Guide** - +## Reviewing -- **reStructuredText Primer (Sphinx)** - +A good review checks that: ---- +- the meaning matches the English original, +- glossary terms are used, +- code, placeholders and markup are unchanged, +- the Punjabi reads naturally. -# License +## Getting help -This project follows the licensing model of the official Python Documentation Translation project. +Open an issue, or ask one of the coordinators listed in the [README](README.en.md). -Documentation translations are contributed under the CC0 1.0 Universal license. +## License -By contributing to this repository, you agree that your contributions may be distributed under the same licensing terms as the official Python documentation translations. \ No newline at end of file +Translations are contributed under the CC0 1.0 Universal license. By contributing, you agree that your contributions may be distributed under the same license. From 8591572842615d68a617058d49e6efb195b0ed35 Mon Sep 17 00:00:00 2001 From: Bhuvansh Kataria Date: Thu, 22 Oct 2026 17:48:30 +0000 Subject: [PATCH 06/12] Shorten Transifex_Setup.md and fix the publishing step --- Transifex_Setup.md | 401 +++++---------------------------------------- 1 file changed, 42 insertions(+), 359 deletions(-) diff --git a/Transifex_Setup.md b/Transifex_Setup.md index a99474b..129d09b 100644 --- a/Transifex_Setup.md +++ b/Transifex_Setup.md @@ -1,384 +1,67 @@ -# Transifex Translator Setup & Getting Started Guide +# Transifex Guide -**Project:** Punjabi (pa) Python Documentation -**Platform:** Transifex -**Audience:** Punjabi Translation Contributors +This guide helps new translators get started in Transifex. Translating and reviewing happen there, so you do not need Git, a fork or a pull request. ---- +## Join the project -## 1. What You Need +1. Create a Transifex account, or sign in, at . +2. Open the [Python Documentation project](https://explore.transifex.com/python-doc/python-newest/) and press "Join this project". +3. Choose Punjabi (`pa`) and wait for a coordinator to approve you. The coordinators are listed in the [README](README.en.md). +4. Ask a coordinator which resource to start with, so that two people do not work on the same one. A resource is one documentation file, for example `library-fileinput`. -You only need: +If you cannot see Punjabi or your resource, ask a coordinator. Please do not create another project, language or resource. -* A Transifex account -* Access to the Punjabi (pa) translation team -* Your assigned worklist -* The project Style Guide -* The project Glossary +## Translate -You do **not** need: +1. Open the project, choose Punjabi (`pa`) and open your resource in the editor. +2. Use the **Untranslated** filter to see the strings that still need translation. +3. Click a string. The editor shows the English source and a field for your Punjabi translation. +4. Press **Save**. Typing alone does not save the translation. Then go to the next string. -* A GitHub fork -* A local clone of the repository -* Git/GitHub knowledge -* Pull requests - -All translation work is done directly on Transifex. - ---- - -# 2. Sign In to Transifex - -Go to: - -https://app.transifex.com/ - -Sign in using the account that was added to the Punjabi translation team. - -After you are approved as a translator, the project should appear in your Transifex dashboard. Transifex's current translator documentation confirms that approved team members can access the project from their dashboard and begin translating. - ---- - -# 3. Open the Python Documentation Project - -From your Transifex dashboard: - -1. Find the Python Documentation project. -2. Open the project. -3. Select the **Punjabi (pa)** language. -4. Open the resource assigned to you. - -If you cannot see the Punjabi language or the assigned resource, **do not create another project or request another language**. Contact the coordinator. - ---- - -# 4. Open the Translation Editor - -Transifex provides a Web Editor where translators can work directly in their browser. - -The general path is: - -**Dashboard → Editor → Project → Resource → Punjabi (pa)** - -Transifex's current documentation describes this as the normal way to access a resource for translation. - ---- - -# 5. Select Your Assigned Resource - -For example, if your worklist says: - -`library-fileinput` - -select that resource. - -You will see the strings belonging to that resource. - -Do not start another resource unless the coordinator asks you to. - -This prevents multiple contributors from unknowingly working on the same resource. - ---- - -# 6. Find Untranslated Strings - -Once the resource is open, you will see the list of strings. - -Use the: - -**Untranslated** - -filter/tab. - -This shows strings that still need translation. Transifex provides filters such as **All**, **Untranslated**, and **Unreviewed** in the Web Editor. - ---- - -# 7. Translate a String - -Click an untranslated string. - -You will see: - -**Source** - -The original English text. - -**Translation** - -The field where you enter the Punjabi translation. - -Example: - -Source: - -`Input and Output` - -Translation: - -`ਇਨਪੁੱਟ ਅਤੇ ਆਉਟਪੁੱਟ` - -Enter your Punjabi translation in the translation field. - ---- - -# 8. Save the Translation - -After entering your translation, use the **Save** option in the editor. - -Do not assume that typing the translation automatically saves it. - -Transifex allows you to save an individual translation or save multiple drafts while working. - -After saving, move to the next untranslated string. - ---- - -# 9. Important: Preserve Code and Markup - -Python documentation contains technical formatting. - -You may encounter things such as: - -`Python` - -`print()` - -`os.path` - -`:class:` - -`:func:` - -`{name}` - -`%s` - -``` -.. code-block:: python +```text +Source: Input and Output +Translation: ਇਨਪੁੱਟ ਅਤੇ ਆਉਟਪੁੱਟ ``` -Do **not** translate or modify Python code, identifiers, Sphinx roles, placeholders, or markup unless the project guidelines specifically say otherwise. +## Keep code and markup -For example: +Python documentation contains code and Sphinx markup, such as `print()`, `os.path`, `:func:`, `{name}`, `%s` and `.. code-block:: python`. Do not translate or change them. Translate only the text around them. -Source: - -`Use the :func:\`print` function.` - -Do not change: - -`:func:\`print`` - -Translate the surrounding natural-language text while preserving the Sphinx markup. - ---- - -# 10. Follow the Project Glossary - -Before translating technical terms, check the project's Glossary. - -The glossary exists to keep terminology consistent across the entire Punjabi documentation. - -If you find a technical term that is not covered by the glossary and you are unsure how it should be translated: - -**Do not guess.** - -Ask the coordinator. - -A terminology decision can then be discussed and, if necessary, added to the glossary for future translators. - ---- - -# 11. Follow the Style Guide - -Always follow the project Style Guide when translating. - -Pay particular attention to: - -* Punjabi grammar -* Natural Punjabi wording -* Technical terminology -* English technical terms that should remain unchanged -* Code formatting -* Sphinx/RST markup -* Placeholders -* Consistency with existing translations - -The goal is not to translate English word-for-word. - -The goal is to produce **clear, natural, technically accurate Punjabi documentation**. - ---- - -# 12. If Transifex Shows a Warning or Error - -Transifex performs translation checks when translations are saved. - -You may see warnings or errors related to things such as: - -* Missing placeholders -* Incorrect formatting -* Variables -* Code/markup -* Numbers -* Other formatting requirements - -If Transifex reports an error, read the message carefully and correct the translation before saving again. Transifex documents these checks as part of the Web Editor workflow. - -If you don't understand the warning, contact the coordinator. - ---- - -# 13. When Have You Finished a Resource? - -A resource is considered ready for review when: - -* All untranslated strings have been translated. -* Your translations have been saved. -* Python code and identifiers are preserved. -* Placeholders are preserved. -* RST/Sphinx markup is preserved. -* You have checked the Style Guide and Glossary. -* You have informed the coordinator. - -Do not mark something as reviewed yourself unless you have been given reviewer permissions. - ---- - -# 14. What Happens After You Finish? - -Your workflow ends at Transifex. - -The process is: - -**Translator** - -↓ - -Translate on Transifex - -↓ - -Save translations - -↓ - -**Reviewer** - -↓ - -Review and approve - -↓ - -**GitHub Automation** - -↓ - -Fetch reviewed translations - -↓ - -Update the `python-docs-pa` repository - -↓ - -Eventually submitted upstream to CPython - -You do not need to manually upload your `.po` file to GitHub. - -You do not need to create a GitHub pull request. - ---- - -# 15. What If You Get Stuck? - -Please contact the coordinator if: - -* You cannot find the assigned resource. -* You cannot see the Punjabi language. -* You cannot edit a string. -* A translation check fails and you don't understand why. -* A technical term is difficult to translate. -* You are unsure whether something should remain in English. -* You are unsure whether markup should be translated. -* You think a string is already translated incorrectly. -* You encounter anything that looks like a Transifex configuration problem. - -**Do not create a new project, resource, language, or file to solve the problem yourself.** - ---- - -# 16. First Translation Checklist - -Before starting: - -* [ ] Transifex account is activated. -* [ ] Punjabi (pa) team access is confirmed. -* [ ] Assigned worklist is available. -* [ ] Style Guide has been read. -* [ ] Glossary has been read. +```text +Source: It uses the :func:`print` function. +Translation: ਇਹ :func:`print` ਫੰਕਸ਼ਨ ਦੀ ਵਰਤੋਂ ਕਰਦਾ ਹੈ। +``` -While translating: +The details are in [RULES.md](RULES.md). Before translating a technical term, check [GLOSSARY.md](GLOSSARY.md). If the term is not there, follow the order in [STYLE_GUIDE.md](STYLE_GUIDE.md), and ask a coordinator if you are unsure. We want clear, natural, technically accurate Punjabi, not a word-for-word copy. -* [ ] Use the Untranslated filter. -* [ ] Translate one string at a time. -* [ ] Save translations. -* [ ] Preserve code and markup. -* [ ] Preserve placeholders. -* [ ] Follow the glossary. -* [ ] Ask the coordinator when unsure. +## Warnings and errors -After finishing: +Transifex checks a translation when you save it, for example for missing placeholders or changed markup. Read the message and fix the translation before saving again. If you do not understand it, ask a coordinator. -* [ ] All strings in the assigned resource are translated. -* [ ] Saved translations have been checked. -* [ ] Coordinator has been notified. -* [ ] Wait for reviewer feedback. +## When you finish a resource ---- +- All strings are translated and saved. +- Code, placeholders and markup are unchanged. +- You followed the glossary and the style guide. -# Quick Workflow +Then tell a coordinator. A reviewer approves the translations. Please do not mark translations as reviewed yourself unless you have been given reviewer permission. -```text -Join Punjabi Team - ↓ -Open Transifex - ↓ -Open Python Documentation Project - ↓ -Select Punjabi (pa) - ↓ -Open Assigned Resource - ↓ -Filter → Untranslated - ↓ -Translate - ↓ -Save - ↓ -Complete Resource - ↓ -Notify Coordinator - ↓ -Reviewer Reviews - ↓ -Approved Translation - ↓ -GitHub Automation -``` +## Review ---- +Reviewers use the **Unreviewed** filter, check each string against the review points in [STYLE_GUIDE.md](STYLE_GUIDE.md), and mark it as reviewed. Ask a coordinator for reviewer permission. -## Important +## What happens next -**Your job is to translate on Transifex.** +Reviewed translations are pulled into this repository every day and published at . You do not need to upload `.po` files or open pull requests. -You do not need to worry about GitHub synchronization, `.po` files, commits, branches, or pull requests. +## If you get stuck -The project coordinators and automation handle the repository side after your translations have been reviewed. +Ask a coordinator or open an issue if, for example: -If you are unsure about anything, **ask before making a change that could affect terminology or formatting.** +- you cannot see Punjabi or your resource, or you cannot edit a string, +- a check fails and you do not understand why, +- you are unsure whether a word or markup should stay in English, +- an existing translation looks wrong, +- something looks like a Transifex configuration problem. -Welcome to the team, and thank you for helping bring Python documentation to Punjabi speakers! +Please do not create a new project, resource, language or file to solve a problem yourself. From 0f652d1ee6cd16a6089a15e7ac290ef6659c36ff Mon Sep 17 00:00:00 2001 From: Bhuvansh Kataria Date: Thu, 22 Oct 2026 17:48:30 +0000 Subject: [PATCH 07/12] Remove PROJECT_REPORT.md --- PROJECT_REPORT.md | 504 ---------------------------------------------- 1 file changed, 504 deletions(-) delete mode 100644 PROJECT_REPORT.md diff --git a/PROJECT_REPORT.md b/PROJECT_REPORT.md deleted file mode 100644 index 560baf2..0000000 --- a/PROJECT_REPORT.md +++ /dev/null @@ -1,504 +0,0 @@ -# 🐍 Python Docs Punjabi (pa) — Project Report - -**Project:** [python-docs-pa](https://github.com/BHUVANSH855/python-docs-pa) -**Coordinators:** -- Bhuvansh Kataria [@BHUVANSH855](https://github.com/BHUVANSH855) -- Mohit Yadav [@mohityadav8](https://github.com/mohityadav8) -- Yashraj Jangra [@Yashraj-Jangra](https://github.com/Yashraj-Jangra) -**Repository:** https://github.com/BHUVANSH855/python-docs-pa -**Translation Platform:** Python Documentation on Transifex -**Language:** Punjabi (pa) -**Translation Branch:** `3.15` -**Project Status:** Active -**Current Status:** Repository infrastructure established, contributor documentation modernized, validation pipeline operational, collaborative review workflow documented, and **7,668 verified translated strings** completed across multiple sections of the official Python documentation. - ---- - -# Project Overview - -## Project Evolution - -The project has evolved from an individual translation initiative into a collaborative community effort supported by multiple coordinators, standardized contributor documentation, automated validation, and an expanding review process. - -Recent development has focused on strengthening the project's infrastructure, documentation quality, contributor onboarding, and long-term maintainability alongside continued translation work. - -The [**python-docs-pa**](https://github.com/BHUVANSH855/python-docs-pa) project aims to translate the official Python documentation into Punjabi (Gurmukhi), making high-quality programming resources more accessible to Punjabi-speaking students, educators, and developers. - -The project follows the official Python Documentation Translation guidelines and emphasizes: - -- Consistent technical terminology -- High-quality translations -- Automated validation -- Sustainable contributor onboarding -- Long-term maintainability - -To support these goals, the repository includes comprehensive contributor documentation, standardized translation guidelines, automated validation workflows, and integration with the official Python Documentation Translation infrastructure. - ---- - -# Project Objectives - -The project focuses on five primary objectives: - -1. Translate the official Python documentation into Punjabi while preserving technical accuracy. -2. Maintain consistent terminology across all translated documentation. -3. Provide contributors with clear documentation, workflows, and quality standards. -4. Ensure translation quality through automated validation and review. -5. Build a sustainable Punjabi translation community within the Python ecosystem. - ---- - -# Major Milestones - -## Repository Modernization - -The repository has been significantly modernized to align with the recommendations of the Python Documentation Translation project. - -Completed work includes: - -- ✅ Comprehensive `README.md` -- ✅ Contributor-focused `CONTRIBUTING.md` -- ✅ Detailed `STYLE_GUIDE.md` -- ✅ Standardized `GLOSSARY.md` -- ✅ Updated `PROJECT_REPORT.md` -- ✅ GitHub Actions validation workflow -- ✅ Automated Transifex synchronization workflow -- ✅ Repository restructuring to match Python translation recommendations -- ✅ Language tag standardized to `pa` -- ✅ Repository renamed to `python-docs-pa` - ---- - -## Validation Infrastructure - -The project includes a complete validation pipeline to ensure translation quality before changes are committed. - -Implemented validation includes: - -- ✅ GNU gettext (`msgfmt`) validation -- ✅ `sphinx-lint` validation -- ✅ GitHub Actions automated validation -- ✅ CPython HTML documentation build -- ✅ Nitpicky (`-n`) documentation build -- ✅ Translation consistency checks - -This validation pipeline helps detect formatting issues, broken references, untranslated messages, and documentation build errors before contributions are merged. - ---- - -# Community Recognition - -## Python Documentation Translation Community - -The Punjabi translation project is now an officially recognized part of the Python Documentation Translation ecosystem. - -Major milestones include: - -- ✅ Introduced the project within the Python Documentation Translation community -- ✅ Received guidance and feedback from Stanislav Dzoba (Stan) and other translation contributors -- ✅ Dedicated Punjabi translation discussion channel established -- ✅ Official Punjabi translation coordinator added on Transifex -- ✅ Punjabi language officially listed in the Python Developer Guide Translation Coordinators (merged via PR #1843) - ---- - -## Transifex - -**Language Team:** Punjabi (`pa`) - -**Translation Platform:** Python Documentation on Transifex - -**Project Coordinators:** - -- Bhuvansh Kataria [@BHUVANSH855](https://github.com/BHUVANSH855) -- Mohit Yadav [@mohityadav8](https://github.com/mohityadav8) -- Yashraj Jangra [@Yashraj-Jangra](https://github.com/Yashraj-Jangra) - -The repository remains synchronized with the official Python Documentation Translation project through the established Transifex workflow. - -Project coordination is now shared across multiple coordinators to improve project continuity, contributor support, and long-term maintenance. - ---- - -# Translation Progress - -The Punjabi translation project has continued to expand beyond its initial milestones and now includes completed translations across multiple documentation areas. - -## Completed Documentation Areas - -| Documentation Area | Status | -|--------------------|--------| -| Tutorial Documentation (17/17 files) | ✅ Complete | -| Using Python Documentation (9/9 files) | ✅ Complete | -| Root Translation Files | ✅ Complete | -| `library/stdtypes.po` | ✅ Complete | -| `library/functions.po` | ✅ Complete | -| `library/exceptions.po` | ✅ Complete | -| `library/functools.po` | ✅ Complete | -| `library/string.po` | ✅ Complete | -| `howto/regex.po` | ✅ Complete | -| `howto/sorting.po` | ✅ Complete | - ---- - -## Translation Statistics - -| Metric | Value | -|--------|------:| -| Verified Translated Strings | **7,668** | -| Tutorial Files | 17 | -| Using Python Files | 9 | -| Completed Core Library Files | 5 | -| Completed HOWTO Files | 2 | -| Root Translation Files | 2 | -| Active Translation Branch | `3.15` | - ---- - -## Review Process - -Translation quality is maintained through two complementary processes: - -### Automated Validation - -Automated validation ensures that translations are syntactically correct and build successfully. - -This includes: - -- GNU gettext (`msgfmt`) -- `sphinx-lint` -- GitHub Actions -- CPython HTML documentation builds -- Nitpicky (`-n`) documentation builds - -### Human Review - -Human review focuses on translation quality rather than syntax. - -Reviewers verify: - -- Technical accuracy -- Terminology consistency -- Compliance with `GLOSSARY.md` -- Compliance with `STYLE_GUIDE.md` -- Natural Punjabi wording -- Preservation of reStructuredText and Sphinx markup - ---- - -## Validation Status - -All completed translations successfully pass the project's quality assurance pipeline. - -| Validation | Status | -|------------|--------| -| GNU gettext (`msgfmt`) | ✅ PASS | -| `sphinx-lint` | ✅ PASS | -| GitHub Actions | ✅ PASS | -| CPython HTML Build | ✅ PASS | -| Nitpicky (`-n`) Build | ✅ PASS | - -Current validation status: - -```text -0 validation errors -0 fuzzy messages -0 untranslated messages -``` - ---- - -## Translation Workflow - -Every completed translation follows the same quality workflow: - -```text -Translate in Transifex - │ - ▼ -Follow GLOSSARY.md - │ - ▼ -Follow STYLE_GUIDE.md - │ - ▼ -Peer Review - │ - ▼ -GitHub Actions Synchronization - │ - ▼ -GNU gettext Validation (`msgfmt`) - │ - ▼ -sphinx-lint - │ - ▼ -CPython HTML Build - │ - ▼ -Nitpicky (`-n`) Documentation Build -``` - -This workflow ensures consistent terminology, valid gettext syntax, successful documentation builds, and high-quality translations before publication. - ---- - -# Repository Development - -## Recent Documentation Improvements - -The repository documentation has recently been updated to better reflect the project's current development practices. - -These improvements include: - -- Clearly distinguishing automated validation from human translation review. -- Documenting the collaborative coordination model. -- Defining reviewer responsibilities and review guidelines. -- Standardizing contributor workflows across project documentation. -- Improving long-term maintainability of project documentation. - -The repository has evolved from an initial translation effort into a fully documented and validated Python Documentation Translation project. - -Major development milestones include: - -- Repository renamed to **[python-docs-pa](https://github.com/BHUVANSH855/python-docs-pa)** -- Repository structure aligned with Python Documentation Translation recommendations -- Language tag standardized to `pa` -- Automated GitHub Actions validation workflow implemented -- Automated Transifex synchronization workflow implemented -- Comprehensive contributor documentation completed -- Translation terminology standardized across the project -- Validation pipeline integrated into the development workflow - ---- - -# Documentation Assets - -The repository now provides complete contributor documentation covering every stage of the translation workflow. - -| Document | Purpose | -|----------|---------| -| `README.md` | Project overview, repository status, translation progress, setup instructions, and useful resources | -| `CONTRIBUTING.md` | Contribution workflow, validation process, quality standards, and pull request guidelines | -| `STYLE_GUIDE.md` | Translation conventions, formatting rules, terminology usage, and writing guidelines | -| `GLOSSARY.md` | Standardized Punjabi terminology for Python documentation | -| `PROJECT_REPORT.md` | Project history, milestones, translation progress, infrastructure, and future roadmap | - -Together, these documents provide contributors with a complete reference for participating in the Punjabi translation project. - ---- - -# Quality Assurance - -Translation quality is maintained through complementary automated validation and human review processes. Automated validation verifies technical correctness, while human review ensures linguistic quality, terminology consistency, and preservation of technical meaning. - -## Manual Quality Checks - -- Translation review -- Terminology consistency -- Style Guide compliance -- Glossary verification -- Formatting review -- Documentation review - ---- - -## Automated Validation - -The project currently validates translations using: - -- GNU gettext (`msgfmt`) -- `sphinx-lint` -- GitHub Actions -- CPython HTML documentation build -- Nitpicky (`-n`) documentation build -- Translation consistency checks - ---- - -## Common Validation Commands - -Validate an individual translation file: - -```bash -msgfmt --check FILE.po -``` - -Display translation statistics: - -```bash -msgfmt --statistics FILE.po -``` - -Validate every translation file in the repository: - -```powershell -Get-ChildItem -Recurse -Filter *.po | ForEach-Object { - msgfmt --check $_.FullName -} -``` - -Run `sphinx-lint`: - -```bash -sphinx-lint . -``` - -Build the translated documentation: - -```bash -python -m sphinx -b html -D language=pa Doc build/html-pa -``` - -Run a Nitpicky build: - -```bash -python -m sphinx -n -b html -D language=pa Doc build/html-pa -``` - ---- - -# Repository Infrastructure - -The repository now includes a comprehensive infrastructure supporting long-term maintenance, contributor onboarding, automated validation, and sustainable project growth. - -Implemented components include: - -- GitHub Actions automation -- Transifex synchronization -- Translation documentation -- Contributor onboarding resources -- Standardized glossary -- Style Guide -- Validation pipeline -- Quality assurance workflow - -This infrastructure enables contributors to produce consistent, high-quality translations while minimizing manual validation work. - ---- - -# Current Repository Status - -The Punjabi (`pa`) translation project is actively maintained and continues to expand its coverage of the official Python documentation. - -## Repository Summary - -| Item | Status | -|------|--------| -| Repository | ✅ Active | -| Translation Branch | `3.15` | -| GitHub Actions | ✅ Operational | -| Transifex Synchronization | ✅ Operational | -| Documentation | ✅ Modernized | -| Validation Pipeline | ✅ Fully Operational | -| Contributor Documentation | ✅ Complete | - ---- - -## Translation Summary - -| Metric | Value | -|--------|------:| -| Verified Translated Strings | **7,668** | -| Tutorial Documentation | ✅ Complete | -| Using Python Documentation | ✅ Complete | -| Core Library Files | ✅ Complete | -| HOWTO Files | ✅ Complete | -| Root Translation Files | ✅ Complete | - ---- - -## Validation Summary - -Current project status: - -```text -Working tree clean -Validation Status : PASS -GitHub Actions : PASS -msgfmt : PASS -sphinx-lint : PASS -HTML Build : PASS -Nitpicky Build : PASS -``` - -The repository is currently in a validated state, with all completed translations passing the project's quality assurance workflow. - ---- - -# Roadmap - -The Punjabi translation project will continue expanding coverage of the official Python documentation. - -## Short-Term Goals - -- Translate additional documentation sections. -- Maintain terminology consistency across all translations. -- Continue synchronizing completed translations with Transifex. -- Review and refine existing translations where needed. -- Support and onboard new contributors. - ---- - -## Medium-Term Goals - -- Expand coverage of the remaining Python documentation. -- Continue improving automation and validation workflows. -- Maintain documentation in line with Python translation recommendations. -- Strengthen collaboration with the Python Documentation Translation community. - ---- - -## Long-Term Vision - -The long-term objective is to provide a comprehensive, high-quality Punjabi translation of the official Python documentation. - -The project also aims to establish a sustainable contributor community that can maintain translations across future Python releases while following the quality standards of the Python Documentation Translation project. - ---- - -# Acknowledgements - -This project has benefited from guidance and support provided by members of the Python Documentation Translation community. - -Special thanks to: - -- Stanislav Dzoba (Stan) -- Python Documentation Translation contributors -- Python Documentation Translation community on Discord -- Python Software Foundation -- Everyone who contributes to improving Python documentation translations - -Their feedback and collaboration have helped shape both the translation workflow and the project's long-term direction. - ---- - -# Report Summary - -At the time of this report, the project has successfully established: - -- A standardized Punjabi terminology glossary. -- Comprehensive contributor documentation. -- Translation and style guidelines. -- Automated validation infrastructure. -- Automated Transifex synchronization. -- Official recognition within the Python Documentation Translation ecosystem. -- A growing collection of validated Punjabi translations totaling **7,668 verified translated strings**. -- A collaborative coordination team supporting long-term project sustainability. -- A documented review workflow complementing the automated validation pipeline. - -The repository is now well-positioned for continued expansion, contributor onboarding, long-term maintenance, and future Python release translations as part of the official Python Documentation Translation effort. - ---- - -# Report Information - -| Item | Value | -|------|-------| -| Report Version | **3.1** | -| Repository | `python-docs-pa` | -| Translation Language | Punjabi (`pa`) | -| Translation Branch | `3.15` | -| Status | Active | -| Last Updated | July 2026 | From e038f26b9adc3472d278e666431d402e1d3aa4b8 Mon Sep 17 00:00:00 2001 From: Bhuvansh Kataria Date: Thu, 22 Oct 2026 17:52:20 +0000 Subject: [PATCH 08/12] Update issue and PR templates and point to the PSF Code of Conduct --- .github/CODE_OF_CONDUCT.md | 82 +------------ .github/ISSUE_TEMPLATE/bug_report.md | 118 ++----------------- .github/ISSUE_TEMPLATE/config.yml | 20 ++-- .github/ISSUE_TEMPLATE/feature_request.md | 89 ++------------ .github/pull_request_template.md | 135 +++------------------- 5 files changed, 44 insertions(+), 400 deletions(-) diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index d712d9d..7e37b2d 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -1,83 +1,5 @@ # Code of Conduct -## Our Commitment +This project follows the [Python Software Foundation Code of Conduct](https://policies.python.org/python.org/code-of-conduct/). We expect everyone who takes part in this repository, in Transifex and in related discussions to follow it. -The Punjabi (`pa`) Python Documentation Translation Project is committed to providing a welcoming, respectful, and collaborative environment for everyone. We value constructive communication, mutual respect, and inclusive participation regardless of experience level, background, or identity. - -Our goal is to work together to produce accurate, consistent, and high-quality Punjabi translations of the official Python documentation. - ---- - -# Expected Behavior - -All contributors are expected to: - -- Be respectful and professional in all interactions. -- Provide constructive and respectful feedback. -- Welcome new contributors and help them learn the project workflow. -- Follow the project's `CONTRIBUTING.md`, `STYLE_GUIDE.md`, and `GLOSSARY.md`. -- Respect reviewer decisions and participate in discussions collaboratively. -- Focus discussions on improving translation quality and project consistency. - ---- - -# Unacceptable Behavior - -Examples of unacceptable behavior include: - -- Harassment, discrimination, or personal attacks. -- Offensive or abusive language. -- Trolling, intimidation, or deliberately disruptive behavior. -- Knowingly submitting misleading, malicious, or low-quality contributions. -- Public or private harassment of contributors or reviewers. - ---- - -# Translation Discussions - -Translation decisions should be based on: - -- Technical accuracy -- Consistency with the project glossary -- Compliance with the project style guide -- Natural and clear Punjabi -- Constructive discussion and consensus - -Disagreements are a normal part of collaborative translation and should always be handled respectfully. - ---- - -# Reporting Issues - -If you experience or observe behavior that violates this Code of Conduct, please open a private discussion with one of the project coordinators or create an issue if appropriate. - -Project Coordinators: - -- [@BHUVANSH855](https://github.com/BHUVANSH855) -- [@mohityadav8](https://github.com/mohityadav8) -- [@jangrayash1505](https://github.com/jangrayash1505) - ---- - -# Enforcement - -Project coordinators are responsible for maintaining a welcoming and productive community. They may remove inappropriate content, request changes to contributions, or take other appropriate actions when this Code of Conduct is violated. - ---- - -# Scope - -This Code of Conduct applies to all project spaces, including: - -- GitHub Issues -- Pull Requests -- Discussions -- Code Reviews -- Repository documentation -- Translation and review activities - ---- - -# Acknowledgements - -This Code of Conduct is inspired by established open source community practices and has been adapted for the Punjabi Python Documentation Translation Project. \ No newline at end of file +To report a violation, email the PSF Conduct Working Group at . You can also contact one of the coordinators listed in the [README](../README.en.md). diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 07b911c..b558f9a 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,124 +1,26 @@ --- -name: Bug Report -about: Report a bug, translation issue, validation error, or documentation problem in the Punjabi translation project. +name: Bug report +about: Report a translation error, a build problem or a problem in this repository. title: "[BUG] " labels: bug assignees: "" --- -# Bug Report +## What is wrong? -Thank you for helping improve the Punjabi (`pa`) translation of the Python documentation. + -Please provide as much information as possible to help us reproduce and resolve the issue. +## Where? ---- - -# Bug Summary - -Provide a clear and concise description of the issue. - -- - ---- - -# Category - -Select all that apply. - -- [ ] Translation error -- [ ] Terminology inconsistency -- [ ] Formatting / reStructuredText markup -- [ ] Broken cross-reference -- [ ] Validation failure -- [ ] GitHub Actions -- [ ] Documentation issue -- [ ] Repository tooling -- [ ] Other - ---- + -# Affected Documentation Area - -Examples: - -- Tutorial -- Using Python -- Standard Library -- HOWTO -- FAQ -- Reference -- C API -- What's New -- Repository documentation - -Documentation area: - -- - -Affected file(s): - -- `example.po` - ---- - -# Steps to Reproduce +## Steps to reproduce (if any) 1. 2. -3. - ---- - -# Expected Behavior - -Describe what you expected to happen. - -- - ---- - -# Actual Behavior - -Describe what actually happened. - -- - ---- - -# Validation Output (if applicable) - -Include any relevant validation output. - -```text -msgfmt -sphinx-lint -HTML build -Nitpicky build -GitHub Actions -``` - ---- - -# Environment - -- Operating System: -- Python Version: -- Sphinx Version: -- gettext Version: - ---- - -# Additional Information - -Include anything that may help reproduce or understand the issue. -Examples: +## Expected and actual result -- screenshots -- logs -- source English text -- suggested translation -- related issue or discussion + -- \ No newline at end of file +## Suggested fix (optional) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 76ce1fc..a1e4660 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,18 +1,18 @@ blank_issues_enabled: true contact_links: - - name: Python Documentation Translation Project + - name: Python documentation translations (Developer's Guide) url: https://devguide.python.org/documentation/translations/ - about: Learn about the official Python Documentation Translation project and its workflow. + about: How Python documentation translations work. - - name: Python Documentation Translation on Transifex + - name: Translate on Transifex url: https://explore.transifex.com/python-doc/python-newest/ - about: Access the official Python Documentation translation platform. + about: Translate and review the Punjabi (pa) strings. - - name: Project Documentation - url: https://github.com/BHUVANSH855/python-docs-pa#readme - about: Read the README, contribution guidelines, style guide, and glossary before opening an issue. + - name: README + url: https://github.com/python/python-docs-pa#readme + about: Start here to learn how this project works. - - name: Contribution Guidelines - url: https://github.com/BHUVANSH855/python-docs-pa/blob/3.15/CONTRIBUTING.md - about: Learn how to contribute translations, reviews, and repository improvements. \ No newline at end of file + - name: Contributing guide + url: https://github.com/python/python-docs-pa/blob/3.15/CONTRIBUTING.md + about: How to contribute translations, reviews and repository improvements. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 603b0f4..8f9578e 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,94 +1,21 @@ --- -name: Feature Request +name: Feature request about: Suggest an improvement for the Punjabi translation project. title: "[FEATURE] " labels: enhancement assignees: "" --- -# Feature Request +## What would you like to improve? -Thank you for helping improve the Punjabi (`pa`) translation of the Python documentation. + -Please describe your idea using the sections below. +## Why would it help? ---- - -# Feature Summary - -Provide a clear and concise description of the proposed improvement. - -- - ---- - -# Category - -Select all that apply. - -- [ ] Translation improvement -- [ ] Documentation improvement -- [ ] Glossary enhancement -- [ ] Style Guide improvement -- [ ] Contributor experience -- [ ] Validation workflow -- [ ] GitHub Actions / CI -- [ ] Repository tooling -- [ ] Automation -- [ ] Other + ---- - -# Motivation - -Why would this improvement benefit the project? - -Examples: - -- improve translation quality -- improve consistency -- simplify contributor workflow -- improve validation -- reduce maintenance effort - -- - ---- - -# Proposed Solution - -Describe your proposed solution. - -- - ---- - -# Alternatives Considered - -Describe any alternative approaches you considered. - -- - ---- - -# Additional Context - -Include any useful information such as: - -- examples -- screenshots -- references -- related discussions -- related issues -- relevant Python documentation - -- - ---- +## Proposed solution (optional) -# Contributor Checklist +## Anything else? -- [ ] This proposal aligns with the goals of the project. -- [ ] I searched for similar feature requests before creating this issue. -- [ ] I have provided enough information for discussion. -- [ ] I am willing to help implement this feature (optional). \ No newline at end of file + diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 217b207..e91b0bb 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,129 +1,22 @@ -# Pull Request +## Summary -Thank you for contributing to the Punjabi (`pa`) translation of the Python documentation. + -Please complete the sections below to help reviewers understand and validate your contribution. +## Type of change ---- - -# Summary - -Provide a brief description of your changes. - -- - ---- - -# Type of Change - -Please check all that apply. - -- [ ] New translation -- [ ] Translation improvement -- [ ] Translation review -- [ ] Terminology update -- [ ] Documentation update -- [ ] Contributor documentation -- [ ] Validation workflow -- [ ] GitHub Actions -- [ ] Repository maintenance -- [ ] Bug fix +- [ ] Guides or documentation +- [ ] Workflow, template or tooling +- [ ] Translation fix that cannot be made in Transifex - [ ] Other ---- - -# Documentation Area - -If this pull request modifies translations, specify the affected documentation area(s). - -Examples: - -- Tutorial -- Using Python -- Standard Library -- HOWTO -- FAQ -- Reference -- C API -- What's New -- Repository documentation - -Documentation area(s): - -- - ---- - -# Files Changed - -List the files modified in this pull request. - -- - ---- - -# Translation Details (if applicable) - -Language: - -- Punjabi (`pa`) - -Approximate number of translated strings: - -- - -Description of translated content: - -- - ---- - -# Validation - -Confirm that the following checks have been completed before submitting this pull request. - -- [ ] `msgfmt --check` -- [ ] `sphinx-lint` -- [ ] HTML documentation build completed successfully -- [ ] Nitpicky (`-n`) documentation build completed successfully (if applicable) -- [ ] No untranslated messages introduced -- [ ] No fuzzy messages introduced -- [ ] Terminology follows `GLOSSARY.md` -- [ ] Translation follows `STYLE_GUIDE.md` -- [ ] reStructuredText and Sphinx markup have been preserved - ---- - -# Review Notes - -Provide any information that may help reviewers. - -Examples: - -- terminology decisions -- intentionally untranslated text -- known limitations -- areas requiring additional review - -- - ---- - -# Related Issues or Discussions - -Reference any related issue, discussion, or Python Documentation Translation conversation. - -- - ---- +## Checks -# Contributor Checklist +- [ ] I have read `CONTRIBUTING.md` +- [ ] `msgfmt --check` passes for every `.po` file I changed +- [ ] I followed `STYLE_GUIDE.md` and `GLOSSARY.md` +- [ ] Code, placeholders and markup are unchanged +- [ ] This pull request is about one topic -Please confirm the following before requesting review. +## Related issues -- [ ] I have read `CONTRIBUTING.md`. -- [ ] I followed `STYLE_GUIDE.md`. -- [ ] I followed `GLOSSARY.md`. -- [ ] I validated my changes locally where applicable. -- [ ] I updated documentation where necessary. -- [ ] My contribution is ready for review. \ No newline at end of file + From a158beab38ffa9d7b70b36995420fd02cd733fcc Mon Sep 17 00:00:00 2001 From: Bhuvansh Date: Thu, 22 Oct 2026 23:42:30 +0530 Subject: [PATCH 09/12] Update README.md --- README.md | 41 +++++++++++++++++++++-------------------- 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index aa65c71..2e4b057 100644 --- a/README.md +++ b/README.md @@ -2,36 +2,37 @@ [English](README.en.md) -[Python ਦਸਤਾਵੇਜ਼ੀਕਰਨ](https://docs.python.org/) ਦਾ ਪੰਜਾਬੀ (ਗੁਰਮੁਖੀ, `pa`) ਅਨੁਵਾਦ। +ਇਹ [Python ਦਸਤਾਵੇਜ਼ੀਕਰਨ](https://docs.python.org/) ਦਾ ਪੰਜਾਬੀ (ਗੁਰਮੁਖੀ, `pa`) ਅਨੁਵਾਦ ਹੈ। -- **ਪੜ੍ਹੋ:** -- **ਪ੍ਰਗਤੀ:** (ਆਪਣੇ-ਆਪ ਅੱਪਡੇਟ ਹੁੰਦੀ ਹੈ) -- **ਅਨੁਵਾਦ ਅਤੇ ਸਮੀਖਿਆ:** [Transifex](https://explore.transifex.com/python-doc/python-newest/), ਭਾਸ਼ਾ ਪੰਜਾਬੀ (`pa`) -- **ਯੋਗਦਾਨ ਪਾਓ:** [CONTRIBUTING.md](CONTRIBUTING.md) ਵੇਖੋ (ਅੰਗਰੇਜ਼ੀ ਵਿੱਚ) +- ਪੜ੍ਹੋ: +- ਕਿੰਨਾ ਅਨੁਵਾਦ ਹੋ ਚੁੱਕਾ ਹੈ: +- ਅਨੁਵਾਦ ਅਤੇ ਸਮੀਖਿਆ: [Transifex](https://explore.transifex.com/python-doc/python-newest/) ਉੱਤੇ, ਭਾਸ਼ਾ ਪੰਜਾਬੀ (`pa`) +- ਯੋਗਦਾਨ ਪਾਉਣ ਲਈ: [CONTRIBUTING.md](CONTRIBUTING.md) ## ਅਨੁਵਾਦ ਕਿਵੇਂ ਕਰੀਏ? -1. Transifex ਉੱਤੇ [Python Documentation ਪ੍ਰੋਜੈਕਟ](https://explore.transifex.com/python-doc/python-newest/) ਖੋਲ੍ਹੋ। -2. "Join this project" ਬਟਨ ਦਬਾਓ। ਜੇ ਤੁਹਾਡਾ Transifex ਖਾਤਾ ਨਹੀਂ ਹੈ, ਤਾਂ ਬਣਾ ਲਓ। -3. ਪ੍ਰੋਜੈਕਟ ਦੇ ਪੰਨੇ ਉੱਤੇ ਪੰਜਾਬੀ (`pa`) ਚੁਣੋ। -4. ਕੋਆਰਡੀਨੇਟਰ ਵੱਲੋਂ ਮਨਜ਼ੂਰੀ ਮਿਲਣ ਤੋਂ ਬਾਅਦ ਕੋਈ ਰਿਸੋਰਸ ਚੁਣੋ ਅਤੇ [Transifex_Setup.md](Transifex_Setup.md) ਵਿੱਚ ਦਿੱਤੇ ਕਦਮਾਂ ਦੀ ਪਾਲਣਾ ਕਰੋ (ਅੰਗਰੇਜ਼ੀ ਵਿੱਚ)। -5. ਸਮੀਖਿਆਕਾਰ ਤੁਹਾਡੇ ਅਨੁਵਾਦਾਂ ਨੂੰ ਮਨਜ਼ੂਰ ਕਰਦੇ ਹਨ, ਅਤੇ ਰੋਜ਼ਾਨਾ ਸਮਕਾਲੀਕਰਨ ਨਾਲ ਉਹ ਇਸ ਰਿਪੋਜ਼ਟਰੀ ਵਿੱਚ ਆ ਜਾਂਦੇ ਹਨ। ਅਨੁਵਾਦਾਂ ਲਈ ਪੁੱਲ ਰਿਕਵੈਸਟ ਬਣਾਉਣ ਦੀ ਲੋੜ ਨਹੀਂ। +1. Transifex ਉੱਤੇ [Python Documentation ਪ੍ਰੋਜੈਕਟ](https://explore.transifex.com/python-doc/python-newest/) ਖੋਲ੍ਹੋ ਅਤੇ "Join this project" ਬਟਨ ਦਬਾਓ। ਜੇ ਤੁਹਾਡਾ ਖਾਤਾ ਨਹੀਂ ਹੈ, ਤਾਂ ਪਹਿਲਾਂ ਬਣਾ ਲਓ। +2. ਪ੍ਰੋਜੈਕਟ ਦੇ ਪੰਨੇ ਉੱਤੇ ਪੰਜਾਬੀ (`pa`) ਚੁਣੋ। ਕੋਆਰਡੀਨੇਟਰ ਤੁਹਾਡੀ ਬੇਨਤੀ ਮਨਜ਼ੂਰ ਕਰਨਗੇ। +3. ਮਨਜ਼ੂਰੀ ਮਿਲਣ ਤੋਂ ਬਾਅਦ ਕੋਈ ਰਿਸੋਰਸ ਚੁਣੋ ਅਤੇ ਅਨੁਵਾਦ ਸ਼ੁਰੂ ਕਰੋ। ਪੂਰੇ ਕਦਮ [Transifex_Setup.md](Transifex_Setup.md) ਵਿੱਚ ਹਨ। +4. ਫਿਰ ਸਮੀਖਿਆਕਾਰ ਤੁਹਾਡੇ ਅਨੁਵਾਦ ਦੀ ਜਾਂਚ ਕਰਦੇ ਹਨ। ਮਨਜ਼ੂਰ ਹੋ ਜਾਣ ਤੋਂ ਬਾਅਦ ਇਹ ਆਪਣੇ-ਆਪ ਇਸ ਰਿਪੋਜ਼ਟਰੀ ਵਿੱਚ ਆ ਜਾਂਦਾ ਹੈ, ਇਸ ਲਈ ਪੁੱਲ ਰਿਕਵੈਸਟ ਬਣਾਉਣ ਦੀ ਲੋੜ ਨਹੀਂ। -## ਇਹ ਕਿਵੇਂ ਕੰਮ ਕਰਦਾ ਹੈ? +## ਇਹ ਕਿਵੇਂ ਚੱਲਦਾ ਹੈ? -ਅਨੁਵਾਦ Transifex ਵਿੱਚ ਲਿਖੇ ਅਤੇ ਸਮੀਖਿਆ ਕੀਤੇ ਜਾਂਦੇ ਹਨ। ਇੱਕ GitHub Actions ਵਰਕਫਲੋ ਹਰ ਰੋਜ਼ **ਸਮੀਖਿਆ ਕੀਤੇ ਗਏ** ਅਨੁਵਾਦਾਂ ਨੂੰ ਇਸ ਰਿਪੋਜ਼ਟਰੀ ਦੀਆਂ `3.13`, `3.14` ਅਤੇ `3.15` ਬ੍ਰਾਂਚਾਂ ਵਿੱਚ ਲਿਆਉਂਦਾ ਹੈ। ਜਿਨ੍ਹਾਂ ਸਤਰਾਂ ਦਾ ਅਨੁਵਾਦ ਹੋ ਚੁੱਕਾ ਹੈ ਪਰ ਸਮੀਖਿਆ ਨਹੀਂ ਹੋਈ, ਉਹ ਸਮੀਖਿਆ ਹੋਣ ਤੱਕ Transifex ਵਿੱਚ ਹੀ ਰਹਿੰਦੀਆਂ ਹਨ, ਇਸ ਲਈ ਉਹ ਅਜੇ ਰਿਪੋਜ਼ਟਰੀ ਵਿੱਚ ਨਹੀਂ ਹਨ। +ਅਨੁਵਾਦ ਅਤੇ ਸਮੀਖਿਆ Transifex ਵਿੱਚ ਹੁੰਦੀ ਹੈ। ਹਰ ਰੋਜ਼ GitHub Actions ਦਾ ਇੱਕ ਵਰਕਫਲੋ ਸਮੀਖਿਆ ਹੋ ਚੁੱਕੇ ਅਨੁਵਾਦਾਂ ਨੂੰ ਇਸ ਰਿਪੋਜ਼ਟਰੀ ਦੀਆਂ `3.13`, `3.14` ਅਤੇ `3.15` ਬ੍ਰਾਂਚਾਂ ਵਿੱਚ ਲੈ ਆਉਂਦਾ ਹੈ। ਜਿਨ੍ਹਾਂ ਸਤਰਾਂ ਦੀ ਸਮੀਖਿਆ ਅਜੇ ਨਹੀਂ ਹੋਈ, ਉਹ Transifex ਵਿੱਚ ਹੀ ਰਹਿੰਦੀਆਂ ਹਨ। -ਹਰ ਪੁਸ਼ ਅਤੇ ਪੁੱਲ ਰਿਕਵੈਸਟ ਉੱਤੇ ਸਾਰੀਆਂ `.po` ਫ਼ਾਈਲਾਂ ਲਈ `msgfmt --check` ਚੱਲਦਾ ਹੈ। Python ਦਸਤਾਵੇਜ਼ੀਕਰਨ ਦੀ ਬਿਲਡ ਪੰਜਾਬੀ ਸਾਈਟ ਪ੍ਰਕਾਸ਼ਿਤ ਕਰਨ ਲਈ ਇਸ ਰਿਪੋਜ਼ਟਰੀ ਦੀ ਵਰਤੋਂ ਕਰਦੀ ਹੈ। +ਹਰ ਪੁਸ਼ ਅਤੇ ਪੁੱਲ ਰਿਕਵੈਸਟ ਉੱਤੇ ਸਾਰੀਆਂ `.po` ਫ਼ਾਈਲਾਂ ਦੀ `msgfmt --check` ਨਾਲ ਜਾਂਚ ਹੁੰਦੀ ਹੈ। ਪੰਜਾਬੀ ਸਾਈਟ Python ਦਸਤਾਵੇਜ਼ੀਕਰਨ ਦੀ ਬਿਲਡ ਰਾਹੀਂ ਇਸੇ ਰਿਪੋਜ਼ਟਰੀ ਤੋਂ ਬਣਦੀ ਹੈ। -## ਮਾਰਗਦਰਸ਼ਿਕਾਵਾਂ +## ਹੋਰ ਫ਼ਾਈਲਾਂ -| ਫ਼ਾਈਲ | ਵਿਸ਼ਾ | -|------|-------| -| [CONTRIBUTING.md](CONTRIBUTING.md) | ਯੋਗਦਾਨ ਕਿਵੇਂ ਪਾਉਣਾ ਹੈ, ਜਾਂਚ ਕਿਵੇਂ ਕਰਨੀ ਹੈ ਅਤੇ ਤਬਦੀਲੀਆਂ ਕਿਵੇਂ ਭੇਜਣੀਆਂ ਹਨ | +ਇਹ ਫ਼ਾਈਲਾਂ ਅੰਗਰੇਜ਼ੀ ਵਿੱਚ ਹਨ। + +| ਫ਼ਾਈਲ | ਇਸ ਵਿੱਚ ਕੀ ਹੈ | +|------|-------------| +| [CONTRIBUTING.md](CONTRIBUTING.md) | ਯੋਗਦਾਨ ਕਿਵੇਂ ਪਾਉਣਾ ਹੈ | | [Transifex_Setup.md](Transifex_Setup.md) | Transifex ਵਿੱਚ ਪਹਿਲੇ ਕਦਮ | -| [STYLE_GUIDE.md](STYLE_GUIDE.md) | ਅਨੁਵਾਦ ਦੀ ਸ਼ੈਲੀ ਅਤੇ ਨਿਯਮ | -| [RULES.md](RULES.md) | ਮਾਰਕਅੱਪ, ਪਲੇਸਹੋਲਡਰ ਅਤੇ `.po` ਫ਼ਾਈਲਾਂ ਲਈ ਵਿਸਤ੍ਰਿਤ ਨਿਯਮ | -| [GLOSSARY.md](GLOSSARY.md) | ਪਸੰਦੀਦਾ ਪੰਜਾਬੀ ਸ਼ਬਦਾਵਲੀ | +| [STYLE_GUIDE.md](STYLE_GUIDE.md) | ਅਨੁਵਾਦ ਦੀ ਭਾਸ਼ਾ ਅਤੇ ਸ਼ੈਲੀ | +| [RULES.md](RULES.md) | ਕੋਡ, ਮਾਰਕਅੱਪ ਅਤੇ `.po` ਫ਼ਾਈਲਾਂ ਦੇ ਨਿਯਮ | +| [GLOSSARY.md](GLOSSARY.md) | ਤਕਨੀਕੀ ਸ਼ਬਦਾਂ ਦੇ ਚੁਣੇ ਹੋਏ ਪੰਜਾਬੀ ਰੂਪ | ## ਕੋਆਰਡੀਨੇਟਰ From e501c0a86875f1c3590c7d711c34905574a05b8c Mon Sep 17 00:00:00 2001 From: Bhuvansh Date: Thu, 22 Oct 2026 23:43:03 +0530 Subject: [PATCH 10/12] Update README.en.md --- README.en.md | 43 +++++++++++++++++++++---------------------- 1 file changed, 21 insertions(+), 22 deletions(-) diff --git a/README.en.md b/README.en.md index 8dedd9a..dfa2525 100644 --- a/README.en.md +++ b/README.en.md @@ -1,37 +1,36 @@ -# Python Documentation Translation — Punjabi (ਪੰਜਾਬੀ) +# Punjabi translation of the Python documentation [ਪੰਜਾਬੀ](README.md) -Punjabi (Gurmukhi, `pa`) translation of the [Python documentation](https://docs.python.org/). +This is the Punjabi (Gurmukhi, `pa`) translation of the [Python documentation](https://docs.python.org/). -- **Read it:** -- **Progress:** (updated automatically) -- **Translate and review:** [Transifex](https://explore.transifex.com/python-doc/python-newest/), language Punjabi (`pa`) -- **Contribute:** see [CONTRIBUTING.md](CONTRIBUTING.md) +- Read it: +- See how much is translated: +- Translate and review: [Transifex](https://explore.transifex.com/python-doc/python-newest/), language Punjabi (`pa`) +- Contribute: [CONTRIBUTING.md](CONTRIBUTING.md) -## How do we translate? +## How to translate -1. Open the [Python Documentation project](https://explore.transifex.com/python-doc/python-newest/) on Transifex. -2. Click "Join this project". Create a Transifex account if you don't have one. -3. Select Punjabi (`pa`) on the project page. -4. After a coordinator approves your request, pick a resource and follow [Transifex_Setup.md](Transifex_Setup.md). -5. A reviewer approves your translations, and the daily sync brings them to this repository. You don't need to open a pull request for translations. +1. Open the [Python Documentation project](https://explore.transifex.com/python-doc/python-newest/) on Transifex and click "Join this project". You need a Transifex account, so create one if you don't have it yet. +2. Choose Punjabi (`pa`) on the project page. A coordinator will approve your request. +3. Pick a resource and start translating. [Transifex_Setup.md](Transifex_Setup.md) explains the steps. +4. A reviewer checks your translation. Once it's approved, it reaches this repository by itself, so you don't need a pull request. -## How does it work? +## How it works -Translations are written and reviewed in Transifex. A GitHub Actions workflow pulls the **reviewed** translations into this repository every day, into the `3.13`, `3.14` and `3.15` branches. Strings that are translated but not yet reviewed stay in Transifex until they are reviewed, so they are not in the repository yet. +We translate and review in Transifex. Every day a GitHub Actions workflow copies the reviewed translations into the `3.13`, `3.14` and `3.15` branches of this repository. Strings that are translated but not yet reviewed stay in Transifex. -Every push and pull request runs `msgfmt --check` on all `.po` files. The Python documentation build uses this repository to publish the Punjabi site. +Each push and pull request runs `msgfmt --check` on all `.po` files. The Python documentation build then uses this repository to publish the Punjabi site. -## Guides +## Other files -| File | Contents | -|------|----------| -| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute, validate and submit changes | +| File | What's in it | +|------|--------------| +| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute | | [Transifex_Setup.md](Transifex_Setup.md) | First steps in Transifex | -| [STYLE_GUIDE.md](STYLE_GUIDE.md) | Translation style and conventions | -| [RULES.md](RULES.md) | Detailed rules for markup, placeholders and `.po` files | -| [GLOSSARY.md](GLOSSARY.md) | Preferred Punjabi terminology | +| [STYLE_GUIDE.md](STYLE_GUIDE.md) | Language and style of the translation | +| [RULES.md](RULES.md) | Rules for code, markup and `.po` files | +| [GLOSSARY.md](GLOSSARY.md) | The agreed Punjabi technical terms | ## Coordinators From c20947d715349b0c0620b1828e7e4695cfc79de7 Mon Sep 17 00:00:00 2001 From: Bhuvansh Kataria Date: Thu, 22 Oct 2026 23:06:49 +0000 Subject: [PATCH 11/12] Make CONTRIBUTING, STYLE_GUIDE and RULES shorter and plainer --- CONTRIBUTING.md | 48 ++++++++++-------------------------------- RULES.md | 55 ++++++++++++++++++++++++------------------------- STYLE_GUIDE.md | 53 +++++++++++++++++++++-------------------------- 3 files changed, 62 insertions(+), 94 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e0e4d3b..4b718e9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,51 +1,25 @@ # Contributing -Thank you for helping translate the Python documentation into Punjabi. Typo fixes, new translations and reviews are all welcome. +Thanks for helping with the Punjabi translation of the Python documentation. There are three ways to help: translate or review strings, improve something in this repository, or report a problem. -## Ways to help +## Translating and reviewing -- **Translate or review** in [Transifex](https://explore.transifex.com/python-doc/python-newest/). Most of the work happens there, and you do not need a pull request. See [Transifex_Setup.md](Transifex_Setup.md). -- **Improve this repository** (guides, workflows, templates) with a pull request. See "Pull requests" below. -- **Report a problem** by opening an issue. +This happens in [Transifex](https://explore.transifex.com/python-doc/python-newest/), and you don't need a pull request for it. [Transifex_Setup.md](Transifex_Setup.md) shows how to start. Please read the [style guide](STYLE_GUIDE.md) and the [glossary](GLOSSARY.md) first, and look at [RULES.md](RULES.md) for what has to stay unchanged. If you review, follow the [review checklist](STYLE_GUIDE.md#review). -## Before you start +Reviewed translations are copied into this repository every day (the [README](README.en.md) explains how). That's why you shouldn't edit translations in the `.po` files here: the next sync can overwrite your change. If a `.po` file needs a fix that can't be made in Transifex, ask a coordinator. -Read [STYLE_GUIDE.md](STYLE_GUIDE.md) and [GLOSSARY.md](GLOSSARY.md). [RULES.md](RULES.md) has the detailed rules for markup, placeholders and `.po` files. Use the glossary terms, and keep code, identifiers and reStructuredText markup unchanged. +## Changing this repository -## Translations - -Translate and review in Transifex. Reviewed translations are pulled into this repository every day (see the [README](README.en.md)). - -Please do not edit translations in the `.po` files here. The daily sync takes them from Transifex, so direct edits can be overwritten. If a `.po` file needs a fix that cannot be made in Transifex, ask a coordinator. - -## Pull requests - -For changes to the guides, workflows or templates: +Pull requests are for the guides, the workflows and the templates. 1. Fork the repository, clone your fork and create a branch from `3.15`. -2. Make your change. Keep each pull request about one topic. -3. If you touched a `.po` file, run `msgfmt --check FILE.po`. -4. Push the branch and open a pull request against `3.15` with a clear description. - -## Checks - -CI runs `msgfmt --check` on every `.po` file for each push and pull request. It must pass. - -```bash -msgfmt --check FILE.po # required -sphinx-lint FILE.po # optional, for larger changes -``` - -## Reviewing - -A good review checks that: +2. Make your change. Keep each pull request to one topic. +3. If you changed a `.po` file, run `msgfmt --check FILE.po`. +4. Push the branch and open a pull request against `3.15`. Say what you changed and why. -- the meaning matches the English original, -- glossary terms are used, -- code, placeholders and markup are unchanged, -- the Punjabi reads naturally. +CI runs `msgfmt --check` on every `.po` file for each push and pull request, and it has to pass. For bigger changes, `sphinx-lint FILE.po` is a useful extra check. -## Getting help +## Questions and problems Open an issue, or ask one of the coordinators listed in the [README](README.en.md). diff --git a/RULES.md b/RULES.md index 2dc9491..842d44f 100644 --- a/RULES.md +++ b/RULES.md @@ -1,36 +1,33 @@ -# Rules for Markup, Code and `.po` Files +# Rules for Code, Markup and `.po` Files -These rules keep the translation valid and the documentation build working. For language and terminology, see [STYLE_GUIDE.md](STYLE_GUIDE.md) and [GLOSSARY.md](GLOSSARY.md). +These rules keep the documentation build working. For wording and terms, see [STYLE_GUIDE.md](STYLE_GUIDE.md) and [GLOSSARY.md](GLOSSARY.md). -We translate in Transifex (see [Transifex_Setup.md](Transifex_Setup.md)). The same rules apply to any `.po` file edited in this repository. +We translate in Transifex ([Transifex_Setup.md](Transifex_Setup.md)). The same rules apply if you edit a `.po` file here. -## Keep unchanged +## Leave these as they are -Keep these exactly as in the English source: +Copy the following from the English source without changes: -- Python keywords, built-in names, and names of modules, packages, classes, functions, methods, attributes, exceptions and constants -- Variable, argument and parameter names in code -- C API names, command names, environment variables, file and directory names -- PEP numbers and version numbers (`3.12`, `Python 3.15`) -- URLs, anchors and reference identifiers -- Placeholders such as `%s`, `%d`, `%(name)s`, `{}`, `{0}`, `{name}` and `` +- Python keywords, built-in names, and the names of modules, packages, classes, functions, methods, attributes, exceptions and constants +- variable, argument and parameter names in code +- C API names, commands, environment variables, and file and folder names +- PEP numbers and version numbers, like `3.12` or `Python 3.15` +- URLs, anchors and reference names +- placeholders like `%s`, `%d`, `%(name)s`, `{}`, `{0}`, `{name}` and `` -A name stays as it is even when a Punjabi spelling is possible. The words around a name are translated as usual. +A name stays as it is even if it could be written in Gurmukhi. Translate the words around it as usual. ## Code -- Do not change Python code: indentation, names, operators, imports, arguments or syntax. -- Do not change output, tracebacks or interactive sessions (the `>>>` and `...` prompts). -- Comments inside code may be translated if the meaning stays the same. -- Translate a string literal only when the English text clearly means the literal itself to be translated. It may also be data, output, an API value or an identifier. +Don't change Python code. That includes indentation, names, operators, imports and arguments. Output, tracebacks and interactive sessions (the `>>>` and `...` prompts) stay as they are too. + +You can translate comments inside code as long as the meaning stays the same. Translate a string literal only if the English text clearly means the literal itself to be translated. It may also be data, output, an API value or an identifier. ## reStructuredText and Sphinx markup -- Keep roles and their targets: `:func:`, `:class:`, `:meth:`, `:exc:`, `:mod:`, `:ref:`, `:pep:` and so on. -- To show a Punjabi label, use the form with an explicit target and translate only the label. The target between `<` and `>` stays as in the English. -- Keep directives and their arguments (`.. note::`, `.. warning::`, `.. versionadded:: 3.12`, `.. code-block:: python`). Translate only the text inside them. -- Keep inline markup: `*italic*`, `**bold**`, ` ``code`` `, backticks, underscores and escaped characters. -- Keep the structure of the text (line breaks, lists, tables) as in the source. +Keep roles and their targets as they are: `:func:`, `:class:`, `:meth:`, `:exc:`, `:mod:`, `:ref:`, `:pep:` and so on. + +If you want to show a Punjabi label, use the form with an explicit target and translate only the label. The target between `<` and `>` must stay as in the English. ```text English: :ref:`function` @@ -38,17 +35,19 @@ Wrong: :ref:`ਫੰਕਸ਼ਨ` Right: :ref:`ਫੰਕਸ਼ਨ ` ``` +Directives and their arguments also stay (`.. note::`, `.. warning::`, `.. versionadded:: 3.12`, `.. code-block:: python`). Translate only the text inside them. The same goes for inline markup such as `*italic*`, `**bold**` and ` ``code`` `. Keep the asterisks, backticks, underscores and escaped characters, and keep the structure of the text (line breaks, lists, tables). + ## `.po` files - Translate `msgstr` only. Never change `msgid`, the `#:` source references, the `#,` flags or the header. They come from the English source and are updated by the sync. -- If the English looks wrong, report it upstream. Do not fix it in the `.po` file. -- Keep the quoting, escapes and line breaks of multi-line strings valid. -- Do not add or remove `fuzzy` to skip a review. Check an uncertain translation and fix it first. -- Do not mix unrelated changes (formatting, metadata, other files) into a translation commit. +- If the English looks wrong, report it upstream. Don't fix it in the `.po` file. +- Keep the quotes, escapes and line breaks of multi-line strings valid. +- Don't add or remove `fuzzy` just to skip a review. Check an uncertain translation and fix it first. +- Don't mix unrelated changes (formatting, metadata, other files) into a translation commit. ## Checks -Before sending a change, run: +Before you send a change, run: ```bash msgfmt --check FILE.po @@ -57,6 +56,6 @@ git diff --check git diff ``` -The first two commands run `msgfmt` on one file and on all files. In `git diff`, confirm that no `msgid`, code, URL or placeholder changed and that there are no unrelated changes. +The first two run `msgfmt` on one file and on all files. In `git diff`, make sure that no `msgid`, code, URL or placeholder changed and that there are no unrelated changes. -Optional: run `sphinx-lint FILE.po`, or build the HTML documentation locally as described in the [Developer's Guide](https://devguide.python.org/documentation/translations/translating/). +You can also run `sphinx-lint FILE.po`, or build the HTML documentation locally as described in the [Developer's Guide](https://devguide.python.org/documentation/translations/translating/). diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 0439ab0..e5841b3 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -1,53 +1,48 @@ # Style Guide -This guide explains how we write the Punjabi (`pa`) translation of the Python documentation. Rules for markup, code, placeholders and `.po` files are in [RULES.md](RULES.md). Approved terms are in [GLOSSARY.md](GLOSSARY.md). +This guide is about how we write the Punjabi. The rules for code and markup are in [RULES.md](RULES.md), and the agreed terms are in [GLOSSARY.md](GLOSSARY.md). -## Principles +## The basics -- We translate the meaning, not the words. The Punjabi must say exactly what the English says. -- Technical accuracy comes first, then consistency, then style. -- We write clear, natural Punjabi (Gurmukhi) that a Punjabi-speaking programmer can read easily. -- We never change the meaning of a technical term. +Translate the meaning, not the words. The Punjabi should say what the English says, no more and no less. If two goals clash, accuracy wins over consistency, and consistency wins over style. -## Tone +Write simple, natural Gurmukhi that a Punjabi-speaking programmer can read without effort. Keep the formal, teaching tone of the English documentation. Avoid slang and regional dialect, and don't translate word for word when the result sounds odd. -- Formal, educational and clear, like the English documentation. -- No slang, no regional dialect, and no word-for-word translation that sounds unnatural. -- When in doubt: clarity over literal wording, consistency over personal preference, accuracy over style. +Never change the meaning of a technical term to make a sentence read better. -## Terminology +## Technical terms -For every technical term we follow this order: +For each term, go through these steps in order: -1. Use the term from [GLOSSARY.md](GLOSSARY.md). Do not create an alternative, and do not switch wording between files. -2. If the term is not listed, use a Punjabi word only when it has exactly the same technical meaning. -3. If there is no such Punjabi word, write the English word in Gurmukhi (transliteration). -4. Proper names, code and UI button labels stay in Latin script. So do the terms listed under "Terms Commonly Left Untranslated" in the glossary. +1. Use the term from the [glossary](GLOSSARY.md). Don't make up another one, and don't use two wordings in different files. +2. If the glossary doesn't have it, use a Punjabi word only if it means exactly the same thing. +3. If there is no such word, write the English word in Gurmukhi, for example ਰਿਪੋਜ਼ਟਰੀ. +4. Names, code and button labels stay in Latin script. So do the terms in the glossary's "Terms Commonly Left Untranslated" list. -Then add the new term to the glossary, as described under "Adding or Changing a Term" there. +After that, add the new term to the glossary. The steps are under "Adding or Changing a Term" there. -Please also: +A few more things to watch: -- Check the context. The same English word can be a technical term, an ordinary word or part of code. Never run a find-and-replace for a term over many files. -- Look at other Python translations (for example Chinese, Japanese or Korean) to see how they handle a term, but do not copy their wording. -- Do not rewrite an existing translation only because you prefer another wording. Change it only for a clear language, technical or consistency reason. +- Look at the context first. The same English word can be a technical term, an everyday word or part of code. For the same reason, never run a find and replace for a term across many files. +- Other Python translations (Chinese, Japanese, Korean and so on) show how they dealt with a term. Use them for ideas, but don't copy their wording. +- An existing translation isn't wrong just because you would write it differently. Change it only when it is unclear, technically wrong or inconsistent. ## Machine translation -We use machine translation only as a first draft. A person must read and correct every string. Watch for unnatural word order, wrong technical meanings, inconsistent terms and unexplained switching between English and Punjabi. +You can use it for a first draft, but a person has to read and fix every string. Typical problems are odd word order, wrong technical meaning, terms that don't match the glossary, and random jumps between English and Punjabi. ## Review -Reviewers in Transifex check each string for: +Before you approve a string in Transifex, check that: -- **Meaning:** it says the same as the English. -- **Terminology:** it uses the glossary term. -- **Punjabi:** it is natural, with correct grammar and spelling. -- **Markup:** roles, links, placeholders and code are intact (see [RULES.md](RULES.md)). +- the meaning is the same as the English, +- it uses the glossary term, +- the Punjabi is natural, with correct grammar and spelling, +- roles, links, placeholders and code are untouched (see [RULES.md](RULES.md)). -Only reviewed strings reach this repository, so approve a string only when it passes all four. +Only reviewed strings reach this repository, so approve a string only when all four are true. -## References +## Useful links - [Python Developer's Guide: Translating](https://devguide.python.org/documentation/translations/translating/) - [Python Developer's Guide: Style guide](https://devguide.python.org/documentation/style-guide/) From eec601b1707eac253e72cc5b04adfb3f19b6c5f1 Mon Sep 17 00:00:00 2001 From: Bhuvansh Kataria Date: Thu, 22 Oct 2026 23:07:49 +0000 Subject: [PATCH 12/12] Make Transifex_Setup.md and the glossary intro plainer --- GLOSSARY.md | 6 +++--- Transifex_Setup.md | 50 +++++++++++++++++++++------------------------- 2 files changed, 26 insertions(+), 30 deletions(-) diff --git a/GLOSSARY.md b/GLOSSARY.md index a9c13dc..f303150 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -1,11 +1,11 @@ # Punjabi (pa) Python Docs Glossary -Preferred Punjabi terms for translating the Python documentation. Use them so translations stay consistent. For writing style, see `STYLE_GUIDE.md`. +These are the Punjabi terms we use when translating the Python documentation, so that the translation stays consistent. For how we write, see `STYLE_GUIDE.md`. # How to Use This Glossary -- Use the listed term whenever one exists. Do not introduce variants. -- For a term that is not listed, reuse the wording from existing translations. If there is none, use one wording consistently in the file and propose it as described under "Adding or Changing a Term". +- If a term is listed here, use it. Don't use a variant. +- If it isn't listed, reuse the wording from existing translations. If there is none, follow the steps under "Technical terms" in `STYLE_GUIDE.md` and propose the term as described under "Adding or Changing a Term" below. - Never translate function, module, class and exception names, directives, roles, placeholders or code. --- diff --git a/Transifex_Setup.md b/Transifex_Setup.md index 129d09b..df83420 100644 --- a/Transifex_Setup.md +++ b/Transifex_Setup.md @@ -1,67 +1,63 @@ # Transifex Guide -This guide helps new translators get started in Transifex. Translating and reviewing happen there, so you do not need Git, a fork or a pull request. +This page shows new translators how to start in Transifex. You do all the work there, so you don't need Git, a fork or a pull request. ## Join the project 1. Create a Transifex account, or sign in, at . -2. Open the [Python Documentation project](https://explore.transifex.com/python-doc/python-newest/) and press "Join this project". -3. Choose Punjabi (`pa`) and wait for a coordinator to approve you. The coordinators are listed in the [README](README.en.md). -4. Ask a coordinator which resource to start with, so that two people do not work on the same one. A resource is one documentation file, for example `library-fileinput`. +2. Open the [Python Documentation project](https://explore.transifex.com/python-doc/python-newest/) and click "Join this project". +3. Choose Punjabi (`pa`). A coordinator will approve your request. The coordinators are listed in the [README](README.en.md). +4. Ask a coordinator which resource to start with, so that two people don't work on the same one. A resource is one documentation file, for example `library-fileinput`. -If you cannot see Punjabi or your resource, ask a coordinator. Please do not create another project, language or resource. +If you can't see Punjabi or your resource, ask a coordinator. Please don't create another project, language or resource. ## Translate 1. Open the project, choose Punjabi (`pa`) and open your resource in the editor. -2. Use the **Untranslated** filter to see the strings that still need translation. -3. Click a string. The editor shows the English source and a field for your Punjabi translation. -4. Press **Save**. Typing alone does not save the translation. Then go to the next string. +2. Use the **Untranslated** filter to see what still needs translating. +3. Click a string. The editor shows the English text and a field for your Punjabi translation. +4. Click **Save**. Typing alone doesn't save it. Then move on to the next string. ```text Source: Input and Output Translation: ਇਨਪੁੱਟ ਅਤੇ ਆਉਟਪੁੱਟ ``` -## Keep code and markup +## Code and markup -Python documentation contains code and Sphinx markup, such as `print()`, `os.path`, `:func:`, `{name}`, `%s` and `.. code-block:: python`. Do not translate or change them. Translate only the text around them. +The documentation contains code and Sphinx markup, like `print()`, `os.path`, `:func:`, `{name}`, `%s` and `.. code-block:: python`. Leave these as they are and translate only the text around them. ```text Source: It uses the :func:`print` function. Translation: ਇਹ :func:`print` ਫੰਕਸ਼ਨ ਦੀ ਵਰਤੋਂ ਕਰਦਾ ਹੈ। ``` -The details are in [RULES.md](RULES.md). Before translating a technical term, check [GLOSSARY.md](GLOSSARY.md). If the term is not there, follow the order in [STYLE_GUIDE.md](STYLE_GUIDE.md), and ask a coordinator if you are unsure. We want clear, natural, technically accurate Punjabi, not a word-for-word copy. +[RULES.md](RULES.md) has the details. Before you translate a technical term, look it up in [GLOSSARY.md](GLOSSARY.md). If it isn't there, follow the steps in [STYLE_GUIDE.md](STYLE_GUIDE.md), and ask a coordinator if you're still unsure. We want Punjabi that is clear and correct, not a word-for-word copy. -## Warnings and errors +## Warnings -Transifex checks a translation when you save it, for example for missing placeholders or changed markup. Read the message and fix the translation before saving again. If you do not understand it, ask a coordinator. +Transifex checks a translation when you save it, for example for missing placeholders or changed markup. Read the message and fix the translation before you save it again. If you don't understand the message, ask a coordinator. ## When you finish a resource -- All strings are translated and saved. -- Code, placeholders and markup are unchanged. -- You followed the glossary and the style guide. +Make sure that all strings are translated and saved, that code, placeholders and markup are unchanged, and that you followed the glossary and the style guide. Then tell a coordinator. A reviewer will approve your translations. Don't mark them as reviewed yourself unless you have reviewer permission. -Then tell a coordinator. A reviewer approves the translations. Please do not mark translations as reviewed yourself unless you have been given reviewer permission. +## Reviewing -## Review - -Reviewers use the **Unreviewed** filter, check each string against the review points in [STYLE_GUIDE.md](STYLE_GUIDE.md), and mark it as reviewed. Ask a coordinator for reviewer permission. +Reviewers use the **Unreviewed** filter, check each string against the [review checklist](STYLE_GUIDE.md#review) and mark it as reviewed. Ask a coordinator for reviewer permission. ## What happens next -Reviewed translations are pulled into this repository every day and published at . You do not need to upload `.po` files or open pull requests. +Reviewed translations are copied into this repository every day and published at . You don't need to upload `.po` files or open pull requests. ## If you get stuck -Ask a coordinator or open an issue if, for example: +Ask a coordinator or open an issue if: -- you cannot see Punjabi or your resource, or you cannot edit a string, -- a check fails and you do not understand why, -- you are unsure whether a word or markup should stay in English, +- you can't see Punjabi or your resource, or you can't edit a string, +- a check fails and you don't know why, +- you're not sure if a word or markup should stay in English, - an existing translation looks wrong, -- something looks like a Transifex configuration problem. +- something looks like a Transifex setup problem. -Please do not create a new project, resource, language or file to solve a problem yourself. +Please don't create a new project, resource, language or file to fix it yourself.