From ca2bf6ebcca2af52998e2b69c3932fc78960dee4 Mon Sep 17 00:00:00 2001
From: rockleona <rockleonjp@gmail.com>
Date: Wed, 8 Nov 2023 17:50:21 +0800
Subject: [PATCH 1/3] Finish Translation

---
 howto/annotations.po | 118 ++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 105 insertions(+), 13 deletions(-)

diff --git a/howto/annotations.po b/howto/annotations.po
index 95c2191a3a..fd52ccecaf 100644
--- a/howto/annotations.po
+++ b/howto/annotations.po
@@ -8,18 +8,19 @@ msgstr ""
 "Project-Id-Version: Python 3.12\n"
 "Report-Msgid-Bugs-To: \n"
 "POT-Creation-Date: 2022-12-25 00:16+0000\n"
-"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
-"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"PO-Revision-Date: 2023-11-08 17:20+0800\n"
+"Last-Translator: \n"
 "Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-"
 "tw)\n"
 "Language: zh_TW\n"
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=UTF-8\n"
 "Content-Transfer-Encoding: 8bit\n"
+"X-Generator: Poedit 3.4\n"
 
 #: ../../howto/annotations.rst:5
 msgid "Annotations Best Practices"
-msgstr ""
+msgstr "註釋 (annotation) 最佳實踐"
 
 #: ../../howto/annotations.rst:0
 msgid "author"
@@ -40,6 +41,9 @@ msgid ""
 "``__annotations__`` on Python objects, we encourage you to follow the "
 "guidelines described below."
 msgstr ""
+"本文件旨在封裝 (encapsulate) 使用註釋字典 (annotations dicts) 的最佳實踐。如"
+"果你寫 Python 程式碼並在調查 Python 物件上的 ``__annotations__`` ，我們鼓勵你"
+"遵循下面描述的準則。"
 
 #: ../../howto/annotations.rst:16
 msgid ""
@@ -49,6 +53,10 @@ msgid ""
 "and older, other best practices for ``__annotations__`` that apply to any "
 "Python version, and quirks of ``__annotations__``."
 msgstr ""
+"本文件分為四個部分：在 Python 3.10 及更高版本中存取物件註釋的最佳實踐、在 "
+"Python 3.9 及更早版本中存取物件註釋的最佳實踐、適用於任何Python 版本 "
+"``__annotations__`` 的最佳實踐，以及 ``__annotations__`` 的 quirks（怪癖、怪"
+"異模式）。"
 
 #: ../../howto/annotations.rst:26
 msgid ""
@@ -57,10 +65,13 @@ msgid ""
 "information on how to use \"type hints\" in your code, please see the :mod:"
 "`typing` module."
 msgstr ""
+"請注意，本文件是特別說明 ``__annotations__`` 的使用，而非\\ *如何使用*\\ 註"
+"釋。如果你正在尋找如何在你的程式碼中使用「型別提示 (type hint)」的資訊，請看"
+"到模組 (module) :mod:`typing`。"
 
 #: ../../howto/annotations.rst:33
 msgid "Accessing The Annotations Dict Of An Object In Python 3.10 And Newer"
-msgstr ""
+msgstr "在 Python 3.10 及更高版本中存取物件的註釋字典"
 
 #: ../../howto/annotations.rst:35
 msgid ""
@@ -70,6 +81,9 @@ msgid ""
 "supports annotations.  This function can also \"un-stringize\" stringized "
 "annotations for you."
 msgstr ""
+"Python 3.10 在標準函式庫中新增了一個新函式：:func:`inspect.get_annotations`。"
+"在 Python 3.10 及更高版本中，呼叫此函式是存取任何支援註釋的物件的註釋字典的最"
+"佳實踐。此函式也可以為你「取消字串化 (un-stringize)」字串化註釋。"
 
 #: ../../howto/annotations.rst:42
 msgid ""
@@ -81,6 +95,11 @@ msgid ""
 "of these three *specific* objects, you may simply use ``o.__annotations__`` "
 "to get at the object's annotations dict."
 msgstr ""
