From 1064c7800ab49d2c7fa03229671f1755cd1e32db Mon Sep 17 00:00:00 2001
From: mattwang44 <mattwang44@gmail.com>
Date: Sun, 7 Jun 2026 00:13:28 +0800
Subject: [PATCH] Translate c-api/profiling.po

Translate the previously-untranslated entries of the C-API profiling and
tracing support documentation into Traditional Chinese, following project
terminology and reST conventions.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 c-api/profiling.po | 84 +++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 80 insertions(+), 4 deletions(-)

diff --git a/c-api/profiling.po b/c-api/profiling.po
index 9ac7800fbea..65f1197245f 100644
--- a/c-api/profiling.po
+++ b/c-api/profiling.po
@@ -19,7 +19,7 @@ msgstr ""
 
 #: ../../c-api/profiling.rst:6
 msgid "Profiling and tracing"
-msgstr "性能分析與追蹤"
+msgstr "效能分析與追蹤"
 
 #: ../../c-api/profiling.rst:8
 msgid ""
@@ -27,6 +27,8 @@ msgid ""
 "profiling and execution tracing facilities.  These are used for profiling, "
 "debugging, and coverage analysis tools."
 msgstr ""
+"Python 直譯器提供了一些底層支援，用於附加效能分析與執行追蹤的機制。這些功能會"
+"被用於效能分析、除錯以及覆蓋率分析工具。"
 
 #: ../../c-api/profiling.rst:12
 msgid ""
@@ -37,6 +39,10 @@ msgid ""
 "basic events reported to the trace function are the same as had been "
 "reported to the Python-level trace functions in previous versions."
 msgstr ""
+"此 C 介面讓效能分析或追蹤的程式碼能夠避免透過 Python 層級的可呼叫物件進行呼叫"
+"所帶來的開銷，而是改為直接進行 C 函式呼叫。此機制的基本屬性並未改變；該介面允"
+"許追蹤函式以每執行緒（per-thread）為單位安裝，而回報給追蹤函式的基本事件，與"
+"先前版本中回報給 Python 層級追蹤函式的事件相同。"
 
 #: ../../c-api/profiling.rst:22
 msgid ""
@@ -49,6 +55,11 @@ msgid ""
 "`PyTrace_C_RETURN`, or :c:data:`PyTrace_OPCODE`, and *arg* depends on the "
 "value of *what*:"
 msgstr ""
+"使用 :c:func:`PyEval_SetProfile` 和 :c:func:`PyEval_SetTrace` 註冊的追蹤函式"
+"的型別。第一個參數是作為 *obj* 傳遞給註冊函式的物件，*frame* 是該事件所屬的框"
+"架（frame）物件，*what* 是常"
+"數 :c:data:`PyTrace_CALL`、:c:data:`PyTrace_EXCEPTION`、:c:data:`PyTrace_LINE`、:c:data:`PyTrace_RETURN`、:c:data:`PyTrace_C_CALL`、:c:data:`PyTrace_C_EXCEPTION`、:c:data:`PyTrace_C_RETURN` "
+"或 :c:data:`PyTrace_OPCODE` 其中之一，而 *arg* 則取決於 *what* 的值："
 
 #: ../../c-api/profiling.rst:31
 msgid "Value of *what*"
@@ -73,7 +84,7 @@ msgstr ":c:data:`PyTrace_EXCEPTION`"
 
 #: ../../c-api/profiling.rst:35
 msgid "Exception information as returned by :func:`sys.exc_info`."
-msgstr ""
+msgstr "由 :func:`sys.exc_info` 回傳的例外資訊。"
 
 #: ../../c-api/profiling.rst:38
 msgid ":c:data:`PyTrace_LINE`"
@@ -86,7 +97,7 @@ msgstr ":c:data:`PyTrace_RETURN`"
 #: ../../c-api/profiling.rst:40
 msgid ""
 "Value being returned to the caller, or ``NULL`` if caused by an exception."
-msgstr ""
+msgstr "回傳給呼叫者的值，若是由例外所引起則為 ``NULL``。"
 
 #: ../../c-api/profiling.rst:43
 msgid ":c:data:`PyTrace_C_CALL`"
