@jet-w/astro-blog 0.2.0 → 0.2.2

package/templates/default/content/posts/blog_docs_zh/03.config/03-i18n.md

@@ -0,0 +1,348 @@
+---
+title: 多语言支持
+description: 为博客添加多语言支持
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - 文档
+tags:
+  - 配置
+  - 多语言
+---
+
+# 多语言支持
+
+添加多语言支持以触达全球受众。
+
+## 概述
+
+多语言系统提供：
+
+- **多种语言** - 支持任意数量的语言
+- **URL 前缀** - `/en/posts`、`/zh-CN/posts`
+- **语言独立配置** - 不同的菜单、标题等
+- **语言切换器** - 内置 UI 组件
+- **SEO** - 正确的 hreflang 标签
+
+## 基本设置
+
+### 1. 配置语言
+
+在 `astro.config.mjs` 中：
+
+```javascript
+import { astroBlog, defineI18nConfig } from '@jet-w/astro-blog';
+import { enConfig } from './src/config/locales/en';
+import { zhCNConfig } from './src/config/locales/zh-CN';
+
+const i18nConfig = defineI18nConfig({
+  defaultLocale: 'en',
+  locales: [
+    { code: 'en', name: 'English', htmlLang: 'en', dateLocale: 'en-US' },
+    { code: 'zh-CN', name: '中文', htmlLang: 'zh-CN', dateLocale: 'zh-CN' },
+  ],
+  routing: {
+    prefixDefaultLocale: false,
+  },
+  localeConfigs: {
+    'en': enConfig,
+    'zh-CN': zhCNConfig,
+  },
+});
+
+export default defineConfig({
+  integrations: [astroBlog({ i18n: i18nConfig })],
+});
+```
+
+### 2. 创建语言配置
+
+为每种语言创建文件夹：
+
+```
+src/config/locales/
+├── en/
+│   ├── index.ts
+│   ├── site.ts
+│   ├── menu.ts
+│   ├── footer.ts
+│   ├── sidebar.ts
+│   └── ui.ts        # UI 翻译
+└── zh-CN/
+    ├── index.ts
+    ├── site.ts
+    ├── menu.ts
+    ├── footer.ts
+    ├── sidebar.ts
+    └── ui.ts        # UI 翻译
+```
+
+### 3. 配置每种语言
+
+**英文 (`en/index.ts`):**
+
+```typescript
+import { site } from './site';
+import { menu } from './menu';
+import { footer } from './footer';
+import { sidebar } from './sidebar';
+import { ui } from './ui';
+
+export const enConfig = {
+  site,
+  menu,
+  footer,
+  sidebar,
+  ui,
+};
+```
+
+**英文站点 (`en/site.ts`):**
+
+```typescript
+export const site = {
+  title: 'My Blog',
+  description: 'A blog about technology',
+};
+```
+
+**英文菜单 (`en/menu.ts`):**
+
+```typescript
+export const menu = [
+  { name: 'Home', href: '/', icon: 'home' },
+  { name: 'Posts', href: '/posts', icon: 'posts' },
+  { name: 'About', href: '/about', icon: 'about' },
+];
+```
+
+## URL 结构
+
+当 `prefixDefaultLocale: false` 时：
+
+| 语言 | URL |
+|------|-----|
+| 英文（默认） | `/posts` |
+| 中文 | `/zh-CN/posts` |
+
+当 `prefixDefaultLocale: true` 时：
+
+| 语言 | URL |
+|------|-----|
+| 英文 | `/en/posts` |
+| 中文 | `/zh-CN/posts` |
+
+## 内容组织
+
+### 方式 1：分开文件夹
+
+为每种语言创建单独的内容文件夹：
+
+```
+content/posts/
+├── blog_docs_en/    # 英文文档
+│   └── ...
+└── blog_docs_zh/    # 中文文档
+    └── ...
+```
+
+### 方式 2：相同内容
+
+使用语言感知的 frontmatter：
+
+```yaml
+---
+title: Hello World
+lang: en
+---
+```
+
+## 语言切换器
+
+当配置多种语言时，语言切换器会自动出现在头部。
+
+它显示：
+- 当前语言标志/名称
+- 包含所有语言的下拉菜单
+- 链接到其他语言的相同页面
+
+## 语言配置选项
+
+### 语言定义
+
+```typescript
+{
+  code: 'en',           // URL 前缀
+  name: 'English',      // 显示名称
+  htmlLang: 'en',       // HTML lang 属性
+  dateLocale: 'en-US',  // 日期格式化
+  direction: 'ltr',     // 文本方向（ltr/rtl）
+}
+```
+
+### 语言独立配置
+
+每种语言可以覆盖：
+
+| 配置 | 用途 |
+|------|------|
+| `site` | 标题、描述、作者 |
+| `menu` | 导航链接 |
+| `footer` | 页脚链接和文本 |
+| `sidebar` | 文档树分组 |
+| `ui` | UI 翻译字符串 |
+
+## UI 翻译
+
+博客为英文和中文内置了 50+ 个 UI 字符串的翻译。你可以在语言的 `ui.ts` 文件中覆盖任何字符串。
+
+### 创建 UI 翻译
+
+**英文 (`en/ui.ts`):**
+
+```typescript
+import type { UITranslations } from '@jet-w/astro-blog';
+
+export const ui: Partial<UITranslations> = {
+  // 在这里覆盖任何 UI 字符串
+  browsePosts: 'Browse Posts',
+  aboutMe: 'About Me',
+  searchPlaceholder: 'Search articles...',
+  readMore: 'Continue reading',
+};
+```
+
+### 可用 UI 键
+
+| 分类 | 键 |
+|------|-----|
+| 导航 | `home`, `blog`, `about`, `search` |
+| 文章 | `posts`, `postList`, `noPostsFound`, `readMore`, `readingTime`, `minuteRead` |
+| 标签与分类 | `tags`, `categories`, `allTags`, `allCategories`, `taggedWith`, `inCategory` |
+| 归档 | `archives`, `postsInArchive` |
+| 侧边栏 | `recentPosts`, `popularTags`, `friendLinks`, `documentTree` |
+| 页脚 | `quickLinks`, `contact` |
+| 搜索 | `searchPlaceholder`, `searchResults`, `noResults`, `searching`, `searchArticles`, `searchTips` 等 |
+| Hero | `browsePosts`, `aboutMe` |
+| 分页 | `previousPage`, `nextPage`, `page`, `of` |
+| 文章 | `publishedOn`, `updatedOn`, `author`, `tableOfContents`, `relatedPosts`, `sharePost` |
+| 其他 | `backToTop`, `copyCode`, `copied`, `expand`, `collapse`, `viewMode`, `sortBy`, `draft` |
+| 幻灯片 | `slides`, `slidesList` |
+| RSS | `rssFeed` |
+
+::: tip 提示
+你只需要覆盖想要自定义的字符串。库为所有字符串提供了合理的默认值。
+:::
+
+## 添加新语言
+
+1. 添加到 `locales` 数组：
+
+```typescript
+locales: [
+  { code: 'en', name: 'English', htmlLang: 'en', dateLocale: 'en-US' },
+  { code: 'zh-CN', name: '中文', htmlLang: 'zh-CN', dateLocale: 'zh-CN' },
+  { code: 'ja', name: '日本語', htmlLang: 'ja', dateLocale: 'ja-JP' },  // 新增
+],
+```
+
+2. 创建配置文件夹：
+
+```
+src/config/locales/ja/
+├── index.ts
+├── site.ts
+├── menu.ts
+├── footer.ts
+├── sidebar.ts
+└── ui.ts          # UI 翻译
+```
+
+3. 创建带翻译的 `ui.ts`：
+
+```typescript
+import type { UITranslations } from '@jet-w/astro-blog';
+
+export const ui: Partial<UITranslations> = {
+  // 导航
+  home: 'ホーム',
+  posts: '記事',
+  tags: 'タグ',
+  categories: 'カテゴリー',
+  search: '検索',
+
+  // Hero 区域
+  browsePosts: '記事を見る',
+  aboutMe: '私について',
+
+  // 搜索
+  searchPlaceholder: '記事を検索...',
+  noResults: '結果が見つかりません',
+
+  // 根据需要添加更多翻译...
+};
+```
+
+4. 创建 `index.ts`：
+
+```typescript
+import { site } from './site';
+import { menu } from './menu';
+import { footer } from './footer';
+import { sidebar } from './sidebar';
+import { ui } from './ui';
+
+export const jaConfig = {
+  site,
+  menu,
+  footer,
+  sidebar,
+  ui,
+  contentPathPrefix: 'blog_docs_ja',
+};
+```
+
+5. 添加到 `astro.config.mjs` 的 `localeConfigs`：
+
+```typescript
+import { jaConfig } from './src/config/locales/ja';
+
+localeConfigs: {
+  'en': enConfig,
+  'zh-CN': zhCNConfig,
+  'ja': jaConfig,  // 新增
+},
+```
+
+## RTL 语言
+
+对于从右到左的语言（阿拉伯语、希伯来语）：
+
+```typescript
+{
+  code: 'ar',
+  name: 'العربية',
+  htmlLang: 'ar',
+  dateLocale: 'ar-SA',
+  direction: 'rtl',  // 启用 RTL
+}
+```
+
+## 最佳实践
+
+::: tip 多语言技巧
+1. **从两种语言开始** - 不需要时不要添加更多
+2. **保持内容同步** - 一起更新所有翻译
+3. **使用一致的 URL** - 跨语言匹配 URL 结构
+4. **彻底测试** - 检查所有语言的所有页面
+:::
+
+::: warning 路径一致性
+更改 `defaultLocale` 时，更新所有菜单和页脚链接以匹配新的 URL 结构。
+:::
+
+---
+
+恭喜！你已完成配置指南。
+
+返回 [文档首页](../) 了解更多主题。

