fix(api-docs): replace all hardcoded Chinese with i18n translation keys for English support

app/i18n.py

@@ -251,6 +251,32 @@ _translations: dict[str, dict[str, str]] = {
     "api_docs.response_label": {"zh": "响应结果", "en": "Response"},
     "api_docs.no_auth": {"zh": "此接口无需鉴权", "en": "No authentication required"},
 
+    # ── API Docs (endpoint descriptions) ──
+    "api_docs.ep.list_profiles": {"zh": "获取当前用户的所有 Profile 列表。", "en": "List all profiles for the current user."},
+    "api_docs.ep.create_profile": {"zh": "创建新 Profile。", "en": "Create a new profile."},
+    "api_docs.ep.get_profile": {"zh": "获取单个 Profile 详情。", "en": "Get a single profile by ID."},
+    "api_docs.ep.update_profile": {"zh": "更新 Profile。", "en": "Update a profile."},
+    "api_docs.ep.delete_profile": {"zh": "删除 Profile 及其下所有明信片。", "en": "Delete a profile and all its postcards."},
+    "api_docs.ep.list_postcards": {"zh": "获取指定 Profile 下的明信片列表。", "en": "List postcards under a profile."},
+    "api_docs.ep.create_postcard": {"zh": "创建新明信片。", "en": "Create a new postcard."},
+    "api_docs.ep.get_postcard": {"zh": "获取单张明信片详情。", "en": "Get a single postcard by ID."},
+    "api_docs.ep.update_postcard": {"zh": "更新明信片。仅传入需要修改的字段。", "en": "Update a postcard. Only send fields you want to change."},
+    "api_docs.ep.delete_postcard": {"zh": "删除单张明信片。", "en": "Delete a single postcard."},
+    "api_docs.ep.upload_image": {"zh": "上传明信片图片（正面或背面），使用", "en": "Upload a postcard image (front or back), using"},
+    "api_docs.ep.upload_uses": {"zh": "上传明信片图片（正面或背面），使用", "en": "Upload a postcard image (front or back), using"},
+    "api_docs.ep.list_keys": {"zh": "获取当前用户的所有 API Key。", "en": "List all API keys for the current user."},
+    "api_docs.ep.create_key": {"zh": "创建新的 API Key。创建后完整 Key 仅在响应中显示一次。", "en": "Create a new API key. The full key is only shown once in the response."},
+    "api_docs.ep.delete_key": {"zh": "删除指定 API Key。", "en": "Delete an API key."},
+    "api_docs.ep.showcase_user": {"zh": "获取用户的公开展示数据。", "en": "Get a user's public showcase data."},
+    "api_docs.ep.showcase_profile": {"zh": "获取单个 Profile 的展示数据。", "en": "Get showcase data for a single profile."},
+    "api_docs.ep.filter_hint": {"zh": "按状态筛选：sent / delivered / received", "en": "Filter by status: sent / delivered / received"},
+    "api_docs.ep.optional_str": {"zh": "string（可选）", "en": "string (optional)"},
+    "api_docs.ep.image_file": {"zh": "图片文件", "en": "image file"},
+    "api_docs.ep.side_hint": {"zh": "string（可选）— front 或 back，默认 front", "en": "string (optional) — front or back, defaults to front"},
+    "api_docs.ep.key_name_hint": {"zh": "string（可选）— Key 的备注名称", "en": "string (optional) — a label for the key"},
+    "api_docs.ep.country_hint": {"zh": "两个大写字母，如 JP", "en": "two uppercase letters, e.g. JP"},
+    "api_docs.ep.date_hint": {"zh": "格式 YYYY-MM-DD 或 YYYY-MM-DDTHH:MM", "en": "format: YYYY-MM-DD or YYYY-MM-DDTHH:MM"},
+
     # ── Misc ──
     "misc.required": {"zh": " *", "en": " *"},
 }

app/templates/api_docs.html

@@ -61,7 +61,7 @@
             <span class="doc-method method-get">GET</span>
             <span class="doc-path">/profiles</span>
         </div>
