diff --git a/docs/AI prompt.md b/docs/AI prompt.md index 6e4cb8a2b..b5ac55e45 100644 --- a/docs/AI prompt.md +++ b/docs/AI prompt.md @@ -2,6 +2,21 @@ 我将在这里记录下开发过程中的AI提示词,让AI更好的助力项目发展(使用VSCode Github Copilot Agent模式) +## 术语与本地化修改规则 + +以下要求适用于所有会新增或修改本地化内容的 AI 任务,包括 `src/locales//translation.json`、对应语言的文档、界面文案与测试快照: + +```md +凡是新增或修改某个语言地区(locale)的内容,必须先检查是否存在对应的术语规范文件 `docs/terminology-.md`;如果存在,必须读取并遵循该文件。例如,修改 Traditional Chinese / 繁体中文(zh-TW)时,必须遵循 `docs/terminology-zh-TW.md`。 + +- 遵循目标语言地区的自然表达和产品界面惯用语,不可仅做文字或字形的机械转换。 +- 对应术语规范文件中标注为必须采用或应避免的用语,视为强制规则。 +- 对需要结合语境判断的项目,不得机械式全局替换;应根据功能语境与原文含义选择用词。 +- 如果目标 locale 尚无术语规范文件,应保持现有翻译风格,并避免擅自引入新的术语标准。 +- 保留 i18next placeholder、程序标识符、HTML/React 标记和既有功能行为。 +- 完成后检查本次修改的本地化内容,确认符合对应的术语规范文件(如存在)。 +``` + ## 单元测试 ```md @@ -33,4 +48,4 @@ 你是一个翻译专家,使用react-i18next做为翻译框架,我需要你帮助我翻译这个React文件中的中文,首先你需要提取文件中的中文部分,生成一个合适的key,使用蛇形命名,添加到 src/locales/zh-CN/translations.json 文件中,然后使用`useTranslation`替换原有中文,如果有参数你可以使用i18next的格式,不需要处理其他语言,不要做多余的事情 -``` \ No newline at end of file +``` diff --git a/docs/terminology-zh-TW.md b/docs/terminology-zh-TW.md new file mode 100644 index 000000000..c6ae9d3fa --- /dev/null +++ b/docs/terminology-zh-TW.md @@ -0,0 +1,116 @@ +# zh-TW 術語與介面文案規範 + +本文件是 ScriptCat 繁體中文(`zh-TW`)介面與文件的用語依據。翻譯或修改繁體中文時,目標是讓台灣使用者自然理解,並維持台灣軟體產品介面常見的語氣。 + +盤點來源:`src/locales/zh-TW/translation.json` + +## 使用原則 + +1. 避免只有繁體字形、但詞彙與語氣仍偏中國大陸介面的翻譯。 +2. 優先使用台灣產品介面慣用詞,例如 `儲存`、`載入`、`設定`、`裝置`、`分頁`。 +3. 不對「需看語境」的詞做機械式全域取代;先確認英文原意、功能和完整句子。 +4. 技術名詞以專案既有術語與台灣開發者常用寫法為準;例如 `expression` 使用 `表達式`,`watch` 使用 `監聽`,不可改為 `運算式` 或 `監看`。 +5. 本文件列出的 `受影響 key` 是目前盤點到的現況,不限制日後在其他文案中套用相同原則。 + +## 分類說明 + +| 分類 | 用法 | +| --- | --- | +| **A. 應直接修正** | 明顯偏中國大陸介面用語,新增或修改 `zh-TW` 文案時應避免使用。 | +| **B. 視語境修正** | 台灣可能使用,但替代詞取決於產品功能或原文意思。 | +| **C. 風格一致性** | 技術上可接受,不一定錯;面向使用者的介面宜優先採用較自然寫法。 | +| **D. 固定保留的技術詞** | 已採用且符合本產品技術語境的詞彙,不應因在地化掃描而替換。 | + +## A. 應直接修正 + +| 避免使用 | 優先使用 | 目前受影響 key | +| --- | --- | --- | +| `新建` | `新增` / `建立` | `create_user_script`, `create_background_script`, `create_scheduled_script`, `create_script`, `create_success_note` | +| `暫無資料` | `尚無資料` / `目前沒有資料` | `no_data` | +| `通用` | `一般` | `general` | +| `列表` | `清單` | `backup_list`, `editor.show_script_list`, `editor.hide_script_list` | +| `連接` | `連線` | `auto_connect_vscode_service`, `connect`, `connection_success`, `connection_failed`, `sync_system_connect_failed` | +| `拉取` | `下載` / `擷取` / `同步取得` | `pulling_data_from_cloud`, `pull_failed` | +| `本地` | `本機` | `source_local_script`, `by_manual_creation` | +| `應用至` | `套用至` | `apply_to_run_status`, `guide_script_list_apply_to_run_status_title` | +| `每星期` | `每週` | `cron_oncetype.week` | +| `返傭連結` | `分潤連結` | `antifeature_referral_link_description` | +| `訂閱源` | `訂閱來源` | `subscribe_source_tooltip` | +| `展示` | `顯示` | `guide_script_list_apply_to_run_status_content` | +| `懸停` | `滑鼠停留` / `將滑鼠移到...上方` | `guide_script_list_apply_to_run_status_content` | +| `運行` | 腳本用 `執行`;功能或環境用 `運作` | `guide_script_list_action_content`, `script_run_at.title`, `runtime`, `enable_background.title`, `enable_background.prompt_title`, `enable_background.prompt_description` | +| `視圖模式` | `檢視模式` | `guide_script_list_action_content` | +| `保存` | `儲存` | `guide_tools_backup_content` | +| `設備` | `裝置` | `guide_setting_sync_content` | +| `其它` | `其他` | `guide_setting_sync_content` | +| `批量` | `批次` | `batch_edit` | +| `代碼` | `程式碼` | `script_code` | +| `回車` | `Enter 鍵` | `input_tags_placeholder` | +| `打開` | `開啟` | `open_sidebar` | +| `聲明` | `宣告` | `error_metadata_line_duplicated` | +| `重覆` | `重複` | `error_metadata_line_duplicated` | +| `加載` | `載入` | `loading` | + +## B. 視語境修正 + +| 目前詞彙 | 建議判斷 | 目前受影響 key | +| --- | --- | --- | +| `目錄` | 指 filesystem directory 的介面動作用 `資料夾`;文章或文件的內容目錄仍用 `目錄`。 | `open_backup_dir`, `open_directory`, `script_operation_description`, `get_backup_dir_url_failed` | +| `恢復` | restore settings/default values 用 `還原`;resume operation 或 recover 依語意使用 `恢復` / `復原`。 | `exclude_on`, `restore_default_values` | +| `控制面板` | 擴充功能或管理 dashboard 可用 `控制台` / `管理介面` / `儀表板`;panel 可能仍應譯為 `面板`。 | `scheduled_script_description_title`, `background_script_description` | +| `查看` | 台灣可用;選單、模式或系統動作可用 `檢視`,開啟工具則可直接寫 `開啟`。 | `guide_script_list_apply_to_run_status_content`, `develop_mode_guide`, `allow_user_script_guide`, `build_success_message`, `ext_update_notification_desc` | +| `退出瀏覽器` | quit/close browser 通常用 `關閉瀏覽器`,必要時可用 `結束瀏覽器`。 | `enable_background.description` | +| `前臺` / `後臺` | foreground/background 用 `前景` / `背景`;frontend/backend 用 `前端` / `後端`;管理系統語境才可能用 `前台` / `後台`。 | `error_script_type_mismatch` | + +## C. 風格一致性 + +| 目前詞彙 | 介面優先寫法 | 目前受影響 key | 說明 | +| --- | --- | --- | --- | +| `幫助` | `說明` / `協助` | `helpcenter`, `help_translate` | 台灣日常用語可使用 `幫助`;Help Center 建議為 `說明中心`,help translate 建議為 `協助翻譯`。 | +| `更新日誌` | `更新紀錄` / `版本紀錄` | `ext_update_notification_desc` | 技術內容可理解,產品介面以 `紀錄` 較自然。 | +| `腳本個數` | `腳本數量` | `badge_type_script_count` | `個數` 可理解,但介面欄位以 `數量` 較自然。 | +| `普通腳本` / `普通油猴腳本` / `普通標籤` | `一般腳本` / `一般使用者腳本` / `一般分頁` | `create_user_script`, `script_status_tooltip`, `script_run_env.normal-tabs`, `script_list.sidebar.normal_script` | 若 `tabs` 指瀏覽器頁籤,台灣瀏覽器介面使用 `分頁`。 | +| `API文件` / `專案文件` | `API 文件` / `API 說明文件` / `專案文件` | `api_docs`, `project_docs` | `文件` 在台灣技術語境可接受;不要改為偏中國大陸用語的 `文檔`。 | + +## D. 固定保留的技術詞 + +| 英文概念 | 固定使用 | 不使用 | 目前使用 key | 理由 | +| --- | --- | --- | --- | --- | +| `expression` | `表達式` | `運算式` | `value_export_expression`, `cookie_export_expression`, `cron_invalid_expr`, `scheduled_script_description_description_expr`, `expression_format_error`, `search_regex` | `表達式` 是台灣程式開發語境常見用法,也與既有 `正規表達式` 術語一致。將不同 expression 文案改成 `運算式` 會造成同一概念在介面中不一致,且容易讓人誤解為只限數學或計算公式。 | +| `watch`(檔案變動功能) | `監聽` | `監看` | `watch_file_description`, `watch_file`, `stop_watch_file` | 在開發工具中,watch 表示持續監聽檔案變動並觸發更新,與 watcher、事件監聽等技術概念相連。`監聽` 能保持技術意義與現有文案一致;`監看` 雖可理解,但不作為本專案術語。 | + +## 常用標準詞 + +新增繁體中文文案時,以下寫法可直接沿用: + +| 優先使用 | 避免使用 | +| --- | --- | +| `匯入` / `匯出` | `導入` / `導出` | +| `檔案` / `資料夾` | `文件`(一般使用者檔案語境)/ `目錄`(filesystem UI 動作) | +| `資訊` | `信息` | +| `設定` | `配置` | +| `支援` | `支持` | +| `搜尋` | `搜索` | +| `載入` | `加載` | +| `程式碼` | `代碼` | +| `帳號` | `賬號` | +| `裝置` | `設備` | +| `網路` | `網絡` | +| `伺服器` | `服務器` | +| `擴充功能` | `擴展` / `插件`(指瀏覽器 extension 時) | +| `滑鼠` | `鼠標` | +| `分頁` | `標籤`(指瀏覽器 tab 時) | +| `正規表達式` | `正則表達式` / `正規運算式` | +| `表達式` | `運算式`(指程式、排程或匯出 expression 時) | +| `監聽檔案` / `停止監聽` | `監看檔案` / `停止監看` | + +## AI 與貢獻者檢查清單 + +修改包含繁體中文的檔案時: + +1. 確認文字的目標語系是 `zh-TW`,而非只將簡體中文字形轉為繁體。 +2. 先套用「應直接修正」與「常用標準詞」。 +3. 遇到「視語境修正」或「風格一致性」詞彙時,檢查功能、英文原文或相鄰文案後再決定。 +4. 遇到「固定保留的技術詞」時,沿用指定寫法,不依一般替換偏好改寫。 +5. 維持既有 placeholder、HTML/React 標記與 i18next 插值格式,不因術語修正而改壞行為。 +6. 交付前重新搜尋本次新增或修改的繁體中文,確認未引入本文件標示應避免的用詞。