docs: add Arabic documentation edition

Author: m0hamed-ux

docs/translations.md

@@ -4,7 +4,7 @@ This documentation is written in English. To make it useful to more people, we a
 
 ## What's available
 
-Translated documentation is currently a **preview** in twelve languages: Deutsch, español, français, हिन्दी, 日本語, 한국어, português (Brasil), русский язык, Türkçe, українська мова, 简体中文 and 繁體中文. Pick one from the language switcher at the top of any page. More languages may follow once these have proved themselves.
+Translated documentation is currently a **preview** in thirteen languages: العربية, Deutsch, español, français, हिन्दी, 日本語, 한국어, português (Brasil), русский язык, Türkçe, українська мова, 简体中文 and 繁體中文. Pick one from the language switcher at the top of any page. More languages may follow once these have proved themselves.
 
 The API reference is not translated: the translated site links to the single English one.
 

i18n/ar/glossary.json

@@ -0,0 +1,294 @@
+{
+  "keep": [
+    "MCP",
+    "Model Context Protocol",
+    "MCPServer",
+    "FastMCP",
+    "ClientSession",
+    "Context",
+    "ctx",
+    "stdio",
+    "Streamable HTTP",
+    "SSE",
+    "JSON-RPC",
+    "JSON",
+    "OAuth",
+    "PKCE",
+    "JWT",
+    "CIMD",
+    "HTTP",
+    "HTTPS",
+    "TLS",
+    "CORS",
+    "URI",
+    "URL",
+    "ASGI",
+    "WebSocket",
+    "API",
+    "SDK",
+    "CLI",
+    "IDE",
+    "LLM",
+    "SEP",
+    "RFC",
+    "Python",
+    "TypeScript",
+    "Node.js",
+    "PyPI",
+    "Pydantic",
+    "Starlette",
+    "FastAPI",
+    "uvicorn",
+    "httpx",
+    "anyio",
+    "asyncio",
+    "trio",
+    "pytest",
+    "OpenTelemetry",
+    "Inspector",
+    "Claude",
+    "GitHub",
+    "VS Code",
+    "Windows",
+    "macOS",
+    "Linux",
+    "llms.txt",
+    "2026-07-28",
+    "2025-11-25",
+    "2025-06-18",
+    "2025-03-26"
+  ],
+  "terms": [
+    {
+      "source": "tool",
+      "target": "أداة",
+      "note": "MCP callable primitive; plural أدوات. Keep Tools when naming the Inspector UI tab, and all code identifiers unchanged."
+    },
+    {
+      "source": "resource",
+      "target": "مورد",
+      "note": "Readable MCP data; plural موارد. A resource template is قالب مورد. Keep Resources and Resource Templates when naming actual UI tabs."
+    },
+    {
+      "source": "prompt",
+      "target": "قالب توجيه",
+      "note": "Reusable MCP message template, plural قوالب توجيه. First prose mention on a page may include (prompt). A general instruction to an LLM is توجيه; a UI confirmation prompt is مطالبة. Keep Prompts as a literal UI label."
+    },
+    {
+      "source": "sampling",
+      "target": "أخذ العينات",
+      "note": "MCP model-generation feature; first prose occurrence takes (sampling). Do not suggest it merely samples existing data. Wire identifiers remain unchanged."
+    },
+    {
+      "source": "roots",
+      "target": "المجلدات الجذرية",
+      "note": "Client-exposed directory roots; first prose mention takes (roots). Not mathematical roots or administrator privileges."
+    },
+    {
+      "source": "elicitation",
+      "target": "استقاء المعلومات",
+      "note": "Server requests user input through the client; first prose mention takes (elicitation). Preserve form/URL and push/pull distinctions."
+    },
+    {
+      "source": "capability",
+      "target": "قدرة",
+      "note": "Declared protocol capability; plural قدرات. A feature is ميزة, not necessarily a declared capability."
+    },
+    {
+      "source": "transport",
+      "target": "وسيلة نقل",
+      "note": "Protocol connection mechanism; plural وسائل نقل. stdio, Streamable HTTP, and SSE stay unchanged."
+    },
+    {
+      "source": "session",
+      "target": "جلسة",
+      "note": "Plural جلسات. Session identifiers and class names stay unchanged."
+    },
+    {
+      "source": "handler",
+      "target": "دالة معالجة",
+      "note": "Registered handler function; plural دوال معالجة. A handler body is جسم دالة المعالجة; avoid the hardware sense of processor."
+    },
+    {
+      "source": "dependency",
+      "target": "اعتمادية",
+      "note": "Plural اعتماديات, for packages and injected dependencies. Dependency injection is حقن الاعتماديات."
+    },
+    {
+      "source": "resolver",
+      "target": "دالة حل الاعتمادية",
+      "note": "Function supplying an injected parameter. Shorten to دالة الحل after the role is clear; preserve Resolve identifiers."
+    },
+    {
+      "source": "client",
+      "target": "عميل",
+      "note": "Plural عملاء; the MCP component inside a host, distinct from the user and host application."
+    },
+    {
+      "source": "server",
+      "target": "خادم",
+      "note": "Plural خوادم. Class and module names remain unchanged."
+    },
+    {
+      "source": "host",
+      "target": "تطبيق مضيف",
+      "note": "The user-facing MCP application containing clients, not the MCP server or a hosting machine. Shorten to المضيف when unambiguous."
+    },
+    {
+      "source": "request",
+      "target": "طلب",
+      "note": "Protocol/HTTP request; plural طلبات. A response is استجابة, a result is نتيجة."
+    },
+    {
+      "source": "token",
+      "target": "رمز",
+      "note": "OAuth: access token رمز وصول, refresh token رمز تحديث, bearer token رمز حامل. LLM token: وحدة نصية (token) on first use, then وحدة نصية. Do not conflate the two."
+    },
+    {
+      "source": "lifespan",
+      "target": "دورة الحياة",
+      "note": "Server startup/shutdown feature. Preserve lifespan= and other identifiers."
+    },
+    {
+      "source": "callback",
+      "target": "دالة رد نداء",
+      "note": "Plural دوال رد نداء. OAuth callback URL is عنوان URL لرد النداء. First prose mention may take (callback)."
+    },
+    {
+      "source": "deploy",
+      "target": "نشر",
+      "note": "Deploy a server: انشر الخادم. Deployment نشر; distinct from running locally, تشغيل."
+    },
+    {
+      "source": "library",
+      "target": "مكتبة",
+      "note": "Software library; plural مكتبات."
+    },
+    {
+      "source": "back-channel",
+      "target": "قناة عكسية",
+      "note": "Server-to-client calls during a request; first prose mention takes (back-channel). Preserve NoBackChannelError."
+    },
+    { "source": "file", "target": "ملف", "note": "Plural ملفات." },
+    {
+      "source": "user",
+      "target": "مستخدم",
+      "note": "Plural مستخدمون / مستخدمين according to case. Distinct from client."
+    },
+    {
+      "source": "escape hatch",
+      "target": "منفذ للتحكم المباشر",
+      "note": "Lower-level API mechanism for bypassing convenience-layer restrictions. Translate metaphor by its function."
+    },
+    {
+      "source": "type hint",
+      "target": "تلميح نوع",
+      "note": "Python typing hint; plural تلميحات الأنواع. Type annotation is تعليق نوع when distinction matters; do not translate the identifier."
+    },
+    {
+      "source": "Get started",
+      "target": "ابدأ هنا",
+      "note": "Guide section/index title; distinct from First steps."
+    },
+    {
+      "source": "First steps",
+      "target": "الخطوات الأولى",
+      "note": "Tutorial page inside Get started."
+    },
+    {
+      "source": "authentication",
+      "target": "مصادقة",
+      "note": "Verifying identity, distinct from authorization."
+    },
+    {
+      "source": "authorization",
+      "target": "تفويض",
+      "note": "Granting/checking permission, distinct from authentication."
+    },
+    {
+      "source": "middleware",
+      "target": "برمجيات وسيطة",
+      "note": "Request-processing middleware. A single middleware component is مكوّن وسيط."
+    },
+    {
+      "source": "schema",
+      "target": "مخطط",
+      "note": "Data/type schema; JSON Schema remains the name JSON Schema."
+    },
+    {
+      "source": "structured output",
+      "target": "مخرجات منظّمة",
+      "note": "Tool output matching a schema; structured content is محتوى منظّم."
+    },
+    {
+      "source": "pagination",
+      "target": "تقسيم النتائج إلى صفحات",
+      "note": "Protocol list pagination, not printed-page numbering."
+    },
+    {
+      "source": "subscription",
+      "target": "اشتراك",
+      "note": "Plural اشتراكات. Subscribe اشترك; unsubscribe ألغِ الاشتراك."
+    },
+    {
+      "source": "notification",
+      "target": "إشعار",
+      "note": "Protocol notification distinct from request and response."
+    },
+    {
+      "source": "cancellation",
+      "target": "إلغاء",
+      "note": "Cancelling a request/task; preserve cooperative cancellation semantics."
+    },
+    {
+      "source": "stateless",
+      "target": "عديم الحالة",
+      "note": "No server-side state required between requests; statelessness انعدام الحالة."
+    },
+    {
+      "source": "stateful",
+      "target": "ذو حالة",
+      "note": "Preserves state across requests; inflect for gender and number."
+    },
+    {
+      "source": "identity assertion",
+      "target": "إفادة الهوية",
+      "note": "Signed assertion carrying authenticated identity; first prose occurrence may take (identity assertion)."
+    },
+    {
+      "source": "completion",
+      "target": "إكمال",
+      "note": "MCP argument autocomplete إكمال تلقائي للوسائط; LLM completion استكمال يولّده النموذج. Preserve protocol/class identifiers."
+    },
+    {
+      "source": "in-memory",
+      "target": "داخل الذاكرة",
+      "note": "Direct in-process test connection, without network transport or subprocess."
+    },
+    {
+      "source": "legacy",
+      "target": "قديم",
+      "note": "Older protocol path, not a judgement about quality. Legacy client عميل قديم. Preserve mode=\"legacy\"."
+    },
+    {
+      "source": "pull",
+      "target": "سحب",
+      "note": "New protocol where clients fetch outstanding requests; contrast with server-initiated دفع (push)."
+    },
+    {
+      "source": "argument",
+      "target": "وسيطة",
+      "note": "Passed call value; plural وسائط. Parameter is مَعلمة, plural مَعلمات; preserve identifiers."
+    },
+    {
+      "source": "stream",
+      "target": "تدفّق",
+      "note": "Streaming تَدَفّق / بث according to context; never translate the name Streamable HTTP."
+    },
+    {
+      "source": "cache",
+      "target": "ذاكرة تخزين مؤقت",
+      "note": "Caching تخزين مؤقت; cached result نتيجة مخزّنة مؤقتًا."
+    }
+  ]
+}

