Make CONTRIBUTING, STYLE_GUIDE and RULES shorter and plainer

Author: BHUVANSH855

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).
 

RULES.md

@@ -1,54 +1,53 @@
-# 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 `<filename>`
+- 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 `<filename>`
 
-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`
 Wrong:   :ref:`ਫੰਕਸ਼ਨ`
 Right:   :ref:`ਫੰਕਸ਼ਨ <function>`
 ```
 
+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/).

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/)