From 60687cc7283aa6d9781f4cc0f8df0814e9116e80 Mon Sep 17 00:00:00 2001 From: ken Date: Sat, 7 Nov 2026 14:23:19 +0800 Subject: [PATCH 1/2] Translate `howto/free-threading-python.po` Co-Authored-By: Claude Sonnet 5.5 --- howto/free-threading-python.po | 226 +++++++++++++++++++++++++-------- 1 file changed, 171 insertions(+), 55 deletions(-) diff --git a/howto/free-threading-python.po b/howto/free-threading-python.po index 068a64c39ff..2d3b2953997 100644 --- a/howto/free-threading-python.po +++ b/howto/free-threading-python.po @@ -1,15 +1,15 @@ # Copyright (C) 2001 Python Software Foundation # This file is distributed under the same license as the Python package. -# FIRST AUTHOR , YEAR. # -#, fuzzy +# Translators: +# ken71301 , 2026 msgid "" msgstr "" -"Project-Id-Version: Python 3.14\n" +"Project-Id-Version: Python 3.15\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2026-09-26 00:19+0000\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" +"PO-Revision-Date: 2026-11-07 12:00+0800\n" +"Last-Translator: ken71301 \n" "Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" "tw)\n" "Language: zh_TW\n" @@ -31,6 +31,11 @@ msgid "" "programs designed with threading in mind will run faster on multi-core " "hardware." msgstr "" +"從 3.13 版本開始，CPython 支援一種名為\\ :term:`自由執行緒 `\\ 的 Python 建置版本，其中\\ :term:`全域直譯器鎖 ` (GIL) 被停用。自由執行緒的執行方式能讓執行緒在可用的 CPU " +"核心上平行運行，進而充分利用可用的處理能力。雖然並非所有軟體都能自動從中受" +"益，但在設計時已考慮執行緒的程式，在多核心硬體上會執行得更快。" #: ../../howto/free-threading-python.rst:14 msgid "" @@ -38,6 +43,8 @@ msgid "" "module`, may not be ready for use in a free-threaded build, and will re-" "enable the :term:`GIL`." msgstr "" +"部分第三方套件，特別是包含\\ :term:`擴充模組 `\\ 的套件，可" +"能尚未準備好在自由執行緒建置中使用，並會重新啟用 :term:`GIL`。" #: ../../howto/free-threading-python.rst:18 msgid "" @@ -45,12 +52,16 @@ msgid "" "See :ref:`freethreading-extensions-howto` for information on how to write C " "extensions that support the free-threaded build." msgstr "" +"本文件說明自由執行緒對 Python 程式碼的影響。關於如何撰寫支援自由執行緒建置的 " +"C 擴充，請參閱 :ref:`freethreading-extensions-howto`。" #: ../../howto/free-threading-python.rst:24 msgid "" ":pep:`703` – Making the Global Interpreter Lock Optional in CPython for an " "overall description of free-threaded Python." msgstr "" +":pep:`703` – Making the Global Interpreter Lock Optional in CPython，其中有對" +"自由執行緒 Python 的整體描述。" #: ../../howto/free-threading-python.rst:29 msgid "Installation" @@ -62,6 +73,8 @@ msgid "" "optionally support installing free-threaded Python binaries. The installers " "are available at https://www.python.org/downloads/." msgstr "" +"從 Python 3.13 開始，官方的 macOS 和 Windows 安裝程式可選擇性地支援安裝自由執" +"行緒的 Python 二進位檔。安裝程式可在 https://www.python.org/downloads/ 取得。" #: ../../howto/free-threading-python.rst:35 msgid "" @@ -69,24 +82,33 @@ msgid "" "Python `_, a " "community-maintained installation guide for installing free-threaded Python." msgstr "" +"關於其他平台的資訊，請參閱 `Installing a Free-Threaded Python `_，這是由社群維護、用於安裝自由" +"執行緒 Python 的安裝指南。" #: ../../howto/free-threading-python.rst:39 msgid "" "When building CPython from source, the :option:`--disable-gil` configure " "option should be used to build a free-threaded Python interpreter." msgstr "" +"從原始碼建置 CPython 時，應使用 :option:`--disable-gil` configure 選項來建置" +"自由執行緒的 Python 直譯器。" #: ../../howto/free-threading-python.rst:44 msgid "Identifying free-threaded Python" -msgstr "" +msgstr "辨識自由執行緒的 Python" #: ../../howto/free-threading-python.rst:46 msgid "" "To check if the current interpreter supports free-threading, :option:`python " -"-VV <-V>` and :data:`sys.version` contain \"free-threading build\". The new :" -"func:`sys._is_gil_enabled` function can be used to check whether the GIL is " -"actually disabled in the running process." +"-VV <-V>` and :data:`sys.version` contain \"free-threading build\". The " +"new :func:`sys._is_gil_enabled` function can be used to check whether the " +"GIL is actually disabled in the running process." msgstr "" +"要檢查目前的直譯器是否支援自由執行緒，可查看 :option:`python -VV <-V>` " +"與 :data:`sys.version` 是否包含「free-threading build」。新" +"的 :func:`sys._is_gil_enabled` 函式可用來檢查執行中的行程裡 GIL 是否真的被停" +"用。" #: ../../howto/free-threading-python.rst:51 msgid "" @@ -95,10 +117,13 @@ msgid "" "variable is set to ``1``, then the build supports free threading. This is " "the recommended mechanism for decisions related to the build configuration." msgstr "" +"可使用 ``sysconfig.get_config_var(\"Py_GIL_DISABLED\")`` 設定變數來判斷該建置" +"是否支援自由執行緒。若該變數設為 ``1``，則該建置支援自由執行緒。這是在做出與" +"建置設定相關的決策時所建議使用的機制。" #: ../../howto/free-threading-python.rst:58 msgid "The global interpreter lock in free-threaded Python" -msgstr "" +msgstr "自由執行緒 Python 中的全域直譯器鎖" #: ../../howto/free-threading-python.rst:60 msgid "" @@ -106,6 +131,8 @@ msgid "" "enabled at runtime using the environment variable :envvar:`PYTHON_GIL` or " "the command-line option :option:`-X gil`." msgstr "" +"自由執行緒的 CPython 建置支援在執行時，透過環境變數 :envvar:`PYTHON_GIL` 或命" +"令列選項 :option:`-X gil` 選擇性地啟用 GIL。" #: ../../howto/free-threading-python.rst:64 msgid "" @@ -113,12 +140,15 @@ msgid "" "module that is not explicitly marked as supporting free threading. A " "warning will be printed in this case." msgstr "" +"引入未明確標示為支援自由執行緒的 C-API 擴充模組時，GIL 也可能被自動啟用。此情" +"況下會印出一則警告。" #: ../../howto/free-threading-python.rst:68 msgid "" "In addition to individual package documentation, the following websites " "track the status of popular packages support for free threading:" msgstr "" +"除了各套件自己的文件之外，以下網站也追蹤了熱門套件對自由執行緒的支援狀態：" #: ../../howto/free-threading-python.rst:71 msgid "https://py-free-threading.github.io/tracking/" @@ -141,6 +171,10 @@ msgid "" "the GIL. See :ref:`threadsafety` for the guarantees provided by built-in " "types." msgstr "" +"CPython 的自由執行緒建置旨在於 Python 層級提供與預設（啟用 GIL）建置相似的執" +"行緒安全行為。內建型別如 :class:`dict`、:class:`list` 和 :class:`set` 使用內" +"部鎖來防止並行修改，其行為與 GIL 相似。關於內建型別所提供的保證，請參" +"閱 :ref:`threadsafety`。" #: ../../howto/free-threading-python.rst:86 msgid "" @@ -148,6 +182,8 @@ msgid "" "primitives instead of relying on the internal locks of built-in types, when " "possible." msgstr "" +"建議盡可能使用 :class:`threading.Lock` 或其他同步原語，而不是依賴內建型別的內" +"部鎖。" #: ../../howto/free-threading-python.rst:92 msgid "Known limitations" @@ -156,7 +192,7 @@ msgstr "已知限制" #: ../../howto/free-threading-python.rst:94 msgid "" "This section describes known limitations of the free-threaded CPython build." -msgstr "" +msgstr "本節說明自由執行緒 CPython 建置的已知限制。" #: ../../howto/free-threading-python.rst:97 msgid "Immortalization" @@ -169,24 +205,28 @@ msgid "" "modified. This is done to avoid reference count contention that would " "prevent efficient multi-threaded scaling." msgstr "" +"在自由執行緒建置中，部分物件是\\ :term:`不滅的 `。不滅物件不會被釋" +"放，其參照計數也永遠不會被修改。這樣做是為了避免參照計數的競爭 (contention)，" +"否則會妨礙多執行緒的有效擴充 (scaling)。" #: ../../howto/free-threading-python.rst:104 msgid "As of the 3.14 release, immortalization is limited to:" -msgstr "" +msgstr "截至 3.14 版本，不滅化僅限於：" #: ../../howto/free-threading-python.rst:106 msgid "" "Code constants: numeric literals, string literals, and tuple literals " "composed of other constants." msgstr "" +"程式碼常數：數值字面值、字串字面值，以及由其他常數組成的 tuple 字面值。" #: ../../howto/free-threading-python.rst:108 msgid "Strings interned by :func:`sys.intern`." -msgstr "" +msgstr "由 :func:`sys.intern` 駐留 (intern) 的字串。" #: ../../howto/free-threading-python.rst:112 msgid "Frame objects" -msgstr "" +msgstr "Frame 物件" #: ../../howto/free-threading-python.rst:114 msgid "" @@ -194,6 +234,8 @@ msgid "" "objects>` object if that frame is currently executing in another thread, and " "doing so may crash the interpreter." msgstr "" +"若某個 :ref:`frame ` 物件目前正在另一個執行緒中執行，則從該物" +"件存取 :attr:`frame.f_locals` 並不安全，這樣做可能會使直譯器當機。" #: ../../howto/free-threading-python.rst:120 msgid "Iterators" @@ -205,6 +247,8 @@ msgid "" "multiple threads concurrently, and threads may see duplicate or missing " "elements." msgstr "" +"同時從多個執行緒存取同一個疊代器物件通常不是執行緒安全的，執行緒可能會看到重" +"複或遺漏的元素。" #: ../../howto/free-threading-python.rst:128 msgid "Single-threaded performance" @@ -218,49 +262,63 @@ msgid "" "average overhead ranges from about 1% on macOS aarch64 to 8% on x86-64 Linux " "systems." msgstr "" +"與預設（啟用 GIL）的建置相比，自由執行緒建置在執行 Python 程式碼時有額外的開" +"銷。開銷的多寡取決於工作負載與硬體。在 pyperformance 基準測試套件上，平均開銷" +"從 macOS aarch64 上的約 1% 到 x86-64 Linux 系統上的 8% 不等。" #: ../../howto/free-threading-python.rst:138 msgid "Behavioral changes" -msgstr "" +msgstr "行為變更" #: ../../howto/free-threading-python.rst:140 msgid "" "This section describes CPython behavioural changes with the free-threaded " "build." -msgstr "" +msgstr "本節說明自由執行緒建置中 CPython 的行為變更。" #: ../../howto/free-threading-python.rst:145 msgid "Context variables" -msgstr "" +msgstr "情境變數" #: ../../howto/free-threading-python.rst:147 msgid "" -"In the free-threaded build, the flag :data:`~sys.flags." -"thread_inherit_context` is set to true by default which causes threads " -"created with :class:`threading.Thread` to start with a copy of the :class:" -"`~contextvars.Context()` of the caller of :meth:`~threading.Thread.start`. " -"In the default GIL-enabled build, the flag defaults to false so threads " -"start with an empty :class:`~contextvars.Context()`." +"In the free-threaded build, the " +"flag :data:`~sys.flags.thread_inherit_context` is set to true by default " +"which causes threads created with :class:`threading.Thread` to start with a " +"copy of the :class:`~contextvars.Context()` of the caller " +"of :meth:`~threading.Thread.start`. In the default GIL-enabled build, the " +"flag defaults to false so threads start with an " +"empty :class:`~contextvars.Context()`." msgstr "" +"在自由執行緒建置中，旗標 :data:`~sys.flags.thread_inherit_context` 預設為 " +"true，這使得以 :class:`threading.Thread` 建立的執行緒，會" +"以 :meth:`~threading.Thread.start` 呼叫者的 :class:`~contextvars.Context()` " +"副本開始。在預設（啟用 GIL）的建置中，該旗標預設為 false，因此執行緒會以空" +"的 :class:`~contextvars.Context()` 開始。" #: ../../howto/free-threading-python.rst:157 msgid "Warning filters" -msgstr "" +msgstr "警告過濾器" #: ../../howto/free-threading-python.rst:159 msgid "" -"In the free-threaded build, the flag :data:`~sys.flags." -"context_aware_warnings` is set to true by default. In the default GIL-" -"enabled build, the flag defaults to false. If the flag is true then the :" -"class:`warnings.catch_warnings` context manager uses a context variable for " -"warning filters. If the flag is false then :class:`~warnings." -"catch_warnings` modifies the global filters list, which is not thread-safe. " -"See the :mod:`warnings` module for more details." +"In the free-threaded build, the " +"flag :data:`~sys.flags.context_aware_warnings` is set to true by default. " +"In the default GIL-enabled build, the flag defaults to false. If the flag " +"is true then the :class:`warnings.catch_warnings` context manager uses a " +"context variable for warning filters. If the flag is false " +"then :class:`~warnings.catch_warnings` modifies the global filters list, " +"which is not thread-safe. See the :mod:`warnings` module for more details." msgstr "" +"在自由執行緒建置中，旗標 :data:`~sys.flags.context_aware_warnings` 預設為 " +"true。在預設（啟用 GIL）的建置中，該旗標預設為 false。若旗標為 " +"true，:class:`warnings.catch_warnings` 情境管理器會使用情境變數來儲存警告過濾" +"器。若旗標為 false，:class:`~warnings.catch_warnings` 會修改全域過濾器串列，" +"而這不是執行緒安全的。更多細節請參閱 :mod:`warnings` 模組。" #: ../../howto/free-threading-python.rst:168 msgid "Increased memory usage" -msgstr "" +msgstr "記憶體用量增加" #: ../../howto/free-threading-python.rst:170 msgid "" @@ -268,10 +326,12 @@ msgid "" "default build. There are multiple reasons for this, mostly due to design " "decisions." msgstr "" +"與預設建置相比，自由執行緒建置通常會使用更多記憶體。原因有多種，主要來自設計" +"上的取捨。" #: ../../howto/free-threading-python.rst:175 msgid "All interned strings are immortal" -msgstr "" +msgstr "所有被駐留的字串都是不滅的" #: ../../howto/free-threading-python.rst:177 msgid "" @@ -282,25 +342,35 @@ msgid "" "any interned string will become immortal, surviving until interpreter " "shutdown." msgstr "" +"對於現代的 Python 版本（自 2.3 版起），駐留一個字串（例如透" +"過 :func:`sys.intern`）並不會使其成為不滅的。相反地，若指向該字串的最後一個參" +"照消失，它就會從駐留字串表中移除。自由執行緒建置並非如此：任何被駐留的字串都" +"會變成不滅的，並一直存活到直譯器關閉。" #: ../../howto/free-threading-python.rst:185 msgid "Non-GC objects have a larger object header" -msgstr "" +msgstr "非 GC 物件有較大的物件標頭" #: ../../howto/free-threading-python.rst:187 msgid "" "The free-threaded build uses a different :c:type:`PyObject` structure. " -"Instead of having the GC related information allocated before the :c:type:" -"`PyObject` structure, like in the default build, the GC related info is part " -"of the normal object header. For example, on the AMD64 platform, ``None`` " -"uses 32 bytes on the free-threaded build vs 16 bytes for the default build. " -"GC objects (such as dicts and lists) are the same size for both builds since " -"the free-threaded build does not use additional space for the GC info." -msgstr "" +"Instead of having the GC related information allocated before " +"the :c:type:`PyObject` structure, like in the default build, the GC related " +"info is part of the normal object header. For example, on the AMD64 " +"platform, ``None`` uses 32 bytes on the free-threaded build vs 16 bytes for " +"the default build. GC objects (such as dicts and lists) are the same size " +"for both builds since the free-threaded build does not use additional space " +"for the GC info." +msgstr "" +"自由執行緒建置使用不同的 :c:type:`PyObject` 結構。與預設建置中將 GC 相關資訊" +"配置於 :c:type:`PyObject` 結構之前不同，自由執行緒建置中的 GC 相關資訊是一般" +"物件標頭的一部分。例如在 AMD64 平台上，``None`` 在自由執行緒建置中使用 32 位" +"元組，而在預設建置中是 16 位元組。GC 物件（例如 dict 和 list）在兩種建置中的" +"大小相同，因為自由執行緒建置不會為 GC 資訊使用額外的空間。" #: ../../howto/free-threading-python.rst:197 msgid "QSBR can delay freeing of memory" -msgstr "" +msgstr "QSBR 可能延遲記憶體的釋放" #: ../../howto/free-threading-python.rst:199 msgid "" @@ -309,17 +379,26 @@ msgid "" "(QSBR). This means that the memory backing data structures allowing lock-" "free access will use QSBR, which defers the free operation, rather than " "immediately freeing the memory. Two examples of these data structures are " -"the list object and the dictionary keys object. See ``InternalDocs/qsbr." -"md`` in the CPython source tree for more details on how QSBR is " +"the list object and the dictionary keys object. See ``InternalDocs/" +"qsbr.md`` in the CPython source tree for more details on how QSBR is " "implemented. Running :func:`gc.collect` should cause all memory being held " "by QSBR to be actually freed. Note that even when QSBR frees the memory, " "the underlying memory allocator may not immediately return that memory to " "the OS and so the resident set size (RSS) of the process might not decrease." msgstr "" +"為了安全地實作無鎖 (lock-free) 資料結構，會使用一種稱為基於靜止狀態的回收 " +"(quiescent state-based reclamation, QSBR) 的安全記憶體回收 (safe memory " +"reclamation, SMR) 機制。這表示支援無鎖存取的資料結構所使用的記憶體會採用 " +"QSBR，它會延後釋放操作，而不是立即釋放記憶體。這類資料結構的兩個例子是 list " +"物件與字典鍵 (dictionary keys) 物件。關於 QSBR 如何實作的更多細節，請參閱 " +"CPython 原始碼樹中的 ``InternalDocs/qsbr.md``。執行 :func:`gc.collect` 應該會" +"使 QSBR 持有的所有記憶體被實際釋放。請注意，即使 QSBR 已釋放記憶體，底層的記" +"憶體配置器也不一定會立即將該記憶體歸還給作業系統，因此行程的常駐集大小 " +"(resident set size, RSS) 可能不會減少。" #: ../../howto/free-threading-python.rst:213 msgid "mimalloc allocator vs pymalloc" -msgstr "" +msgstr "mimalloc 配置器與 pymalloc" #: ../../howto/free-threading-python.rst:215 msgid "" @@ -332,6 +411,11 @@ msgid "" "system. The mimalloc allocator does quite well in these respects as well " "but can have some more overhead." msgstr "" +"預設建置通常會對小型配置（512 位元組或更小）使用「pymalloc」記憶體配置器。自" +"由執行緒建置不使用 pymalloc，而是以「mimalloc」配置器配置所有 Python 物件。" +"pymalloc 配置器具有以下有助於維持低記憶體用量的特性：每個配置區塊的額外開銷" +"小、能有效防止記憶體碎片化，以及能快速將空閒記憶體歸還給作業系統。mimalloc 配" +"置器在這些方面也表現得相當不錯，但可能有稍多的額外開銷。" #: ../../howto/free-threading-python.rst:224 msgid "" @@ -345,6 +429,13 @@ msgid "" "blocks for a page being freed and the memory page being released, either for " "new allocations or back to the OS." msgstr "" +"在自由執行緒建置中，mimalloc 將記憶體管理於數個獨立的堆積 (heap) 中（目前為四" +"個）。例如，所有支援 GC 的物件都從各自專屬的堆積中配置。使用獨立堆積意味著某" +"個堆積中的空閒記憶體無法用於使用另一個堆積的配置。此外，部分堆積在釋放支撐該" +"堆積的記憶體（在 mimalloc 術語中稱為「頁面 (pages)」）時，會設定為使用 QSBR" +"（基於靜止狀態的回收）。使用 QSBR 會造成延遲：一個頁面的所有記憶體區塊被釋放" +"之後，到該記憶體頁面被釋放（無論是供新的配置使用，或是歸還給作業系統）之間會" +"有一段延遲。" #: ../../howto/free-threading-python.rst:234 msgid "" @@ -353,10 +444,13 @@ msgid "" "MIMALLOC_PURGE_DELAY` to ``0``. Note that this will likely reduce the " "performance of the allocator." msgstr "" +"mimalloc 配置器同樣會延後將已釋放的記憶體歸還給作業系統。你可以將環境變" +"數 :envvar:`!MIMALLOC_PURGE_DELAY` 設為 ``0`` 來減少該延遲。請注意，這很可能" +"會降低配置器的效能。" #: ../../howto/free-threading-python.rst:241 msgid "Free-threaded reference counting can cause objects to live longer" -msgstr "" +msgstr "自由執行緒的參照計數可能使物件存活更久" #: ../../howto/free-threading-python.rst:243 msgid "" @@ -368,6 +462,11 @@ msgid "" "can be deferred. The queued state is cleared from the \"eval breaker\" " "section of the bytecode evaluator." msgstr "" +"在預設建置中，當物件的參照計數降為零時，通常會被釋放。自由執行緒建置使用「偏" +"向參照計數 (biased reference counting)」，對由目前執行緒「擁有」的物件走快速" +"路徑，對其他物件則走慢速路徑。更多細節請參閱 :pep:`703`。每當物件的參照計數處" +"於「已佇列 (queued)」狀態時，釋放操作就可能被延後。已佇列狀態會在位元組碼求值" +"器的「eval breaker」區段中被清除。" #: ../../howto/free-threading-python.rst:251 msgid "" @@ -376,26 +475,29 @@ msgid "" "flag on a per-object basis. Deferred reference counting is enabled for the " "following types:" msgstr "" +"自由執行緒建置也允許另一種參照計數模式，稱為「延遲參照計數 (deferred " +"reference counting)」。此模式透過在每個物件上設定旗標來啟用。延遲參照計數會對" +"以下型別啟用：" #: ../../howto/free-threading-python.rst:256 msgid "module objects" -msgstr "" +msgstr "模組物件" #: ../../howto/free-threading-python.rst:257 msgid "module top-level functions" -msgstr "" +msgstr "模組的頂層函式" #: ../../howto/free-threading-python.rst:258 msgid "class methods defined in the class scope" -msgstr "" +msgstr "在類別作用域中定義的類別方法" #: ../../howto/free-threading-python.rst:259 msgid "descriptor objects" -msgstr "" +msgstr "描述器物件" #: ../../howto/free-threading-python.rst:260 msgid "thread-local objects, created by :class:`threading.local`" -msgstr "" +msgstr "由 :class:`threading.local` 建立的執行緒局部物件" #: ../../howto/free-threading-python.rst:262 msgid "" @@ -409,10 +511,15 @@ msgid "" "objects are freed by the GC and not when their reference count goes to zero, " "as is typical." msgstr "" +"啟用延遲參照計數時，來自 Python 函式堆疊的參照不會被加入參照計數。此機制降低" +"了參照計數的開銷，特別是對於被多個執行緒使用的物件。由於堆疊參照不被計入，使" +"用延遲參照計數的物件在其內部參照計數降為零時不會立即被釋放。相反地，它們會在" +"下一次 GC 執行時被檢查，若找不到指向它們的堆疊參照，才會被釋放。這表示這些物" +"件是由 GC 釋放，而不是像一般情況那樣在參照計數降為零時釋放。" #: ../../howto/free-threading-python.rst:273 msgid "Per-thread reference counting can delay freeing objects" -msgstr "" +msgstr "執行緒各自的參照計數可能延遲物件的釋放" #: ../../howto/free-threading-python.rst:275 msgid "" @@ -424,18 +531,23 @@ msgid "" "only computed by summing the per-thread counts when the object's local count " "drops to zero. Per-thread reference counting is currently used for:" msgstr "" +"為避免經常被共享的物件的參照計數欄位發生競爭，自由執行緒建置也對少數選定的物" +"件型別使用「執行緒各自的參照計數 (per-thread reference counting)」。每個執行" +"緒不是更新單一共享的參照計數，而是維護自己的區域參照計數陣列，並以指派給該物" +"件的唯一 id 作為索引。只有當物件的區域計數降為零時，才會加總各執行緒的計數來" +"算出真正的參照計數。目前使用此機制的有：" #: ../../howto/free-threading-python.rst:283 msgid "heap type objects (classes created in Python)" -msgstr "" +msgstr "堆積型別物件（在 Python 中建立的類別）" #: ../../howto/free-threading-python.rst:284 msgid "code objects" -msgstr "" +msgstr "程式碼物件" #: ../../howto/free-threading-python.rst:285 msgid "the ``__dict__`` of module objects" -msgstr "" +msgstr "模組物件的 ``__dict__``" #: ../../howto/free-threading-python.rst:287 msgid "" @@ -447,3 +559,7 @@ msgid "" "section of the bytecode evaluator) or exits. Running :func:`gc.collect` " "will merge the per-thread counts and allow these objects to be freed." msgstr "" +"由於在物件被釋放之前，必須先將各執行緒的計數合併回該物件，使用此機制的物件通" +"常會比在預設建置中更晚被釋放。尤其是，這類物件通常要等到參照它的執行緒到達安" +"全點（例如在位元組碼求值器的「eval breaker」區段中）或結束後才會被釋放。執" +"行 :func:`gc.collect` 會合併各執行緒的計數，並讓這些物件得以被釋放。" From 3d465d124c225a7b9172abca15e66e135a35e0d0 Mon Sep 17 00:00:00 2001 From: ken Date: Sat, 7 Nov 2026 16:45:51 +0800 Subject: [PATCH 2/2] docs(translate-po): clarify role spacing and parentheses rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Use a plain space before roles that render Latin text (:ref:, :mod:, :func:, :class:); `\ ` removes the required CJK-Latin space. Keep `\ ` only for roles that render Chinese. - Fix examples that taught `參閱\ :mod:` as the default. - Add the parentheses rule: English-only brackets are half-width with spaces, Chinese content uses full-width; annotate a term on first use. Co-Authored-By: Claude Sonnet 5.5 --- .claude/skills/translate-po/SKILL.md | 13 ++++++-- .../translate-po/references/rst-cheatsheet.md | 31 +++++++++++++++++-- 2 files changed, 38 insertions(+), 6 deletions(-) diff --git a/.claude/skills/translate-po/SKILL.md b/.claude/skills/translate-po/SKILL.md index 0c8b21e000b..ef9d36e7f6d 100644 --- a/.claude/skills/translate-po/SKILL.md +++ b/.claude/skills/translate-po/SKILL.md @@ -34,6 +34,10 @@ Identify content type: - Add space between Chinese and Latin: "使用 CPU 運算" (correct) - No space with symbols: "使用「CPU」運算" (correct) +**Parentheses:** Chinese inside -> full-width `（）`; English only inside -> +half-width with spaces around, e.g. "全域直譯器鎖 (GIL) 被停用". Annotate a term +only at its first occurrence on the page. + **Line Width:** Max 79 characters (use multi-line format for longer text) ### Step 3: reST Handling @@ -43,7 +47,9 @@ See `references/rst-cheatsheet.md` for complete rules. **Key patterns:** - `:mod:`os`` -> Keep unchanged - `:term:`iterator`` -> `:term:`疊代器 `` -- Chinese before role: "參閱\\ :mod:`os`" +- Role renders Latin (`:mod:`, `:func:`, `:class:`, `:ref:` without a title): plain space, "參閱 :mod:`os`" +- Role renders Chinese (`:term:`/`:ref:` with a translated title): `\\ ` separator, "一個\\ :term:`情境管理器 `" +- `\\ ` renders as nothing, so never put it before a role that renders Latin (it removes the required CJK-Latin space). See `references/rst-cheatsheet.md` - After `::` markers: "範例： ::" ### Step 4: Terminology Workflow @@ -67,7 +73,8 @@ For uncertain translations, add `#, fuzzy` flag before the entry. Before outputting, verify: - [ ] Line length <= 79 characters - [ ] Full-width punctuation in Chinese text -- [ ] CJK-Latin spacing correct +- [ ] CJK-Latin spacing correct (also across roles: no `\\ ` before roles that render Latin) +- [ ] Parentheses: English-only content uses half-width `( )` with spaces - [ ] reST syntax preserved - [ ] Terminology matches glossary - [ ] No forbidden zh_CN terms @@ -89,7 +96,7 @@ msgstr "此函式回傳一個疊代器。" ### With reST Role ``` msgid "See :func:`len` for details." -msgstr "詳情請參閱\\ :func:`len`。" +msgstr "詳情請參閱 :func:`len`。" ``` ### With Link diff --git a/.claude/skills/translate-po/references/rst-cheatsheet.md b/.claude/skills/translate-po/references/rst-cheatsheet.md index d651eb08ba5..26d201462ae 100644 --- a/.claude/skills/translate-po/references/rst-cheatsheet.md +++ b/.claude/skills/translate-po/references/rst-cheatsheet.md @@ -38,15 +38,17 @@ Rules for preserving reStructuredText syntax in translations. ## Backslash Escaping -Use `\\ ` (backslash-backslash-space) as zero-width separator: +`\\ ` (backslash-backslash-space) is a zero-width separator. It is needed where +reST requires a boundary but no visible space is wanted (see the table below +for when a plain space is the right choice instead): -### CJK Before Role +### CJK Before Role (only if the role renders Chinese) ``` # Wrong 參閱:mod:`os`模組 # Correct -參閱\\ :mod:`os` 模組 +參閱 :mod:`os` 模組 ``` ### CJK After Link @@ -58,6 +60,29 @@ Use `\\ ` (backslash-backslash-space) as zero-width separator: `連結 `_\\ 中 ``` +### Rendered Text Decides: `\\ ` or a Space + +`\\ ` renders as nothing, so it removes the space the CJK-Latin rule requires. +Choose by what the role *renders*, not by how the source looks: + +| Role renders | Use | Example | +|--------------|-----|---------| +| Chinese (`:term:` with a translated display text) | `\\ ` | `包含\\ :term:`擴充模組 `\\ 的套件` | +| Latin (`:ref:`/`:doc:` with no explicit title, which shows the target's English section title; `:mod:`, `:func:`, `:class:`, etc.) | a plain space | `請參閱 :ref:`threadsafety`。` | + +``` +# Wrong: renders "請參閱C API Extension Support for Free Threading" +請參閱\\ :ref:`freethreading-extensions-howto`。 + +# Correct: renders "請參閱 C API Extension Support for Free Threading" +請參閱 :ref:`freethreading-extensions-howto`。 +``` + +For `:ref:`/`:doc:` without an explicit title, the rendered text is the +target page's title, which is often still English, so check the rendered page. +A role with a translated title (`:ref:`詳細說明 ``) renders +Chinese, so `\\ ` applies. + ### Full-width Punctuation After Role ``` # May break build