@@ -35,7 +35,15 @@ jobs:
       - name: Setup virtual environment
         run: make venv
         working-directory: ./Doc
-        
+
+      - name: Pin Sphinx to 9.1.0
+        # make venv may resolve an older Sphinx via requirements.txt; pin
+        # explicitly so we get the reordered-ref / translated-display-text
+        # i18n fixes (sphinx-doc/sphinx#14144). Bump this once #14162 lands
+        # upstream and re-check whether the suppression below is still needed.
+        run: ./venv/bin/pip install "sphinx==9.1.0"
+        working-directory: ./Doc
+
       - name: Checkout translation files
         uses: actions/checkout@v4
         with:
@@ -50,7 +58,7 @@ jobs:
         uses: sphinx-doc/github-problem-matcher@v1.1
 
       - name: Build documentation
-        run: make -e SPHINXERRORHANDLING="" SPHINXOPTS="--color -D language='fa' -D gettext_allow_fuzzy_translations=1 -D html_theme_options.is_rtl=true --keep-going" html
+        run: make -e SPHINXERRORHANDLING="" SPHINXOPTS="--color -D language='fa' -D gettext_allow_fuzzy_translations=1 -D html_theme_options.is_rtl=true -D suppress_warnings=i18n.inconsistent_references --keep-going" html
         working-directory: ./Doc
 
       - name: Setup Pages
 
@@ -36,6 +36,14 @@ jobs:
         run: make venv
         working-directory: ./Doc
 
+      - name: Pin Sphinx to 9.1.0
+        # make venv may resolve an older Sphinx via requirements.txt; pin
+        # explicitly so we get the reordered-ref / translated-display-text
+        # i18n fixes (sphinx-doc/sphinx#14144). Bump this once #14162 lands
+        # upstream and re-check whether the suppression below is still needed.
+        run: ./venv/bin/pip install "sphinx==9.1.0"
+        working-directory: ./Doc
+
       - name: Checkout translation files
         uses: actions/checkout@v4
         with:
@@ -59,5 +67,9 @@ jobs:
         working-directory: Doc/locales/fa/LC_MESSAGES
 
       - name: Build documentation
-        run: make -e SPHINXOPTS="--color -D language='fa' -D gettext_allow_fuzzy_translations=1 -W --keep-going" html
+        # suppress_warnings for i18n.inconsistent_references: confirmed
+        # upstream false positive for translated display text / custom
+        # pending_xref directives (e.g. CPython's `.. availability::`),
+        # tracked and still open at sphinx-doc/sphinx#14162.
+        run: make -e SPHINXOPTS="--color -D language='fa' -D gettext_allow_fuzzy_translations=1 -D suppress_warnings=i18n.inconsistent_references -W --keep-going" html
         working-directory: ./Doc
@@ -7,6 +7,11 @@ build:
   commands:
     - git clone --depth 1 --branch v3.14.7 https://github.com/python/cpython venv/cpython
     - pip install -r venv/cpython/Doc/requirements.txt
+    # Pin Sphinx separately: requirements.txt may resolve to an older version,
+    # and 9.1.0+ is needed for the reordered- ref / translated-display-text
+    # i18n fixes (sphinx-doc/sphinx#14144). Bump this once #14162 lands
+    # upstream and re-check whether the suppression below is still needed.
+    - pip install "sphinx==9.1.0"
     - mkdir -p venv/cpython/Doc/locales/fa/LC_MESSAGES
     - cp --parents *.po venv/cpython/Doc/locales/fa/LC_MESSAGES/
     - find */ -name "*.po" -not -path "venv/*" | xargs -I{} cp --parents {} venv/cpython/Doc/locales/fa/LC_MESSAGES/
@@ -18,6 +23,7 @@ build:
         -D gettext_allow_fuzzy_translations=1
         -D gettext_compact=0
         -D html_theme_options.is_rtl=true
+        -D suppress_warnings=i18n.inconsistent_references
         --keep-going
         venv/cpython/Doc
