From 47ee48ff63fd6506ebc85612c452bfe013bedc13 Mon Sep 17 00:00:00 2001
From: Mohammad222PR <mohammades13851@gmail.com>
Date: Mon, 17 Mar 2025 22:48:44 +0330
Subject: [PATCH] docs: add Persian (fa) translation for environment-variables
 section

---
 docs/fa/docs/environment-variables.md | 300 ++++++++++++++++++++++++++
 1 file changed, 300 insertions(+)
 create mode 100644 docs/fa/docs/environment-variables.md

diff --git a/docs/fa/docs/environment-variables.md b/docs/fa/docs/environment-variables.md
new file mode 100644
index 000000000..802f0b586
--- /dev/null
+++ b/docs/fa/docs/environment-variables.md
@@ -0,0 +1,300 @@
+# متغیرهای محیطی
+
+/// نکته
+
+اگر از قبل می‌دونید «متغیرهای محیطی» چی هستن و چطور کار می‌کنن، می‌تونید این بخش رو رد کنید.
+
+///
+
+متغیر محیطی (که بهش «**env var**» هم می‌گن) یه متغیره که **خارج از کد پایتون** و توی **سیستم‌عامل** زندگی می‌کنه. کد پایتون شما (یا حتی برنامه‌های دیگه) می‌تونن این متغیرها رو بخونن و ازشون استفاده کنن.
+
+این متغیرها برای مدیریت **تنظیمات برنامه**، نصب پایتون یا چیزای دیگه خیلی به‌درد می‌خورن.
+
+## ساختن و استفاده از متغیرهای محیطی
+
+شما می‌تونید متغیرهای محیطی رو توی **شل (ترمینال)** بسازید و استفاده کنید، بدون اینکه نیازی به پایتون داشته باشید:
+
+//// tab | لینوکس، مک‌او‌اس، ویندوز Bash
+
+<div class="termy">
+
+```console
+// می‌تونید یه متغیر محیطی به اسم MY_NAME بسازید با
+$ export MY_NAME="وید ویلسون"
+
+// بعدش می‌تونید ازش توی برنامه‌های دیگه استفاده کنید، مثل
+$ echo "سلام $MY_NAME"
+
+سلام وید ویلسون
+```
+
+</div>
+
+////
+
+//// tab | ویندوز PowerShell
+
+<div class="termy">
+
+```console
+// یه متغیر محیطی به اسم MY_NAME بسازید
+$ $Env:MY_NAME = "وید ویلسون"
+
+// ازش توی برنامه‌های دیگه استفاده کنید، مثل
+$ echo "سلام $Env:MY_NAME"
+
+سلام وید ویلسون
+```
+
+</div>
+
+////
+
+## خوندن متغیرهای محیطی توی پایتون
+
+شما می‌تونید متغیرهای محیطی رو **خارج از پایتون**، مثلاً توی ترمینال (یا هر روش دیگه) بسازید و بعد توی پایتون بخونیدشون.
+
+مثلاً فرض کنید یه فایل `main.py` دارید با این کد:
+
+```Python hl_lines="3"
+import os
+
+name = os.getenv("MY_NAME", "جهان")
+print(f"سلام {name} از پایتون")
+```
+
+/// نکته
+
+آرگومان دوم تابع <a href="https://docs.python.org/3.8/library/os.html#os.getenv" class="external-link" target="_blank">`os.getenv()`</a> مقدار پیش‌فرضیه که برمی‌گرده.
+
+اگه چیزی ندید، به صورت پیش‌فرض `None` برمی‌گرده، ولی اینجا ما «جهان» رو به‌عنوان مقدار پیش‌فرض گذاشتیم.
+
+///
+
+حالا می‌تونید این برنامه پایتون رو اجرا کنید:
+
+//// tab | لینوکس، مک‌او‌اس، ویندوز Bash
+
+<div class="termy">
+
+```console
+// اینجا هنوز متغیر محیطی رو تنظیم نکردیم
+$ python main.py
+
+// چون متغیر رو نذاشتیم، مقدار پیش‌فرض رو می‌گیره
+
+سلام جهان از پایتون
+
+// حالا اگه اول یه متغیر محیطی بسازیم
+$ export MY_NAME="وید ویلسون"
+
+// و دوباره برنامه رو اجرا کنیم
+$ python main.py
+
+// حالا متغیر محیطی رو می‌خونه
+
+سلام وید ویلسون از پایتون
+```
+
+</div>
+
+////
+
+//// tab | ویندوز PowerShell
+
+<div class="termy">
+
+```console
+// اینجا هنوز متغیر محیطی رو تنظیم نکردیم
+$ python main.py
+
+// چون متغیر رو نذاشتیم، مقدار پیش‌فرض رو می‌گیره
+
+سلام جهان از پایتون
+
+// حالا اگه اول یه متغیر محیطی بسازیم
+$ $Env:MY_NAME = "وید ویلسون"
+
+// و دوباره برنامه رو اجرا کنیم
+$ python main.py
+
+// حالا متغیر محیطی رو می‌خونه
+
+سلام وید ویلسون از پایتون
+```
+
+</div>
+
+////
+
+از اونجایی که متغیرهای محیطی رو می‌شه بیرون از کد تنظیم کرد، ولی کد می‌تونه بخوندشون و نیازی نیست توی فایل‌ها ذخیره بشن (مثلاً توی `git` commit بشن)، برای مدیریت تنظیمات یا **settings** خیلی استفاده می‌شن.
+
+یه راه دیگه هم هست که متغیر محیطی رو فقط برای **یه اجرای خاص برنامه** بسازید، یعنی فقط برای همون برنامه و همون لحظه در دسترس باشه.
+
+برای این کار، متغیر رو درست قبل از اجرای برنامه، توی همون خط تعریف کنید:
+
+<div class="termy">
+
+```console
+// متغیر MY_NAME رو توی همین خط برای این اجرا می‌سازیم
+$ MY_NAME="وید ویلسون" python main.py
+
+// حالا متغیر محیطی رو می‌خونه
+
+سلام وید ویلسون از پایتون
+
+// بعدش دیگه متغیر وجود نداره
+$ python main.py
+
+سلام جهان از پایتون
+```
+
+</div>
+
+/// نکته
+
+می‌تونید بیشتر در موردش توی <a href="https://12factor.net/config" class="external-link" target="_blank">The Twelve-Factor App: Config</a> بخونید.
+
+///
+
+## انواع و اعتبارسنجی
+
+این متغیرهای محیطی فقط می‌تونن **رشته‌های متنی** رو نگه دارن، چون خارج از پایتون هستن و باید با بقیه برنامه‌ها و سیستم (حتی سیستم‌عامل‌های مختلف مثل لینوکس، ویندوز، مک‌او‌اس) سازگار باشن.
+
+یعنی **هر مقداری** که توی پایتون از متغیر محیطی می‌خونید، یه `str` هست و اگه بخواید به نوع دیگه‌ای تبدیلش کنید یا اعتبارسنجی کنید، باید توی کدتون انجامش بدید.
+
+توی [راهنمای پیشرفته - تنظیمات و متغیرهای محیطی](./advanced/settings.md){.internal-link target=_blank} بیشتر در مورد استفاده از متغیرهای محیطی برای **تنظیمات برنامه** یاد می‌گیرید.
+
+## متغیر محیطی `PATH`
+
+یه متغیر محیطی **خاص** به اسم **`PATH`** وجود داره که سیستم‌عامل‌ها (لینوکس، مک‌او‌اس، ویندوز) ازش برای پیدا کردن برنامه‌هایی که باید اجرا بشن استفاده می‌کنن.
+
+مقدار `PATH` یه رشته طولانیه که از دایرکتوری‌ها تشکیل شده و توی لینوکس و مک‌او‌اس با دونقطه `:` و توی ویندوز با نقطه‌ویرگول `;` از هم جدا شدن.
+
+مثلاً متغیر `PATH` می‌تونه این شکلی باشه:
+
+//// tab | لینوکس، مک‌او‌اس
+
+```plaintext
+/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
+```
+
+یعنی سیستم باید دنبال برنامه‌ها توی این دایرکتوری‌ها بگرده:
+
+* `/usr/local/bin`
+* `/usr/bin`
+* `/bin`
+* `/usr/sbin`
+* `/sbin`
+
+////
+
+//// tab | ویندوز
+
+```plaintext
+C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32
+```
+
+یعنی سیستم باید دنبال برنامه‌ها توی این دایرکتوری‌ها بگرده:
+
+* `C:\Program Files\Python312\Scripts`
+* `C:\Program Files\Python312`
+* `C:\Windows\System32`
+
+////
+
+وقتی توی ترمینال یه **دستور** می‌نویسید، سیستم‌عامل توی **هر کدوم از این دایرکتوری‌ها** که توی متغیر `PATH` لیست شدن دنبال برنامه می‌گرده.
+
+مثلاً وقتی `python` رو توی ترمینال می‌نویسید، سیستم‌عامل دنبال برنامه‌ای به اسم `python` توی **اولین دایرکتوری** اون لیست می‌گرده.
+
+اگه پیداش کنه، **اجرا می‌کنه**. اگه نه، توی **بقیه دایرکتوری‌ها** دنبالش می‌گرده.
+
+### نصب پایتون و به‌روزرسانی `PATH`
+
+وقتی پایتون رو نصب می‌کنید، ممکنه ازتون بپرسه که آیا می‌خواید متغیر `PATH` رو به‌روز کنید.
+
+//// tab | لینوکس، مک‌او‌اس
+
+فرض کنید پایتون رو نصب کردید و توی دایرکتوری `/opt/custompython/bin` قرار گرفته.
+
+اگه بگید بله و بخواید `PATH` رو به‌روز کنید، نصب‌کننده `/opt/custompython/bin` رو به متغیر `PATH` اضافه می‌کنه.
+
+ممکنه این شکلی بشه:
+
+```plaintext
+/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin
+```
+
+اینجوری وقتی توی ترمینال `python` رو تایپ کنید، سیستم برنامه پایتون رو توی `/opt/custompython/bin` (آخرین دایرکتوری) پیدا می‌کنه و از اون استفاده می‌کنه.
+
+////
+
+//// tab | ویندوز
+
+فرض کنید پایتون رو نصب کردید و توی دایرکتوری `C:\opt\custompython\bin` قرار گرفته.
+
+اگه بگید بله و بخواید `PATH` رو به‌روز کنید، نصب‌کننده `C:\opt\custompython\bin` رو به متغیر `PATH` اضافه می‌کنه.
+
+ممکنه این شکلی بشه:
+
+```plaintext
+C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin
+```
+
+اینجوری وقتی توی ترمینال `python` رو تایپ کنید، سیستم برنامه پایتون رو توی `C:\opt\custompython\bin` (آخرین دایرکتوری) پیدا می‌کنه و از اون استفاده می‌کنه.
+
+////
+
+پس اگه تایپ کنید:
+
+<div class="termy">
+
+```console
+$ python
+```
+
+</div>
+
+//// tab | لینوکس، مک‌او‌اس
+
+سیستم برنامه `python` رو توی `/opt/custompython/bin` **پیدا می‌کنه** و اجراش می‌کنه.
+
+تقریباً مثل اینه که تایپ کنید:
+
+<div class="termy">
+
+```console
+$ /opt/custompython/bin/python
+```
+
+</div>
+
+////
+
+//// tab | ویندوز
+
+سیستم برنامه `python` رو توی `C:\opt\custompython\bin\python` **پیدا می‌کنه** و اجراش می‌کنه.
+
+تقریباً مثل اینه که تایپ کنید:
+
+<div class="termy">
+
+```console
+$ C:\opt\custompython\bin\python
+```
+
+</div>
+
+////
+
+این اطلاعات وقتی در مورد [محیط‌های مجازی](virtual-environments.md){.internal-link target=_blank} یاد می‌گیرید به کارتون میاد.
+
+## نتیجه‌گیری
+
+با این توضیحات، باید یه درک اولیه از اینکه **متغیرهای محیطی** چی هستن و چطور توی پایتون ازشون استفاده می‌شه داشته باشید.
+
+می‌تونید توی <a href="https://en.wikipedia.org/wiki/Environment_variable" class="external-link" target="_blank">ویکی‌پدیا برای متغیر محیطی</a> بیشتر در موردشون بخونید.
+
+خیلی وقت‌ها معلوم نیست متغیرهای محیطی چطور می‌تونن همین الان به‌درد بخورن. ولی وقتی دارید کد می‌نویسید، توی موقعیت‌های مختلف سر و کله‌شون پیدا می‌شه، پس خوبه که باهاشون آشنا باشید.
+
+مثلاً توی بخش بعدی که در مورد [محیط‌های مجازی](virtual-environments.md) هست، به این اطلاعات نیاز پیدا می‌کنید.