i18n/ar/instructions.md

@@ -0,0 +1,82 @@
+# Arabic (ar) — translation instructions
+
+Target language: Modern Standard Arabic (العربية الفصحى), directory and URL
+code `ar`, page language tag `ar`. These instructions accompany the shared
+rules in `../general-prompt.md`; `glossary.json` wins terminology conflicts.
+
+## 1. Register
+
+Write clear Modern Standard Arabic for software developers across the Arabic-speaking
+world. Use neither regional dialect nor ornate literary or bureaucratic language.
+Address the reader with direct singular imperatives: "ثبّت", "أنشئ", "شغّل", "مرّر".
+Prefer verbs to nominal constructions: "شغّل الخادم", not "قم بعملية تشغيل الخادم".
+Use "يمكنك" for can, "يجب" for must, "ينبغي" for should, and "قد" for may
+when it expresses possibility; never weaken a requirement or turn an option into one.
+Do not add "يرجى" to instructions that are direct in English.
+
+## 2. Voice
+
+Sound like an experienced Arabic-speaking developer explaining the SDK to a colleague:
+direct, practical, and approachable. Prefer short sentences and familiar connectors
+such as "ثم", "لذلك", and "أي". Preserve every technical claim, caveat, condition,
+negation, example, and step, including those in a friendly aside. Recast clause order
+when Arabic needs it without rearranging blocks or changing emphasis.
+
+Avoid inflated introductions such as "تجدر الإشارة إلى" and "من الجدير بالذكر",
+mechanical English word order, excessive passive voice, and transliterated verbs.
+"Returns" is "يعيد" in a function description, not "يرجع إلى". "Expose" means
+"يتيح" in MCP prose, not "يفضح". "Argument" means a passed value, never a dispute.
+Distinguish the MCP host application from the client inside it and the server it
+connects to. Distinguish authentication (المصادقة) from authorization (التفويض).
+
+## 3. Humour and idioms
+
+Translate the meaning of an idiom rather than its literal image. "Out of the box"
+is "افتراضيًا"; "under the hood" is "داخليًا"; "the whole story" is "التفاصيل كاملة".
+"That's it. It's just Python." is "هذا كل شيء. إنها Python فحسب.".
+Keep short payoff sentences short. Preserve the source's emojis and punctuation
+emphasis without adding new ones. Do not omit an aside or invent explanatory notes.
+
+## 4. Typography
+
+Arabic prose reads right to left; Latin identifiers and code retain their original
+left-to-right spelling. Do not reverse text, insert invisible bidi control characters,
+or wrap identifiers in added HTML or Markdown. Direction is the site's responsibility.
+Use the Arabic comma "،", semicolon "؛", and question mark "؟" in prose; retain
+ordinary colons, parentheses, straight quotes, and the source's Markdown syntax.
+Do not translate punctuation inside code, URLs, or pinned heading anchors.
+
+Use ASCII digits throughout, including quantities, ports, versions, dates, HTTP
+status codes, percentages, RFCs, and SEPs. Preserve decimal separators and protocol
+revision identifiers exactly. Avoid decorative elongation (tatweel) and full vowel
+marks; use an occasional mark only to resolve ambiguity. Spell hamza and final
+letters correctly (إعداد، إنشاء، استدعاء، واجهة، مكتبة).
+
+Translate headings, table cells, admonition titles, tab labels, link text, and image
+alt text. Product/package names used as labels (uv, pip, Claude Desktop) stay as named.
+When referring to an actual English UI tab, keep its displayed label (Tools,
+Resources, Resource Templates, Prompts) so the reader can find it. Preserve bold and
+italic emphasis on the corresponding meaning and never add code spans.
+
+## 5. Terminology pointer
+
+Follow `glossary.json` consistently, allowing normal Arabic inflection, definiteness,
+agreement, and plural forms (أداة / الأدوات، مورد / الموارد، عميل / العملاء).
+The listed targets name concepts; do not force the singular into a plural sentence.
+Everything in a code span or fenced block stays byte-identical, including comments,
+docstrings, strings, snippet includes, annotation markers, and error messages.
+API identifiers, classes, functions, parameters, modules, headers, environment
+variables, commands, and protocol methods stay unchanged even outside code font.
+
+On a page's first prose use of an unfamiliar MCP concept, include its English term
+in parentheses where the glossary asks for it. Subsequent uses use Arabic alone.
+Do not add a gloss to a code identifier or to a heading when the concept is explained
+in the body. Acronyms and proper names in `keep` remain exactly as in the source.
+Translate all other reader-visible English; do not leave whole sentences in English.
+
+## 6. Provisional note
+
+These choices require review by native Arabic-speaking developers. Propose durable
+corrections here or in `glossary.json`, then regenerate the affected pages; do not
+patch generated `pages/` or `notices.md`. The normal command is
+`translate --lang ar --pages …`; the English documentation remains authoritative.