-        $READTHEDOCS_OUTPUT/html
+        $READTHEDOCS_OUTPUT/html
@@ -33,11 +33,21 @@ msgstr "نسخه‌گذاری API و ABI"
 msgid "Build-time version constants"
 msgstr "ثابتهای نسخه در زمان ساخت"
 
-msgid "CPython exposes its version number in the following macros. Note that these correspond to the version code is **built** with. See :c:var:`Py_Version` for the version used at **run time**."
-msgstr "CPython شماره‌ی نسخه‌ی خود را در ماکروهای زیر در معرض دید قرار می‌دهد. توجه داشته باشید که اینها مربوط به نسخه‌ای هستند که کد با آن **ساخته ** شده است. برای نسخه‌ای که در **زمان اجرا** استفاده می‌شود، به :c:var:`Py_Version` مراجعه کنید."
+msgid ""
+"CPython exposes its version number in the following macros. Note that these "
+"correspond to the version code is **built** with. See :c:var:`Py_Version` "
+"for the version used at **run time**."
+msgstr ""
+"CPython شماره‌ی نسخه‌ی خود را در ماکروهای زیر در معرض دید قرار می‌دهد. توجه "
+"داشته باشید که اینها مربوط به نسخه‌ای هستند که کد با آن **ساخته** شده است. "
+"برای نسخه‌ای که در **زمان اجرا** استفاده می‌شود، به :c:var:`Py_Version` "
+"مراجعه کنید."
 
-msgid "See :ref:`stable` for a discussion of API and ABI stability across versions."
-msgstr "برای بحث درباره‌ی پایداری API و ABI در میان نسخه‌ها، به :ref:`stable` مراجعه کنید."
+msgid ""
+"See :ref:`stable` for a discussion of API and ABI stability across versions."
+msgstr ""
+"برای بحث درباره‌ی پایداری API و ABI در میان نسخه‌ها، به :ref:`stable` مراجعه"
+" کنید."
 
 msgid "The ``3`` in ``3.4.1a2``."
 msgstr "``3`` در ``3.4.1a2``."
@@ -48,35 +58,61 @@ msgstr "``4`` در ``3.4.1a2``."
 msgid "The ``1`` in ``3.4.1a2``."
 msgstr "``1`` در ``3.4.1a2``."
 
-msgid "The ``a`` in ``3.4.1a2``. This can be ``0xA`` for alpha, ``0xB`` for beta, ``0xC`` for release candidate or ``0xF`` for final."
-msgstr "``a`` در ``3.4.1a2``. این می‌تواند ``0xA`` برای آلفا باشد، ``0xB`` برای بتا، ``0xC`` برای کاندیدای انتشار (release candidate) یا ``0xF`` برای نهایی (final)."
+msgid ""
+"The ``a`` in ``3.4.1a2``. This can be ``0xA`` for alpha, ``0xB`` for beta, "
+"``0xC`` for release candidate or ``0xF`` for final."
+msgstr ""
+"``a`` در ``3.4.1a2``. این می‌تواند ``0xA`` برای آلفا باشد، ``0xB`` برای بتا،"
+" ``0xC`` برای کاندیدای انتشار (release candidate) یا ``0xF`` برای نهایی "
+"(final)."
 
 msgid "The ``2`` in ``3.4.1a2``. Zero for final releases."
 msgstr "``2`` در ``3.4.1a2``. برای انتشارهای نهایی، صفر است."
 
-msgid "The Python version number encoded in a single integer. See :c:func:`Py_PACK_FULL_VERSION` for the encoding details."
-msgstr "شماره‌ی نسخه‌ی پایتون که در یک عدد صحیح کدگذاری شده است. برای جزئیات کدگذاری، به :c:func:`Py_PACK_FULL_VERSION` مراجعه کنید."
+msgid ""
+"The Python version number encoded in a single integer. See "
+":c:func:`Py_PACK_FULL_VERSION` for the encoding details."
+msgstr ""
+"شماره‌ی نسخه‌ی پایتون که در یک عدد صحیح کدگذاری شده است. برای جزئیات "
+"کدگذاری، به :c:func:`Py_PACK_FULL_VERSION` مراجعه کنید."
 
