国际化（i18n） 2026-09-03 新增
SveltePress 可以在同一个站点中提供多种语言。国际化是可选的：不传 locales 时，站点保持单语言，行为与之前完全一致。
启用多语言
向 sveltepress() 传入 locales 映射。键是 URL 前缀（默认语言为 /，其余如 /zh/、/bn/）。每个条目需要 BCP 47 的 lang、语言切换器展示用的 label，以及该语言完整的主题选项：
import { } from '@sveltepress/theme-default'
import { } from '@sveltepress/vite'
import { } from 'vite'
import { } from './config/locales'
export default ({
: [
({
: ({
// 各语言共享的站点级选项（logo、github、pwa 等）
}),
,
}),
],
})import type { } from '@sveltepress/vite'
import from './navbar'
import from './sidebar'
import from './zh/i18n'
import from './zh/navbar'
import from './zh/sidebar'
export const : = {
'/': {
: 'en',
: 'English',
: { , },
},
'/zh/': {
: 'zh',
: '中文',
: {
: ,
: ,
: ,
},
},
}未配置 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/默认语言保持无前缀的 /。其他语言使用各自配置的前缀（/zh/、/bn/ 等）。各语言的逻辑路径一致，只有前缀不同。导航栏、侧边栏、首页动作按钮和特性卡片都应使用这些逻辑路径（例如 /guide/introduction/）；默认主题会自动加上当前语言前缀。
语言切换器与回退
配置 locales 后，默认主题会在导航栏渲染语言切换器。切换语言会保留当前文档版本、同一逻辑页面，以及正在阅读的标题位置（#hash）。若当前位于历史版本页面（/v/<id>/… 或 /zh/v/<id>/…），会优先进入目标语言的同一冻结版本。只有该冻结页面不存在时，才回退到该语言当前版的同一逻辑页面；再不行则打开该语言首页，并显示简短提示（svp-locale-fallback=1）。
可通过主题 i18n.localeSwitcher 与 i18n.localePageUnavailable 自定义切换器与提示文案。
virtual:sveltepress/locale
主题与自定义布局可从该虚拟模块导入语言相关辅助函数：
import {
,
,
,
,
} from 'virtual:sveltepress/locale'
const = ('/zh/guide/introduction/')
const = ('/guide/quick-start/', )
const = ('/zh/guide/introduction/', '/')locales— 已配置的映射；未启用 i18n 时为nullresolveLocale(pathname)— 当前语言（lang、label、prefix、theme等）resolveLocalizedPath(to, locale)— 将内部链接改写到当前语言resolveLocaleSwitch(pathname, targetPrefix)— 切换器用的{ href, fallback }
SSR <html lang>
使用 @sveltepress/vite/hooks 中的 createLocaleHandle，让首屏 HTML 带上正确的语言属性，方便爬虫与辅助技术。默认主题会在客户端路由切换后同步 document.documentElement.lang。
// @noErrors
import { createLocaleHandle } from '@sveltepress/vite/hooks'
import { locales } from '../config/locales'
export const handle = createLocaleHandle(locales)按语言的 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 zhinit --locale zh 默认使用基路径 /zh/v；增量源码位于 version-deltas-zh/（或清单中的 artifacts.sources）。完整发版流程见 文档版本管理 。
按语言的搜索
本地搜索会按 <html lang="…"> 过滤。DocSearch 与自定义搜索应通过各语言主题选项配置独立索引。细节与版本相关行为见 搜索 。