package/templates/default/content/posts/blog_docs_zh/03.config/README.md

@@ -0,0 +1,85 @@
+---
+title: 配置
+description: 使用站点设置、侧边栏和多语言自定义你的博客
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - 文档
+tags:
+  - 配置
+  - 设置
+---
+
+# 配置
+
+通过配置文件自定义博客的各个方面。
+
+## 配置文件
+
+所有配置都在 `src/config/` 目录：
+
+```
+src/config/
+├── locales/          # 语言特定配置
+│   ├── en/          # 英文
+│   └── zh-CN/       # 中文
+├── site.ts           # 站点元数据
+├── menu.ts           # 导航菜单
+├── sidebar.ts        # 侧边栏设置
+├── footer.ts         # 页脚内容
+└── social.ts         # 社交链接
+```
+
+## 配置指南
+
+| 指南 | 描述 |
+|------|------|
+| [站点设置](./01-site) | 标题、描述、作者信息 |
+| [侧边栏](./02-sidebar) | 导航和文档树 |
+| [多语言](./03-i18n) | 添加多语言支持 |
+
+## 快速概览
+
+### 站点配置
+
+```typescript
+// src/config/site.ts
+export const siteConfig = {
+  title: '我的博客',
+  description: '一个技术博客',
+  author: '你的名字',
+  avatar: '/images/avatar.jpg',
+};
+```
+
+### 导航菜单
+
+```typescript
+// src/config/locales/zh-CN/menu.ts
+export const menu = [
+  { name: '首页', href: '/', icon: 'home' },
+  { name: '文章', href: '/posts', icon: 'posts' },
+  { name: '关于', href: '/about', icon: 'about' },
+];
+```
+
+### 多语言
+
+```javascript
+// astro.config.mjs
+const i18nConfig = defineI18nConfig({
+  defaultLocale: 'en',
+  locales: [
+    { code: 'en', name: 'English' },
+    { code: 'zh-CN', name: '中文' },
+  ],
+  localeConfigs: {
+    'en': enConfig,
+    'zh-CN': zhCNConfig,
+  },
+});
+```
+
+---
+
+从 [站点设置](./01-site) 开始！