+"若由於某種原因 :func:`inspect.get_annotations` 對你的場合不可行，你可以手動存"
+"取 ``__annotations__`` 資料成員。 Python 3.10 中的最佳實踐也已經改變：從 "
+"Python 3.10 開始，保證 ``o.__annotations__`` \\ *始終*\\ 適用於 Python 函式、"
+"類別 (class) 和模組。如果你確定正在檢查的物件是這三個\\ *特定*\\ 物件之一，你"
+"可以簡單地使用 ``o.__annotations__`` 來取得物件的註釋字典。"
 
 #: ../../howto/annotations.rst:52
 msgid ""
@@ -90,6 +109,11 @@ msgid ""
 "practice in Python versions 3.10 and newer is to call :func:`getattr` with "
 "three arguments, for example ``getattr(o, '__annotations__', None)``."
 msgstr ""
+"但是，其他型別的 callable（可呼叫物件）（例如，由 :func:`functools.partial` "
+"建立的 callable）可能沒有定義 ``__annotations__`` 屬性 (attribute)。當存取可"
+"能未知的物件的 ``__annotations__`` 時，Python 3.10 及更高版本中的最佳實踐是使"
+"用三個參數呼叫 :func:`getattr`，例如 ``getattr(o, '__annotations__', "
+"None)``。"
 
 #: ../../howto/annotations.rst:60
 msgid ""
@@ -98,10 +122,13 @@ msgid ""
 "parent's ``__annotations__``. In Python 3.10 and newer, the child class's "
 "annotations will be an empty dict instead."
 msgstr ""
+"在 Python 3.10 之前，存取未定義註釋但具有註釋的父類別的類別上的 "
+"``__annotations__`` 將傳回父類別的 `` __annotations__``。在 Python 3.10 及更"
+"高版本中，子類別的註釋將會是一個空字典。"
 
 #: ../../howto/annotations.rst:68
 msgid "Accessing The Annotations Dict Of An Object In Python 3.9 And Older"
-msgstr ""
+msgstr "在 Python 3.9 及更早版本中存取物件的註釋字典"
 
 #: ../../howto/annotations.rst:70
 msgid ""
@@ -109,6 +136,8 @@ msgid ""
 "more complicated than in newer versions. The problem is a design flaw in "
 "these older versions of Python, specifically to do with class annotations."
 msgstr ""
+"在 Python 3.9 及更早版本中，存取物件的註釋字典比新版本複雜得多。問題出在於這"
+"些舊版 Python 中有設計缺陷，特別是與類別註釋有關的設計缺陷。"
 
 #: ../../howto/annotations.rst:75
 msgid ""
@@ -118,6 +147,9 @@ msgid ""
 "should use three-argument :func:`getattr` to access the object's "
 "``__annotations__`` attribute."
 msgstr ""
+"存取其他物件（如函式、其他 callable 和模組）的註釋字典的最佳實踐與 3.10 的最"
+"佳實踐相同，假設你沒有呼叫 :func:`inspect.get_annotations`：你應該使用三個："
+"參數 :func:`getattr` 來存取物件的 ``__annotations__`` 屬性。"
 
 #: ../../howto/annotations.rst:82
 msgid ""
@@ -127,10 +159,14 @@ msgid ""
 "``__annotations__`` attribute of a class may inadvertently return the "
 "annotations dict of a *base class.* As an example::"
 msgstr ""
+"不幸的是，這不是類別的最佳實踐。問題是，由於 ``__annotations__`` 在類別上是選"
+"填的 (optional)，並且因為類別可以從其基底類別 (base class) 繼承屬性，所以存取"
+"類別的 ``__annotations__`` 屬性可能會無意中回傳\\ *基底類別的註釋字典。*\\ 舉"
+"例來說： ::"
 
 #: ../../howto/annotations.rst:98
 msgid "This will print the annotations dict from ``Base``, not ``Derived``."