-        <div class="doc-desc">获取当前用户的所有 Profile 列表。</div>
+        <div class="doc-desc">{{ 'api_docs.ep.list_profiles'|t(user.language) }}</div>
         <div class="doc-json">[
   {"id": 1, "nickname": "Japan", "showcase_enabled": false, "showcase_visible": "both", "notes": "", "created_at": "2025-01-01T00:00:00"},
   ...
@@ -73,7 +73,7 @@
             <span class="doc-method method-post">POST</span>
             <span class="doc-path">/profiles</span>
         </div>
-        <div class="doc-desc">创建新 Profile。</div>
+        <div class="doc-desc">{{ 'api_docs.ep.create_profile'|t(user.language) }}</div>
         <table class="doc-table">
             <tr><th>{{ 'api_docs.body'|t(user.language) }}</th><th></th></tr>
             <tr><td>nickname</td><td>string <span class="tag-required">{{ 'misc.required'|t(user.language) }}</span></td></tr>
@@ -86,7 +86,7 @@
             <span class="doc-method method-get">GET</span>
             <span class="doc-path">/profiles/{id}</span>
         </div>
-        <div class="doc-desc">获取单个 Profile 详情。</div>
+        <div class="doc-desc">{{ 'api_docs.ep.get_profile'|t(user.language) }}</div>
     </div>
 
     <div class="doc-endpoint">
@@ -94,10 +94,10 @@
             <span class="doc-method method-put">PUT</span>
             <span class="doc-path">/profiles/{id}</span>
         </div>
-        <div class="doc-desc">更新 Profile。</div>
+        <div class="doc-desc">{{ 'api_docs.ep.update_profile'|t(user.language) }}</div>
         <table class="doc-table">
             <tr><th>{{ 'api_docs.body'|t(user.language) }}</th><th></th></tr>
-            <tr><td>nickname</td><td>string（可选）</td></tr>
+            <tr><td>nickname</td><td>{{ 'api_docs.ep.optional_str'|t(user.language) }}</td></tr>
         </table>
     </div>
 
@@ -106,7 +106,7 @@
             <span class="doc-method method-delete">DELETE</span>
             <span class="doc-path">/profiles/{id}</span>
         </div>
-        <div class="doc-desc">删除 Profile 及其下所有明信片。</div>
+        <div class="doc-desc">{{ 'api_docs.ep.delete_profile'|t(user.language) }}</div>
         <div class="doc-json">{"ok": true}</div>
     </div>
 </div>
@@ -120,10 +120,10 @@
             <span class="doc-method method-get">GET</span>
             <span class="doc-path">/profiles/{profile_id}/postcards</span>
         </div>
-        <div class="doc-desc">获取指定 Profile 下的明信片列表。</div>
+        <div class="doc-desc">{{ 'api_docs.ep.list_postcards'|t(user.language) }}</div>
         <table class="doc-table">
             <tr><th>{{ 'api_docs.params'|t(user.language) }}</th><th></th></tr>
-            <tr><td>status</td><td>string（可选）— 按状态筛选：sent / delivered / received</td></tr>
+            <tr><td>status</td><td>string（{{ 'api_docs.ep.optional_str'|t(user.language) }}）— {{ 'api_docs.ep.filter_hint'|t(user.language) }}</td></tr>
         </table>
     </div>
 
@@ -132,18 +132,18 @@
             <span class="doc-method method-post">POST</span>
             <span class="doc-path">/profiles/{profile_id}/postcards</span>
         </div>
-        <div class="doc-desc">创建新明信片。</div>
+        <div class="doc-desc">{{ 'api_docs.ep.create_postcard'|t(user.language) }}</div>
         <table class="doc-table">
             <tr><th>{{ 'api_docs.body'|t(user.language) }}</th><th></th></tr>
             <tr><td>card_number</td><td>string <span class="tag-required">* {{ 'misc.required'|t(user.language) }}</span></td></tr>
             <tr><td>status</td><td>string <span class="tag-required">* {{ 'misc.required'|t(user.language) }}</span> — sent / delivered / received</td></tr>
-            <tr><td>recipient_name</td><td>string（可选）</td></tr>
-            <tr><td>country</td><td>string（可选）— 两个大写字母，如 JP</td></tr>
-            <tr><td>send_time</td><td>string（可选）— 格式 YYYY-MM-DD 或 YYYY-MM-DDTHH:MM</td></tr>
-            <tr><td>arrival_time</td><td>string（可选）</td></tr>
-            <tr><td>sender_name</td><td>string（可选）</td></tr>
-            <tr><td>receive_time</td><td>string（可选）</td></tr>
-            <tr><td>notes</td><td>string（可选）</td></tr>
+            <tr><td>recipient_name</td><td>{{ 'api_docs.ep.optional_str'|t(user.language) }}</td></tr>
+            <tr><td>country</td><td>{{ 'api_docs.ep.optional_str'|t(user.language) }} — {{ 'api_docs.ep.country_hint'|t(user.language) }}</td></tr>
+            <tr><td>send_time</td><td>{{ 'api_docs.ep.optional_str'|t(user.language) }} — {{ 'api_docs.ep.date_hint'|t(user.language) }}</td></tr>
+            <tr><td>arrival_time</td><td>{{ 'api_docs.ep.optional_str'|t(user.language) }}</td></tr>
+            <tr><td>sender_name</td><td>{{ 'api_docs.ep.optional_str'|t(user.language) }}</td></tr>
+            <tr><td>receive_time</td><td>{{ 'api_docs.ep.optional_str'|t(user.language) }}</td></tr>
+            <tr><td>notes</td><td>{{ 'api_docs.ep.optional_str'|t(user.language) }}</td></tr>
         </table>
     </div>
 
@@ -152,7 +152,7 @@
             <span class="doc-method method-get">GET</span>
             <span class="doc-path">/profiles/{profile_id}/postcards/{id}</span>
         </div>
-        <div class="doc-desc">获取单张明信片详情。</div>
+        <div class="doc-desc">{{ 'api_docs.ep.get_postcard'|t(user.language) }}</div>
     </div>
 
     <div class="doc-endpoint">
@@ -160,18 +160,18 @@
             <span class="doc-method method-put">PUT</span>
             <span class="doc-path">/profiles/{profile_id}/postcards/{id}</span>
         </div>
-        <div class="doc-desc">更新明信片。仅传入需要修改的字段。</div>
+        <div class="doc-desc">{{ 'api_docs.ep.update_postcard'|t(user.language) }}</div>
         <table class="doc-table">
             <tr><th>{{ 'api_docs.body'|t(user.language) }}</th><th></th></tr>
-            <tr><td>card_number</td><td>string（可选）</td></tr>
-            <tr><td>status</td><td>string（可选）</td></tr>
-            <tr><td>recipient_name</td><td>string（可选）</td></tr>
-            <tr><td>country</td><td>string（可选）</td></tr>
-            <tr><td>send_time</td><td>string（可选）</td></tr>
-            <tr><td>arrival_time</td><td>string（可选）</td></tr>
-            <tr><td>sender_name</td><td>string（可选）</td></tr>
-            <tr><td>receive_time</td><td>string（可选）</td></tr>
-            <tr><td>notes</td><td>string（可选）</td></tr>
+            <tr><td>card_number</td><td>{{ 'api_docs.ep.optional_str'|t(user.language) }}</td></tr>
+            <tr><td>status</td><td>{{ 'api_docs.ep.optional_str'|t(user.language) }}</td></tr>
+            <tr><td>recipient_name</td><td>{{ 'api_docs.ep.optional_str'|t(user.language) }}</td></tr>
+            <tr><td>country</td><td>{{ 'api_docs.ep.optional_str'|t(user.language) }}</td></tr>
+            <tr><td>send_time</td><td>{{ 'api_docs.ep.optional_str'|t(user.language) }}</td></tr>
+            <tr><td>arrival_time</td><td>{{ 'api_docs.ep.optional_str'|t(user.language) }}</td></tr>
+            <tr><td>sender_name</td><td>{{ 'api_docs.ep.optional_str'|t(user.language) }}</td></tr>
+            <tr><td>receive_time</td><td>{{ 'api_docs.ep.optional_str'|t(user.language) }}</td></tr>
+            <tr><td>notes</td><td>{{ 'api_docs.ep.optional_str'|t(user.language) }}</td></tr>
         </table>
     </div>
 
@@ -180,7 +180,7 @@
             <span class="doc-method method-delete">DELETE</span>
             <span class="doc-path">/profiles/{profile_id}/postcards/{id}</span>
         </div>
-        <div class="doc-desc">删除单张明信片。</div>
+        <div class="doc-desc">{{ 'api_docs.ep.delete_postcard'|t(user.language) }}</div>
         <div class="doc-json">{"ok": true}</div>
     </div>
 </div>
@@ -194,11 +194,11 @@
             <span class="doc-method method-post">POST</span>
             <span class="doc-path">/profiles/{profile_id}/postcards/{id}/upload</span>
         </div>
-        <div class="doc-desc">上传明信片图片（正面或背面），使用 <code>multipart/form-data</code>。</div>
+        <div class="doc-desc">{{ 'api_docs.ep.upload_uses'|t(user.language) }} <code>multipart/form-data</code>。</div>
         <table class="doc-table">
             <tr><th>Form Field</th><th></th></tr>
-            <tr><td>file</td><td>File <span class="tag-required">* {{ 'misc.required'|t(user.language) }}</span> — 图片文件</td></tr>
-            <tr><td>side</td><td>string（可选）— front 或 back，默认 front</td></tr>
+            <tr><td>file</td><td>File <span class="tag-required">* {{ 'misc.required'|t(user.language) }}</span> — {{ 'api_docs.ep.image_file'|t(user.language) }}</td></tr>
+            <tr><td>side</td><td>{{ 'api_docs.ep.side_hint'|t(user.language) }}</td></tr>
         </table>
     </div>
 </div>
@@ -212,7 +212,7 @@
             <span class="doc-method method-get">GET</span>
             <span class="doc-path">/keys</span>
         </div>
-        <div class="doc-desc">获取当前用户的所有 API Key。</div>
+        <div class="doc-desc">{{ 'api_docs.ep.list_keys'|t(user.language) }}</div>
     </div>
 
     <div class="doc-endpoint">
@@ -220,10 +220,10 @@
             <span class="doc-method method-post">POST</span>
             <span class="doc-path">/keys</span>
         </div>
-        <div class="doc-desc">创建新的 API Key。创建后完整 Key 仅在响应中显示一次。</div>
+        <div class="doc-desc">{{ 'api_docs.ep.create_key'|t(user.language) }}</div>
         <table class="doc-table">
             <tr><th>{{ 'api_docs.body'|t(user.language) }}</th><th></th></tr>
-            <tr><td>name</td><td>string（可选）— Key 的备注名称</td></tr>
+            <tr><td>name</td><td>{{ 'api_docs.ep.key_name_hint'|t(user.language) }}</td></tr>
         </table>
     </div>
 
@@ -232,7 +232,7 @@
             <span class="doc-method method-delete">DELETE</span>
             <span class="doc-path">/keys/{id}</span>
         </div>
-        <div class="doc-desc">删除指定 API Key。</div>
+        <div class="doc-desc">{{ 'api_docs.ep.delete_key'|t(user.language) }}</div>
         <div class="doc-json">{"ok": true}</div>
     </div>
 </div>
@@ -246,7 +246,7 @@
             <span class="doc-method method-get">GET</span>
             <span class="doc-path">/showcase/{username}</span>
         </div>
-        <div class="doc-desc">{{ 'api_docs.no_auth'|t(user.language) }} — 获取用户的公开展示数据。</div>
+        <div class="doc-desc">{{ 'api_docs.no_auth'|t(user.language) }} — {{ 'api_docs.ep.showcase_user'|t(user.language) }}</div>
     </div>
 
     <div class="doc-endpoint">
@@ -254,7 +254,7 @@
             <span class="doc-method method-get">GET</span>
             <span class="doc-path">/showcase/{username}/profile/{id}</span>
         </div>
-        <div class="doc-desc">{{ 'api_docs.no_auth'|t(user.language) }} — 获取单个 Profile 的展示数据。</div>
+        <div class="doc-desc">{{ 'api_docs.no_auth'|t(user.language) }} — {{ 'api_docs.ep.showcase_profile'|t(user.language) }}</div>
     </div>
 </div>