Sveltepress

SveltePress 可以在同一个站点中提供多种语言。国际化是可选的：不传 locales 时，站点保持单语言，行为与之前完全一致。

演练场中的国际化条目会按作者提交的内容启动三语言默认主题 Starter，并打开 config/locales.ts。中文和孟加拉语演练场仍打开同一棵树，预览分别停在 /zh/ 与 /bn/。这是例外：其他演练场条目都是用页面语言写在默认路径上的单语言树。

按需启用多语言

启用多语言

向 sveltepress() 传入 locales 映射。键是 URL 前缀（默认语言为 /，其余如 /zh/、/bn/）。每个条目需要 BCP 47 的 lang、语言切换器展示用的 label，以及该语言完整的主题选项：

vite.config.ts

import { const defaultTheme: ThemeDefaultdefaultTheme } from '@sveltepress/theme-default'
import { const sveltepress: (options?: SveltepressVitePluginOptions) => PluginOptionsveltepress } from '@sveltepress/vite'
import { function defineConfig(config: UserConfig): UserConfig (+5 overloads)Type helper to make it easier to use vite.config.ts
accepts a direct
UserConfig
object, or a function that returns it.
The function receives a
ConfigEnv
object.defineConfig } from 'vite'
import { const locales: LocalesConfigThe merged documentation site's locales. Each locale carries its full
theme options; the theme resolves them per route via
virtual:sveltepress/locale.locales } from './config/locales'

export default function defineConfig(config: UserConfig): UserConfig (+5 overloads)Type helper to make it easier to use vite.config.ts
accepts a direct
UserConfig
object, or a function that returns it.
The function receives a
ConfigEnv
object.defineConfig({
  UserConfig.plugins?: PluginOption[] | undefinedArray of vite plugins to use.plugins: [
    function sveltepress(options?: SveltepressVitePluginOptions): PluginOptionsveltepress({
      SveltepressVitePluginOptions.theme?: ResolvedTheme | undefinedtheme: function defaultTheme(themeOptions?: DefaultThemeOptions | undefined): ResolvedThemedefaultTheme({
        // 各语言共享的站点级选项（logo、github、pwa 等）
      }),
      SveltepressVitePluginOptions.locales?: LocalesConfig<any> | undefinedMulti-locale site configuration keyed by URL prefix ('/' for the default
locale, '/zh/', '/bn/', ...). Each entry carries that locale's lang,
a user-facing label for the switcher, and its full theme options.
When omitted the site stays single-locale and behavior is unchanged.locales,
    }),
  ],
})

config/locales.ts

import type { 
type LocalesConfig<ThemeOptions = any> = {
    [x: string]: LocaleConfig<ThemeOptions>;
}Multi-locale site configuration keyed by URL prefix.LocalesConfig } from '@sveltepress/vite'
import import navbarnavbar from './navbar'
import import sidebarsidebar from './sidebar'
import import zhI18nzhI18n from './zh/i18n'
import import zhNavbarzhNavbar from './zh/navbar'
import import zhSidebarzhSidebar from './zh/sidebar'

export const const locales: LocalesConfiglocales: 
type LocalesConfig<ThemeOptions = any> = {
    [x: string]: LocaleConfig<ThemeOptions>;
}Multi-locale site configuration keyed by URL prefix.LocalesConfig = {
  '/': {
    LocaleConfig<any>.lang: stringBCP 47 language tag, e.g. 'en', 'zh-CN', 'bn'.lang: 'en',
    LocaleConfig<any>.label: stringUser-facing label rendered in the language switcher.label: 'English',
    LocaleConfig<any>.theme: anyThe locale's full theme options.theme: { navbar: anynavbar, sidebar: anysidebar },
  },
  '/zh/': {
    LocaleConfig<any>.lang: stringBCP 47 language tag, e.g. 'en', 'zh-CN', 'bn'.lang: 'zh',
    LocaleConfig<any>.label: stringUser-facing label rendered in the language switcher.label: '中文',
    LocaleConfig<any>.theme: anyThe locale's full theme options.theme: {
      navbar: anynavbar: import zhNavbarzhNavbar,
      sidebar: anysidebar: import zhSidebarzhSidebar,
      i18n: anyi18n: import zhI18nzhI18n,
    },
  },
}

未配置 locales 时，SveltePress 不会改写路径、不会渲染语言切换器，也不会扫描各语言路由树。

语言路由与前缀

路由与前缀

把翻译页面放在与默认语言相同的逻辑路由下：

src/routes/
├─ guide/introduction/+page.md          # 英文 → /guide/introduction/
├─ zh/guide/introduction/+page.md       # 中文 → /zh/guide/introduction/
└─ bn/guide/introduction/+page.md       # 孟加拉语 → /bn/guide/introduction/

txt

默认语言保持无前缀的 /。其他语言使用各自配置的前缀（/zh/、/bn/ 等）。各语言的逻辑路径一致，只有前缀不同。导航栏、侧边栏、首页动作按钮和特性卡片都应使用这些逻辑路径（例如 /guide/introduction/）；默认主题会自动加上当前语言前缀。

