From fb98974382e43587e53f472c6d1003126eb3bd2d Mon Sep 17 00:00:00 2001 From: Zichao Lin Date: Tue, 7 Jul 2026 09:33:01 +0800 Subject: [PATCH] fix(api-docs): replace all hardcoded Chinese with i18n translation keys for English support --- app/i18n.py | 26 +++++++++++++ app/templates/api_docs.html | 74 ++++++++++++++++++------------------- 2 files changed, 63 insertions(+), 37 deletions(-) diff --git a/app/i18n.py b/app/i18n.py index 6a4937e..9761b7d 100644 --- a/app/i18n.py +++ b/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": " *"}, } diff --git a/app/templates/api_docs.html b/app/templates/api_docs.html index 1f342c1..9d6edaa 100644 --- a/app/templates/api_docs.html +++ b/app/templates/api_docs.html @@ -61,7 +61,7 @@ GET /profiles -
获取当前用户的所有 Profile 列表。
+
{{ 'api_docs.ep.list_profiles'|t(user.language) }}
[ {"id": 1, "nickname": "Japan", "showcase_enabled": false, "showcase_visible": "both", "notes": "", "created_at": "2025-01-01T00:00:00"}, ... @@ -73,7 +73,7 @@ POST /profiles
-
创建新 Profile。
+
{{ 'api_docs.ep.create_profile'|t(user.language) }}
@@ -86,7 +86,7 @@ GET/profiles/{id} -
获取单个 Profile 详情。
+
{{ 'api_docs.ep.get_profile'|t(user.language) }}
@@ -94,10 +94,10 @@ PUT /profiles/{id}
-
更新 Profile。
+
{{ 'api_docs.ep.update_profile'|t(user.language) }}
{{ 'api_docs.body'|t(user.language) }}
nicknamestring {{ 'misc.required'|t(user.language) }}
- +
{{ 'api_docs.body'|t(user.language) }}
nicknamestring（可选）
nickname{{ 'api_docs.ep.optional_str'|t(user.language) }}
@@ -106,7 +106,7 @@ DELETE /profiles/{id} -
删除 Profile 及其下所有明信片。
+
{{ 'api_docs.ep.delete_profile'|t(user.language) }}
{"ok": true}
@@ -120,10 +120,10 @@ GET /profiles/{profile_id}/postcards -
获取指定 Profile 下的明信片列表。
+
{{ 'api_docs.ep.list_postcards'|t(user.language) }}
- +
{{ 'api_docs.params'|t(user.language) }}
statusstring（可选）— 按状态筛选：sent / delivered / received
statusstring（{{ 'api_docs.ep.optional_str'|t(user.language) }}）— {{ 'api_docs.ep.filter_hint'|t(user.language) }}
@@ -132,18 +132,18 @@ POST /profiles/{profile_id}/postcards -
创建新明信片。
+
{{ 'api_docs.ep.create_postcard'|t(user.language) }}
- - - - - - - + + + + + + +
{{ 'api_docs.body'|t(user.language) }}
card_numberstring * {{ 'misc.required'|t(user.language) }}
statusstring * {{ 'misc.required'|t(user.language) }} — sent / delivered / received
recipient_namestring（可选）
countrystring（可选）— 两个大写字母，如 JP
send_timestring（可选）— 格式 YYYY-MM-DD 或 YYYY-MM-DDTHH:MM
arrival_timestring（可选）
sender_namestring（可选）
receive_timestring（可选）
notesstring（可选）
recipient_name{{ 'api_docs.ep.optional_str'|t(user.language) }}
country{{ 'api_docs.ep.optional_str'|t(user.language) }} — {{ 'api_docs.ep.country_hint'|t(user.language) }}
send_time{{ 'api_docs.ep.optional_str'|t(user.language) }} — {{ 'api_docs.ep.date_hint'|t(user.language) }}
arrival_time{{ 'api_docs.ep.optional_str'|t(user.language) }}
sender_name{{ 'api_docs.ep.optional_str'|t(user.language) }}
receive_time{{ 'api_docs.ep.optional_str'|t(user.language) }}
notes{{ 'api_docs.ep.optional_str'|t(user.language) }}
@@ -152,7 +152,7 @@ GET /profiles/{profile_id}/postcards/{id} -
获取单张明信片详情。
+
{{ 'api_docs.ep.get_postcard'|t(user.language) }}
@@ -160,18 +160,18 @@ PUT /profiles/{profile_id}/postcards/{id}
-
更新明信片。仅传入需要修改的字段。
+
{{ 'api_docs.ep.update_postcard'|t(user.language) }}
- - - - - - - - - + + + + + + + + +
{{ 'api_docs.body'|t(user.language) }}
card_numberstring（可选）
statusstring（可选）
recipient_namestring（可选）
countrystring（可选）
send_timestring（可选）
arrival_timestring（可选）
sender_namestring（可选）
receive_timestring（可选）
notesstring（可选）
card_number{{ 'api_docs.ep.optional_str'|t(user.language) }}
status{{ 'api_docs.ep.optional_str'|t(user.language) }}
recipient_name{{ 'api_docs.ep.optional_str'|t(user.language) }}
country{{ 'api_docs.ep.optional_str'|t(user.language) }}
send_time{{ 'api_docs.ep.optional_str'|t(user.language) }}
arrival_time{{ 'api_docs.ep.optional_str'|t(user.language) }}
sender_name{{ 'api_docs.ep.optional_str'|t(user.language) }}
receive_time{{ 'api_docs.ep.optional_str'|t(user.language) }}
notes{{ 'api_docs.ep.optional_str'|t(user.language) }}
@@ -180,7 +180,7 @@ DELETE /profiles/{profile_id}/postcards/{id} -
删除单张明信片。
+
{{ 'api_docs.ep.delete_postcard'|t(user.language) }}
{"ok": true}
@@ -194,11 +194,11 @@ POST /profiles/{profile_id}/postcards/{id}/upload -
上传明信片图片（正面或背面），使用 multipart/form-data。
+
{{ 'api_docs.ep.upload_uses'|t(user.language) }} multipart/form-data。
- - + +
Form Field
fileFile * {{ 'misc.required'|t(user.language) }} — 图片文件
sidestring（可选）— front 或 back，默认 front
fileFile * {{ 'misc.required'|t(user.language) }} — {{ 'api_docs.ep.image_file'|t(user.language) }}
side{{ 'api_docs.ep.side_hint'|t(user.language) }}
@@ -212,7 +212,7 @@ GET /keys -
获取当前用户的所有 API Key。
+
{{ 'api_docs.ep.list_keys'|t(user.language) }}
@@ -220,10 +220,10 @@ POST /keys
-
创建新的 API Key。创建后完整 Key 仅在响应中显示一次。
+
{{ 'api_docs.ep.create_key'|t(user.language) }}
- +
{{ 'api_docs.body'|t(user.language) }}
namestring（可选）— Key 的备注名称
name{{ 'api_docs.ep.key_name_hint'|t(user.language) }}
@@ -232,7 +232,7 @@ DELETE /keys/{id} -
删除指定 API Key。
+
{{ 'api_docs.ep.delete_key'|t(user.language) }}
{"ok": true}
@@ -246,7 +246,7 @@ GET /showcase/{username} -
{{ 'api_docs.no_auth'|t(user.language) }} — 获取用户的公开展示数据。
+
{{ 'api_docs.no_auth'|t(user.language) }} — {{ 'api_docs.ep.showcase_user'|t(user.language) }}
@@ -254,7 +254,7 @@ GET /showcase/{username}/profile/{id}
-
{{ 'api_docs.no_auth'|t(user.language) }} — 获取单个 Profile 的展示数据。
+
{{ 'api_docs.no_auth'|t(user.language) }} — {{ 'api_docs.ep.showcase_profile'|t(user.language) }}