使用您最喜欢的AI助手总结文档,并引用此页面和AI提供商
通过将 Intlayer MCP 服务器集成到您的 AI 助手,您可以直接从 ChatGPT、DeepSeek、Cursor、VSCode 等获取所有文档。
查看 MCP 服务器文档此页面的内容已使用 AI 翻译。
查看英文原文的最新版本如果您有改善此文档的想法,请随时通过在GitHub上提交拉取请求来贡献。
文档的 GitHub 链接复制文档 Markdown 到剪贴板
使用 Intlayer 和 Astro 开始国际化(i18n)
请参阅 GitHub 上的应用模板。
什么是 Intlayer?
Intlayer 是一个创新的开源国际化(i18n)库,旨在简化现代 Web 应用中的多语言支持。
使用 Intlayer,您可以:
- 通过组件级声明式字典轻松管理翻译。
- 动态本地化元数据、路由和内容。
- 确保 TypeScript 支持,通过自动生成类型,提升自动补全和错误检测能力。
- 享受高级功能,如动态语言环境检测和切换。
在 Astro 中设置 Intlayer 的分步指南
第一步:安装依赖
使用您的包管理器安装必要的包:
npm install intlayer astro-intlayer# 可选:添加 React 岛屿支持npm install react react-dom react-intlayer @astrojs/react
astro-intlayer
包括用于将 Intlayer 与 Vite 打包工具 集成的 Astro 集成插件,以及用于检测用户首选语言环境、管理 Cookie 和处理 URL 重定向的中间件。
第 2 步:配置您的项目
创建一个配置文件来配置您的应用程序语言:
复制代码到剪贴板
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 日志等。有关可用参数的完整列表,请参阅配置文档。
第三步:在您的 Astro 配置中集成 Intlayer
将 intlayer 插件添加到您的配置中。
复制代码到剪贴板
// @ts-checkimport { intlayer } from "astro-intlayer";import { defineConfig } from "astro/config";// https://astro.build/configexport default defineConfig({ integrations: [intlayer()],});
intlayer() Astro 集成插件用于将 Intlayer 与 Astro 集成。它确保内容声明文件的构建,并在开发模式下监控这些文件。在 Astro 应用中定义了 Intlayer 环境变量。此外,它还提供别名以优化性能。
第4步:声明您的内容
创建并管理您的内容声明以存储翻译:
复制代码到剪贴板
import { t, type Dictionary } from "intlayer";import type { ReactNode } from "react";const appContent = { key: "app", content: { title: t({ en: "Hello World", fr: "Bonjour le monde", es: "Hola mundo", }), },} satisfies Dictionary;export default appContent;
您的内容声明可以定义在应用程序中的任何位置,只要它们被包含在 contentDir 目录中(默认是 ./src)。并且文件扩展名需匹配内容声明文件扩展名(默认是 .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx})。
更多详情,请参阅内容声明文档。
第5步:在 Astro 中使用您的内容
您可以直接在 .astro 文件中使用 intlayer 导出的核心辅助函数来消费字典。
复制代码到剪贴板
<!-- astro -->---import { getIntlayer } from "intlayer";import appContent from "../app.content";const { title } = getIntlayer('app');---<html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width" /> <title>{title}</title> </head> <body> <h1>{title}</h1> </body></html>
第6步:本地化路由
创建一个动态路由段来服务本地化页面,例如 src/pages/[locale]/index.astro:
复制代码到剪贴板
<!-- astro -->---import { getIntlayer } from "intlayer";const { title } = getIntlayer('app');---<h1>{title}</h1>
Astro 集成在开发期间添加了一个 Vite 中间件,帮助处理基于语言环境的路由和环境定义。你仍然可以使用自己的逻辑或 intlayer 提供的工具函数如 getLocalizedUrl 来实现语言环境间的链接。
第7步:继续使用你喜欢的框架
继续使用您喜欢的框架来构建您的应用程序。
- Intlayer + React: Intlayer 与 React
- Intlayer + Vue: Intlayer 与 Vue
- Intlayer + Svelte: Intlayer 与 Svelte
- Intlayer + Solid: Intlayer 与 Solid
- Intlayer + Preact: Intlayer 与 Preact
配置 TypeScript
Intlayer 使用模块增强来利用 TypeScript 的优势,使您的代码库更强大。
确保您的 TypeScript 配置包含自动生成的类型。
复制代码到剪贴板
{ // ... 您现有的 TypeScript 配置 "include": [ // ... 您现有的 TypeScript 配置 ".intlayer/**/*.ts", // 包含自动生成的类型 ],}
Git 配置
建议忽略 Intlayer 生成的文件。这样可以避免将它们提交到您的 Git 仓库中。
要做到这一点,您可以将以下指令添加到您的 .gitignore 文件中:
# 忽略 Intlayer 生成的文件.intlayer
VS Code 扩展
为了提升您使用 Intlayer 的开发体验,您可以安装官方的 Intlayer VS Code 扩展。
该扩展提供:
- 翻译键的 自动补全。
- 缺失翻译的 实时错误检测。
- 翻译内容的 内联预览。
- 轻松创建和更新翻译的 快速操作。
有关如何使用该扩展的更多详细信息,请参阅 Intlayer VS Code 扩展文档。
深入探索
要进一步使用,您可以实现可视化编辑器或使用内容管理系统(CMS)将内容外部化。
文档历史
版本 | 日期 | 变更内容 |
---|---|---|
6.2.0 | 2025-10-03 | 针对 Astro 集成、配置和使用进行了更新 |