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

• Translate meaning, not individual words.
• Use clear and natural Punjabi (Gurmukhi).
• Maintain consistency across all files.
• Follow terminology defined in GLOSSARY.md.
• Preserve technical accuracy at all times.

The Python Tutorial section has been fully translated and validated.

Contributors should follow the established terminology and translation patterns already present in completed tutorial files before introducing new wording.

if
else
elif
for
while
class
def
return
import
from
try
except
finally
raise
pass
with
yield
lambda
and
or
not

x
y
count
user_name
my_list
self
cls

Examples:

print
len
range
ValueError
TypeError
Exception
list
dict
tuple
set
os
sys
json

These names must remain unchanged.

Never modify:

msgid
#: source references

Translate only:

msgstr

Preserve placeholders exactly as written:

%s
%d
%r
%s%.*f
{}
{0}
{name}

These placeholders must remain unchanged.

Never modify Sphinx or reStructuredText markup.

Examples:

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

Translate only surrounding explanatory text.

Keep inline markup exactly as written.

Examples:

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

Correct:

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

Incorrect:

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

Preserve directives exactly as written.

Examples:

.. note::
.. warning::
.. code-block:: python
.. versionadded::
.. versionchanged::

Translate the content inside notes and warnings, but never change the directive itself.

Translate:

• Comments
• User-facing explanatory text

Do not translate:

• Python keywords
• Variable names
• Function names
• Class names
• Module names
• Exception names
• Example code behavior

Example:

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

Only the comment may be translated.

For Python interactive examples:

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

Do not translate:

• Python code
• Output values
• Tracebacks
• Exception names

Only translate surrounding explanatory text.

Leave all URLs unchanged.

Examples:

https://docs.python.org/
https://devguide.python.org/

When a technical term is widely recognized in English, it may remain untranslated.

Examples:

Python
module
package
API
Unicode
JSON
XML
HTML
HTTP
URL

Prefer glossary-approved translations for concepts that already have established Punjabi equivalents.

Always consult GLOSSARY.md before introducing new translations.

When a technical term already exists in the glossary, use the glossary version consistently throughout the project.

• Use the same translation for the same term everywhere.
• Preserve punctuation when possible.
• Preserve formatting and inline markup.
• Keep examples technically correct after translation.
• Reuse terminology from previously completed files whenever possible.

Machine translation may be used only as a drafting aid.

Every translated string must be manually reviewed for:

• Accuracy
• Terminology consistency
• Natural Punjabi wording
• Correct markup preservation

Contributors are responsible for the final quality of submitted translations.

Before committing a translation:

• Verify all msgids have corresponding translations.
• Verify no markup has been altered.
• Verify code examples remain executable.
• Verify placeholders remain unchanged.
• Verify glossary terminology is used consistently.
• Verify formatting matches the source file.
• Complete a manual review of translated content.

Run:

msgfmt --check tutorial/FILENAME.po

Check progress:

msgfmt --statistics tutorial/FILENAME.po

Review untranslated entries:

msgattrib --untranslated tutorial/FILENAME.po

Validate all tutorial files:

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

A translation is considered complete only when:

• 0 validation errors
• 0 untranslated messages
• Consistent glossary usage
• Manual review completed

Use descriptive commit messages.

Examples:

Translate tutorial/classes.po to Punjabi
Translate tutorial/stdlib.po to Punjabi
Translate tutorial/stdlib2.po to Punjabi (100%)
Update glossary terminology
Update README after tutorial completion

Major project milestones should be tagged.

Examples:

tutorial-phase-1
tutorial-complete

Tags should represent validated translation milestones rather than work-in-progress states.

• Use formal Punjabi.
• Keep explanations clear and educational.
• Prefer consistency over stylistic variation.
• Follow Python documentation writing conventions whenever possible.
• Prioritize clarity and technical accuracy over literal word-for-word translation.