@astro-minimax/ai 0.7.2 → 0.7.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astro-minimax/ai",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "type": "module",
   "description": "Vendor-agnostic AI integration package with full RAG pipeline for astro-minimax blogs — supports OpenAI, Cloudflare AI, and custom providers.",
   "author": "Souloss",
@@ -76,6 +76,9 @@
   "files": [
     "dist/",
     "src/components/",
+    "src/providers/mock.ts",
+    "src/server/types.ts",
+    "src/utils/i18n.ts",
     "src/styles/",
     "README.md"
   ],
@@ -84,7 +87,7 @@
     "@ai-sdk/openai-compatible": "^2.0.35",
     "ai": "^6.0.116",
     "workers-ai-provider": "^3.1.2",
-    "@astro-minimax/notify": "0.7.2"
+    "@astro-minimax/notify": "0.7.4"
   },
   "optionalDependencies": {
     "undici": "^6.0.0"
@@ -112,7 +115,7 @@
     "pnpm": ">=9.0.0"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/server/dev-server.js",
     "build:watch": "tsc -p tsconfig.build.json --watch",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist"

package/src/components/AIChatContainer.tsx

@@ -1,7 +1,8 @@
+/** @jsxImportSource preact */
 import { useState, useCallback } from 'preact/hooks';
-import { ChatPanel } from './ChatPanel.js';
-import type { AIChatConfig } from './ChatPanel.js';
-import type { ArticleChatContext } from '../server/types.js';
+import { ChatPanel } from './ChatPanel.tsx';
+import type { AIChatConfig } from './ChatPanel.tsx';
+import type { ArticleChatContext } from '../server/types.ts';
 
 interface Props {
   config: AIChatConfig;

package/src/components/ChatPanel.tsx

@@ -1,11 +1,12 @@
+/** @jsxImportSource preact */
 import { useCallback, useEffect, useMemo, useRef, useState } from 'preact/hooks';
 import { useChat } from '@ai-sdk/react';
 import { DefaultChatTransport } from 'ai';
 import type { UIMessage } from 'ai';
-import { getMockResponse, createMockStream } from '../providers/mock.js';
-import type { ArticleChatContext, ChatStatusData } from '../server/types.js';
-import { isChatStatusData } from '../server/types.js';
-import { t, getLang } from '../utils/i18n.js';
+import { getMockResponse, createMockStream } from '../providers/mock.ts';
+import type { ArticleChatContext, ChatStatusData } from '../server/types.ts';
+import { isChatStatusData } from '../server/types.ts';
+import { t, getLang } from '../utils/i18n.ts';
 
 export interface AIChatConfig {
   enabled?: boolean;
@@ -775,7 +776,7 @@ export function ChatPanel({ open, onClose, config, articleContext }: ChatPanelPr
   };
 
   return (
-    <div ref={panelRef} data-ai-chat-panel
+    <div ref={panelRef} id="ai-chat-panel" data-ai-chat-panel
       class="fixed right-4 bottom-20 z-[90] flex w-[370px] max-w-[calc(100vw-2rem)] flex-col overflow-hidden rounded-2xl border border-border bg-background shadow-2xl sm:right-6 sm:bottom-20"
       style={{ height: 'min(520px, calc(100vh - 7rem))' }}>
 
@@ -844,7 +845,7 @@ export function ChatPanel({ open, onClose, config, articleContext }: ChatPanelPr
       {/* Input Area */}
       <div class="shrink-0 border-t border-border px-3 pb-2.5 pt-2">
         <div class="flex items-end gap-1.5 rounded-xl border border-border bg-muted/30 px-2.5 py-1.5 transition-colors focus-within:border-accent/40 focus-within:bg-background">
-          <textarea ref={inputRef} rows={1} value={inputValue}
+          <textarea id="ai-chat-input" ref={inputRef} rows={1} value={inputValue}
             onInput={(e) => { setInputValue((e.target as HTMLTextAreaElement).value); autoResize(); }}
             onKeyDown={handleKeyDown} placeholder={placeholder} maxLength={500}
             class="min-w-0 flex-1 resize-none bg-transparent py-0.5 text-[13px] leading-snug text-foreground outline-none placeholder:text-foreground-soft"

package/src/providers/mock.ts

@@ -0,0 +1,240 @@
+/**
+ * Mock provider for development and testing.
+ * Returns predefined responses with article/link recommendations.
+ * Responses use Markdown links which the ChatPanel renders as clickable elements.
+ */
+
+const MOCK_RESPONSES: Array<{ patterns: RegExp[]; zh: string; en: string }> = [
+  {
+    patterns: [/astro/i, /框架/],
+    zh: `Astro 是一个现代化的静态站点生成器，核心优势是"岛屿架构"——默认零 JS，只在交互组件上加载脚本。本博客基于 Astro 构建。
+
+推荐阅读：
+- [快速上手：两种集成方式](/zh/posts/getting-started) — 了解如何搭建 astro-minimax 博客
+- [如何配置主题](/zh/posts/how-to-configure-astro-minimax-theme) — 自定义你的博客外观
+
+外部资源：
+- [Astro 官方文档](https://docs.astro.build) — 深入学习 Astro 框架
+- [Astro 主题市场](https://astro.build/themes/) — 发现更多 Astro 主题`,
+    en: `Astro is a modern static site generator with an "Islands Architecture" — zero JS by default, loading scripts only for interactive components. This blog is built with Astro.
+
+Recommended reading:
+- [Getting Started: Two Integration Methods](/en/posts/getting-started) — Learn how to set up an astro-minimax blog
+- [How to Configure the Theme](/en/posts/how-to-configure-astro-minimax-theme) — Customize your blog
+
+External resources:
+- [Astro Documentation](https://docs.astro.build) — Learn Astro in depth
+- [Astro Themes](https://astro.build/themes/) — Discover more themes`,
+  },
+  {
+    patterns: [/推荐|文章|看什么|读什么|recommend/i],
+    zh: `以下是一些热门文章推荐：
+
+**入门系列：**
+- [快速上手：两种集成方式](/zh/posts/getting-started) — 搭建你的第一个博客
+- [如何添加新文章](/zh/posts/adding-new-post) — 内容创作指南
+- [预定义配色方案](/zh/posts/predefined-color-schemes) — 选一个你喜欢的主题色
+
+**技术深度：**
+- [如何在博客中使用 LaTeX 公式](/zh/posts/how-to-add-latex-equations-in-blog-posts) — 数学公式支持
+- [动态 OG 图片生成](/zh/posts/dynamic-og-images) — 自动生成社交分享图
+
+你对哪个方向的内容更感兴趣？我可以做更精准的推荐。`,
+    en: `Here are some recommended articles:
+
+**Getting Started:**
+- [Getting Started: Two Integration Methods](/en/posts/getting-started) — Build your first blog
+- [Adding New Posts](/en/posts/adding-new-post) — Content creation guide
+- [Predefined Color Schemes](/en/posts/predefined-color-schemes) — Pick your favorite theme color
+
+**Technical Deep Dives:**
+- [LaTeX Equations in Blog Posts](/en/posts/how-to-add-latex-equations-in-blog-posts) — Math formula support
+- [Dynamic OG Images](/en/posts/dynamic-og-images) — Auto-generate social share images
+
+What direction interests you more? I can provide more specific recommendations.`,
+  },
+  {
+    patterns: [/博客|blog|功能|feature/i],
+    zh: `这个博客基于 **astro-minimax** 主题，功能丰富：
+
+核心功能：Markdown/MDX、代码高亮、[数学公式(KaTeX)](/zh/posts/how-to-add-latex-equations-in-blog-posts)、[Mermaid 图表](/zh/posts/mermaid-diagrams)、标签分类、全文搜索(Pagefind)、[Waline 评论](https://waline.js.org)、深色模式。
+
+了解更多：
+- [配置指南](/zh/posts/how-to-configure-astro-minimax-theme) — 完整配置选项
+- [Markdown 扩展语法](/zh/posts/markdown-extended) — 所有支持的语法特性
+
+开源地址：[souloss/astro-minimax](https://github.com/souloss/astro-minimax)`,
+    en: `This blog uses the **astro-minimax** theme with rich features:
+
+Core features: Markdown/MDX, syntax highlighting, [math equations (KaTeX)](/en/posts/how-to-add-latex-equations-in-blog-posts), [Mermaid diagrams](/en/posts/mermaid-diagrams), tags & categories, full-text search (Pagefind), [Waline comments](https://waline.js.org), dark mode.
+
+Learn more:
+- [Configuration Guide](/en/posts/how-to-configure-astro-minimax-theme) — Full config options
+- [Extended Markdown](/en/posts/markdown-extended) — All supported syntax features
+
+Open source: [souloss/astro-minimax](https://github.com/souloss/astro-minimax)`,
+  },
+  {
+    patterns: [/主题|theme|暗色|dark|颜色|color|配色/i],
+    zh: `博客支持亮色和暗色主题，右下角按钮即可切换，也会自动检测系统偏好。
+
+配色方案可以在配置中自定义，目前提供多种预设：
+- [预定义配色方案](/zh/posts/predefined-color-schemes) — 查看所有可用配色
+- [自定义主题色](/zh/posts/customizing-astro-minimax-theme-color-schemes) — 创建你自己的配色
+
+参考 [Tailwind CSS 调色板](https://tailwindcss.com/docs/customizing-colors) 获取灵感。`,
+    en: `The blog supports light and dark themes — toggle with the bottom-right button or auto-detect system preference.
+
+Color schemes are customizable:
+- [Predefined Color Schemes](/en/posts/predefined-color-schemes) — See all available schemes
+- [Custom Theme Colors](/en/posts/customizing-astro-minimax-theme-color-schemes) — Create your own
+
+Check [Tailwind CSS Color Palette](https://tailwindcss.com/docs/customizing-colors) for inspiration.`,
+  },
+  {
+    patterns: [/搭建|部署|deploy|build|install|安装|搭/i],
+    zh: `搭建类似的博客非常简单！有两种方式：
+
+1. **GitHub 模板**（推荐新手）— 一键 Fork，开箱即用
+2. **NPM 包集成** — 适合内容与系统分离的进阶用法
+
+详细步骤请看 [快速上手](/zh/posts/getting-started)。
+
+部署推荐 [Cloudflare Pages](https://pages.cloudflare.com)（免费、全球 CDN），也支持 [Vercel](https://vercel.com) 和 [Netlify](https://netlify.com)。`,
+    en: `Setting up a similar blog is easy! Two methods:
+
+1. **GitHub Template** (recommended for beginners) — One-click fork, ready to use
+2. **NPM Package Integration** — For advanced content/system separation
+
+See [Getting Started](/en/posts/getting-started) for detailed steps.
+
+Deploy with [Cloudflare Pages](https://pages.cloudflare.com) (free, global CDN), or [Vercel](https://vercel.com) / [Netlify](https://netlify.com).`,
+  },
+  {
+    patterns: [/rust/i],
+    zh: `博客中有一系列 Rust 文章：
+- [Rust 入门介绍](/zh/posts/rust-series-01-introduction) — 语言基础
+- [所有权系统](/zh/posts/rust-series-02-ownership) — Rust 核心概念
+- [错误处理](/zh/posts/rust-series-03-error-handling) — Result 和 Option
+- [并发编程](/zh/posts/rust-series-04-concurrency) — 安全的多线程
+
+外部学习资源：
+- [The Rust Book](https://doc.rust-lang.org/book/) — 官方教程
+- [Rust by Example](https://doc.rust-lang.org/rust-by-example/) — 实例学习`,
+    en: `The blog has a Rust series:
+- [Rust Introduction](/en/posts/rust-series-01-introduction) — Language basics
+- [Ownership System](/en/posts/rust-series-02-ownership) — Core Rust concept
+- [Error Handling](/en/posts/rust-series-03-error-handling) — Result and Option
+- [Concurrency](/en/posts/rust-series-04-concurrency) — Safe multithreading
+
+External resources:
+- [The Rust Book](https://doc.rust-lang.org/book/) — Official tutorial
+- [Rust by Example](https://doc.rust-lang.org/rust-by-example/) — Learn by examples`,
+  },
+  {
+    patterns: [/ai|人工智能|助手|assistant|chat/i],
+    zh: `我是这个博客的 AI 助手！当前运行在 Demo 模式，可以：
+- 根据你的问题推荐相关博客文章
+- 推荐有用的外部学习资源
+- 解答关于博客技术栈的问题
+
+启用完整 AI 功能（RAG 搜索增强）需要配置 \`AI_BASE_URL\` 和 \`AI_API_KEY\` 环境变量。
+
+试试问我："有哪些文章推荐？" 或 "怎么搭建类似的博客？"`,
+    en: `I'm the blog AI assistant! Currently in Demo mode, I can:
+- Recommend relevant blog articles based on your questions
+- Suggest useful external learning resources
+- Answer questions about the blog's tech stack
+
+For full AI features (RAG search enhancement), configure \`AI_BASE_URL\` and \`AI_API_KEY\` environment variables.
+
+Try asking: "Recommend some articles?" or "How to build a similar blog?"`,
+  },
+  {
+    patterns: [/搜索|search|pagefind/i],
+    zh: `博客集成了 [Pagefind](https://pagefind.app) 全文搜索引擎，构建时自动索引。点击页面顶部搜索图标即可使用。
+
+了解更多搜索功能：
+- [Pagefind 官方文档](https://pagefind.app/docs/) — 完整配置指南
+- 搜索支持中文和英文内容`,
+    en: `The blog integrates [Pagefind](https://pagefind.app) for full-text search, auto-indexed at build time. Click the search icon at the top to use it.
+
+Learn more:
+- [Pagefind Documentation](https://pagefind.app/docs/) — Complete configuration guide
+- Search supports both Chinese and English content`,
+  },
+  {
+    patterns: [/markdown|mdx|语法|syntax|公式|latex|mermaid|图表/i],
+    zh: `博客支持丰富的内容语法：
+
+- [Markdown 基础语法](/zh/posts/markdown-basics) — 标题、列表、表格等
+- [Markdown 扩展语法](/zh/posts/markdown-extended) — 脚注、高亮、折叠等
+- [LaTeX 数学公式](/zh/posts/how-to-add-latex-equations-in-blog-posts) — KaTeX 渲染
+- [Mermaid 图表](/zh/posts/mermaid-diagrams) — 流程图、时序图
+- [Markmap 思维导图](/zh/posts/markmap-mindmaps) — 交互式思维导图
+
+外部参考：[GitHub Flavored Markdown](https://github.github.com/gfm/)`,
+    en: `The blog supports rich content syntax:
+
+- [Markdown Basics](/en/posts/markdown-basics) — Headings, lists, tables
+- [Extended Markdown](/en/posts/markdown-extended) — Footnotes, highlights, collapsible
+- [LaTeX Equations](/en/posts/how-to-add-latex-equations-in-blog-posts) — KaTeX rendering
+- [Mermaid Diagrams](/en/posts/mermaid-diagrams) — Flowcharts, sequence diagrams
+- [Markmap Mind Maps](/en/posts/markmap-mindmaps) — Interactive mind maps
+
+Reference: [GitHub Flavored Markdown](https://github.github.com/gfm/)`,
+  },
+];
+
+const FALLBACK = {
+  zh: `感谢提问！我目前在 Demo 模式下，可以推荐博客文章和外部资源。
+
+试试这些话题：
+- "有哪些文章推荐？"
+- "Astro 框架是什么？"
+- "怎么搭建类似的博客？"
+- "支持哪些 Markdown 语法？"`,
+  en: `Thanks for asking! I'm in Demo mode and can recommend blog articles and external resources.
+
+Try these topics:
+- "Recommend some articles?"
+- "What is Astro?"
+- "How to build a similar blog?"
+- "What Markdown syntax is supported?"`,
+};
+
+/**
+ * Returns a mock response with Markdown links for article/external link recommendations.
+ */
+export function getMockResponse(question: string, lang = 'zh'): string {
+  const q = question.toLowerCase();
+  const isZh = lang !== 'en';
+
+  for (const { patterns, zh, en } of MOCK_RESPONSES) {
+    if (patterns.some(p => p.test(q))) {
+      return isZh ? zh : en;
+    }
+  }
+
+  return isZh ? FALLBACK.zh : FALLBACK.en;
+}
+
+/**
+ * Creates a ReadableStream that simulates character-by-character streaming.
+ */
+export function createMockStream(text: string): ReadableStream<string> {
+  let index = 0;
+  return new ReadableStream<string>({
+    async pull(controller) {
+      if (index >= text.length) {
+        controller.close();
+        return;
+      }
+      const chunkSize = Math.random() < 0.3 ? 2 : 1;
+      const chunk = text.slice(index, index + chunkSize);
+      index += chunkSize;
+      controller.enqueue(chunk);
+      await new Promise(resolve => setTimeout(resolve, 12 + Math.random() * 23));
+    },
+  });
+}

package/src/server/types.ts

@@ -0,0 +1,89 @@
+import type { UIMessage } from 'ai';
+import type { ProviderManagerEnv } from '../provider-manager/types.js';
+import type { CacheEnv } from '../cache/types.js';
+
+// ── Chat Context ──────────────────────────────────────────────
+
+export interface ChatContext {
+  scope: 'global' | 'article';
+  article?: ArticleChatContext;
+}
+
+export interface ArticleChatContext {
+  slug: string;
+  title: string;
+  categories?: string[];
+  summary?: string;
+  abstract?: string;
+  keyPoints?: string[];
+  relatedSlugs?: string[];
+}
+
+// ── Request / Response ────────────────────────────────────────
+
+export interface ChatRequestBody {
+  context?: ChatContext;
+  id?: string;
+  messages: UIMessage[];
+  lang?: string;
+}
+
+export interface ChatHandlerEnv extends ProviderManagerEnv, CacheEnv {
+  SITE_AUTHOR?: string;
+  SITE_URL?: string;
+  [key: string]: unknown;
+}
+
+export interface ChatHandlerOptions {
+  env: ChatHandlerEnv;
+  request: Request;
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+
+// ── Status Metadata ───────────────────────────────────────────
+
+export type ChatStatusStage = 'search' | 'answer' | 'complete';
+
+export interface ChatStatusData {
+  stage: ChatStatusStage;
+  message: string;
+  progress: number;
+  done: boolean;
+  at: number;
+}
+
+export function createChatStatusData(
+  partial: Omit<ChatStatusData, 'done' | 'at'> & { done?: boolean },
+): ChatStatusData {
+  return {
+    ...partial,
+    done: partial.done ?? partial.stage === 'complete',
+    at: Date.now(),
+  };
+}
+
+export function isChatStatusData(value: unknown): value is ChatStatusData {
+  if (!value || typeof value !== 'object') return false;
+  const v = value as Record<string, unknown>;
+  return typeof v.stage === 'string' && typeof v.message === 'string' && typeof v.progress === 'number';
+}
+
+// ── Error Response ────────────────────────────────────────────
+
+export interface ChatErrorResponse {
+  error: string;
+  code: string;
+  retryable: boolean;
+  retryAfter?: number;
+}
+
+// ── Metadata Initialization ───────────────────────────────────
+
+export interface MetadataConfig {
+  summaries: unknown;
+  authorContext: unknown;
+  voiceProfile: unknown;
+  factRegistry?: unknown;
+  vectorIndex?: unknown;
+  siteUrl?: string;
+}

package/src/utils/i18n.ts

@@ -0,0 +1,238 @@
+/**
+ * AI Package Internationalization
+ * Follows the same pattern as packages/core/src/utils/i18n.ts
+ */
+
+export type AITranslationKey =
+  // Reasoning UI
+  | "ai.reasoning.thinking"
+  | "ai.reasoning.viewReasoning"
+  | "ai.reasoning.waiting"
+  // Error messages
+  | "ai.error.network"
+  | "ai.error.aborted"
+  | "ai.error.rateLimit"
+  | "ai.error.unavailable"
+  | "ai.error.generic"
+  | "ai.error.format"
+  | "ai.error.noOutput"
+  // UI labels
+  | "ai.placeholder"
+  | "ai.clear"
+  | "ai.clearConversation"
+  | "ai.close"
+  | "ai.closeChat"
+  | "ai.retry"
+  | "ai.status.searching"
+  | "ai.status.generating"
+  | "ai.status.found"
+  | "ai.status.citation"
+  | "ai.status.fallback"
+  // Quick prompts
+  | "ai.prompt.techStack"
+  | "ai.prompt.recommend"
+  | "ai.prompt.build"
+  | "ai.prompt.summarize"
+  | "ai.prompt.explain"
+  | "ai.prompt.related"
+  // Welcome messages
+  | "ai.welcome.reading"
+  | "ai.welcome.canHelp"
+  | "ai.welcome.greeting"
+  | "ai.welcome.demo"
+  | "ai.welcome.demoHint"
+  | "ai.welcome.demoPrompt"
+  // Header
+  | "ai.header.reading"
+  | "ai.header.mode"
+  // Assistant branding
+  | "ai.assistantName"
+  | "ai.status.live"
+  // Additional error messages
+  | "ai.error.emptyMessage"
+  | "ai.error.emptyContent"
+  | "ai.error.inputTooLong"
+  | "ai.error.timeout"
+  // Rate limit messages
+  | "ai.error.rateLimit.burst"
+  | "ai.error.rateLimit.sustained"
+  | "ai.error.rateLimit.daily"
+  // Prompt section titles
+  | "ai.prompt.section.responsibilities"
+  | "ai.prompt.section.format"
+  | "ai.prompt.section.principles"
+  | "ai.prompt.section.constraints"
+  | "ai.prompt.section.sourceLayers"
+  | "ai.prompt.section.privacy"
+  | "ai.prompt.section.answerModes"
+  | "ai.prompt.section.preOutputChecks"
+  // Semi-static layer labels
+  | "ai.semiStatic.blogOverview"
+  | "ai.semiStatic.totalPosts"
+  | "ai.semiStatic.mainCategories"
+  | "ai.semiStatic.latestArticles";
+
+const translations: Record<string, Record<AITranslationKey, string>> = {
+  en: {
+    // Reasoning UI
+    "ai.reasoning.thinking": "Thinking...",
+    "ai.reasoning.viewReasoning": "View reasoning",
+    "ai.reasoning.waiting": "Waiting for thoughts...",
+    // Error messages
+    "ai.error.network": "Network connection failed. Please check your connection.",
+    "ai.error.aborted": "Request was cancelled.",
+    "ai.error.rateLimit": "Too many requests. Please try again later.",
+    "ai.error.unavailable": "AI service is temporarily unavailable.",
+    "ai.error.generic": "Something went wrong. Please try again later.",
+    "ai.error.format": "Invalid request format.",
+    // UI labels
+    "ai.placeholder": "Ask a question...",
+    "ai.clear": "Clear",
+    "ai.clearConversation": "Clear conversation",
+    "ai.close": "Close",
+    "ai.closeChat": "Close chat",
+    "ai.retry": "Retry",
+    "ai.status.searching": "Searching...",
+    "ai.status.generating": "Generating response...",
+    "ai.status.found": "Found {count} related items",
+    "ai.status.citation": "Answered from public records",
+    "ai.status.fallback": "AI service unavailable, using demo mode",
+    // Quick prompts
+    "ai.prompt.techStack": "What tech stack is used?",
+    "ai.prompt.recommend": "Recommend some articles?",
+    "ai.prompt.build": "How to build a similar blog?",
+    "ai.prompt.summarize": 'Summarize the key points of "{title}"',
+    "ai.prompt.explain": 'Explain "{point}"',
+    "ai.prompt.related": "What related content should I read next?",
+    // Welcome messages
+    "ai.welcome.reading": 'I\'m reading "{title}" with you.\nAsk me to summarize, explain a concept, or explore related topics.',
+    "ai.welcome.canHelp": "Hi! I'm the blog AI assistant. Ask me anything and I'll help you find related articles.",
+    "ai.welcome.greeting": "Hi! I'm the blog AI assistant.",
+    "ai.welcome.demo": "I'm running in demo mode. I can recommend blog articles and external resources.",
+    "ai.welcome.demoHint": "For full AI features (RAG search), configure AI_BASE_URL and AI_API_KEY.",
+    "ai.welcome.demoPrompt": 'Try: "Recommend articles?" or "How to build this blog?"',
+    // Header
+    "ai.header.reading": "Reading:",
+    "ai.header.mode": "Demo",
+    // Assistant branding
+    "ai.assistantName": "Blog Avatar",
+    "ai.status.live": "Live",
+    // Additional error messages
+    "ai.error.emptyMessage": "Message cannot be empty.",
+    "ai.error.emptyContent": "Message content cannot be empty.",
+    "ai.error.inputTooLong": "Message too long, max {max} characters.",
+    "ai.error.timeout": "Response timeout, please retry or simplify your question.",
+    // Rate limit messages
+    "ai.error.rateLimit.burst": "Too many requests, please try again later.",
+    "ai.error.rateLimit.sustained": "Too many requests, please wait a minute.",
+    "ai.error.rateLimit.daily": "Daily limit reached, please come back tomorrow.",
+    "ai.error.noOutput": "Sorry, I could not generate a valid response. Please try rephrasing your question.",
+    "ai.prompt.section.responsibilities": "Your Responsibilities",
+    "ai.prompt.section.format": "Response Format",
+    "ai.prompt.section.principles": "Recommendation Principles",
+    "ai.prompt.section.constraints": "Constraints",
+    "ai.prompt.section.sourceLayers": "Source Priority Protocol (must follow)",
+    "ai.prompt.section.privacy": "Privacy Protection",
+    "ai.prompt.section.answerModes": "Answer Mode Guide (follow detected mode)",
+    "ai.prompt.section.preOutputChecks": "Pre-Output Checks (execute mentally, do not output steps)",
+    "ai.semiStatic.blogOverview": "Blog Overview",
+    "ai.semiStatic.totalPosts": "{count} posts total",
+    "ai.semiStatic.mainCategories": "Main categories: {categories}",
+    "ai.semiStatic.latestArticles": "Latest Posts",
+  },
+  zh: {
+    // Reasoning UI
+    "ai.reasoning.thinking": "思考中...",
+    "ai.reasoning.viewReasoning": "查看思考过程",
+    "ai.reasoning.waiting": "等待思考...",
+    // Error messages
+    "ai.error.network": "网络连接失败，请检查网络",
+    "ai.error.aborted": "请求已取消",
+    "ai.error.rateLimit": "请求太频繁，请稍后再试",
+    "ai.error.unavailable": "AI 服务暂时不可用",
+    "ai.error.generic": "出了点问题，请稍后再试",
+    "ai.error.format": "请求格式错误",
+    // UI labels
+    "ai.placeholder": "输入你的问题...",
+    "ai.clear": "清除",
+    "ai.clearConversation": "清除对话",
+    "ai.close": "关闭",
+    "ai.closeChat": "关闭聊天",
+    "ai.retry": "重试",
+    "ai.status.searching": "搜索中...",
+    "ai.status.generating": "正在生成回答...",
+    "ai.status.found": "找到 {count} 篇相关内容",
+    "ai.status.citation": "已基于公开记录直接给出回答",
+    "ai.status.fallback": "AI 服务不可用，使用演示模式回复",
+    // Quick prompts
+    "ai.prompt.techStack": "这个博客用了什么技术？",
+    "ai.prompt.recommend": "有哪些文章推荐？",
+    "ai.prompt.build": "怎么搭建类似的博客？",
+    "ai.prompt.summarize": "总结一下《{title}》的核心观点",
+    "ai.prompt.explain": "解释一下「{point}」",
+    "ai.prompt.related": "这篇文章和哪些内容相关？",
+    // Welcome messages
+    "ai.welcome.reading": "我在结合《{title}》陪你阅读。\n你可以让我总结这篇文章、解释某个观点，或者顺着这篇文章继续延伸到相关主题。",
+    "ai.welcome.canHelp": "你好！我是博客 AI 助手，问我任何关于博客内容的问题，我可以帮你找到相关文章。",
+    "ai.welcome.greeting": "你好！我是博客 AI 助手。",
+    "ai.welcome.demo": "我目前在 Demo 模式下，可以推荐博客文章和外部资源。",
+    "ai.welcome.demoHint": "启用完整 AI 功能（RAG 搜索增强）需要配置 AI_BASE_URL 和 AI_API_KEY 环境变量。",
+    "ai.welcome.demoPrompt": "试试：「有哪些文章推荐？」或「怎么搭建类似的博客？」",
+    // Header
+    "ai.header.reading": "正在阅读：",
+    "ai.header.mode": "演示",
+    // Assistant branding
+    "ai.assistantName": "博客分身",
+    "ai.status.live": "在线",
+    // Additional error messages
+    "ai.error.emptyMessage": "消息不能为空。",
+    "ai.error.emptyContent": "消息内容不能为空。",
+    "ai.error.inputTooLong": "消息过长，最多 {max} 字。",
+    "ai.error.timeout": "响应超时，请重试或简化问题。",
+    // Rate limit messages
+    "ai.error.rateLimit.burst": "请求太频繁，请稍后再试。",
+    "ai.error.rateLimit.sustained": "请求次数过多，请一分钟后再试。",
+    "ai.error.rateLimit.daily": "今日对话次数已达上限，请明天再来。",
+    "ai.error.noOutput": "抱歉，我无法生成有效的回答。请尝试换一种方式提问。",
+    "ai.prompt.section.responsibilities": "你的职责",
+    "ai.prompt.section.format": "回答格式",
+    "ai.prompt.section.principles": "推荐原则",
+    "ai.prompt.section.constraints": "约束",
+    "ai.prompt.section.sourceLayers": "来源分层协议（必须遵守）",
+    "ai.prompt.section.privacy": "隐私保护",
+    "ai.prompt.section.answerModes": "回答模式指导（按检测到的模式执行）",
+    "ai.prompt.section.preOutputChecks": "输出前检查（在心里执行，不输出步骤）",
+    "ai.semiStatic.blogOverview": "博客概况",
+    "ai.semiStatic.totalPosts": "共有 {count} 篇文章",
+    "ai.semiStatic.mainCategories": "主要分类：{categories}",
+    "ai.semiStatic.latestArticles": "最新文章",
+  },
+};
+
+/**
+ * Get translation by key.
+ * @param key - Translation key (type-safe)
+ * @param lang - Language code ('zh' or 'en')
+ * @param vars - Optional variables for interpolation (e.g., { count: 5 })
+ */
+export function t(key: AITranslationKey, lang: string = 'zh', vars?: Record<string, string | number>): string {
+  const l = lang === 'zh' ? 'zh' : 'en';
+  let text = translations[l]?.[key] ?? translations['en'][key] ?? key;
+  
+  // Interpolate variables like {count}, {title}, etc.
+  if (vars) {
+    for (const [k, v] of Object.entries(vars)) {
+      text = text.replace(new RegExp(`\\{${k}\\}`, 'g'), String(v));
+    }
+  }
+  
+  return text;
+}
+
+/**
+ * Get normalized language code.
+ * Returns 'zh' for Chinese, 'en' for everything else.
+ */
+export function getLang(lang?: string): string {
+  return lang === 'zh' ? 'zh' : 'en';
+}