使用您最喜欢的AI助手总结文档，并引用此页面和AI提供商
版本历史
- "更新 Solid useIntlayer API 用法以直接访问属性"v8.9.02026/5/4
- "针对 Tanstack Start Solid.js 添加"v8.5.12026/3/25
此页面的内容已使用 AI 翻译。
查看英文原文的最新版本If you have an idea for improving this documentation, please feel free to contribute by submitting a pull request on GitHub.
GitHub link to the documentationCopy doc Markdown to clipboard
使用 Intlayer 翻译您的 Tanstack Start + Solid.js 网站 | 国际化 (i18n)
目录
本指南演示了如何集成 Intlayer，以便在包含 Solid.js 的 Tanstack Start 项目中实现无缝国际化、本地化感知路由、TypeScript 支持以及现代开发实践。
为什么选择 Inlayer 而不是替代品？
与“react-i18next”或“i18next”等主要解决方案相比，Intlayer是一个具有集成优化的解决方案，例如：
完整的 TanStack Start 覆盖
Intlayer 经过优化，可与 TanStack Start 和 Solid 完美配合，提供多语言路由、站点地图以及扩展国际化 (i18n) 所需的所有功能。
捆绑尺寸
不要将大量 JSON 文件加载到页面中，而只需加载必要的内容。 Intlayer 有助于将捆绑包和页面大小减少多达 50%。
可维护性
确定应用程序内容的范围有利于大型应用程序的维护。您可以复制或删除单个功能文件夹，而无需承担检查整个内容代码库的精神负担。此外，Intlayer 具有完全类型化 (fully typed)，以确保您的内容的准确性。
人工智能代理
共置内容减少大型语言模型 (LLM) 所需的上下文。 Intlayer 还附带了一套工具，例如用于测试缺失翻译的 CLI、LSP、MCP 和 agent技能，使 AI 代理的开发者体验 (DX) 更加流畅。
自动化
使用您选择的法学硕士，通过自动化在 CI/CD 管道中进行翻译，而费用由您的 AI 提供商承担。 Intlayer 还提供了一个编译器来自动提取内容，以及一个网络平台来帮助在后台翻译。
表现
将大量 JSON 文件连接到组件可能会导致性能和反应性问题。 Intlayer 可在构建时 (build time)优化您的内容加载。
无需开发即可扩展
Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个自托管的可视化编辑器和一个完整的 CMS 来帮助您管理多语言内容实时，与译员、文案人员和其他团队成员无缝协作。内容可以本地和/或远程存储。
第 8 步：利用语言感知的组件和钩子
为语言敏感的导航创建一个 LocalizedLink 组件：
复制代码到剪贴板
import { Link, type LinkProps } from "@tanstack/solid-router";import { getPrefix } from "intlayer";import { useLocale } from "solid-intlayer";import type { JSX } from "solid-js";export const LOCALE_ROUTE = "{-$locale}" as const;export type RemoveLocaleParam<TVal> = TVal extends string ? RemoveLocaleFromString<TVal> : TVal;export type To = RemoveLocaleParam<LinkProps["to"]>;type CollapseDoubleSlashes<TString extends string> = TString extends `${infer THead}//${infer TTail}` ? CollapseDoubleSlashes<`${THead}/${TTail}`> : TString;export type LocalizedLinkProps = Omit<LinkProps, "to"> & { to?: To;} & JSX.AnchorHTMLAttributes<HTMLAnchorElement>;type RemoveAll< TString extends string, TSub extends string,> = TString extends `${infer THead}${TSub}${infer TTail}` ? RemoveAll<`${THead}${TTail}`, TSub> : TString;type RemoveLocaleFromString<TString extends string> = CollapseDoubleSlashes< RemoveAll<TString, typeof LOCALE_ROUTE>>;export const LocalizedLink = (props: LocalizedLinkProps) => { const { locale } = useLocale(); return ( <Link {...props} params={{ locale: getPrefix(locale()).localePrefix, ...(typeof props.params === "object" ? props.params : {}), }} to={`/${LOCALE_ROUTE}${props.to ?? ""}` as LinkProps["to"]} /> );};此组件有两个目的：
- 从 URL 中删除不必要的
{-$locale}前缀。 - 在 URL 中注入语言参数，以确保用户直接重定向到本地化路由。
接着，我们可以为编程式导航创建一个 useLocalizedNavigate 钩子：
复制代码到剪贴板
import { useNavigate } from "@tanstack/solid-router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "solid-intlayer";export const useLocalizedNavigate = () => { const navigate = useNavigate(); const { locale } = useLocale(); const localizedNavigate = (to: string) => { const localizedTo = getLocalizedUrl(to, locale()); return navigate({ to: localizedTo }); }; return localizedNavigate;};第 10 步：创建一个语言切换组件
创建一个允许用户更改语言的组件：
复制代码到剪贴板
import { useLocation } from "@tanstack/solid-router";import { getLocaleName, getPathWithoutLocale, getPrefix } from "intlayer";import { For } from "solid-js";import { useIntlayer, useLocale } from "solid-intlayer";import { LocalizedLink, type To } from "./LocalizedLink";export const LocaleSwitcher = () => { const content = useIntlayer("locale-switcher"); const location = useLocation(); const { availableLocales, locale, setLocale } = useLocale(); const pathWithoutLocale = () => getPathWithoutLocale(location().pathname); return ( <div class="flex flex-row gap-2"> <For each={availableLocales}> {(localeEl) => ( <LocalizedLink aria-current={localeEl === locale() ? "page" : undefined} onClick={() => setLocale(localeEl)} params={{ locale: getPrefix(localeEl).localePrefix }} to={pathWithoutLocale() as To} > {getLocaleName(localeEl)} </LocalizedLink> )} </For> </div> );};export default LocaleSwitcher;在 Solid 中，来自
useLocale的locale是一个 signal accessor。请使用locale()(带括号) 来响应式地读取其当前值。欲了解更多关于
useLocale钩子的信息，请参考文档。
第 16 步：生成站点地图 (可选)
Intlayer 带有内置的站点地图生成器，可帮助您轻松为应用程序创建站点地图。它处理本地化路由并为搜索引擎添加必要的元数据。
Intlayer 生成的站点地图支持xhtml:link命名空间（Hreflang XML 扩展）。与仅列出原始 URL 的默认站点地图生成器不同，Intlayer 会自动在页面的所有语言版本（例如/about、/about?lang=fr和/about?lang=es）之间创建所需的双向链接。这确保了搜索引擎能够正确索引并向合适的受众提供正确的语言版本。
要使用它，您首先需要配置 vite.config.ts 以启用本地化路由的预渲染，并禁用 TanStack Start 的默认站点地图生成。
复制代码到剪贴板
import { localeMap, localeFlatMap } from "intlayer";// ... 其他导入export const pathList = ["", "/about", "/404"];const localizedPages = localeFlatMap(({ urlPrefix }) => pathList.map((path) => ({ path: `${urlPrefix}${path}`, prerender: { enabled: true, }, })));export default defineConfig({ plugins: [ // ... 其他插件 tanstackStart({ // ... 其他配置 sitemap: { enabled: false, }, prerender: { enabled: true, crawlLinks: false, concurrency: 10, }, pages: localizedPages, }), ],});然后，创建一个使用 generateSitemap 函数的 src/routes/sitemap[.]xml.ts 路由：
复制代码到剪贴板
import { createFileRoute } from "@tanstack/solid-router";import { generateSitemap } from "intlayer";const SITE_URL = "http://localhost:3000";export const Route = createFileRoute("/sitemap.xml")({ server: { handlers: { GET: async () => { const sitemap = generateSitemap( [ { path: "/", changefreq: "daily", priority: 1.0 }, { path: "/about", changefreq: "monthly", priority: 0.8 }, ], { siteUrl: SITE_URL } ); return new Response(sitemap, { headers: { "Content-Type": "application/xml" }, }); }, }, },});Git 配置
建议忽略 Intlayer 生成的文件。这可以避免将它们提交到您的 Git 仓库。
为此，您可以在 .gitignore 文件中添加以下指令：
复制代码到剪贴板
# 忽略由 Intlayer 生成的文件.intlayerVS Code 扩展
为了提升 Intlayer 的开发体验，您可以安装官方的 Intlayer VS Code 扩展。
此扩展提供：
- 翻译键的自动补全。
- 缺失翻译的实时错误检测。
- 翻译内容的内联预览。
- 用于轻松创建和更新翻译的快速操作。
有关如何使用该扩展的更多详细信息，请参阅 Intlayer VS Code 扩展文档。
深入探索
如需深入了解，您可以实现可视化编辑器或使用 CMS 外置您的内容。