Python 文档现在提供波斯语版本。对波斯语开发者来说，这不只是语言菜单里多了一个选项：初学者可以用母语理解迭代器、异常和上下文管理器等概念，团队也能更顺畅地开展培训与知识共享。
不过，翻译文档并不会改变 Python 的语法、标准库 API 或错误信息。更有效的使用方式，是把波斯语解释和英文技术标识结合起来，而不是完全舍弃英文术语。
母语解释降低的是什么成本
程序员遇到的障碍通常有两层：一层是理解技术概念，另一层是理解描述这些概念的语言。当两层问题同时出现时，一段原本简单的文档也可能变得难以消化。
波斯语文档可以直接降低第二层成本，尤其适合以下场景：
- 初学者第一次接触类、生成器、装饰器和异常处理；
- 教师或企业培训人员准备波斯语课程；
- 开发者需要向非英语母语同事解释标准库行为；
- 社区成员希望统一常见 Python 术语的波斯语表达。
与此同时，代码里的 asyncio、pathlib.Path、ValueError 等名称不会被翻译。搜索第三方库问题、阅读报错和参与国际社区讨论时，英文名称仍然不可替代。因此，推荐把“波斯语概念解释 + 英文 API 名称”作为默认阅读方式。
建立双语阅读习惯
使用翻译文档时，可以保留三个简单动作：
- 先确认页面对应的 Python 版本与本地解释器版本一致；
- 遇到关键术语时，同时记住英文原词；
- 如果译文存在歧义或页面尚未覆盖，切换到英文页面交叉核对。
先在终端确认项目实际使用的 Python 版本：
python3 --version
python3 -c "import sys; print(sys.version); print(sys.executable)"
文档中的行为可能随 Python 版本变化，特别是类型标注、异步 API、标准库新增功能和弃用提示。团队内部引用文档时，最好同时记录版本，例如“Python 3.12 的 pathlib 文档”，而不是只写“Python 文档”。
还要注意，网页文档提供波斯语版本，并不意味着解释器报错、第三方包文档或终端中的 pydoc 都会自动变成波斯语。例如：
python3 -m pydoc pathlib.Path
这条命令显示的是当前 Python 环境中可用的文档字符串，其语言取决于代码本身，而不是浏览器里的文档语言设置。
一个可运行的双语术语示例
团队可以维护一份很小的术语表：英文键名与实际 API、报错和搜索结果保持一致，波斯语用于解释概念。下面的示例只使用 Python 标准库，可直接运行。
先创建一个临时项目：
mkdir python-fa-demo
cd python-fa-demo
python3 -m venv .venv
. .venv/bin/activate
cat > glossary.py <<'PY'
from dataclasses import dataclass
TERMS = {
"iterator": "تکرارگر",
"exception": "استثنا",
"context manager": "مدیر زمینه",
"type annotation": "حاشیهنویسی نوع",
}
@dataclass
class User:
name: str
language: str = "fa"
def show_terms(user: User) -> None:
print(f"سلام {user.name}!")
print("Python terminology:")
for english, persian in TERMS.items():
print(f"- {english}: {persian}")
if __name__ == "__main__":
show_terms(User(name="Sara"))
PY
python glossary.py
运行前只需要把 Sara 改成想显示的名字。这个例子还体现了一个适合多语言团队的边界：用户界面、说明文字和注释可以本地化，但公共类名、函数名以及技术术语索引最好保留稳定的英文形式。这样既能照顾母语阅读，也不会增加代码审查、搜索和跨团队协作的成本。
Python 3 源文件默认使用 UTF-8，因此波斯语字符串可以直接写入源码。虽然 Python 也允许许多 Unicode 字符出现在标识符中，但共享项目通常不建议把核心 API 命名成不同语言，否则键盘输入、代码搜索和工具兼容性都可能受到影响。
团队采用时检查这几项
把波斯语文档纳入学习或培训流程时，可以使用下面的清单：
- 明确课程和项目采用的 Python 主版本；
- 在培训材料中并列记录波斯语译名与英文术语；
- 代码、异常类型和 API 名称保持原样；
- 对安全、并发、类型系统等容易产生歧义的主题进行双语核对；
- 不假设所有标准库页面和第三方包都具有相同的翻译覆盖度；
- 发现翻译问题时，整理最小示例、页面版本和建议措辞，再反馈给文档社区。
波斯语版本最直接的价值，是让更多开发者可以先准确理解概念，再进入代码与英文 API 的世界。将它作为英文文档的协作伙伴，而不是完全替代品，通常能获得更稳定的学习和工程效果。