作者:
    Aymeric PINEAU
    Creation:2025-06-18Last update:2026-05-31

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

    目录

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

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

    完整 Nuxt 覆盖

    Intlayer 经过优化，可与 Nuxt 完美配合，提供多语言路由、用于区域设置检测的中间件、站点地图以及扩展国际化 (i18n) 所需的所有功能。

    捆绑尺寸

    不要将大量 JSON 文件加载到页面中，而只需加载必要的内容。 Intlayer 有助于将捆绑包和页面大小减少多达 50%。

    </Accordion>

    可维护性

    确定应用程序内容的范围有利于大型应用程序的维护。您可以复制或删除单个功能文件夹，而无需承担检查整个内容代码库的精神负担。此外，Intlayer 具有完全类型化 (fully typed)，以确保您的内容的准确性。

    人工智能代理

    共置内容减少大型语言模型 (LLM) 所需的上下文。 Intlayer 还附带了一套工具，例如用于测试缺失翻译的 CLI、LSP、MCP 和 agent skills，使 AI 代理的开发者体验 (DX) 更加流畅。

    自动化

    使用您选择的法学硕士，通过自动化在 CI/CD 管道中进行翻译，而费用由您的 AI 提供商承担。 Intlayer 还提供了一个编译器来自动提取内容，以及一个网络平台来帮助在后台翻译。

    表现

    将大量 JSON 文件连接到组件可能会导致性能和反应性问题。 Intlayer 可在构建时 (build time)优化您的内容加载。

    无需开发即可扩展

    Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个自托管的可视化编辑器和一个完整的 CMS 来帮助您管理多语言内容实时，与译员、文案人员和其他团队成员无缝协作。内容可以本地和/或远程存储。

    </AccordionGroup>

    在 Nuxt 应用中设置 Intlayer 的分步指南

    www.youtube.com
    ide.intlayer.org
    intlayer-nuxt-4-template.vercel.app

    查看 GitHub 上的应用模板。

    1. 安装依赖

      使用 npm 安装必要的包：

      bash
      npx intlayer init --interactive
      --interactive 标志是可选的。如果您是 AI 代理，请使用 intlayer-cli init。
      此命令将检测您的环境并安装所需的包。例如：
      bash
      npm install intlayer vue-intlayer
npm install --save-dev nuxt-intlayer

      • intlayer

        核心包，为配置管理、翻译、内容声明、转译和 CLI 命令提供国际化工具。

      • vue-intlayer 将 Intlayer 与 Vue 应用集成的包。为 Vue 组件提供 composables。

      • nuxt-intlayer 将 Intlayer 与 Nuxt 应用集成的 Nuxt 模块。它提供自动设置、locale 检测中间件、cookie 管理和 URL 重定向。

    2. 配置您的项目

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

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // 您的其他 locales
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;
      通过此配置文件，您可以设置本地化 URL、中间件重定向、cookie 名称、内容声明的位置和扩展名、禁用控制台中的 Intlayer 日志等。有关可用参数的完整列表，请参阅配置文档。

    3. 在您的 Nuxt 配置中集成 Intlayer

      将 intlayer 模块添加到您的 Nuxt 配置中：

      nuxt.config.ts
      import { defineNuxtConfig } from "nuxt/config";

export default defineNuxtConfig({
  // ... 您现有的 Nuxt 配置
  modules: ["nuxt-intlayer"],
});
      nuxt-intlayer 模块自动处理 Intlayer 与 Nuxt 的集成。它设置内容声明构建、在开发模式下监视文件、提供 locale 检测中间件，并管理本地化路由。

    4. 声明您的内容

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

      您的内容声明可以定义在应用程序中的任何位置，只要它们包含在 contentDir 目录中（默认情况下为 ./src）。并匹配内容声明文件扩展名（默认情况下为 .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}）。
      有关更多详细信息，请参阅内容声明文档。

    5. 在您的代码中使用 Intlayer

      使用 useIntlayer composable 在整个 Nuxt 应用中访问您的内容字典：

      components/HelloWorld.vue
      <script setup lang="ts">
import { ref } from "vue";
import { useIntlayer } from "vue-intlayer";

defineProps({
  msg: String,
});

const {
  count,
  edit,
  checkOut,
  nuxtIntlayer,
  learnMore,
  nuxtDocs,
  readTheDocs,
} = useIntlayer("helloworld");
const countRef = ref(0);
</script>

