This guide defines translation conventions for the Punjabi (Gurmukhi) translation of the Python documentation.

All contributors should follow these rules to ensure consistency, technical accuracy, and long-term maintainability across the project.

Current verified milestones:

• ✅ Complete Tutorial documentation translated (17/17 files)
• ✅ bugs.po fully translated
• ✅ glossary.po fully translated
• ✅ library/functions.po fully translated
• ✅ library/stdtypes.po fully translated
• ✅ library/functools.po fully translated
• ✅ library/exceptions.po fully translated
• ✅ Repository-wide validation passing
• ✅ GitHub Actions validation workflow active
• ✅ Transifex upload completed
• ✅ Language tag standardized to pa
• ✅ More than 4,000 documentation messages translated

Contributors should review previously completed translations before introducing new terminology or translation patterns.

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

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:

Clear
Accurate
Consistent
Natural

Poor translation:

Word-for-word
Ambiguous
Inconsistent
Artificial sounding

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

print
len
range
list
dict
tuple
set
frozenset
bytes
bytearray
str
int
float
complex
bool
object
type
property
classmethod
staticmethod

Exception
ValueError
TypeError
KeyError
IndexError
ImportError
RuntimeError
AttributeError
StopIteration

os
sys
json
pathlib
re
typing
collections
itertools
asyncio

These identifiers must remain unchanged.

Never translate variable names.

Examples:

x
y
count
index
user_name
my_list
self
cls

Correct:

count = 5

Incorrect:

ਗਿਣਤੀ = 5

Never modify:

msgid
#: source references
#, flags

Translate only:

msgstr

Placeholders must remain exactly unchanged.

Examples:

%s
%d
%i
%r
%f
%s%.*f

{}
{0}
{name}
{value}

%(name)s
%(count)d

Correct:

"%s ਆਈਟਮ ਮਿਲੇ"

Incorrect:

"%d ਆਈਟਮ ਮਿਲੇ"

unless the original uses %d.

Never modify reStructuredText roles.

Examples:

:func:`print`
:class:`list`
:class:`dict`
:mod:`os`
:meth:`append`
:attr:`name`
:exc:`ValueError`
:term:`iterator`
:ref:`section`

Translate only surrounding text.

Correct:

ਇਹ :func:`print` ਫੰਕਸ਼ਨ ਦੀ ਵਰਤੋਂ ਕਰਦਾ ਹੈ।

Incorrect:

ਇਹ :func:`ਛਾਪੋ` ਫੰਕਸ਼ਨ ਦੀ ਵਰਤੋਂ ਕਰਦਾ ਹੈ।

Keep inline markup unchanged.

Examples:

*italic*
**bold**
``code``

Do not modify formatting syntax.

Never modify Sphinx directives.

Examples:

.. note::
.. warning::
.. important::
.. tip::
.. versionadded::
.. versionchanged::
.. deprecated::
.. code-block:: python

Translate the directive content only.

Translate:

• Comments
• Explanatory text

Do not translate:

• Python code
• Keywords
• Identifiers
• Module names
• Function names
• Class names
• Exception names

Example:

# Calculate the square of a number
x = 5
print(x * x)

Only the comment may be translated.

Examples:

>>> x = 5
>>> print(x)
5

Do not translate:

• Code
• Output
• Tracebacks
• Exception names

Translate only surrounding explanations.

Never translate URLs.

Examples:

https://docs.python.org/
https://devguide.python.org/
https://github.com/python/cpython

Never modify version numbers.

Examples:

Python 3.13
Python 3.14
Changed in version 3.12
Deprecated since version 3.11

Translate surrounding text only.

Some technical terms should remain in English.

Examples:

Python
API
Unicode
JSON
XML
HTML
HTTP
URL
ASCII
UTF-8

Use glossary-approved Punjabi translations where available.

Always consult:

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.

For large files, translations should be performed in reviewable batches.

Recommended format:

Replace this block:

msgid "example"
msgstr ""

With:

msgid "example"
msgstr "ਉਦਾਹਰਨ"

For multiple consecutive entries:

Replace these consecutive blocks:
...

This workflow was successfully used for:

library/functions.po
library/stdtypes.po
library/functools.po
library/exceptions.po

and is recommended for future large files.

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.

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.
• Complete a manual review.

Validate a file:

msgfmt --check FILE.po

Show statistics:

msgfmt --statistics FILE.po

Show untranslated entries:

msgattrib --untranslated FILE.po

Show translated entries:

msgattrib --translated FILE.po

Validate all files:

Get-ChildItem -Recurse -Filter *.po | ForEach-Object {
    msgfmt --check $_.FullName
}

A completed file should have:

0 validation errors
0 fuzzy entries
0 untranslated messages

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.

Use descriptive commit messages.

Examples:

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

Major validated milestones should be tagged.

Examples:

tutorial-phase-1
tutorial-complete
v1.0-tutorial-complete
library-functions-complete
library-stdtypes-complete
library-functools-complete
library-exceptions-complete

Tags should represent completed, validated work.

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

Documentation should be:

• Formal
• Educational
• Clear
• Consistent
• Professional

Avoid:

• Slang
• Regional dialect variations
• Excessively literal translations
• Unnecessary English/Punjabi mixing

When in doubt:

Clarity > Literal Translation
Consistency > Personal Preference
Accuracy > Style

Every translation should satisfy three requirements:

Technically correct
Consistent with the project glossary
Natural for Punjabi readers

If any of these are missing, revise the translation before committing.