Creation:2025-04-18Last update:2026-05-06
将此文档参考到您的 AI 助手ChatGPTClaudeDeepSeekGoogle AI modeGeminiPerplexityMistralGrok
使用您最喜欢的AI助手总结文档，并引用此页面和AI提供商
版本历史
- "更新 Solid useIntlayer API 用法以直接访问属性"v8.9.02026/5/4
- "添加 init 命令"v7.5.92025/12/30
- "初始化历史"v5.5.102025/6/29
此页面的内容已使用 AI 翻译。
查看英文原文的最新版本编辑此文档
如果您有改善此文档的想法，请随时通过在GitHub上提交拉取请求来贡献。
文档的 GitHub 链接Copy
复制文档 Markdown 到剪贴板
使用Intlayer翻译您的Vite and Solid | 国际化(i18n)
目录
该包正在开发中。更多信息请参见issue。通过点赞该 issue 来表达您对 Solid 版 Intlayer 的兴趣。
什么是 Intlayer？
Intlayer 是一个创新的开源国际化（i18n）库，旨在简化现代 Web 应用中的多语言支持。
使用 Intlayer，您可以：
- 通过组件级声明式字典轻松管理翻译。
- 动态本地化元数据、路由和内容。
- 通过自动生成类型确保 TypeScript 支持，提升自动补全和错误检测能力。
- 受益于高级功能，如动态语言环境检测和切换。
在 Vite 和 Solid 应用中设置 Intlayer 的分步指南
目录
第一步：安装依赖
使用 npm 安装所需的包：
bash
复制代码
复制代码到剪贴板
npm install intlayer solid-intlayernpm install vite-intlayer --save-devnpx intlayer initsolid-intlayer 将 Intlayer 集成到 Solid 应用中的包。它提供了 Solid 国际化的上下文提供者和钩子。
vite-intlayer 包含用于将 Intlayer 集成到Vite 打包器的 Vite 插件，以及用于检测用户首选语言、管理 Cookie 和处理 URL 重定向的中间件。
第 2 步：项目配置
创建一个配置文件来配置您的应用程序语言：
intlayer.config.ts
复制代码
复制代码到剪贴板
import { Locales, type IntlayerConfig } from "intlayer";
const config: IntlayerConfig = {
internationalization: {
locales: [
Locales.ENGLISH,
Locales.FRENCH,
Locales.SPANISH,
// 您的其他语言
],
defaultLocale: Locales.ENGLISH,
},
};
export default config;通过此配置文件，你可以设置本地化的 URL、中间件重定向、cookie 名称、内容声明的位置和扩展名，禁用控制台中的 Intlayer 日志等。有关可用参数的完整列表，请参阅配置文档。
第3步：在你的 Vite 配置中集成 Intlayer
将 intlayer 插件添加到你的配置中。
vite.config.ts
复制代码
复制代码到剪贴板
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import { intlayer } from "vite-intlayer";
// https://vitejs.dev/config/
export default defineConfig({
plugins: [react(), intlayer()],
});intlayer() 是用于将 Intlayer 集成到 Vite 中的插件。它确保内容声明文件的构建，并在开发模式下监视这些文件。它在 Vite 应用中定义了 Intlayer 的环境变量。此外，它还提供别名以优化性能。第4步：声明您的内容
创建并管理您的内容声明以存储翻译：
src/app.content.tsx
复制代码
复制代码到剪贴板
import { t, type Dictionary } from "intlayer";
const appContent = {
key: "app",
content: {},
} satisfies Dictionary;
export default appContent;您的内容声明可以在应用程序中的任何位置定义，只要它们被包含在contentDir目录中（默认是./src）。并且文件扩展名需匹配内容声明文件扩展名（默认是.content.{json,ts,tsx,js,jsx,mjs,cjs}）。
更多详情，请参考内容声明文档。
第5步：在代码中使用 Intlayer
在整个应用程序中访问您的内容字典：
src/App.tsx
复制代码
复制代码到剪贴板
import { createSignal, type Component } from "solid-js";import solidLogo from "./assets/solid.svg";import viteLogo from "/vite.svg";import "./App.css";import { IntlayerProvider, useIntlayer } from "solid-intlayer";const AppContent: Component = () => { const [count, setCount] = createSignal(0); const content = useIntlayer("app"); return ( <> <div> <a href="https://vitejs.dev" target="_blank"> <img src={viteLogo} class="logo" alt={content.viteLogo.value} /> </a> <a href="https://www.solidjs.com/" target="_blank"> <img src={solidLogo} class="logo solid" alt={content.solidLogo.value} /> </a> </div> <h1>{content.title}</h1> <div class="card"> <button onClick={() => setCount((count) => count + 1)}> {content.count({ count: count() })} </button> <p>{content.edit}</p> </div> <p class="read-the-docs">{content.readTheDocs}</p> </> );};const App: Component = () => ( <IntlayerProvider> <AppContent /> </IntlayerProvider>);export default App;在 Solid 中，useIntlayer 返回一个 accessor 函数（例如，`content.）。您必须调用此函数才能访问响应式内容。
如果您想在
string属性（如alt、title、href、aria-label等）中使用您的内容，可以使用函数的值，例如：html复制代码复制代码到剪贴板
<img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />
（可选）第6步：更改内容语言
要更改内容语言，您可以使用 useLocale 钩子提供的 setLocale 函数。此函数允许您设置应用程序的语言环境并相应地更新内容。
src/components/LocaleSwitcher.tsx
复制代码
复制代码到剪贴板
import { type Component, For } from "solid-js";import { Locales } from "intlayer";import { useLocale } from "solid-intlayer";const LocaleSwitcher: Component = () => { const { locale, setLocale, availableLocales } = useLocale(); return ( <select value={locale()} onChange={(e) => setLocale(e.currentTarget.value as Locales)} > <For each={availableLocales}> {(loc) => ( <option value={loc} selected={loc === locale()}> {loc} </option> )} </For> </select> );};（可选）第7步：为应用添加本地化路由
此步骤的目的是为每种语言创建唯一的路由。这对 SEO 和 SEO 友好的 URL 很有用。 示例：
plaintext
复制代码
复制代码到剪贴板
- https://example.com/about- https://example.com/es/about- https://example.com/fr/about要为您的应用程序添加本地化路由，您可以使用 @solidjs/router。
首先，安装必要的依赖项：
bash
复制代码
复制代码到剪贴板
npm install @solidjs/router然后，用 Router 包装您的应用程序，并使用 localeMap 定义您的路由：
src/index.tsx
复制代码
复制代码到剪贴板
import { render } from "solid-js/web";import { Router } from "@solidjs/router";import App from "./App";const root = document.getElementById("root");render( () => ( <Router> <App /> </Router> ), root!);src/App.tsx
复制代码
复制代码到剪贴板
import { type Component } from "solid-js";import { Route } from "@solidjs/router";import { localeMap } from "intlayer";import { IntlayerProvider } from "solid-intlayer";import Home from "./pages/Home";import About from "./pages/About";const App: Component = () => ( <IntlayerProvider> {localeMap(({ locale, urlPrefix }) => ( <Route path={urlPrefix || "/"} component={(props: any) => ( <IntlayerProvider locale={locale}>{props.children}</IntlayerProvider> )} > <Route path="/" component={Home} /> <Route path="/about" component={About} /> </Route> ))} </IntlayerProvider>);export default App;（可选）第8步：当语言环境变化时更改 URL
要在语言环境更改时更改 URL，您可以使用 useLocale 钩子提供的 onLocaleChange 属性。您可以使用 @solidjs/router 的 useNavigate 和 useLocation 钩子来更新 URL 路径。
src/components/LocaleSwitcher.tsx
复制代码
复制代码到剪贴板
import { type Component, For } from "solid-js";import { useLocation, useNavigate } from "@solidjs/router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "solid-intlayer";const LocaleSwitcher: Component = () => { const location = useLocation(); const navigate = useNavigate(); const { locale, setLocale, availableLocales } = useLocale({ onLocaleChange: (loc) => { const pathWithLocale = getLocalizedUrl(location.pathname, loc); navigate(pathWithLocale); }, }); return ( <select value={locale()} onChange={(e) => setLocale(e.currentTarget.value as any)} > <For each={availableLocales}> {(loc) => ( <option value={loc} selected={loc === locale()}> {loc} </option> )} </For> </select> );};（可选）第9步：切换 HTML 的语言和方向属性
更新 <html> 标签的 lang 和 dir 属性以匹配当前语言环境，以便于可访问性和 SEO。
src/App.tsx
复制代码
复制代码到剪贴板
import { createEffect, type Component } from "solid-js";import { useLocale } from "solid-intlayer";import { getHTMLTextDir } from "intlayer";const AppContent: Component = () => { const { locale } = useLocale(); createEffect(() => { document.documentElement.lang = locale(); document.documentElement.dir = getHTMLTextDir(locale()); }); return ( // ... 您的应用程序内容 );};（可选）步骤 10：创建本地化链接组件
创建一个自定义 Link 组件，自动为内部 URL 添加当前语言的前缀。
src/components/Link.tsx
复制代码
复制代码到剪贴板
import { type ParentComponent } from "solid-js";import { A, type AnchorProps } from "@solidjs/router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "solid-intlayer";export const Link: ParentComponent<AnchorProps> = (props) => { const { locale } = useLocale(); const isExternal = () => props.href.startsWith("http"); const localizedHref = () => isExternal() ? props.href : getLocalizedUrl(props.href, locale()); return <A {...props} href={localizedHref()} />;};（可选）步骤 11：渲染 Markdown
Intlayer 支持使用其自己的内部解析器直接在您的 Solid 应用程序中渲染 Markdown 内容。默认情况下，Markdown 被视为纯文本。要将其渲染为富 HTML，请用 MarkdownProvider 包装您的应用程序。
src/index.tsx
复制代码
复制代码到剪贴板
import { render } from "solid-js/web";import { MarkdownProvider } from "solid-intlayer/markdown";import App from "./App";const root = document.getElementById("root");render( () => ( <MarkdownProvider> <App /> </MarkdownProvider> ), root!);然后您可以在组件中使用它：
tsx
复制代码
复制代码到剪贴板
import { useIntlayer } from "solid-intlayer";const MyComponent = () => { const content = useIntlayer("my-content"); return ( <div> {/* 通过 MarkdownProvider 渲染为 HTML */} {content.markdownContent} </div> );};配置 TypeScript
确保您的 TypeScript 配置包含自动生成的类型。
tsconfig.json
复制代码
复制代码到剪贴板
{ "compilerOptions": { // ... }, "include": ["src", ".intlayer/**/*.ts"],}Git 配置
建议忽略 Intlayer 生成的文件。这样可以避免将它们提交到您的 Git 仓库中。
为此，您可以将以下指令添加到您的 .gitignore 文件中：
bash
复制代码
复制代码到剪贴板
# 忽略 Intlayer 生成的文件.intlayerVS Code 扩展
为了提升您使用 Intlayer 的开发体验，您可以安装官方的 Intlayer VS Code 扩展。
该扩展提供：
- 翻译键的自动补全。
- 缺失翻译的实时错误检测。
- 已翻译内容的内联预览。
- 快速操作，轻松创建和更新翻译。
有关如何使用该扩展的更多详细信息，请参阅Intlayer VS Code 扩展文档。
(可选) 步骤 1 : 提取组件内容
如果您有现有的代码库，转换数千个文件可能会非常耗时。
为了简化此过程，Intlayer 提出了 编译器 / 提取器 来转换您的组件并提取内容。
要进行设置，您可以在 intlayer.config.ts 文件中添加 compiler 部分：
intlayer.config.ts
复制代码
复制代码到剪贴板
import { type IntlayerConfig } from "intlayer";
const config: IntlayerConfig = {
// ... 您的其他配置
compiler: {
/**
* 指示是否应启用编译器。
*/
enabled: true,
/**
* 定义输出文件路径
*/
output: ({ fileName, extension }) => `./${fileName}${extension}`,
/**
* 指示在转换后是否应保存组件。这样，编译器只需运行一次即可转换应用程序，然后即可将其删除。
*/
saveComponents: false,
/**
* 字典键前缀
*/
dictionaryKeyPrefix: "",
},
};
export default config;运行提取器以转换组件并提取内容
bash
复制代码
复制代码到剪贴板
npx intlayer extract（可选）站点地图与 robots.txt（构建时生成）
Intlayer 提供 generateSitemap 与 getMultilingualUrls，可将面向爬虫的多语言 sitemap.xml 和 robots.txt 格式化并自动写入 public/。实践中在 Vite 之前运行小型 Node 脚本（例如 npm 的 predev / prebuild）即可在构建或开发时生成这些文件。
站点地图
Intlayer 的站点地图生成会尊重你的语言配置，并包含爬虫所需的元数据。
生成的站点地图支持xhtml:link（hreflang）。与只列出扁平 URL 不同，Intlayer 会在各语言版本之间建立双向关联（例如/about、/fr/about或/about?lang=fr，取决于路由模式）。
Robots.txt
使用 getMultilingualUrls，使 Disallow 覆盖敏感路径的每一种本地化写法。
1. 在项目根目录添加 generate-seo.mjs
generate-seo.mjs
复制代码
复制代码到剪贴板
import fs from "fs";import path from "path";import { fileURLToPath } from "url";import { generateSitemap, getMultilingualUrls } from "intlayer";const __dirname = path.dirname(fileURLToPath(import.meta.url));const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace( /\/$/, "");const pathList = [ { path: "/", changefreq: "daily", priority: 1.0 }, { path: "/about", changefreq: "monthly", priority: 0.7 },];const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);const getAllMultilingualUrls = (urls) => urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);const robotsTxt = [ "User-agent: *", "Allow: /", ...disallowedPaths.map((path) => `Disallow: ${path}`), "", `Sitemap: ${SITE_URL}/sitemap.xml`,].join("\n");fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);console.log("SEO files generated successfully.");需已安装 intlayer 以便脚本导入。生产环境请设置环境变量 SITE_URL（例如在 CI 中）。
建议在 Node 中使用generate-seo.mjs（ESM）。若使用generate-seo.js，请在package.json中设置"type": "module"或以其他方式启用 ESM。
2. 在运行 Vite 之前执行脚本
package.json
复制代码
复制代码到剪贴板
{ "scripts": { "dev": "vite", "prebuild": "node generate-seo.mjs", "build": "vite build", "preview": "vite preview" }}若使用 pnpm 或 yarn，请相应调整命令；也可在 CI 或其他步骤中调用该脚本。
深入了解
要进一步使用，您可以实现可视化编辑器或使用内容管理系统（CMS）将内容外部化。