<template>
  <h1>{{ msg }}</h1>

  <div class="card">
    <button type="button" @click="countRef++">
      <count />
      {{ countRef }}
    </button>
    <p v-html="edit"></p>
  </div>

  <p>
    <checkOut />
    <a href="https://nuxt.com/docs/getting-started/introduction" target="_blank"
      >Nuxt</a
    >, <nuxtIntlayer />
  </p>
  <p>
    <learnMore />
    <a href="https://nuxt.com" target="_blank"><nuxtDocs /></a>.
  </p>
  <p class="read-the-docs"><readTheDocs /></p>
  <p class="read-the-docs">{{ readTheDocs }}</p>
</template>

      访问 Intlayer 中的内容

      Intlayer 提供了多种 API 来访问您的内容：

      • 基于组件的语法（推荐）： 使用 <myContent /> 或 <Component :is="myContent" /> 语法将内容渲染为 Intlayer 节点。这与可视化编辑器和CMS无缝集成。

      • 基于字符串的语法： 使用 {{ myContent }} 将内容渲染为纯文本，不支持可视化编辑器。

      • 原始 HTML 语法： 使用 <div v-html="myContent" /> 将内容渲染为原始 HTML，不支持可视化编辑器。

      • 解构语法： useIntlayer 组合函数返回一个包含内容的 Proxy。该 Proxy 可以被解构以访问内容，同时保持响应性。

        • 使用 const content = useIntlayer("myContent"); 以及 {{ content.myContent }} / <content.myContent />。
        • 或者使用 const { myContent } = useIntlayer("myContent"); 以及 {{ myContent}} / <myContent/> 来解构内容。

    6. 更改内容语言

      要更改内容的语言，可以使用 useLocale 组合函数提供的 setLocale 函数。该函数允许您设置应用程序的语言环境并相应地更新内容。

      创建一个组件，使用 NuxtLink 在语言之间切换。使用链接而非按钮进行语言切换是 SEO 和页面可发现性的最佳实践，因为这允许搜索引擎抓取并索引页面的所有本地化版本：

      components/LocaleSwitcher.vue
      <script setup lang="ts">
import { getLocaleName, getLocalizedUrl } from "intlayer";
import { useLocale } from "vue-intlayer";

// Nuxt 自动导入 useRoute
const route = useRoute();
const { locale, availableLocales, setLocale } = useLocale();
</script>

<template>
  <nav class="locale-switcher">
    <NuxtLink
      v-for="localeEl in availableLocales"
      :key="localeEl"
      :to="getLocalizedUrl(route.fullPath, localeEl)"
      class="locale-link"
      :class="{ 'active-locale': localeEl === locale }"
      @click="setLocale(localeEl)"
    >
      {{ getLocaleName(localeEl) }}
    </NuxtLink>
  </nav>
</template>
      使用带有正确 href 属性（通过 getLocalizedUrl）的 NuxtLink 确保搜索引擎能够发现您页面的所有语言版本。这比仅使用 JavaScript 的语言切换更优，因为搜索引擎爬虫可能无法跟踪后者。

      然后，设置您的 app.vue 以使用布局：

      app.vue
      <template>
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>

    7. 为您的应用添加本地化路由

      当使用 nuxt-intlayer 模块时，Nuxt 会自动处理本地化路由。它会根据您的页面目录结构自动为每种语言创建路由。

      示例：

      plaintext
      pages/
├── index.vue          → /, /fr, /es
├── about.vue          → /about, /fr/about, /es/about
└── contact/
    └── index.vue      → /contact, /fr/contact, /es/contact

      要创建本地化页面，只需在 pages/ 目录中创建您的 Vue 文件。以下是两个示例页面：

      主页 (pages/index.vue):

      pages/index.vue
      <script setup lang="ts">
import { useIntlayer } from "vue-intlayer";

const content = useIntlayer("home-page");

useHead({
  title: content.metaTitle.raw,
  meta: [
    {
      name: "description",
      content: content.metaDescription.raw,
    },
  ],
});
</script>

<template>
  <h1><content.title /></h1>
</template>

      关于页面 (pages/about.vue):

      pages/about.vue
      <script setup lang="ts">
import { useIntlayer } from "vue-intlayer";

const content = useIntlayer("about-page");

useHead({
  title: content.metaTitle.raw, // 使用 .raw 访问原始字符串
  meta: [
    {
      name: "description",
      content: content.metaDescription.raw, // 使用 .raw 访问原始字符串
    },
  ],
});
</script>

<template>
  <h1><content.title /></h1>
</template>
      注意：useHead 在 Nuxt 中是自动导入的。你可以根据需要使用 .value（响应式）或 .raw（原始字符串）来访问内容值。

      nuxt-intlayer 模块将自动：

      • 检测用户的首选语言环境
      • 通过 URL 处理语言切换
      • 设置适当的 <html lang=""> 属性
      • 管理语言环境 Cookie
      • 将用户重定向到相应的本地化 URL

    8. 创建本地化链接组件

      为了确保您的应用程序导航遵循当前的语言环境，您可以创建一个自定义的 Links 组件。该组件会自动为内部 URL 添加当前语言前缀，这对于 SEO 和页面可发现性 至关重要。

      components/Links.vue
      <script setup lang="ts">