@@ -117,6 +128,10 @@ msgid ""
 "is not reported as there is no control transfer to the Python bytecode in "
 "the corresponding frame."
 msgstr ""
+"當回報一個對函式或方法的新呼叫，或進入產生器的新進入點時，傳遞"
+"給 :c:type:`Py_tracefunc` 函式的 *what* 參數的值。請注意，產生器函式的疊代器"
+"之建立並不會被回報，因為在對應的框架（frame）中並沒有控制權轉移到 Python 位元"
+"組碼。"
 
 #: ../../c-api/profiling.rst:63
 msgid ""
@@ -129,6 +144,11 @@ msgid ""
 "Only trace functions receive these events; they are not needed by the "
 "profiler."
 msgstr ""
+"當例外被引發時，傳遞給 :c:type:`Py_tracefunc` 函式的 *what* 參數的值。在任何"
+"位元組碼被處理後，若例外在正在執行的框架（frame）內被設定，回呼函式就會以此 "
+"*what* 值被呼叫。其效果是，當例外傳播導致 Python 堆疊回溯（unwind）時，隨著例"
+"外傳播，每當返回到各個框架時就會呼叫該回呼。只有追蹤函式會收到這些事件；效能"
+"分析器並不需要它們。"
 
 #: ../../c-api/profiling.rst:74
 msgid ""
@@ -137,30 +157,39 @@ msgid ""
 "reported. It may be disabled for a frame by setting :attr:`~frame."
 "f_trace_lines` to *0* on that frame."
 msgstr ""
+"當回報一個列號（line-number）事件時，傳遞給 :c:type:`Py_tracefunc` 函式（但非"
+"效能分析函式）的 *what* 參數的值。可藉由將該框架（frame）上"
+"的 :attr:`~frame.f_trace_lines` 設為 *0* 來為該框架停用它。"
 
 #: ../../c-api/profiling.rst:82
 msgid ""
 "The value for the *what* parameter to :c:type:`Py_tracefunc` functions when "
 "a call is about to return."
 msgstr ""
+"當一個呼叫即將回傳時，傳遞給 :c:type:`Py_tracefunc` 函式的 *what* 參數的值。"
 
 #: ../../c-api/profiling.rst:88
 msgid ""
 "The value for the *what* parameter to :c:type:`Py_tracefunc` functions when "
 "a C function is about to be called."
 msgstr ""
+"當一個 C 函式即將被呼叫時，傳遞給 :c:type:`Py_tracefunc` 函式的 *what* 參數的"
+"值。"
 
 #: ../../c-api/profiling.rst:94
 msgid ""
 "The value for the *what* parameter to :c:type:`Py_tracefunc` functions when "
 "a C function has raised an exception."
 msgstr ""
+"當一個 C 函式已引發例外時，傳遞給 :c:type:`Py_tracefunc` 函式的 *what* 參數的"
+"值。"
 
 #: ../../c-api/profiling.rst:100
 msgid ""
 "The value for the *what* parameter to :c:type:`Py_tracefunc` functions when "
 "a C function has returned."
 msgstr ""
+"當一個 C 函式已回傳時，傳遞給 :c:type:`Py_tracefunc` 函式的 *what* 參數的值。"
 
 #: ../../c-api/profiling.rst:106
 msgid ""
@@ -169,6 +198,9 @@ msgid ""
 "event is not emitted by default: it must be explicitly requested by setting :"
 "attr:`~frame.f_trace_opcodes` to *1* on the frame."
 msgstr ""
+"當一個新的運算碼（opcode）即將被執行時，傳遞給 :c:type:`Py_tracefunc` 函式"
+"（但非效能分析函式）的 *what* 參數的值。此事件預設不會被發出：它必須藉由將該"
+"框架（frame）上的 :attr:`~frame.f_trace_opcodes` 設為 *1* 來明確地請求。"
 
 #: ../../c-api/profiling.rst:114
 msgid ""
@@ -179,6 +211,11 @@ msgid ""
 "it.  The profile function is called for all monitored events except :c:data:"
 "`PyTrace_LINE` :c:data:`PyTrace_OPCODE` and :c:data:`PyTrace_EXCEPTION`."
 msgstr ""