package/templates/default/content/posts/blog_docs_zh/README.md

@@ -0,0 +1,78 @@
+---
+title: Astro 博客文档
+description: 一个基于 Astro、Vue 和 Tailwind CSS 构建的现代博客系统
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - 文档
+tags:
+  - Astro
+  - 指南
+star: true
+---
+
+# Astro 博客
+
+一个基于 **Astro**、**Vue 3** 和 **Tailwind CSS** 构建的现代化、功能丰富的博客系统。
+
+::: tip 为什么选择这个博客？
+- **快速** - 静态站点生成，页面加载近乎即时
+- **现代** - 采用最新的 Web 技术构建
+- **灵活** - 支持 Markdown、MDX 和丰富的组件
+- **美观** - 简洁设计，支持深色模式
+:::
+
+## 快速入门
+
+第一次使用 Astro 博客？从这里开始：
+
+| 章节 | 描述 |
+|------|------|
+| [介绍](./01.get-started/) | 什么是 Astro 博客以及为什么要使用它 |
+| [安装](./01.get-started/02-install) | 设置你的开发环境 |
+| [第一篇文章](./01.get-started/03-create-post) | 创建并发布你的第一篇文章 |
+| [项目结构](./01.get-started/04-structure) | 了解文件组织方式 |
+| [部署](./01.get-started/05-deploy) | 构建并部署你的博客 |
+
+## 写作指南
+
+学习如何创作精美的内容：
+
+| 指南 | 描述 |
+|------|------|
+| [Markdown 基础](./02.guide/) | 基本 Markdown 语法 |
+| [容器](./02.guide/02-containers) | 提示框、警告框和标注 |
+| [代码块](./02.guide/03-code-blocks) | 语法高亮及更多功能 |
+| [图表](./02.guide/03-mermaid) | 使用 Mermaid 绘制流程图和图表 |
+| [数学公式](./02.guide/06-latex) | LaTeX 数学公式渲染 |
+| [视频嵌入](./02.guide/07-video) | 嵌入 YouTube、Bilibili 等视频 |
+| [图标](./02.guide/04-icons) | 使用多个图标库的图标 |
+
+## 配置
+
+自定义你的博客：
+
+| 配置 | 描述 |
+|------|------|
+| [站点设置](./03.config/01-site) | 标题、描述和元数据 |
+| [侧边栏](./03.config/02-sidebar) | 导航和文档树 |
+| [多语言](./03.config/03-i18n) | 添加多语言支持 |
+
+## 快速开始
+
+```bash
+# 安装依赖
+npm install
+
+# 启动开发服务器
+npm run dev
+
+# 构建生产版本
+npm run build
+```
+
+然后访问 `http://localhost:4321` 查看你的博客！
+
+---
+
+准备好了吗？从 [介绍](./01.get-started/) 开始！