import { getLocalizedUrl } from "intlayer";
import { useLocale } from "vue-intlayer";

interface Props {
  href: string;
  locale?: string;
}

const props = defineProps<Props>();

const { locale: currentLocale } = useLocale();

// 计算最终路径
const finalPath = computed(() => {
  // 1. 检查链接是否为外部链接
  const isExternal = /^https?:\/\//.test(props.href || "");

  // 2. 如果是外部链接，原样返回（NuxtLink 负责生成 <a> 标签）
  if (isExternal) return props.href;

  // 3. 如果是内部链接，则本地化 URL
  const targetLocale = props.locale || currentLocale.value;
  return getLocalizedUrl(props.href, targetLocale);
});
</script>

<template>
  <NuxtLink :to="finalPath" v-bind="$attrs">
    <slot />
  </NuxtLink>
</template>

      然后在整个应用中使用此组件：

      layouts/default.vue
      <script setup lang="ts">
import Links from "~/components/Links.vue";
import LocaleSwitcher from "~/components/LocaleSwitcher.vue";
</script>

<template>
  <div>
    <header>
      <LocaleSwitcher />
    </header>
    <main>
      <slot />
    </main>

    <Links href="/">首页</Links>
    <Links href="/about">关于</Links>
  </div>
</template>

      通过使用带有本地化路径的 NuxtLink，您可以确保：

      • 搜索引擎能够抓取并索引您页面的所有语言版本
      • 用户可以直接分享本地化的 URL
      • 浏览器历史记录能正确处理带有语言前缀的 URL

    9. 处理元数据和 SEO

      Nuxt 通过 useHead 组合式函数（自动导入）提供了出色的 SEO 功能。您可以使用 Intlayer 处理本地化的元数据，使用 .raw 或 .value 访问器获取原始字符串值：

      pages/about.vue
      <script setup lang="ts">
import { useIntlayer } from "vue-intlayer";

// useHead 在 Nuxt 中自动导入
const content = useIntlayer("about-page");

useHead({
  title: content.metaTitle.raw, // 使用 .raw 获取原始字符串
  meta: [
    {
      name: "description",
      content: content.metaDescription.raw, // 使用 .raw 获取原始字符串值
    },
  ],
});
</script>

<template>
  <h1><content.title /></h1>
</template>
      或者，你可以使用 import { getIntlayer } from "intlayer" 函数来获取内容，且不带 Vue 响应性。

      访问内容值：

      • 使用 .raw 获取原始字符串值（非响应式）
      • 使用 .value 获取响应式值
      • 使用 <content.key /> 组件语法以支持可视化编辑器

      创建对应的内容声明：

      pages/about-page.content.ts
      import { t, type Dictionary } from "intlayer";

const aboutPageContent = {
  key: "about-page",
  content: {
    metaTitle: t({
      en: "关于我们 - 我的公司",
      fr: "À Propos - Ma Société",
      es: "Acerca de Nosotros - Mi Empresa",
    }),
    metaDescription: t({
      en: "了解更多关于我们公司及我们的使命",
      fr: "En savoir plus sur notre société et notre mission",
      es: "Conozca más sobre nuestra empresa y nuestra misión",
    }),
    title: t({
      en: "关于我们",
      fr: "À Propos",
      es: "Acerca de Nosotros",
    }),
  },
} satisfies Dictionary;

export default aboutPageContent;

    10. 创建带导航的布局

      可选

      Nuxt 布局允许您为页面定义一个通用结构。创建一个包含语言切换器和导航的默认布局：

      layouts/default.vue
      <script setup lang="ts">
import Links from "~/components/Links.vue";
import LocaleSwitcher from "~/components/LocaleSwitcher.vue";
</script>

<template>
  <div>
    <header>
      <LocaleSwitcher />
    </header>
    <main>
      <slot />
    </main>

    <Links href="/">首页</Links>
    <Links href="/about">关于</Links>
  </div>
</template>

      Links 组件（如下所示）确保内部导航链接会自动本地化。

    Git 配置

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

    为此，您可以将以下指令添加到您的 .gitignore 文件中：

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

    VS Code 扩展

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

    从 VS Code 市场安装

    该扩展提供：

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

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

    更进一步

    要进一步提升，您可以实现可视化编辑器或使用CMS将内容外部化。

    Vite和VueVite和Solid