-msgstr ""
+msgstr "這將印出 (print) 來自 ``Base`` 的註釋字典，而不是 ``Derived``。"
 
 #: ../../howto/annotations.rst:101
 msgid ""
@@ -141,6 +177,11 @@ msgid ""
 "dictionary.  Since the class may or may not have annotations defined, best "
 "practice is to call the ``get`` method on the class dict."
 msgstr ""
+"如果你正在檢查的物件是一個類別 (``isinstance(o, type)``)，你的程式碼將必須有"
+"一個單獨的程式碼路徑。在這種情況下，最佳實踐依賴 Python 3.9 及之前版本的實作"
+"細節 (implementation detail)：如果一個類別定義了註釋，它們將儲存在該類別的 "
+"``__dict__`` 字典中。由於類別可能定義了註釋，也可能沒有定義，因此最佳實踐是在"
+"類別字典上呼叫 ``get`` 方法。"
 
 #: ../../howto/annotations.rst:109
 msgid ""
@@ -148,6 +189,8 @@ msgid ""
 "``__annotations__`` attribute on an arbitrary object in Python 3.9 and "
 "before::"
 msgstr ""
+"總而言之，以下是一些範例程式碼，可以安全地存取 Python 3.9 及先前版本中任意物"
+"件上的 ``__annotations__`` 屬性："
 
 #: ../../howto/annotations.rst:118
 msgid ""
@@ -155,6 +198,8 @@ msgid ""
 "You're encouraged to double-check the type of ``ann`` using :func:"
 "`isinstance` before further examination."
 msgstr ""
+"運行此程式碼後，``ann`` 應該是字典或 ``None``。我們鼓勵你在進一步檢查之前使"
+"用 :func:`isinstance` 仔細檢查 ``ann`` 的型別。"
 
 #: ../../howto/annotations.rst:123
 msgid ""
@@ -162,10 +207,13 @@ msgid ""
 "attribute, so for extra safety you may also wish to use :func:`getattr` to "
 "access ``__dict__``."
 msgstr ""
+"請注意，某些外來 (exotic) 或格式錯誤 (malform) 的型別物件可能沒有 "
+"``__dict__`` 屬性，因此為了額外的安全，你可能還希望使用 :func:`getattr` 來存"
+"取 ``__dict__`` 。"
 
 #: ../../howto/annotations.rst:129
 msgid "Manually Un-Stringizing Stringized Annotations"
-msgstr ""
+msgstr "手動取消字串化註釋"
 
 #: ../../howto/annotations.rst:131
 msgid ""
@@ -174,6 +222,8 @@ msgid ""
 "really is best to call :func:`inspect.get_annotations` to do this work for "
 "you."
 msgstr ""
+"在某些註釋可能被「字串化」的情況下，並且你希望評估這些字串以產生它們表示的 "
+"Python 值，最好呼叫 :func:`inspect.get_annotations` 來為你完成這項工作。"
 
 #: ../../howto/annotations.rst:137
 msgid ""
@@ -182,18 +232,23 @@ msgid ""
 "encouraged to examine the implementation of :func:`inspect.get_annotations` "
 "in the current Python version and follow a similar approach."
 msgstr ""
+"如果你使用的是 Python 3.9 或更早版本，或者由於某種原因你無法使用 :func:"
+"`inspect.get_annotations`，則需要複製其邏輯。我們鼓勵你檢查目前 Python 版本"
+"中 :func:`inspect.get_annotations` 的實作並遵循類似的方法。"
 
 #: ../../howto/annotations.rst:143
 msgid ""
 "In a nutshell, if you wish to evaluate a stringized annotation on an "
 "arbitrary object ``o``:"
-msgstr ""
+msgstr "簡而言之，如果你希望評估任意物件 ``o`` 上的字串化註釋： ::"
 
 #: ../../howto/annotations.rst:146
 msgid ""
 "If ``o`` is a module, use ``o.__dict__`` as the ``globals`` when calling :"
 "func:`eval`."
 msgstr ""
