@jet-w/astro-blog 0.1.5 → 0.2.0

package/templates/default/astro.config.mjs

@@ -8,17 +8,37 @@ import rehypeKatex from 'rehype-katex';
 import rehypeRaw from 'rehype-raw';
 
 // Import plugins and integration from @jet-w/astro-blog
-import { astroBlog } from '@jet-w/astro-blog';
+import { astroBlog, defineI18nConfig } from '@jet-w/astro-blog';
 import { remarkContainers } from '@jet-w/astro-blog/plugins/remark-containers.mjs';
 import { remarkMermaid } from '@jet-w/astro-blog/plugins/remark-mermaid.mjs';
 import { rehypeCleanContainers } from '@jet-w/astro-blog/plugins/rehype-clean-containers.mjs';
 import { rehypeTabs } from '@jet-w/astro-blog/plugins/rehype-tabs.mjs';
 import { rehypeRelativeLinks } from '@jet-w/astro-blog/plugins/rehype-relative-links.mjs';
 
+// Import locale-specific configurations
+import { zhCNConfig } from './src/config/locales/zh-CN';
+import { enConfig } from './src/config/locales/en';
+
+// i18n configuration - supports any number of languages
+const i18nConfig = defineI18nConfig({
+  defaultLocale: 'en',
+  locales: [
+    { code: 'zh-CN', name: '中文', htmlLang: 'zh-CN', dateLocale: 'zh-CN' },
+    { code: 'en', name: 'English', htmlLang: 'en', dateLocale: 'en-US' },
+  ],
+  routing: {
+    prefixDefaultLocale: false, // en (default) uses /posts, zh-CN uses /zh-CN/posts
+  },
+  localeConfigs: {
+    'zh-CN': zhCNConfig,
+    'en': enConfig,
+  },
+});
+
 // https://astro.build/config
 export default defineConfig({
   integrations: [
-    astroBlog(),
+    astroBlog({ i18n: i18nConfig }),
     vue(),
     mdx(),
     tailwind({

package/templates/default/content/posts/blog_docs/12-i18n.md

@@ -0,0 +1,355 @@
+---
+title: 多语言支持
+description: 配置博客的多语言支持，实现国际化
+pubDate: 2025-12-11
+author: Astro Blog
+categories:
+  - 博客教程
+tags:
+  - i18n
+  - 多语言
+  - 配置
+---
+
+# 多语言支持 (i18n)
+
+本博客内置多语言支持，可以配置任意数量的语言，实现站点的国际化。
+
+## 功能特点
+
+::: info 核心特性
+- **灵活配置**：支持任意数量的语言
+- **自动路由**：自动生成带语言前缀的路由（如 `/en/posts`）
+- **独立配置**：每种语言可以有独立的菜单、站点信息、页脚配置
+- **内置翻译**：自带中文和英文的 UI 翻译
+- **SEO 优化**：自动生成 `hreflang` 标签
+- **语言切换器**：内置语言切换组件
+:::
+
+## 基本配置
+
+在 `astro.config.mjs` 中配置多语言：
+
+```javascript
+import { defineConfig } from 'astro/config';
+import { astroBlog, defineI18nConfig } from '@jet-w/astro-blog';
+
+// i18n 配置
+const i18nConfig = defineI18nConfig({
+  defaultLocale: 'zh-CN',
+  locales: [
+    { code: 'zh-CN', name: '中文', htmlLang: 'zh-CN', dateLocale: 'zh-CN' },
+    { code: 'en', name: 'English', htmlLang: 'en', dateLocale: 'en-US' },
+  ],
+  routing: {
+    prefixDefaultLocale: false,  // 默认语言不加前缀
+  },
+  localeConfigs: {
+    'zh-CN': {
+      // 中文配置
+    },
+    'en': {
+      // 英文配置
+    },
+  },
+});
+
+export default defineConfig({
+  integrations: [
+    astroBlog({ i18n: i18nConfig }),
+    // ... 其他集成
+  ],
+});
+```
+
+## 配置详解
+
+### 语言定义 (locales)
+
+每种语言需要定义以下属性：
+
+```typescript
+interface Locale {
+  code: string;        // 语言代码，如 'en', 'zh-CN', 'ja'
+  name: string;        // 显示名称，如 'English', '中文'
+  htmlLang: string;    // HTML lang 属性值
+  dateLocale: string;  // 日期格式化使用的语言
+  direction?: 'ltr' | 'rtl';  // 文字方向（可选）
+}
+```
+
+示例：
+
+```javascript
+locales: [
+  { code: 'zh-CN', name: '中文', htmlLang: 'zh-CN', dateLocale: 'zh-CN' },
+  { code: 'en', name: 'English', htmlLang: 'en', dateLocale: 'en-US' },
+  { code: 'ja', name: '日本語', htmlLang: 'ja', dateLocale: 'ja-JP' },
+  { code: 'ko', name: '한국어', htmlLang: 'ko', dateLocale: 'ko-KR' },
+]
+```
+
+### 路由配置 (routing)
+
+```javascript
+routing: {
+  prefixDefaultLocale: false,  // 是否为默认语言添加 URL 前缀
+}
+```
+
+| 设置 | 默认语言路径 | 其他语言路径 |
+|:---|:---|:---|
+| `prefixDefaultLocale: false` | `/posts` | `/en/posts` |
+| `prefixDefaultLocale: true` | `/zh-CN/posts` | `/en/posts` |
+
+### 语言配置 (localeConfigs)
+
+为每种语言配置独立的站点信息、菜单和页脚：
+
+```javascript
+localeConfigs: {
+  'zh-CN': {
+    site: {
+      title: '我的博客',
+      description: '基于 Astro 构建的个人博客',
+    },
+    menu: [
+      { name: '首页', href: '/', icon: 'home' },
+      { name: '博客', href: '/posts', icon: 'posts' },
+      { name: '关于', href: '/about', icon: 'about' },
+    ],
+    footer: {
+      quickLinksTitle: '快速链接',
+      contactTitle: '联系方式',
+    },
+  },
+  'en': {
+    site: {
+      title: 'My Blog',
+      description: 'A personal blog built with Astro',
+    },
+    menu: [
+      { name: 'Home', href: '/en/', icon: 'home' },
+      { name: 'Blog', href: '/en/posts', icon: 'posts' },
+      { name: 'About', href: '/en/about', icon: 'about' },
+    ],
+    footer: {
+      quickLinksTitle: 'Quick Links',
+      contactTitle: 'Contact',
+    },
+  },
+}
+```
+
+::: warning 路径注意
+非默认语言的菜单链接需要包含语言前缀（如 `/en/posts`）。
+:::
+
+## UI 翻译
+
+### 内置翻译
+
+博客内置了中文和英文的 UI 翻译，包括：
+
+| 分类 | 翻译项 |
+|:---|:---|
+| 导航 | 首页、博客、关于、搜索 |
+| 文章 | 文章列表、阅读更多、阅读时间 |
+| 标签分类 | 标签、分类、全部标签、全部分类 |
+| 归档 | 归档、篇文章 |
+| 侧边栏 | 最新文章、热门标签、文档目录 |
+| 页脚 | 快速链接、联系方式 |
+| 搜索 | 搜索文章、搜索结果、无结果 |
+| 分页 | 上一页、下一页、第 X 页 |
+| 文章详情 | 发布于、更新于、目录、相关文章 |
+| 其他 | 回到顶部、复制、已复制、展开、收起 |
+
+### 自定义翻译
+
+可以在 `localeConfigs` 中覆盖默认翻译：
+
+```javascript
+localeConfigs: {
+  'zh-CN': {
+    ui: {
+      readMore: '继续阅读',
+      noPostsFound: '还没有文章哦~',
+      searchPlaceholder: '输入关键词搜索...',
+    },
+  },
+  'en': {
+    ui: {
+      readMore: 'Continue Reading',
+      noPostsFound: 'No articles yet~',
+    },
+  },
+}
+```
+
+### 添加新语言翻译
+
+对于不内置支持的语言，需要提供完整的 UI 翻译：
+
+```javascript
+localeConfigs: {
+  'ja': {
+    site: { title: '私のブログ' },
+    menu: [...],
+    ui: {
+      home: 'ホーム',
+      blog: 'ブログ',
+      posts: '記事',
+      tags: 'タグ',
+      categories: 'カテゴリー',
+      search: '検索',
+      readMore: '続きを読む',
+      // ... 其他翻译
+    },
+  },
+}
+```
+
+## 内容管理
+
+### 文件组织方式
+
+多语言内容可以通过文件夹组织：
+
+```
+content/posts/
+├── blog_docs/           # 中文文档（默认语言）
+│   ├── README.md
+│   └── 01-quick-start.md
+├── blog_docs_en/        # 英文文档
+│   ├── README.md
+│   └── 01-quick-start.md
+```
+
+::: info 内容自由管理
+框架不强制内容的多语言对应关系，创作者可以自由决定哪些内容需要翻译。
+:::
+
+### 路径映射
+
+| 文件路径 | 默认语言 URL | 其他语言 URL |
+|:---|:---|:---|
+| `blog_docs/README.md` | `/posts/blog_docs` | - |
+| `blog_docs_en/README.md` | - | `/en/posts/blog_docs_en` |
+
+## 语言切换器
+
+博客内置语言切换器组件，显示在页面头部。
+
+### 工作原理
+
+1. 显示所有可用语言
+2. 点击切换到对应语言版本
+3. 自动构建正确的目标 URL
+
+### 在 Vue 组件中使用 i18n
+
+```vue
+<script setup>
+import { useI18n } from '@jet-w/astro-blog/utils/useI18n';
+
+const { t, formatDate, locale } = useI18n();
+</script>
+
+<template>
+  <h1>{{ t('postList') }}</h1>
+  <span>{{ formatDate(post.pubDate) }}</span>
+</template>
+```
+
+## 完整配置示例
+
+```javascript
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import { astroBlog, defineI18nConfig } from '@jet-w/astro-blog';
+
+const i18nConfig = defineI18nConfig({
+  defaultLocale: 'zh-CN',
+  locales: [
+    { code: 'zh-CN', name: '中文', htmlLang: 'zh-CN', dateLocale: 'zh-CN' },
+    { code: 'en', name: 'English', htmlLang: 'en', dateLocale: 'en-US' },
+  ],
+  routing: {
+    prefixDefaultLocale: false,
+  },
+  localeConfigs: {
+    'zh-CN': {
+      site: {
+        title: 'My Astro Blog',
+        description: '基于 Astro + Vue + Tailwind 构建的个人技术博客',
+      },
+      menu: [
+        { name: '首页', href: '/', icon: 'home' },
+        { name: '博客教学', href: '/posts/blog_docs', icon: 'posts' },
+        { name: '演示', href: '/slides', icon: 'slides' },
+        { name: '关于', href: '/about', icon: 'about' },
+      ],
+      footer: {
+        quickLinksTitle: '快速链接',
+        contactTitle: '联系方式',
+      },
+    },
+    'en': {
+      site: {
+        title: 'My Astro Blog',
+        description: 'A personal tech blog built with Astro + Vue + Tailwind',
+      },
+      menu: [
+        { name: 'Home', href: '/en/', icon: 'home' },
+        { name: 'Blog Docs', href: '/en/posts/blog_docs', icon: 'posts' },
+        { name: 'Slides', href: '/en/slides', icon: 'slides' },
+        { name: 'About', href: '/en/about', icon: 'about' },
+      ],
+      footer: {
+        quickLinksTitle: 'Quick Links',
+        contactTitle: 'Contact',
+      },
+    },
+  },
+});
+
+export default defineConfig({
+  integrations: [
+    astroBlog({ i18n: i18nConfig }),
+    // ... 其他集成
+  ],
+});
+```
+
+## SEO 优化
+
+### hreflang 标签
+
+框架自动为多语言页面生成 `hreflang` 标签：
+
+```html
+<link rel="alternate" hreflang="zh-CN" href="https://example.com/posts/hello" />
+<link rel="alternate" hreflang="en" href="https://example.com/en/posts/hello" />
+<link rel="alternate" hreflang="x-default" href="https://example.com/posts/hello" />
+```
+
+这有助于搜索引擎理解页面的语言版本关系。
+
+## 注意事项
+
+::: tip 向后兼容
+不配置 i18n 时，博客默认使用中文单语言模式，与之前的行为完全一致。
+:::
+
+::: warning 路径一致性
+确保菜单链接、内部链接使用正确的语言前缀，避免出现 404 错误。
+:::
+
+::: info 渐进式采用
+可以先配置好 i18n，然后逐步添加多语言内容，不需要一次性完成所有翻译。
+:::
+
+## 下一步
+
+- [站点配置](./11-config) - 了解更多配置选项
+- [快速开始](./01-quick-start) - 返回入门指南

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

@@ -42,6 +42,7 @@ star: true
 | [图标系统](./09-icons) | 多图标库支持与使用方法 |
 | [侧边栏配置](./10-sidebar) | 导航菜单的自动扫描与手动配置 |
 | [站点配置](./11-config) | 站点信息、菜单、样式等配置 |
+| [多语言支持](./12-i18n) | 多语言配置与国际化 |
 
 ## 核心特性
 

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

@@ -0,0 +1,78 @@
+---
+title: Astro Blog Documentation
+description: A modern blog system built with Astro, Vue, and Tailwind CSS
+pubDate: 2025-01-01
+author: Astro Blog
+categories:
+  - Documentation
+tags:
+  - Astro
+  - Guide
+star: true
+---
+
+# Astro Blog
+
+A modern, feature-rich blog system built with **Astro**, **Vue 3**, and **Tailwind CSS**.
+
+::: tip Why Choose This Blog?
+- **Fast** - Static site generation with near-instant page loads
+- **Modern** - Built with the latest web technologies
+- **Flexible** - Markdown, MDX, and rich component support
+- **Beautiful** - Clean design with dark mode support
+:::
+
+## Get Started
+
+New to Astro Blog? Start here:
+
+| Chapter | Description |
+|---------|-------------|
+| [Introduction](./get-started/) | What is Astro Blog and why use it |
+| [Installation](./get-started/02-install) | Set up your development environment |
+| [First Post](./get-started/03-create-post) | Create and publish your first article |
+| [Project Structure](./get-started/04-structure) | Understand the file organization |
+| [Deployment](./get-started/05-deploy) | Build and deploy your blog |
+
+## Writing Guide
+
+Learn how to write beautiful content:
+
+| Guide | Description |
+|-------|-------------|
+| [Markdown Basics](./guide/markdown/) | Essential Markdown syntax |
+| [Containers](./guide/markdown/02-containers) | Tips, warnings, and callouts |
+| [Code Blocks](./guide/markdown/03-code-blocks) | Syntax highlighting and more |
+| [Diagrams](./guide/features/01-mermaid) | Flowcharts and diagrams with Mermaid |
+| [Math Formulas](./guide/features/02-latex) | LaTeX math rendering |
+| [Videos](./guide/features/03-video) | Embed YouTube, Bilibili, and more |
+| [Icons](./guide/features/04-icons) | Use icons from multiple libraries |
+
+## Configuration
+
+Customize your blog:
+
+| Config | Description |
+|--------|-------------|
+| [Site Settings](./config/01-site) | Title, description, and metadata |
+| [Sidebar](./config/02-sidebar) | Navigation and document trees |
+| [Multi-language](./config/03-i18n) | Add multiple language support |
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Build for production
+npm run build
+```
+
+Then visit `http://localhost:4321` to see your blog!
+
+---
+
+Ready to begin? Start with the [Introduction](./get-started/)!

package/templates/default/content/posts/blog_docs_en/config/01-site.md

@@ -0,0 +1,208 @@
+---
+title: Site Settings
+description: Configure your site's title, description, and metadata
+pubDate: 2025-01-01
+author: Astro Blog
+categories:
+  - Documentation
+tags:
+  - Configuration
+  - Site
+---
+
+# Site Settings
+
+Configure your blog's basic information and metadata.
+
+## Site Configuration
+
+### Basic Settings
+
+Edit `src/config/site.ts`:
+
+```typescript
+export const siteConfig = {
+  // Site title (shown in browser tab and header)
+  title: 'My Awesome Blog',
+
+  // Site description (used for SEO)
+  description: 'A blog about web development and technology',
+
+  // Author name
+  author: 'John Doe',
+
+  // Author avatar (shown in header and footer)
+  avatar: '/images/avatar.jpg',
+
+  // Site URL (for SEO and RSS)
+  url: 'https://myblog.com',
+};
+```
+
+### Per-Language Settings
+
+For multi-language sites, configure in locale folders:
+
+```typescript
+// src/config/locales/en/site.ts
+export const site = {
+  title: 'My Blog',
+  description: 'A tech blog about web development',
+};
+
+// src/config/locales/zh-CN/site.ts
+export const site = {
+  title: '我的博客',
+  description: '关于 Web 开发的技术博客',
+};
+```
+
+## Navigation Menu
+
+### Menu Configuration
+
+```typescript
+// src/config/locales/en/menu.ts
+export const menu = [
+  { name: 'Home', href: '/', icon: 'home' },
+  { name: 'Posts', href: '/posts', icon: 'posts' },
+  { name: 'Tags', href: '/tags', icon: 'tags' },
+  { name: 'About', href: '/about', icon: 'about' },
+];
+```
+
+### Available Icons
+
+| Icon | Name |
+|------|------|
+| Home icon | `home` |
+| Posts icon | `posts` |
+| Tags icon | `tags` |
+| Categories icon | `categories` |
+| Archives icon | `archives` |
+| Slides icon | `slides` |
+| About icon | `about` |
+
+### External Links
+
+```typescript
+{
+  name: 'GitHub',
+  href: 'https://github.com/username',
+  icon: 'github',
+  external: true  // Opens in new tab
+}
+```
+
+## Social Links
+
+Configure social media links in `src/config/social.ts`:
+
+```typescript
+export const socialLinks = [
+  {
+    type: 'github',
+    url: 'https://github.com/username',
+    label: 'GitHub',
+  },
+  {
+    type: 'twitter',
+    url: 'https://twitter.com/username',
+    label: 'Twitter',
+  },
+  {
+    type: 'email',
+    url: 'mailto:hello@example.com',
+    label: 'Email',
+  },
+];
+```
+
+### Supported Platforms
+
+| Type | Platform |
+|------|----------|
+| `github` | GitHub |
+| `twitter` | Twitter/X |
+| `linkedin` | LinkedIn |
+| `email` | Email |
+| `youtube` | YouTube |
+| `discord` | Discord |
+| `rss` | RSS Feed |
+
+## Footer Configuration
+
+```typescript
+// src/config/locales/en/footer.ts
+export const footer = {
+  quickLinksTitle: 'Quick Links',
+  quickLinks: [
+    { name: 'Home', href: '/' },
+    { name: 'Posts', href: '/posts' },
+    { name: 'About', href: '/about' },
+  ],
+  contactTitle: 'Contact',
+};
+```
+
+## Astro Configuration
+
+Main configuration in `astro.config.mjs`:
+
+```javascript
+export default defineConfig({
+  // Your site's URL (required for RSS and sitemap)
+  site: 'https://myblog.com',
+
+  // Base path if not at root
+  base: '/',
+
+  integrations: [
+    astroBlog({ i18n: i18nConfig }),
+    vue(),
+    tailwind(),
+  ],
+});
+```
+
+## SEO Settings
+
+SEO is configured through:
+
+1. **Site config** - Default title and description
+2. **Frontmatter** - Per-post title and description
+3. **Auto-generated** - Meta tags, Open Graph, Twitter cards
+
+### Default SEO
+
+```typescript
+// src/config/site.ts
+export const defaultSEO = {
+  title: 'My Blog',
+  description: 'Default description for pages',
+  image: '/images/og-default.jpg',
+};
+```
+
+### Per-Post SEO
+
+```yaml
+---
+title: Post Title
+description: Post description for search results
+image: /images/post-cover.jpg
+---
+```
+
+## Best Practices
+
+::: tip Configuration Tips
+1. **Keep URLs consistent** - Use trailing slashes or not, but be consistent
+2. **Optimize images** - Avatar and OG images should be web-optimized
+3. **Write good descriptions** - 150-160 characters for SEO
+4. **Update social links** - Keep them current and working
+:::
+
+---
+
+Next: [Sidebar Configuration](./02-sidebar)