-msgid "Use this for numeric comparisons, for example, ``#if PY_VERSION_HEX >= ...``."
-msgstr "از این (مقدار) برای مقایسه‌های عددی استفاده کنید، برای مثال، ``#if PY_VERSION_HEX >= ...``."
+msgid ""
+"Use this for numeric comparisons, for example, ``#if PY_VERSION_HEX >= "
+"...``."
+msgstr ""
+"از این (مقدار) برای مقایسه‌های عددی استفاده کنید، برای مثال، ``#if "
+"PY_VERSION_HEX >= ...``."
 
 msgid "These macros are defined in :source:`Include/patchlevel.h`."
 msgstr "این ماکروها در :source:`Include/patchlevel.h` تعریف می‌شوند."
 
 msgid "Run-time version"
 msgstr "نسخه‌ی زمان اجرا"
 
-msgid "The Python runtime version number encoded in a single constant integer. See :c:func:`Py_PACK_FULL_VERSION` for the encoding details. This contains the Python version used at run time."
-msgstr "شماره‌ی نسخه‌ی ران‌تایم پایتون که در یک عدد صحیح ثابت کدگذاری شده است. برای جزئیات کدگذاری، به :c:func:`Py_PACK_FULL_VERSION` مراجعه کنید. این (مقدار) شامل نسخه‌ی پایتون است که در زمان اجرا استفاده می‌شود."
+msgid ""
+"The Python runtime version number encoded in a single constant integer. See "
+":c:func:`Py_PACK_FULL_VERSION` for the encoding details. This contains the "
+"Python version used at run time."
+msgstr ""
+"شماره‌ی نسخه‌ی ران‌تایم پایتون که در یک عدد صحیح ثابت کدگذاری شده است. برای "
+"جزئیات کدگذاری، به :c:func:`Py_PACK_FULL_VERSION` مراجعه کنید. این (مقدار) "
+"شامل نسخه‌ی پایتون است که در زمان اجرا استفاده می‌شود."
 
-msgid "Use this for numeric comparisons, for example, ``if (Py_Version >= ...)``."
-msgstr "از این (مقدار) برای مقایسه‌های عددی استفاده کنید، برای مثال، ``if (Py_Version >= ...)``."
+msgid ""
+"Use this for numeric comparisons, for example, ``if (Py_Version >= ...)``."
+msgstr ""
+"از این (مقدار) برای مقایسه‌های عددی استفاده کنید، برای مثال، ``if "
+"(Py_Version >= ...)``."
 
 msgid "Bit-packing macros"
 msgstr "ماکروهای بسته‌بندی بیتی"
 
-msgid "Return the given version, encoded as a single 32-bit integer with the following structure:"
-msgstr "نسخه‌ی داده‌شده را که به صورت یک عدد صحیح ۳۲-بیتی با ساختار زیر کدگذاری شده است، برمی‌گرداند:"
+msgid ""
+"Return the given version, encoded as a single 32-bit integer with the "
+"following structure:"
+msgstr ""
+"نسخه‌ی داده‌شده را که به صورت یک عدد صحیح ۳۲-بیتی با ساختار زیر کدگذاری شده "
+"است، برمی‌گرداند:"
 
 msgid "Argument"
 msgstr "آرگومان"
@@ -195,8 +231,12 @@ msgstr "``(3, 10, 0, 0xF, 0)``"
 msgid "``0x030a00f0``"
 msgstr "``0x030a00f0``"
 
