Commit 716fc2e

ترجمه‌ها دیگر روی Transifex انجام نمی‌شوند و مستقیماً از طریق پول‌ریکوئست در همین ریپازیتوری مدیریت می‌شوند. فایل‌های `.po` هر کدام به بخشی از مستندات پایتون (مثل `tutorial/`، `library/` یا `c-api/`) مربوط‌اند و می‌توانید هرکدام را جداگانه ویرایش و پول‌ریکوئست بزنید.

خلاصه فرایند مشارکت:

1. ریپازیتوری را فورک و کلون کنید.

2. فایل `.po` مورد نظر را با [Poedit](https://poedit.net/) باز کنید (رشته‌های ترجمه‌نشده یا fuzzy را می‌توانید از پنل فیلتر پیدا کنید).

3. متن انگلیسی (`msgid`) را ترجمه کنید و در بخش ترجمه (`msgstr`) وارد کنید.

4. نشانه‌گذاری‌های Sphinx مثل `` :class:`int` ``، `` :func:`repr` ``، `` ``code`` ``، و جای‌گزین‌هایی مثل `%s` یا `{name}` را دقیقاً بدون تغییر نگه دارید؛ فقط متن اطراف آن‌ها ترجمه می‌شود.

5. پیش از ارسال پول‌ریکوئست، بررسی کنید فایل‌ها مشکلی ندارند:

msgfmt --check your_file.po

python3 scripts/check_markup.py your_file.po

6. پول‌ریکوئست را باز کنید — روی هر پول‌ریکوئست به‌صورت خودکار بررسی‌های لازم اجرا می‌شود.

برای دیدن این‌که کدام فایل‌ها هنوز نیاز به ترجمه دارند و چقدر از هرکدام باقی مانده:

python3 scripts/translation_status.py --only-incomplete

راهنمای کامل‌تر مشارکت (شامل نحوه‌ی همگام‌سازی با نسخه‌های جدید پایتون و اسکریپت‌های موجود در `scripts/`) در [RESOURCE.md](RESOURCE.md) موجود است.

import re

import sys

from pathlib import Path

PATTERNS = [

("sphinx role", re.compile(r":(?:\w+:)?[\w.-]+:`.*?`")),

("literal/code span", re.compile(r"``.*?``")),

("substitution ref", re.compile(r"\|[\w.-]+\|")),

("percent placeholder", re.compile(r"%\(\w+\)[a-zA-Z]|%[a-zA-Z]")),

("brace placeholder", re.compile(r"\{[^{}\s]*\}")),

]

def unescape(raw: str) -> str:

"""Undo PO string escaping (raw includes the surrounding quotes)."""

inner = raw[1:-1]

out = []

i = 0

while i < len(inner):

c = inner[i]

if c == "\\" and i + 1 < len(inner):

nxt = inner[i + 1]

out.append({"n": "\n", "t": "\t", '"': '"', "\\": "\\"}.get(nxt, nxt))

i += 2

else:

out.append(c)

i += 1

return "".join(out)

def parse_po(path: Path):

"""Yield (location, flags, msgid, msgstr) for each entry in a .po file."""

lines = path.read_text(encoding="utf-8").splitlines()

i, n = 0, len(lines)

def read_block(keyword_line):

nonlocal i

parts = [unescape(keyword_line.split(" ", 1)[1].strip())]

i += 1

while i < n and lines[i].strip().startswith('"'):

parts.append(unescape(lines[i].strip()))

i += 1

return "".join(parts)

while i < n:

location, flags = "", []

while i < n and lines[i].startswith("#"):

if lines[i].startswith("#:"):

location = lines[i][2:].strip()

elif lines[i].startswith("#,"):

flags = [f.strip() for f in lines[i][2:].split(",")]

i += 1

if i >= n or not lines[i].startswith("msgid"):

i += 1

continue

msgid = read_block(lines[i])

msgid_plural = read_block(lines[i]) if i < n and lines[i].startswith("msgid_plural") else None

if i < n and lines[i].startswith("msgstr["):

msgstrs = {}

while i < n and lines[i].startswith("msgstr["):

idx = int(lines[i][7:lines[i].index("]")])

msgstrs[idx] = read_block(lines[i])

yield location, flags, msgid, msgstrs.get(0, "")

if msgid_plural is not None and 1 in msgstrs:

yield location, flags, msgid_plural, msgstrs[1]

continue

msgstr = read_block(lines[i]) if i < n and lines[i].startswith("msgstr") else ""

yield location, flags, msgid, msgstr

def check_file(path: Path) -> int:

problems = 0

for location, flags, msgid, msgstr in parse_po(path):

if not msgid or not msgstr:

continue # header entry or still untranslated

for label, pattern in PATTERNS:

expected = pattern.findall(msgid)

if not expected:

continue

missing = [tok for tok in expected if tok not in msgstr]

if missing:

problems += 1

loc = f" ({location})" if location else ""

tag = " [fuzzy]" if "fuzzy" in flags else ""

print(f"{path}{loc}{tag}: missing {label}: {missing}")

print(f" msgid : {msgid[:100]}")

print(f" msgstr: {msgstr[:100]}")

return problems

def main():

if len(sys.argv) < 2:

print(__doc__)

sys.exit(1)

files = []

for arg in sys.argv[1:]:

p = Path(arg)

files.extend(sorted(p.rglob("*.po"))) if p.is_dir() else files.append(p)

total = sum(check_file(f) for f in files)

if total:

print(f"\n{total} markup mismatch(es) found.")

sys.exit(1)

print("No markup mismatches found.")

if __name__ == "__main__":

main()

import argparse

import sys

from pathlib import Path

def unescape(raw: str) -> str:

"""Undo PO string escaping (raw includes the surrounding quotes)."""

inner = raw[1:-1]

out = []

i = 0

while i < len(inner):

c = inner[i]

if c == "\\" and i + 1 < len(inner):

nxt = inner[i + 1]

out.append({"n": "\n", "t": "\t", '"': '"', "\\": "\\"}.get(nxt, nxt))

i += 2

else:

out.append(c)

i += 1

return "".join(out)

def parse_po_entries(path: Path):

"""Yield (flags, msgid, msgstrs) for each entry in a .po file."""

lines = path.read_text(encoding="utf-8").splitlines()

i, n = 0, len(lines)

def read_block(keyword_line):

nonlocal i

parts = [unescape(keyword_line.split(" ", 1)[1].strip())]

i += 1

while i < n and lines[i].strip().startswith('"'):

parts.append(unescape(lines[i].strip()))

i += 1

return "".join(parts)

while i < n:

flags = []

while i < n and lines[i].startswith("#"):

if lines[i].startswith("#,"):

flags = [f.strip() for f in lines[i][2:].split(",")]

i += 1

if i >= n or not lines[i].startswith("msgid"):

i += 1

continue

msgid = read_block(lines[i])

if i < n and lines[i].startswith("msgid_plural"):

read_block(lines[i]) # plural source not needed for counting

msgstrs = []

if i < n and lines[i].startswith("msgstr["):

while i < n and lines[i].startswith("msgstr["):

msgstrs.append(read_block(lines[i]))

elif i < n and lines[i].startswith("msgstr"):

msgstrs.append(read_block(lines[i]))

yield flags, msgid, msgstrs

def file_stats(path: Path):

translated = fuzzy = untranslated = 0

for flags, msgid, msgstrs in parse_po_entries(path):

if not msgid:

continue # header entry

if "fuzzy" in flags:

fuzzy += 1

elif any(m.strip() for m in msgstrs):

translated += 1

else:

untranslated += 1

return translated, fuzzy, untranslated

def collect_files(paths):

files = []

for arg in paths:

p = Path(arg)

if p.is_dir():

files.extend(sorted(p.rglob("*.po")))

elif p.suffix == ".po":

files.append(p)

return files

def main():

parser = argparse.ArgumentParser(

description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter

)

parser.add_argument("paths", nargs="*", default=["."],

help="Files or directories to scan (default: whole repo)")

parser.add_argument("--sort", choices=["percent", "untranslated", "name"], default="percent",

help="Sort order (default: percent, least-translated first)")

parser.add_argument("--only-incomplete", action="store_true",

help="Hide files that are already fully translated")

parser.add_argument("--format", choices=["text", "markdown", "csv"], default="text")

args = parser.parse_args()

files = collect_files(args.paths)

if not files:

print("No .po files found.")

sys.exit(1)

rows = []

for f in files:

t, fz, u = file_stats(f)

total = t + fz + u

percent = (t / total * 100) if total else 100.0

rows.append((str(f), t, fz, u, total, percent))

if args.only_incomplete:

rows = [r for r in rows if r[2] > 0 or r[3] > 0]

if args.sort == "percent":

rows.sort(key=lambda r: r[5])

elif args.sort == "untranslated":

rows.sort(key=lambda r: -r[3])

else:

rows.sort(key=lambda r: r[0])

total_t = sum(r[1] for r in rows)

total_fz = sum(r[2] for r in rows)

total_u = sum(r[3] for r in rows)

total_all = total_t + total_fz + total_u

total_percent = (total_t / total_all * 100) if total_all else 100.0

if args.format == "csv":

print("file,translated,fuzzy,untranslated,total,percent")

for path, t, fz, u, total, percent in rows:

print(f"{path},{t},{fz},{u},{total},{percent:.1f}")

print(f"TOTAL,{total_t},{total_fz},{total_u},{total_all},{total_percent:.1f}")

return

if args.format == "markdown":

print("| File | Translated | Fuzzy | Untranslated | % done |")

print("|---|---:|---:|---:|---:|")

for path, t, fz, u, total, percent in rows:

print(f"| `{path}` | {t} | {fz} | {u} | {percent:.1f}% |")

print(f"| **TOTAL** | **{total_t}** | **{total_fz}** | **{total_u}** | **{total_percent:.1f}%** |")

return

name_width = max((len(r[0]) for r in rows), default=4)

header = f"{'File':<{name_width}} {'Translated':>10} {'Fuzzy':>6} {'Untranslated':>12} {'% done':>7}"

print(header)

print("-" * len(header))

for path, t, fz, u, total, percent in rows:

print(f"{path:<{name_width}} {t:>10} {fz:>6} {u:>12} {percent:>6.1f}%")

print("-" * len(header))

print(f"{'TOTAL':<{name_width}} {total_t:>10} {total_fz:>6} {total_u:>12} {total_percent:>6.1f}%")

print(f"\n{len(rows)} file(s) shown. "

f"{sum(1 for r in rows if r[5] < 100)} file(s) not fully translated.")

if __name__ == "__main__":

main()