语言切换器与回退

语言切换器与回退

配置 locales 后，默认主题会在导航栏渲染语言切换器。切换语言会保留当前文档版本、同一逻辑页面，以及正在阅读的标题位置（#hash）。若当前位于历史版本页面（/v/<id>/… 或 /zh/v/<id>/…），会优先进入目标语言的同一冻结版本。只有该冻结页面不存在时，才回退到该语言当前版的同一逻辑页面；再不行则打开该语言首页，并显示简短提示（svp-locale-fallback=1）。

可通过主题 i18n.localeSwitcher 与 i18n.localePageUnavailable 自定义切换器与提示文案。

virtual/locale

`virtual:sveltepress/locale`

主题与自定义布局可从该虚拟模块导入语言相关辅助函数：

import {
  const locales: LocalesConfig | nulllocales,
  const resolveLocale: (pathname: string, base?: string) => ResolvedLocale | nullresolveLocale,
  const resolveLocaleSwitch: (pathname: string, targetPrefix: string, base?: string) => LocaleSwitchTarget | nullresolveLocaleSwitch,
  const resolveLocalizedPath: (to: string, locale: ResolvedLocale | null, base?: string) => stringresolveLocalizedPath,
} from 'virtual:sveltepress/locale'

const const active: ResolvedLocale<any> | nullactive = function resolveLocale(pathname: string, base?: string): ResolvedLocale | nullresolveLocale('/zh/guide/introduction/')
const const href: stringhref = function resolveLocalizedPath(to: string, locale: ResolvedLocale | null, base?: string): stringresolveLocalizedPath('/guide/quick-start/', const active: ResolvedLocale<any> | nullactive)
const const target: LocaleSwitchTarget | nulltarget = function resolveLocaleSwitch(pathname: string, targetPrefix: string, base?: string): LocaleSwitchTarget | nullresolveLocaleSwitch('/zh/guide/introduction/', '/')

locales — 已配置的映射；未启用 i18n 时为 null
resolveLocale(pathname) — 当前语言（lang、label、prefix、theme 等）
resolveLocalizedPath(to, locale) — 将内部链接改写到当前语言
resolveLocaleSwitch(pathname, targetPrefix) — 切换器用的 { href, fallback }

createLocaleHandle

SSR `<html lang>`

使用 @sveltepress/vite/hooks 中的 createLocaleHandle，让首屏 HTML 带上正确的语言属性，方便爬虫与辅助技术。默认主题会在客户端路由切换后同步 document.documentElement.lang。

src/hooks.server.js

// @noErrors
import { createLocaleHandle } from '@sveltepress/vite/hooks'
import { locales } from '../config/locales'

export const handle = createLocaleHandle(locales)

按语言的 llms 与 hreflang sitemap

按语言的 llms 与 sitemap

启用 llms 后，生产构建会写入按语言划分的 llms.txt / llms-full.txt（例如 /llms.txt 与 /zh/llms.txt），只列出该语言页面及带前缀的 URL。历史索引写在各语言的版本基路径下（/v/<id>/、/zh/v/<id>/ 等）。

sitemap.xml 会列出每种语言的当前页面，并为共享同一逻辑路由的语言生成 hreflang 备用地址，同时包含各语言清单中符合条件的历史版本 URL。EOL 历史默认排除，除非该版本设置 noIndex: false。

按语言的文档版本管理

按语言的文档版本管理

新增语言不需要改 SveltePress 的包代码。在 locales 中加上前缀，把页面放到 src/routes/<slug>/；若启用文档版本，再运行 sveltepress versions init --locale <slug>。语言切换、侧边栏本地化和历史 URL 都会按这个前缀工作。

每种语言可以维护自己的文档版本清单：

语言前缀	清单文件	版本基路径
`/`（默认）	`sveltepress.versions.json`	`/v`
`/<slug>/`（例如 `/zh/`、`/bn/`、`/ja/`）	`sveltepress.versions.<slug>.json`	`/<slug>/v`

默认的 sveltepress versions build 会为配置中的每种语言生成草稿，并把各语言的 /v/ 树写入同一份产物。init、create、validate 以及只处理某一种语言的任务才需要 --locale：

sveltepress versions build
sveltepress versions create 8.2 --label "8.2" --locale zh
sveltepress versions validate --locale zh

init --locale zh 默认使用基路径 /zh/v；增量源码位于 version-deltas-zh/（或清单中的 artifacts.sources）。完整发版流程见文档版本管理。

按语言的搜索

本地搜索会按 <html lang="…"> 过滤。DocSearch 与自定义搜索应通过各语言主题选项配置独立索引。细节与版本相关行为见搜索。

当前页面

启用多语言路由与前缀语言切换器与回退 virtual:sveltepress/locale SSR <html lang> 按语言的 llms 与 sitemap 按语言的文档版本管理按语言的搜索