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>

Author: mattwang44

c-api/profiling.po

@@ -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,18 +39,25 @@ 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 ""
 "The type of the trace function registered using :c:func:`PyEval_SetProfile` "
 "and :c:func:`PyEval_SetTrace`. The first parameter is the object passed to "
 "the registration function as *obj*, *frame* is the frame object to which the "
-"event pertains, *what* is one of the constants :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`, or :c:data:`PyTrace_OPCODE`, and *arg* depends on the "
-"value of *what*:"
+"event pertains, *what* is one of the "
+"constants :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`, "
+"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 +82,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 +95,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 +126,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,56 +142,79 @@ 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 ""
 "The value passed as the *what* parameter to a :c:type:`Py_tracefunc` "
 "function (but not a profiling function) when a line-number event is being "
-"reported. It may be disabled for a frame by setting :attr:`~frame."
-"f_trace_lines` to *0* on that frame."
+"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 ""
 "The value for the *what* parameter to :c:type:`Py_tracefunc` functions (but "
 "not profiling functions) when a new opcode is about to be executed.  This "
-"event is not emitted by default: it must be explicitly requested by setting :"
-"attr:`~frame.f_trace_opcodes` to *1* on the frame."
+"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 ""
 "Set the profiler function to *func*.  The *obj* parameter is passed to the "
 "function as its first parameter, and may be any Python object, or ``NULL``.  "
 "If the profile function needs to maintain state, using a different value for "
 "*obj* for each thread provides a convenient and thread-safe place to store "
-"it.  The profile function is called for all monitored events except :c:data:"
-"`PyTrace_LINE` :c:data:`PyTrace_OPCODE` and :c:data:`PyTrace_EXCEPTION`."
+"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,23 +231,32 @@ 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 ""
-"Set the tracing function to *func*.  This is similar to :c:func:"
-"`PyEval_SetProfile`, except the tracing function does receive line-number "
-"events and per-opcode events, but does not receive any event related to C "
-"function objects being called.  Any trace function registered using :c:func:"
-"`PyEval_SetTrace` will not receive :c:data:`PyTrace_C_CALL`, :c:data:"
-"`PyTrace_C_EXCEPTION` or :c:data:`PyTrace_C_RETURN` as a value for the "
-"*what* parameter."
+"Set the tracing function to *func*.  This is similar "
+"to :c:func:`PyEval_SetProfile`, except the tracing function does receive "
+"line-number events and per-opcode events, but does not receive any event "
+"related to C function objects being called.  Any trace function registered "
+"using :c:func:`PyEval_SetTrace` will not "
+"receive :c:data:`PyTrace_C_CALL`, :c:data:`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,26 +268,35 @@ 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"
 msgstr "參照追蹤"
 
 #: ../../c-api/profiling.rst:174
 msgid ""
-"The type of the trace function registered using :c:func:"
-"`PyRefTracer_SetTracer`. The first parameter is a Python object that has "
-"been just created (when **event** is set to :c:data:`PyRefTracer_CREATE`) or "
-"about to be destroyed (when **event** is set to :c:data:"
-"`PyRefTracer_DESTROY`). The **data** argument is the opaque pointer that was "
-"provided when :c:func:`PyRefTracer_SetTracer` was called."
+"The type of the trace function registered "
+"using :c:func:`PyRefTracer_SetTracer`. The first parameter is a Python "
+"object that has been just created (when **event** is set "
+"to :c:data:`PyRefTracer_CREATE`) or about to be destroyed (when **event** is "
+"set to :c:data:`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 +305,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 +341,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,18 +353,23 @@ 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 ""
 "If another tracer function was already registered, the old function will be "
 "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 +378,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。"