package/templates/default/package.dev.json

@@ -0,0 +1,31 @@
+{
+  "name": "my-astro-blog",
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/mdx": "^4.3.12",
+    "@astrojs/rss": "^4.0.14",
+    "@astrojs/tailwind": "^5.1.3",
+    "@astrojs/vue": "^5.0.6",
+    "@jet-w/astro-blog": "file:../../",
+    "@tailwindcss/typography": "^0.5.15",
+    "astro": "^5.14.1",
+    "echarts": "^6.0.0",
+    "fuse.js": "^7.0.0",
+    "mermaid": "^11.12.2",
+    "rehype-katex": "^7.0.1",
+    "rehype-raw": "^7.0.0",
+    "remark-directive": "^4.0.0",
+    "remark-math": "^6.0.0",
+    "tailwindcss": "^3.4.17",
+    "typescript": "^5.7.2",
+    "vue": "^3.5.13"
+  }
+}

package/templates/default/package.json

@@ -14,7 +14,7 @@
     "@astrojs/rss": "^4.0.14",
     "@astrojs/tailwind": "^5.1.3",
     "@astrojs/vue": "^5.0.6",
-    "@jet-w/astro-blog": "file:../../",
+    "@jet-w/astro-blog": "^0.2.1",
     "@tailwindcss/typography": "^0.5.15",
     "astro": "^5.14.1",
     "echarts": "^6.0.0",

package/templates/default/src/config/locales/en/index.ts

@@ -5,12 +5,16 @@ import { site } from './site';
 import { menu } from './menu';
 import { footer } from './footer';
 import { sidebar } from './sidebar';
+import { ui } from './ui';
 
 export const enConfig = {
   site,
   menu,
   footer,
   sidebar,
+  ui,
+  // Content path prefix for filtering posts by locale
+  contentPathPrefix: 'blog_docs_en',
 };
 
-export { site, menu, footer, sidebar };
+export { site, menu, footer, sidebar, ui };

package/templates/default/src/config/locales/en/menu.ts

@@ -6,7 +6,9 @@
  */
 export const menu = [
   { name: 'Home', href: '/', icon: 'home' },
-  { name: 'Blog Docs', href: '/posts/blog_docs_en', icon: 'posts' },
+  { name: 'Get Started', href: '/posts/blog_docs_en/01.get-started', icon: 'posts' },
+  { name: 'Guide', href: '/posts/blog_docs_en/02.guide', icon: 'posts' },
+  { name: 'Config', href: '/posts/blog_docs_en/03.config', icon: 'posts' },
   { name: 'Slides', href: '/slides', icon: 'slides' },
   { name: 'About', href: '/about', icon: 'about' },
 ];

package/templates/default/src/config/locales/en/sidebar.ts