-msgid "Out-of range bits in the arguments are ignored. That is, the macro can be defined as:"
-msgstr "بیت‌های خارج از محدوده در آرگومان‌ها نادیده گرفته می‌شوند. به عبارت دیگر، این ماکرو را می‌توان به صورت زیر تعریف کرد:"
+msgid ""
+"Out-of range bits in the arguments are ignored. That is, the macro can be "
+"defined as:"
+msgstr ""
+"بیت‌های خارج از محدوده در آرگومان‌ها نادیده گرفته می‌شوند. به عبارت دیگر، "
+"این ماکرو را می‌توان به صورت زیر تعریف کرد:"
 
 msgid ""
 "#ifndef Py_PACK_FULL_VERSION\n"
@@ -217,8 +257,19 @@ msgstr ""
 "   (((SERIAL) & 0xf) << 0))\n"
 "#endif"
 
-msgid "``Py_PACK_FULL_VERSION`` is primarily a macro, intended for use in ``#if`` directives, but it is also available as an exported function."
-msgstr "``Py_PACK_FULL_VERSION`` در درجه‌ی نخست یک ماکرو است که برای استفاده در دستورهای ``#if`` در نظر گرفته شده است، اما به‌عنوان یک تابع صادرشده نیز در دسترس است."
+msgid ""
+"``Py_PACK_FULL_VERSION`` is primarily a macro, intended for use in ``#if`` "
+"directives, but it is also available as an exported function."
+msgstr ""
+"``Py_PACK_FULL_VERSION`` در درجه‌ی نخست یک ماکرو است که برای استفاده در "
+"دستورهای ``#if`` در نظر گرفته شده است، اما به‌عنوان یک تابع صادرشده نیز در "
+"دسترس است."
 
-msgid "Equivalent to ``Py_PACK_FULL_VERSION(major, minor, 0, 0, 0)``. The result does not correspond to any Python release, but is useful in numeric comparisons."
-msgstr "معادل ``Py_PACK_FULL_VERSION(major, minor, 0, 0, 0)`` است. نتیجه با هیچ نسخه‌ی انتشار یافته‌ای از پایتون مطابقت ندارد، اما در مقایسه‌های عددی مفید است."
+msgid ""
+"Equivalent to ``Py_PACK_FULL_VERSION(major, minor, 0, 0, 0)``. The result "
+"does not correspond to any Python release, but is useful in numeric "
+"comparisons."
+msgstr ""
+"معادل ``Py_PACK_FULL_VERSION(major, minor, 0, 0, 0)`` است. نتیجه با هیچ "
+"نسخه‌ی انتشار یافته‌ای از پایتون مطابقت ندارد، اما در مقایسه‌های عددی مفید "
+"است."
@@ -139,7 +139,7 @@ msgid "This is a convenience function to raise :exc:`OSError`. If called with *i
 msgstr "این یک تابع کمکی برای پرتاب :exc:`OSError` است. اگر با مقدار ``0`` برای *ierr* فراخوانی شود، به‌جای آن از کد خطایی که فراخوانی :c:func:`!GetLastError` برمی‌گرداند استفاده می‌شود. این تابع برای بازیابی توضیح ویندوز برای کد خطای داده‌شده توسط *ierr* یا :c:func:`!GetLastError`، تابع Win32 یعنی :c:func:`!FormatMessage` را فراخوانی می‌کند؛ سپس یک شیء :exc:`OSError` می‌سازد که ویژگی :attr:`~OSError.winerror` آن روی کد خطا و ویژگی :attr:`~OSError.strerror` آن روی پیام خطای متناظر (گرفته‌شده از :c:func:`!FormatMessage`) تنظیم شده‌اند، و سپس ``PyErr_SetObject(PyExc_OSError, object)`` را فراخوانی می‌کند. این تابع همیشه ``NULL`` را برمی‌گرداند."
 
 msgid "Availability"
-msgstr "دسترسی‌پذیری"
+msgstr "دسترس‌پذیری"
 
 msgid "Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter specifying the exception type to be raised."
 msgstr "مشابه :c:func:`PyErr_SetFromWindowsErr`، با یک پارامتر اضافی برای تعیین نوع استثنایی که باید ایجاد شود."