{
  "title": "قوانین زبانی",
  "slug": "team/platform/standards/language-policy",
  "url": "/docs/team/platform/standards/language-policy",
  "frontmatter": {
    "layout": "doc",
    "title": "قوانین زبانی",
    "description": "زبان رسمی کد، موارد مجاز فارسی، ممنوعیت‌ها و استثناها",
    "version": "1.0.0",
    "status": "PRIVATE",
    "author": "xoxxel",
    "owner": "xoxxel",
    "created_at": "2026-06-07",
    "updated_at": "2026-06-07",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "قوانین زبانی",
      "content": "**Language Policy**\n\nنسخه 1.0 | الزامی برای همه سرویس‌ها، پکیج‌ها و مشارکت‌کنندگان\n\n---"
    },
    {
      "level": 2,
      "heading": "1. زبان رسمی کد (Canonical Language)",
      "content": "زبان رسمی و یکتای بکند **انگلیسی** است. تمام کدها، نام‌ها، کامنت‌ها، لاگ‌ها، پیام‌های خطا، متغیرها، توابع، کلاس‌ها، فایل‌ها، برنچ‌ها و کامیت‌ها باید به زبان انگلیسی باشند.\n\n```typescript\n// ✅ درست\nlogger.info('Order created successfully', { orderId });\nthrow new Error('Payment escrow lock failed');\n\n// ❌ غلط\nlogger.info('سفارش با موفقیت ایجاد شد', { orderId });\nthrow new Error('قفل Escrow ناموفق بود');\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "2. موارد مجاز برای فارسی",
      "content": "فارسی فقط در این موارد مجاز است:\n\n| مورد | توضیح | مثال |\n|---|---|---|\n| مستندات محصول | فایل‌های داخل `/docs` | این راهنما، استایل گاید، آموزش‌ها |\n| فایل‌های i18n | متن‌های رابط کاربری | `fa.json`, `en.json` |\n| ابزارهای مدیریت پروژه | پلتفرم‌های تیمی | Jira, Notion, Linear tasks |\n| مستندات کسب‌وکار | توضیحات دامنه و فرآیند | ADRها، نیازمندی‌ها |\n\n---"
    },
    {
      "level": 2,
      "heading": "3. ممنوعیت‌های قطعی",
      "content": "هیچ متن فارسی در فایل‌های زیر مجاز نیست:\n\n| نوع فایل | مثال |\n|---|---|\n| TypeScript / JavaScript | `*.ts`, `*.js`, `*.tsx`, `*.jsx` |\n| Go | `*.go` |\n| Python | `*.py` |\n| YAML | `*.yml`, `*.yaml` |\n| JSON | `*.json` |\n| Environment | `.env`, `.env.*` (جز `.env.example`) |\n| Shell Script | `*.sh`, `*.bash` |\n| Dockerfile | `Dockerfile`, `*.dockerfile` |\n| Makefile | `Makefile` |\n| Database | فایل‌های SQL, Migration |\n\n```yaml"
    },
    {
      "level": 1,
      "heading": "✅ درست",
      "content": "environment:\n  NODE_ENV: production\n  LOG_LEVEL: info"
    },
    {
      "level": 1,
      "heading": "❌ غلط",
      "content": "environment:\n  NODE_ENV: تولید\n  LOG_LEVEL: اطلاعات\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "4. مقادیر و ثابت‌ها",
      "content": "همه مقادیر وضعیت‌ها، نقش‌ها، مجوزها، رویدادها، کدهای خطا و مقادیر `enum` به زبان انگلیسی هستند:\n\n```typescript\n// ✅ درست\nenum OrderStatus {\n  PENDING = 'pending',\n  PAID = 'paid',\n  SHIPPED = 'shipped',\n  DELIVERED = 'delivered',\n  DISPUTED = 'disputed',\n  CANCELLED = 'cancelled'\n}\n\nenum UserRole {\n  BUYER = 'buyer',\n  SELLER = 'seller',\n  ADMIN = 'admin'\n}\n\n// ❌ غلط\nenum OrderStatus {\n  PENDING = 'در_انتظار',\n  PAID = 'پرداخت_شده'\n}\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "5. لاگ‌ها و پیام‌های خطا",
      "content": "همه لاگ‌ها و خطاها به انگلیسی هستند:\n\n```typescript\n// ✅ درست - لاگ\nlogger.warn('Payment timeout exceeded', {\n  orderId: 'abc-123',\n  timeoutMs: 30000\n});\n\n// ✅ درست - خطا\nthrow new AppError('ORDER_NOT_FOUND', 'The requested order does not exist');\n\n// ❌ غلط - لاگ\nlogger.warn('مدت زمان پرداخت تمام شد', { orderId: 'abc-123' });\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "6. کامیت‌ها و برنچ‌ها",
      "content": "پیام کامیت و نام برنچ باید انگلیسی باشد. توضیحات فارسی در کامیت ممنوع است:\n\n```\n✅ feat(order): add guarantee timer with 24h default\n✅ fix(payment): prevent double escrow release\n❌ feat(order): اضافه کردن تایمر گارانتی\n❌ fix(payment): رفع باگ انتشار دوبرابر\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "7. استثناها (Exception)",
      "content": "تنها استثنا برای فارسی در کد، **کامنت‌های توضیحی برای قطعات کد بسیار پیچیده** است که می‌تواند به صورت دوزبانه (فارسی + انگلیسی) نوشته شود، اما ترجیح با انگلیسی است.\n\n---"
    },
    {
      "level": 2,
      "heading": "خلاصه",
      "content": "| محیط | زبان | اجباری |\n|---|---|---|\n| کد منبع (`src/`) | انگلیسی | بله |\n| کامنت‌ها | انگلیسی | ترجیح |\n| لاگ‌ها | انگلیسی | بله |\n| خطاها | انگلیسی | بله |\n| نام متغیرها | انگلیسی | بله |\n| نام فایل‌ها | انگلیسی | بله |\n| کامیت‌ها | انگلیسی | بله |\n| برنچ‌ها | انگلیسی | بله |\n| مستندات (`docs/`) | فارسی | بله |\n| i18n | فارسی | بله |\n| Jira / Notion | فارسی | آزاد |"
    }
  ]
}