+"將效能分析器函式設為 *func*。*obj* 參數會作為函式的第一個參數傳遞，且可以是任"
+"何 Python 物件或 ``NULL``。如果效能分析函式需要維護狀態，為每個執行緒的 "
+"*obj* 使用不同的值，能提供一個方便且執行緒安全的儲存位置。效能分析函式會針對"
+"所有被監控的事件被呼叫，但 :c:data:`PyTrace_LINE`、:c:data:`PyTrace_OPCODE` "
+"和 :c:data:`PyTrace_EXCEPTION` 除外。"
 
 #: ../../c-api/profiling.rst:121
 msgid "See also the :func:`sys.setprofile` function."
@@ -195,12 +232,16 @@ msgid ""
 "running threads belonging to the current interpreter instead of the setting "
 "it only on the current thread."
 msgstr ""
+"與 :c:func:`PyEval_SetProfile` 類似，但會在所有屬於目前直譯器的執行中執行緒上"
+"設定效能分析函式，而非僅在目前的執行緒上設定。"
 
 #: ../../c-api/profiling.rst:133
 msgid ""
 "As :c:func:`PyEval_SetProfile`, this function ignores any exceptions raised "
 "while setting the profile functions in all threads."
 msgstr ""
+"如同 :c:func:`PyEval_SetProfile`，此函式會忽略在所有執行緒上設定效能分析函式"
+"時所引發的任何例外。"
 
 #: ../../c-api/profiling.rst:141
 msgid ""
@@ -212,6 +253,11 @@ msgid ""
 "`PyTrace_C_EXCEPTION` or :c:data:`PyTrace_C_RETURN` as a value for the "
 "*what* parameter."
 msgstr ""
+"將追蹤函式設為 *func*。這與 :c:func:`PyEval_SetProfile` 類似，差別在於追蹤函"
+"式確實會收到列號（line-number）事件與逐運算碼（per-opcode）事件，但不會收到任"
+"何與被呼叫的 C 函式物件相關的事件。任何使用 :c:func:`PyEval_SetTrace` 註冊的"
+"追蹤函式都不會收到 :c:data:`PyTrace_C_CALL`、:c:data:`PyTrace_C_EXCEPTION` "
+"或 :c:data:`PyTrace_C_RETURN` 作為 *what* 參數的值。"
 
 #: ../../c-api/profiling.rst:148
 msgid "See also the :func:`sys.settrace` function."
@@ -223,12 +269,16 @@ msgid ""
 "threads belonging to the current interpreter instead of the setting it only "
 "on the current thread."
 msgstr ""
+"與 :c:func:`PyEval_SetTrace` 類似，但會在所有屬於目前直譯器的執行中執行緒上設"
+"定追蹤函式，而非僅在目前的執行緒上設定。"
 
 #: ../../c-api/profiling.rst:160
 msgid ""
 "As :c:func:`PyEval_SetTrace`, this function ignores any exceptions raised "
 "while setting the trace functions in all threads."
 msgstr ""
+"如同 :c:func:`PyEval_SetTrace`，此函式會忽略在所有執行緒上設定追蹤函式時所引"
+"發的任何例外。"
 
 #: ../../c-api/profiling.rst:167
 msgid "Reference tracing"
@@ -243,6 +293,11 @@ msgid ""
 "`PyRefTracer_DESTROY`). The **data** argument is the opaque pointer that was "
 "provided when :c:func:`PyRefTracer_SetTracer` was called."
 msgstr ""
+"使用 :c:func:`PyRefTracer_SetTracer` 註冊的追蹤函式的型別。第一個參數是一個剛"
+"被建立（當 **event** 設為 :c:data:`PyRefTracer_CREATE` 時）或即將被銷毀（當 "
+"**event** 設為 :c:data:`PyRefTracer_DESTROY` 時）的 Python 物件。**data** 引"
+"數是呼叫 :c:func:`PyRefTracer_SetTracer` 時所提供的不透明指標（opaque "
+"pointer）。"
 
 #: ../../c-api/profiling.rst:180
 msgid ""
