feat: add header button and clarify routing flow

Author: pudding483

README.en.md

@@ -20,6 +20,14 @@ export default defineConfig({
 
   base: "/",
 
+  // 新增語言轉換按鈕
+  i18n: {
+    defaultLocale: "zh-TW",
+    locales: ["zh-TW", "en"], // 支援 繁體中文 和 英文
+    routing: {
+      prefixDefaultLocale: false, // 預設語言 (zh-TW) 不顯示 /zh-TW/
+    },
+  },
   markdown: {
     remarkPlugins: [remarkMath],
     rehypePlugins: [

astro.config.mjs

@@ -9,6 +9,7 @@ import {
   MENU,
   BANNER,
   BANNER_SRCSET,
+  Translation, // 新增這個區塊，專門控制翻譯功能
   TRIANGLE_BADGE,
 } from "../utils/config";
 import { urlFor } from "../utils/urlFor";
@@ -18,6 +19,7 @@ import RssBtn from "./partial/RssBtn";
 import SearchBtn from "./partial/SearchBtn";
 import ThemeBtn from "./partial/ThemeBtn";
 import SearchBox from "./partial/SearchBox";
+import TranslateBtn from "./partial/TranslateBtn"; // 新增語言轉換按鈕
 
 type Props = {
   title?: string;
@@ -26,7 +28,9 @@ type Props = {
 
 const { title = SITE.title, cover } = Astro.props;
 const posts = await getCollection("blog");
-const sortedPosts = posts.sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
+const sortedPosts = posts.sort(
+  (a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf(),
+);
 ---
 
 <div id="header-nav">
@@ -50,6 +54,10 @@ const sortedPosts = posts.sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDa
   <nav id="sub-nav" aria-label="Secondary navigation">
     <RssBtn client:load url={BASE_URL} className="nav-icon" />
     <SearchBtn client:load className="nav-icon" />
+
+    {/* 新增語言轉換按鈕，同時在 config.ts 設定可自由開關顯示 */}
+    {Translation.enable && <TranslateBtn client:load className="nav-icon" />}
+
     <ThemeBtn client:load className="nav-icon" />
   </nav>
   {

src/components/Header.astro

@@ -8,12 +8,34 @@ import {
 
 import useTheme, { type Theme } from "../../hooks/useTheme";
 
+// 定義多語言提示文字
+const I18N_TEXT = {
+  "zh-TW": {
+    toLight: "切換至淺色模式",
+    toDark: "切換至深色模式",
+    auto: "跟隨系統主題",
+  },
+  en: {
+    toLight: "Switch to Light Mode",
+    toDark: "Switch to Dark Mode",
+    auto: "System Theme",
+  },
+};
+
 export default function ThemeToggle({ className }: { className?: string }) {
   const { theme, setTheme } = useTheme();
   const [isMounted, setIsMounted] = useState(false);
+  const [lang, setLang] = useState<"zh-TW" | "en">("zh-TW"); // 預設語言為中文
 
   useEffect(() => {
     setIsMounted(true);
+
+    // 用路徑判斷當前語言
+    if (window.location.pathname.startsWith("/en")) {
+      setLang("en");
+    } else {
+      setLang("zh-TW");
+    }
   }, []);
   if (!isMounted) {
     return <></>;
@@ -26,7 +48,7 @@ export default function ThemeToggle({ className }: { className?: string }) {
         detail: {
           theme,
         },
-      })
+      }),
     );
   };
 
@@ -40,17 +62,25 @@ export default function ThemeToggle({ className }: { className?: string }) {
     }
   };
 
+  const getTitle = () => {
+    // 根據當前主題和語言返回對應的提示文字
+    const t = I18N_TEXT[lang];
+
+    if (theme === "dark") return t.toLight; // 現在是暗的，提示按下去會變亮
+    if (theme === "light") return t.toDark; // 現在是亮的，提示按下去會變暗
+    return t.auto;
+  };
+
   return (
-    <span 
-      className={className} 
+    <span
+      className={className}
       onClick={handleClick}
+      role="button" // 建議補上，增加可訪問性
+      aria-label="Toggle Theme"
+      title={getTitle()} // 根據當前主題動態設定提示文字
     >
-      {theme === "dark" && (
-        <FontAwesomeIcon icon={faMoon} scale={20} />
-      )}
-      {theme === "light" && (
-        <FontAwesomeIcon icon={faSun} scale={20} />
-      )}
+      {theme === "dark" && <FontAwesomeIcon icon={faMoon} scale={20} />}
+      {theme === "light" && <FontAwesomeIcon icon={faSun} scale={20} />}
       {theme === "auto" && (
         <FontAwesomeIcon icon={faCircleHalfStroke} scale={20} />
       )}

src/components/partial/ThemeBtn.tsx

@@ -0,0 +1,61 @@
+import React, { useState, useEffect } from "react";
+
+interface Props {
+  className?: string;
+}
+
+export default function TranslateBtn({ className }: Props) {
+  const [currentLang, setCurrentLang] = useState("zh-TW");
+
+  useEffect(() => {
+    // 判斷當前語言
+    if (window.location.pathname.startsWith("/en")) {
+      setCurrentLang("en");
+    } else {
+      setCurrentLang("zh-TW");
+    }
+  }, []);
+
+  const toggleLanguage = () => {
+    const currentPath = window.location.pathname;
+
+    // 1. 取得不含語言前綴的路徑 (把 /en 去掉)
+    // 例如: "/en/about" -> "/about", "/en" -> "/"
+    const basePath = currentPath.replace(/^\/en/, "") || "/";
+
+    let newPath = "";
+
+    if (currentLang === "zh-TW") {
+      // 2. 切換到英文
+      // 邏輯：加上 /en 前綴
+      // 注意：如果 basePath 是 "/"，則變為 "/en"，否則為 "/en/about"
+      newPath = `/en${basePath === "/" ? "" : basePath}`;
+    } else {
+      // 3. 切換到中文
+      // 邏輯：直接使用 basePath (即移除 /en 之後的路徑)
+      newPath = basePath;
+    }
+
+    window.location.href = newPath;
+  };
+
+  return (
+    <div
+      className={className}
+      onClick={toggleLanguage}
+      title={`Switch to ${currentLang === "zh-TW" ? "English" : "繁體中文"}`}
+      role="button"
+      aria-label="Switch Language"
+    >
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="14"
+        height="14"
+        viewBox="0 0 640 640"
+        fill="currentColor"
+      >
+        <path d="M192 64C209.7 64 224 78.3 224 96L224 128L352 128C369.7 128 384 142.3 384 160C384 177.7 369.7 192 352 192L342.4 192L334 215.1C317.6 260.3 292.9 301.6 261.8 337.1C276 345.9 290.8 353.7 306.2 360.6L356.6 383L418.8 243C423.9 231.4 435.4 224 448 224C460.6 224 472.1 231.4 477.2 243L605.2 531C612.4 547.2 605.1 566.1 589 573.2C572.9 580.3 553.9 573.1 546.8 557L526.8 512L369.3 512L349.3 557C342.1 573.2 323.2 580.4 307.1 573.2C291 566 283.7 547.1 290.9 531L330.7 441.5L280.3 419.1C257.3 408.9 235.3 396.7 214.5 382.7C193.2 399.9 169.9 414.9 145 427.4L110.3 444.6C94.5 452.5 75.3 446.1 67.4 430.3C59.5 414.5 65.9 395.3 81.7 387.4L116.2 370.1C132.5 361.9 148 352.4 162.6 341.8C148.8 329.1 135.8 315.4 123.7 300.9L113.6 288.7C102.3 275.1 104.1 254.9 117.7 243.6C131.3 232.3 151.5 234.1 162.8 247.7L173 259.9C184.5 273.8 197.1 286.7 210.4 298.6C237.9 268.2 259.6 232.5 273.9 193.2L274.4 192L64.1 192C46.3 192 32 177.7 32 160C32 142.3 46.3 128 64 128L160 128L160 96C160 78.3 174.3 64 192 64zM448 334.8L397.7 448L498.3 448L448 334.8z" />
+      </svg>
+    </div>
+  );
+}

src/components/partial/TranslateBtn.tsx

@@ -3,7 +3,7 @@ import covers from "./covers";
 export default {
   site: {
     title: "483's Blog",
-    subtitle: "My Blog Subtitle",
+    subtitle: "483 的小天地",
     description: "483's blog",
     keywords: "483, blog, astro, theme",
     author: "483",
@@ -38,6 +38,11 @@ export default {
     ],
   },
 
+  // 新增這個區塊，專門控制翻譯功能
+  translation: {
+    enable: true,
+  },
+
   footer: {
     since: 2026, // 2026 - current year
     powered: true,

src/config.ts

@@ -1,5 +1,5 @@
 export default [
-  "/images/SAO_2014.webp",
+  // "/images/SAO_2014.webp",
   "/images/Re0-765x372.webp",
   "/images/NGNL-1048x645.webp",
   "/images/GuiltyCrown-1440x900.webp",

src/covers.ts

@@ -30,7 +30,9 @@ type Props = {
 
 export async function getStaticPaths({ paginate }: { paginate: Function }) {
   const posts = await getCollection("blog");
-  const sortedPosts = posts.sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
+  const sortedPosts = posts.sort(
+    (a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf(),
+  );
   return paginate(sortedPosts, {
     pageSize: 10,
   });
@@ -41,6 +43,7 @@ const { page } = Astro.props;
 <BaseLayout>
   <!-- Header -->
   <HeaderTitle title={SITE.title} url=`${BASE_URL}/` slot="header" />
+  {/* slot 是 Astro 的俱名插槽，把 component 塞進指定 slot */}
   {
     SITE.subtitle && (
       <HeaderSubTitle
@@ -53,13 +56,19 @@ const { page } = Astro.props;
   <!-- Content -->
   <section id="main" aria-label="Main content">
     {
+      // 非常重要，用條件渲染且引入元件的方式，實作 config 裡面 Home Categories 的開關
       HOME_CATEGORIES.enable && (
         <HomeCategories content={HOME_CATEGORIES.content} />
       )
     }
+    {
+      /* page.data 從 Astro.props 中解構出來，一頁有 pagesize 篇文章，
+      用 map 把每一筆 post 轉換成 HTML 標籤 */
+    }
     {
       page.data.map((post, index) => (
         <div class="post-wrapper">
+          {/* 利用 { right: index % 2 === 1 } ，一個動態 class 來實作左圖右文、右圖左文 */}
           <div
             class:list={["post-wrap", { right: index % 2 === 1 }]}
             data-aos="fade-up"
@@ -70,6 +79,7 @@ const { page } = Astro.props;
               aria-label={post.id}
             />
             <div class:list={["post-cover", { right: index % 2 === 1 }]}>
+              {/* urlFor 定義在 utils ，保持模板 .astro 的乾淨 */}
               <img
                 loading="lazy"
                 src={urlFor(post.data.cover || randomCover() || BANNER)}
@@ -107,6 +117,7 @@ const { page } = Astro.props;
         </div>
       ))
     }
+    {/* 把 page 物件(父層)傳遞給子組件(pagination) */}
     <Pagination
       prevUrl={page.url.prev}
       nextUrl={page.url.next}

src/pages/[...page].astro

@@ -11,12 +11,15 @@ import HeaderTitle from "../../components/partial/HeaderTitle.astro";
 import { BASE_URL } from "../../utils/config";
 import CategoryList from "../../components/partial/CategoryList.astro";
 
+// 首頁使用 paginate 來產生分頁路由 (Astro 原生的魔法函式)
 export async function getStaticPaths({ paginate }: { paginate: Function }) {
   const posts = await getCollection("blog");
   posts.sort((a, b) => {
+    // 以發佈日期排序，最新的在前面
     return b.data.pubDate.getTime() - a.data.pubDate.getTime();
   });
   return paginate(posts, {
+    // 每頁顯示 10 篇文章
     pageSize: 10,
   });
 }
@@ -48,6 +51,8 @@ page.data.forEach((post) => {
 const posts = await getCollection("blog");
 const tags = new Set<string>();
 const categories = new Set<string>();
+
+// 收集所有文章的 tags 和 categories
 posts.forEach((post) => {
   if (Array.isArray(post.data.tags)) {
     post.data.tags.forEach((tag) => {

src/pages/archives/[...page].astro

@@ -1,26 +1,35 @@
 ---
+// astro: ... 引入 astro 原生的虛擬模組， slug: 通常只包含 小寫英文、數字 和 連字號 -
 import { type CollectionEntry, getCollection, render } from "astro:content";
 
 import BlogLayout from "../../layouts/BlogLayout.astro";
 
+// 動態路由的靜態路徑產生函式
 export async function getStaticPaths() {
-  const posts = await getCollection("blog");
+  const posts = await getCollection("blog"); // 抓取所有文章
   return posts.map((post, index) => ({
-    params: { slug: post.id },
+    params: { slug: post.id }, // slug variable = post.id
     props: {
+      // 把文章資料傳給頁面使用
       post,
       prev: posts[index - 1] || null,
       next: posts[index + 1] || null,
     },
   }));
 }
+// 定義頁面接收的 props 類型，同時能做到 Error checking
 type Props = {
   post: CollectionEntry<"blog">;
   prev: CollectionEntry<"blog"> | null;
   next: CollectionEntry<"blog"> | null;
 };
 
-const { post, prev, next } = Astro.props;
+const { post, prev, next } = Astro.props; // 藉由 Astro 框架來傳遞 props
+/* Equals to: (所以 Astro.props 就是一個 JavaScript 物件)
+const post = Astro.props.post;
+const prev = Astro.props.prev;
+const next = Astro.props.next;
+*/
 const { Content, headings } = await render(post);
 ---
 
@@ -38,10 +47,15 @@ const { Content, headings } = await render(post);
   import PhotoSwipeLightbox from "photoswipe/lightbox";
   import "photoswipe/style.css";
 
+  // 啟用了 View Transitions ，當使用者按上一頁或連結時，不會整頁刷新。
+  // 所以使用 astro:page-load 確定每次頁面內容更新後，
+  // 程式碼都會被執行一次，來重新綁定圖片點擊事件。
   document.addEventListener("astro:page-load", () => {
     document
       .querySelectorAll(".article-entry img")
       // @ts-expect-error - change from Element to HTMLImageElement
+      // PhotoSwipe 套件要求圖片必須被包在 <a> 連結標籤內才能運作
+      // 所以這裡的邏輯是把每一張圖片都包在 <a> 標籤內，並且把圖片的 src 設為連結的 href
       .forEach((element: HTMLImageElement) => {
         if (
           element.parentElement?.tagName === "A" ||
@@ -50,12 +64,13 @@ const { Content, headings } = await render(post);
           return;
         const a = document.createElement("a");
         a.href ? (a.href = element.src) : a.setAttribute("href", element.src);
+        // 確認圖片是否載入完成，因為 PhotoSwipe 需要知道圖片的寬高才能正常運作
         if (element.naturalWidth || element.naturalHeight) {
           a.dataset.pswpWidth = element.naturalWidth + "";
           a.dataset.pswpHeight = element.naturalHeight + "";
         } else {
           console.warn(
-            "Image naturalWidth and naturalHeight cannot be obtained right now, fallback to onload."
+            "Image naturalWidth and naturalHeight cannot be obtained right now, fallback to onload.",
           );
           element.onload = () => {
             a.dataset.pswpWidth = element.naturalWidth + "";
@@ -73,10 +88,12 @@ const { Content, headings } = await render(post);
       gallery: ".article-entry",
       children: "a.article-gallery-item",
       pswpModule: () => import("photoswipe"),
+      //// pswpModule 動態引入模組 (Code Splitting)，節省效能
     }).init();
   });
 </script>
 
+{/* 針對流程圖，目的是解決「深色模式切換」與「頁面跳轉」的問題 */}
 <script>
   import mermaid from "mermaid";
 
@@ -130,6 +147,7 @@ const { Content, headings } = await render(post);
       querySelector: "pre.mermaid",
     });
   };
+  // 當使用者切換主題時，會觸發 theme-set 事件，邏輯是重新載入 Mermaid 圖表
   const themeSetHandler = (e: any) => {
     let theme = e.detail.theme;
     if (e.detail.theme === "light") {
@@ -149,6 +167,7 @@ const { Content, headings } = await render(post);
       .catch(console.error);
   };
   const mermaidInit = () => {
+    // 為了確保事件不會被重複綁定，先移除再添加
     document.body.removeEventListener("theme-set", themeSetHandler);
     document.body.addEventListener("theme-set", themeSetHandler);