@@ -10,9 +10,25 @@ export const sidebar = {
       type: 'scan' as const,
       title: 'Documentation',
       icon: 'ri:book-open-line',
-      scanPath: 'blog_docs_en',
+      scanPath: 'blog_docs_en/01.get-started',
       collapsed: false,
-      showForPaths: ['/posts/blog_docs_en/**'],
+      showForPaths: ['/posts/blog_docs_en/01.get-started/**'],
+    },
+    {
+      type: 'scan' as const,
+      title: 'Documentation',
+      icon: 'ri:book-open-line',
+      scanPath: 'blog_docs_en/02.guide',
+      collapsed: false,
+      showForPaths: ['/posts/blog_docs_en/02.guide/**'],
+    },
+    {
+      type: 'scan' as const,
+      title: 'Documentation',
+      icon: 'ri:book-open-line',
+      scanPath: 'blog_docs_en/03.config',
+      collapsed: false,
+      showForPaths: ['/posts/blog_docs_en/03.config/**'],
     },
   ],
 };

package/templates/default/src/config/locales/en/site.ts

@@ -3,5 +3,5 @@
  */
 export const site = {
   title: 'My Astro Blog',
-  description: 'A personal tech blog built with Astro + Vue + Tailwind',
+  description: '',
 };

package/templates/default/src/config/locales/en/ui.ts

@@ -0,0 +1,29 @@
+/**
+ * English UI translations
+ *
+ * Override any UI strings here. The library provides default English translations,
+ * so you only need to add strings you want to customize.
+ *
+ * See UITranslations interface for all available keys:
+ * - Navigation: home, blog, about, search
+ * - Posts: posts, postList, noPostsFound, readMore, readingTime, minuteRead
+ * - Tags & Categories: tags, categories, allTags, allCategories, taggedWith, inCategory
+ * - Archives: archives, postsInArchive
+ * - Sidebar: recentPosts, popularTags, friendLinks, documentTree
+ * - Footer: quickLinks, contact
+ * - Search: searchPlaceholder, searchResults, noResults, searching, searchArticles, etc.
+ * - Hero: browsePosts, aboutMe
+ * - Pagination: previousPage, nextPage, page, of
+ * - Article: publishedOn, updatedOn, author, tableOfContents, relatedPosts, etc.
+ * - Misc: backToTop, copyCode, copied, expand, collapse, viewMode, sortBy, etc.
+ * - Slides: slides, slidesList
+ * - RSS: rssFeed
+ */
+import type { UITranslations } from '@jet-w/astro-blog';
+
+export const ui: Partial<UITranslations> = {
+  // Example overrides:
+  // browsePosts: 'Browse Posts',
+  // aboutMe: 'About Me',
+  // searchPlaceholder: 'Search articles...',
+};

package/templates/default/src/config/locales/zh-CN/index.ts

@@ -5,12 +5,16 @@ import { site } from './site';
 import { menu } from './menu';
 import { footer } from './footer';
 import { sidebar } from './sidebar';
+import { ui } from './ui';
 
 export const zhCNConfig = {
   site,
   menu,
   footer,
   sidebar,
+  ui,
+  // 内容路径前缀，用于按语言过滤文章
+  contentPathPrefix: 'blog_docs_zh',
 };
 
-export { site, menu, footer, sidebar };
+export { site, menu, footer, sidebar, ui };

package/templates/default/src/config/locales/zh-CN/menu.ts

@@ -1,12 +1,14 @@
 /**
  * 中文导航菜单配置
  *
- * 当英语是默认语言时 (prefixDefaultLocale: false)，
- * 中文路径需要 /zh-CN 前缀
+ * 当英文是默认语言且 prefixDefaultLocale: false 时，
+ * 中文路径需要包含 /zh-CN/ 前缀
  */
 export const menu = [
-  { name: '首页', href: '/zh-CN/', icon: 'home' },
-  { name: '博客教学', href: '/zh-CN/posts/blog_docs', icon: 'posts' },
-  { name: '演示', href: '/zh-CN/slides', icon: 'slides' },
+  { name: '主页', href: '/zh-CN/', icon: 'home' },
+  { name: '开始使用', href: '/zh-CN/posts/blog_docs_zh/01.get-started', icon: 'posts' },
+  { name: '指南', href: '/zh-CN/posts/blog_docs_zh/02.guide', icon: 'posts' },
+  { name: '配置', href: '/zh-CN/posts/blog_docs_zh/03.config', icon: 'posts' },
+  { name: '幻灯片', href: '/zh-CN/slides', icon: 'slides' },
   { name: '关于', href: '/zh-CN/about', icon: 'about' },
 ];