@@ -251,24 +306,33 @@ msgid ""
 "**event** set to :c:data:`PyRefTracer_TRACKER_REMOVED`. This will happen "
 "just before the new function is registered."
 msgstr ""
+"如果註冊了一個新的追蹤函式來取代目前的追蹤函式，將會對追蹤函式進行一次呼叫，"
+"其中物件設為 **NULL**、**event** 設為 :c:data:`PyRefTracer_TRACKER_REMOVED`。"
+"這會在新函式被註冊之前發生。"
 
 #: ../../c-api/profiling.rst:190
 msgid ""
 "The value for the *event* parameter to :c:type:`PyRefTracer` functions when "
 "a Python object has been created."
 msgstr ""
+"當一個 Python 物件已被建立時，傳遞給 :c:type:`PyRefTracer` 函式的 *event* 參"
+"數的值。"
 
 #: ../../c-api/profiling.rst:196
 msgid ""
 "The value for the *event* parameter to :c:type:`PyRefTracer` functions when "
 "a Python object has been destroyed."
 msgstr ""
+"當一個 Python 物件已被銷毀時，傳遞給 :c:type:`PyRefTracer` 函式的 *event* 參"
+"數的值。"
 
 #: ../../c-api/profiling.rst:202
 msgid ""
 "The value for the *event* parameter to :c:type:`PyRefTracer` functions when "
 "the current tracer is about to be replaced by a new one."
 msgstr ""
+"當目前的追蹤器即將被一個新的追蹤器取代時，傳遞給 :c:type:`PyRefTracer` 函式"
+"的 *event* 參數的值。"
 
 #: ../../c-api/profiling.rst:210
 msgid ""
@@ -278,6 +342,10 @@ msgid ""
 "when the tracer function is called. Return ``0`` on success. Set an "
 "exception and return ``-1`` on error."
 msgstr ""
+"註冊一個參照追蹤器函式。當一個新的 Python 物件已被建立，或當一個物件即將被銷"
+"毀時，該函式就會被呼叫。如果有提供 **data**，它必須是一個不透明指標（opaque "
+"pointer），會在追蹤器函式被呼叫時提供。成功時回傳 ``0``。錯誤時設定一個例外並"
+"回傳 ``-1``。"
 
 #: ../../c-api/profiling.rst:216
 msgid ""
@@ -286,11 +354,14 @@ msgid ""
 "any existing exception or set an exception.  A :term:`thread state` will be "
 "active every time the tracer function is called."
 msgstr ""
+"請注意，追蹤器函式 **不可以** 在內部建立 Python 物件，否則該呼叫將會是可重入"
+"的（re-entrant）。追蹤器也 **不可以** 清除任何既有的例外或設定例外。每次呼叫"
+"追蹤器函式時，都會有一個 :term:`執行緒狀態 <thread state>` 處於作用中。"
 
 #: ../../c-api/profiling.rst:221 ../../c-api/profiling.rst:237
 msgid ""
 "There must be an :term:`attached thread state` when calling this function."
-msgstr ""
+msgstr "呼叫此函式時必須有一個 :term:`attached thread state`。"
 
 #: ../../c-api/profiling.rst:223
 msgid ""
@@ -298,6 +369,8 @@ msgid ""
 "called with **event** set to :c:data:`PyRefTracer_TRACKER_REMOVED` just "
 "before the new function is registered."
 msgstr ""
+"如果先前已註冊了另一個追蹤器函式，則在新函式被註冊之前，舊函式會以 **event** "
+"設為 :c:data:`PyRefTracer_TRACKER_REMOVED` 的方式被呼叫。"
 
 #: ../../c-api/profiling.rst:232
 msgid ""
@@ -306,3 +379,6 @@ msgid ""
 "called. If no tracer was registered this function will return NULL and will "
 "set the **data** pointer to NULL."
 msgstr ""
+"取得已註冊的參照追蹤器函式，以及呼叫 :c:func:`PyRefTracer_SetTracer` 時所註冊"
+"的不透明資料指標（opaque data pointer）的值。如果沒有註冊任何追蹤器，此函式將"
+"回傳 NULL 並會將 **data** 指標設為 NULL。"