+"如果 ``o`` 是一個模組，則在呼叫 :func:`eval` 時使用 ``o.__dict__`` 作為\\ ``"
+"全域變數``\\ 。"
 
 #: ../../howto/annotations.rst:148
 msgid ""
@@ -201,6 +256,9 @@ msgid ""
 "``globals``, and ``dict(vars(o))`` as the ``locals``, when calling :func:"
 "`eval`."
 msgstr ""
+"如果 ``o`` 是一個類別，當呼叫 :func:`eval` 時，則使用 ``sys.modules[o."
+"__module__].__dict__`` 作為\\ ``全域變數``\\ ，使用 ``dict(vars(o))`` 作為\\ "
+"``區域變數``\\ 。"
 
 #: ../../howto/annotations.rst:151
 msgid ""
@@ -209,12 +267,17 @@ msgid ""
 "accessing either ``o.__wrapped__`` or ``o.func`` as appropriate, until you "
 "have found the root unwrapped function."
 msgstr ""
+"如果 ``o`` 是使用 :func:`functools.update_wrapper`、:func:`functools.wraps` "
+"或 :func:`functools.partial` 包裝的 callable ，請依據需求，透過存取 ``o."
+"__wrapped__`` 或``o.func`` 來疊代解開它，直到找到根解包函式。"
 
 #: ../../howto/annotations.rst:155
 msgid ""
 "If ``o`` is a callable (but not a class), use ``o.__globals__`` as the "
 "globals when calling :func:`eval`."
 msgstr ""
+"如果 ``o`` 是 callable（但不是類別），則在呼叫 :func:`eval` 時使用 ``o."
+"__globals__`` 作為全域變數。"
 
 #: ../../howto/annotations.rst:158
 msgid ""
@@ -224,18 +287,23 @@ msgid ""
 "hints that require annotating with string values that specifically *can't* "
 "be evaluated.  For example:"
 msgstr ""
+"然而，並非所有用作註釋的字串值都可以透過 :func:`eval` 成功轉換為 Python 值。"
+"理論上，字串值可以包含任何有效的字串，並且在實踐中，型別提示存在有效的用例，"
+"需要使用特定「無法」評估的字串值進行註釋。例如： ::"
 
 #: ../../howto/annotations.rst:165
 msgid ""
 ":pep:`604` union types using ``|``, before support for this was added to "
 "Python 3.10."
 msgstr ""
+"在 Python 3.10 支援 :pep:`604` 聯合型別 (union type) ``|`` 之前使用它。"
 
 #: ../../howto/annotations.rst:167
 msgid ""
 "Definitions that aren't needed at runtime, only imported when :const:`typing."
 "TYPE_CHECKING` is true."
 msgstr ""
+"Runtime 中不需要的定義，僅在 :const:`typing.TYPE_CHECKING` 為 true 時匯入。"
 
 #: ../../howto/annotations.rst:170
 msgid ""
@@ -244,22 +312,28 @@ msgid ""
 "it's recommended to only attempt to evaluate string values when explicitly "
 "requested to by the caller."
 msgstr ""
+"如果 :func:`eval` 嘗試計算這類型的值，它將失敗並引發例外。因此，在設計使用註"
+"釋的函式庫 API 時，建議僅在呼叫者 (caller) 明確請求時嘗試評估字串值。"
 
 #: ../../howto/annotations.rst:178
 msgid "Best Practices For ``__annotations__`` In Any Python Version"
-msgstr ""
+msgstr "任何 Python 版本中 ``__annotations__`` 的最佳實踐"
 
 #: ../../howto/annotations.rst:180
 msgid ""
 "You should avoid assigning to the ``__annotations__`` member of objects "
 "directly.  Let Python manage setting ``__annotations__``."
 msgstr ""
+"你應該避免直接指派給物件的 ``__annotations__`` 成員。讓 Python 管理設定 "
+"``__annotations__``。"
 
 #: ../../howto/annotations.rst:183
 msgid ""
 "If you do assign directly to the ``__annotations__`` member of an object, "
 "you should always set it to a ``dict`` object."
 msgstr ""
