Creation:2024-03-07Last update:2026-05-31

    使用 Intlayer 翻译您的 Astro 网站 | 国际化 (i18n)

    ide.intlayer.org

    目录

    为什么选择 Inlayer 而不是替代品？

    与“astro-i18n”或“i18next”等主要解决方案相比，Intlayer是一个具有集成优化的解决方案，例如：

    完整的 Astro 报道

    Intlayer 经过优化，可与 Astro 完美配合，提供多语言路由、站点地图以及扩展国际化 (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 来帮助您管理多语言内容实时，与译员、文案人员和其他团队成员无缝协作。内容可以本地和/或远程存储。

    在 Astro 中配置 Intlayer 的分步指南

    在 GitHub 上查看应用程序模板。

    第一步：安装依赖

    使用您喜欢的包管理器安装所需的软件包：

    bash
    npm install intlayer astro-intlayer# 可选：如果添加 React 岛支持npm install react react-dom react-intlayer @astrojs/react

    • intlayer 核心软件包，提供用于配置管理、翻译、内容声明、编译和 CLI 命令的国际化工具。

    • astro-intlayer 包含将 Intlayer 与 Vite 构建器集成的 Astro 集成插件，以及用于检测用户首选语言、管理 Cookie 和处理 URL 重定向的中间件。

    第二步：配置您的项目

    创建一个配置文件来定义您的应用程序语言：

    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 日志等。有关可用参数的完整列表，请参阅配置文档。

    第三步：在 Astro 配置中集成 Intlayer

    将 intlayer 插件添加到您的 Astro 配置中。

    astro.config.ts
    // @ts-checkimport { intlayer } from "astro-intlayer";import { defineConfig } from "astro/config";// https://astro.build/configexport default defineConfig({  integrations: [intlayer()],});
    intlayer() 集成插件用于将 Intlayer 与 Astro 集成。它确保内容声明文件的构建并在开发模式下进行监视。它在 Astro 应用程序中定义 Intlayer 环境变量，并提供别名以优化性能。

    第四步：声明您的内容

    创建并管理您的内容声明以存储翻译：

    src/app.content.tsx
    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",      zh: "你好，世界",    }),  },} satisfies Dictionary;export default appContent;
    只要您的内容声明包含在 contentDir（默认为 ./src）中，且匹配内容声明文件扩展名（默认为 .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}），就可以在应用程序的任何位置定义。
    有关更多信息，请参阅内容声明文档。

    第五步：在 Astro 中使用内容

    您可以使用 intlayer 导出的核心辅助函数直接在 .astro 文件中消费词典。

    src/pages/index.astro
    ---import {  getIntlayer,  getLocaleFromPath,  getLocalizedUrl,  defaultLocale,  localeMap,  getHTMLTextDir,  type LocalesValues,} from "intlayer";import LocaleSwitcher from "../components/LocaleSwitcher.astro";// Get the current locale from the URL (e.g. /es/about -> 'es')const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;// Get the content for the 'app' dictionaryconst { title } = getIntlayer("app", locale);---<!doctype html><html lang={locale} dir={getHTMLTextDir(locale)}>  <head>    <meta charset="utf-8" />    <meta name="viewport" content="width=device-width" />    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />    <title>{title}</title>    <!-- Canonical link: Tells search engines which is the primary version of this page -->    <link      rel="canonical"      href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}    />    <!-- Hreflang: Tell Google about all localized versions -->    {      localeMap(({ locale: mapLocale }) => (        <link          rel="alternate"          hreflang={mapLocale}          href={new URL(            getLocalizedUrl(Astro.url.pathname, mapLocale),            Astro.site          )}        />      ))    }    <!-- x-default: Fallback for users in unmatched languages -->    <link      rel="alternate"      hreflang="x-default"      href={new URL(        getLocalizedUrl(Astro.url.pathname, defaultLocale),        Astro.site      )}    />  </head>  <body>    <header>      <LocaleSwitcher />    </header>    <main>      <h1>{title}</h1>    </main>  </body></html>

    第六步：本地化路由

    创建动态路由段以提供本地化页面（例如 src/pages/[locale]/index.astro）：

    src/pages/[locale]/index.astro
    <!-- astro -->---import { getIntlayer } from "intlayer";const { title } = getIntlayer('app');---<h1>{title}</h1>

    Astro 集成添加了一个 Vite 中间件，有助于在开发期间进行语言感知路由和环境定义。您还可以使用自己的逻辑或 intlayer 的 getLocalizedUrl 等工具创建语言之间的链接。

    第七步：继续使用您喜欢的框架

    继续使用您喜欢的框架构建您的应用程序。

    TypeScript 配置

    Intlayer 使用模块扩展来利用 TypeScript，使您的代码库更加健壮。

    自动补全

    翻译错误

    确保您的 TypeScript 配置包含自动生成的类型。

    tsconfig.json
    {  // ... 您现有的 TypeScript 配置  "include": [    // ... 您现有的 TypeScript 配置    ".intlayer/**/*.ts", // 包含自动生成的类型  ],}

    Git 配置

    建议忽略 Intlayer 生成的文件。这可以避免将它们提交到您的 Git 仓库。

    为此，您可以将以下说明添加到 .gitignore 文件中：

    bash
    # 忽略 Intlayer 生成的文件.intlayer

    VS Code 扩展

    为了改善使用 Intlayer 的开发体验，您可以安装官方 Intlayer VS Code 扩展。

    从 VS Code Marketplace 安装

    此扩展提供：

    • 翻译键的自动补全。
    • 缺失翻译的实时错误检测。
    • 翻译内容的内联预览。
    • 轻松创建和更新翻译的快速操作。

    有关使用该扩展的更多信息，请参阅 Intlayer VS Code 扩展文档。

    第十五步：提取组件中的内容（可选）

    如果您有现有的代码库，转换数千个文件可能会非常耗时。

    为了简化此过程，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

    深入了解

    如果您想了解更多，还可以实现可视化编辑器或使用 CMS 将您的内容外部化。

    Tanstack Start Solid
    Astro和React