+"如果你直接指派給物件的 `` __annotations__`` 成員，則應始終將其設為 ``dict`` "
+"物件。"
 
 #: ../../howto/annotations.rst:186
 msgid ""
@@ -267,19 +341,21 @@ msgid ""
 "should ensure that it's a dictionary before attempting to examine its "
 "contents."
 msgstr ""
+"如果直接存取物件的 ``__annotations__`` 成員，則應在嘗試檢查其內容之前確保它是"
+"字典。"
 
 #: ../../howto/annotations.rst:190
 msgid "You should avoid modifying ``__annotations__`` dicts."
-msgstr ""
+msgstr "你應該避免修改 ``__annotations__`` 字典。"
 
 #: ../../howto/annotations.rst:192
 msgid ""
 "You should avoid deleting the ``__annotations__`` attribute of an object."
-msgstr ""
+msgstr "你應該避免刪除物件的 ``__annotations__`` 屬性。"
 
 #: ../../howto/annotations.rst:197
 msgid "``__annotations__`` Quirks"
-msgstr ""
+msgstr "``__annotations__`` Quirks"
 
 #: ../../howto/annotations.rst:199
 msgid ""
@@ -292,12 +368,18 @@ msgid ""
 "an ``AttributeError``; using ``del fn.__annotations__`` twice in a row is "
 "guaranteed to always throw an ``AttributeError``."
 msgstr ""
+"在 Python 3 的所有版本中，如果沒有在該物件上定義註釋，則函式物件會延遲建立 "
+"(lazy-create) 註釋字典。你可以使用 ``del fn.__annotations__`` 刪除 "
+"``__annotations__`` 屬性，但如果你隨後存取 ``fn.__annotations__``，該物件將建"
+"立一個新的空字典，它將作為註釋儲存並傳回。在函式延遲建立註釋字典之前刪除函式"
+"上的註釋將拋出 ``AttributeError``；連續兩次使用 ``del fn.__annotations__`` 保"
+"證總是拋出 ``AttributeError`` 。"
 
 #: ../../howto/annotations.rst:209
 msgid ""
 "Everything in the above paragraph also applies to class and module objects "
 "in Python 3.10 and newer."
-msgstr ""
+msgstr "上一段的所有內容也適用於 Python 3.10 及更高版本中的類別和模組物件。"
 
 #: ../../howto/annotations.rst:212
 msgid ""
@@ -309,6 +391,11 @@ msgid ""
 "``__annotations__`` to any Python value, and will retain whatever value is "
 "set."
 msgstr ""
+"在 Python 3 的所有版本中，你可以將函式物件上的 ``__annotations__`` 設定為 "
+"``None``。但是，隨後使用 ``fn.__annotations__`` 存取該物件上的註釋將根據本節"
+"第一段的內容延遲建立一個空字典。對於任何 Python 版本中的模組和類別來說，情況"
+"\\ *並非如此*\\；這些物件允許將  ``__annotations__`` 設定為任何 Python 值，並"
+"且將保留設定的任何值。"
 
 #: ../../howto/annotations.rst:220
 msgid ""
@@ -317,9 +404,14 @@ msgid ""
 "will itself be quoted.  In effect the annotation is quoted *twice.*  For "
 "example::"
 msgstr ""
+"如果 Python 為你字串化你的註釋（使用 ``from __future__ import "
+"annotations``），並且你指定一個字串作為註釋，則該字串本身將被引用。實際上，註"
+"釋被引用了\\ *兩次。*\\ 例如： ::"
 
 #: ../../howto/annotations.rst:231
 msgid ""
 "This prints ``{'a': \"'str'\"}``.  This shouldn't really be considered a "
 "\"quirk\"; it's mentioned here simply because it might be surprising."
 msgstr ""
+"這會印出 ``{'a': \"'str'\"}``。這不應該被認為是一個「quirk」，他在這裡被簡單"
+"提及，因為他可能會讓人意想不到。"

From c2e285d3bfecf5dd4da35b0655a7059bc969438e Mon Sep 17 00:00:00 2001
From: rockleona <rockleonjp@gmail.com>
Date: Wed, 8 Nov 2023 23:14:05 +0800
Subject: [PATCH 2/3] Update Info

---
 howto/annotations.po | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/howto/annotations.po b/howto/annotations.po
index fd52ccecaf..953792880d 100644
--- a/howto/annotations.po
+++ b/howto/annotations.po
@@ -8,15 +8,15 @@ msgstr ""
 "Project-Id-Version: Python 3.12\n"
 "Report-Msgid-Bugs-To: \n"
 "POT-Creation-Date: 2022-12-25 00:16+0000\n"
-"PO-Revision-Date: 2023-11-08 17:20+0800\n"
-"Last-Translator: \n"
+"PO-Revision-Date: 2023-11-08 23:11+0800\n"
+"Last-Translator: rockleon <therockleona@gmail.com>\n"
 "Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-"
 "tw)\n"
 "Language: zh_TW\n"
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=UTF-8\n"
 "Content-Transfer-Encoding: 8bit\n"
-"X-Generator: Poedit 3.4\n"
+"X-Generator: Poedit 3.4.1\n"
 
 #: ../../howto/annotations.rst:5
 msgid "Annotations Best Practices"

From 6788871c44772a5b812686c85c0e5fbbf248cfb5 Mon Sep 17 00:00:00 2001
From: rockleona <rockleonjp@gmail.com>
Date: Sun, 12 Nov 2023 21:36:17 +0800
Subject: [PATCH 3/3] Update with reviewer's comment

---
 howto/annotations.po | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/howto/annotations.po b/howto/annotations.po
index 953792880d..9d94b9c572 100644
--- a/howto/annotations.po
+++ b/howto/annotations.po
@@ -55,8 +55,7 @@ msgid ""
 msgstr ""
 "本文件分為四個部分：在 Python 3.10 及更高版本中存取物件註釋的最佳實踐、在 "
 "Python 3.9 及更早版本中存取物件註釋的最佳實踐、適用於任何Python 版本 "
-"``__annotations__`` 的最佳實踐，以及 ``__annotations__`` 的 quirks（怪癖、怪"
-"異模式）。"
+"``__annotations__`` 的最佳實踐，以及 ``__annotations__`` 的奇異之處。"
 
 #: ../../howto/annotations.rst:26
 msgid ""
@@ -66,8 +65,8 @@ msgid ""
 "`typing` module."
 msgstr ""
 "請注意，本文件是特別說明 ``__annotations__`` 的使用，而非\\ *如何使用*\\ 註"
-"釋。如果你正在尋找如何在你的程式碼中使用「型別提示 (type hint)」的資訊，請看"
-"到模組 (module) :mod:`typing`。"
+"釋。如果你正在尋找如何在你的程式碼中使用「型別提示 (type hint)」的資訊，請查"
+"閱模組 (module) :mod:`typing`。"
 
 #: ../../howto/annotations.rst:33
 msgid "Accessing The Annotations Dict Of An Object In Python 3.10 And Newer"
@@ -355,7 +354,7 @@ msgstr "你應該避免刪除物件的 ``__annotations__`` 屬性。"
 
 #: ../../howto/annotations.rst:197
 msgid "``__annotations__`` Quirks"
-msgstr "``__annotations__`` Quirks"
+msgstr "``__annotations__`` 奇異之處"
 
 #: ../../howto/annotations.rst:199
 msgid ""
@@ -413,5 +412,5 @@ msgid ""
 "This prints ``{'a': \"'str'\"}``.  This shouldn't really be considered a "
 "\"quirk\"; it's mentioned here simply because it might be surprising."
 msgstr ""
-"這會印出 ``{'a': \"'str'\"}``。這不應該被認為是一個「quirk」，他在這裡被簡單"
+"這會印出 ``{'a': \"'str'\"}``。這不應該被認為是一個「奇異的事」，他在這裡被簡單"
 "提及，因為他可能會讓人意想不到。"