使用您最喜欢的AI助手总结文档,并引用此页面和AI提供商
通过将 Intlayer MCP 服务器集成到您的 AI 助手,您可以直接从 ChatGPT、DeepSeek、Cursor、VSCode 等获取所有文档。
查看 MCP 服务器文档版本历史
- 更新 LocaleSwitcher、SEO、元数据v7.3.112025/12/7
- 初始化历史记录v5.5.102025/6/29
此页面的内容已使用 AI 翻译。
查看英文原文的最新版本如果您有改善此文档的想法,请随时通过在GitHub上提交拉取请求来贡献。
文档的 GitHub 链接复制文档 Markdown 到剪贴板
使用 Intlayer 翻译您的 Nuxt 和 Vue 网站 | 国际化 (i18n)
目录
什么是 Intlayer?
Intlayer 是一个创新的开源国际化(i18n)库,旨在简化现代 Web 应用中的多语言支持。
使用 Intlayer,您可以:
- 通过组件级声明式字典轻松管理翻译。
- 动态本地化元数据、路由和内容。
- 确保 TypeScript 支持,通过自动生成类型,提升自动补全和错误检测能力。
- 享受高级功能,如动态语言环境检测和切换。
在 Nuxt 应用中设置 Intlayer 的分步指南
第一步:安装依赖
查看 GitHub 上的应用模板。
使用 npm 安装必要的包:
npm install intlayer vue-intlayernpm install --save-dev nuxt-intlayerintlayer
vue-intlayer 将 Intlayer 集成到 Vue 应用中的包。它提供了 Vue 组件的组合式函数。
nuxt-intlayer 集成 Intlayer 与 Nuxt 应用的 Nuxt 模块。它提供自动设置、用于语言环境检测的中间件、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 日志等。有关可用参数的完整列表,请参阅配置文档。
第三步:在您的 Nuxt 配置中集成 Intlayer
将 intlayer 模块添加到您的 Nuxt 配置中:
复制代码到剪贴板
import { defineNuxtConfig } from "nuxt/config";export default defineNuxtConfig({ // ... 您现有的 Nuxt 配置 modules: ["nuxt-intlayer"],});nuxt-intlayer 模块会自动处理 Intlayer 与 Nuxt 的集成。它设置内容声明的构建,监控开发模式下的文件,提供用于语言环境检测的中间件,并管理本地化路由。
第4步:声明您的内容
创建并管理您的内容声明以存储翻译:
复制代码到剪贴板
import { type Dictionary, t } from "intlayer";const content = { key: "home-page", content: { title: t({ en: "Hello world", fr: "Bonjour le monde", es: "Hola mundo", }), metaTitle: t({ en: "Welcome | My Application", fr: "Bienvenue | Mon Application", es: "Bienvenido | Mi Aplicación", }), metaDescription: t({ en: "Discover your multilingual Nuxt app homepage powered by Intlayer.", fr: "Découvrez la page d'accueil multilingue de votre application Nuxt propulsée par Intlayer.", es: "Descubre la página de inicio multilingüe de tu aplicación Nuxt impulsada por Intlayer.", }), },} satisfies Dictionary;export default content;您的内容声明可以定义在应用程序中的任何位置,只要它们包含在 contentDir 目录中(默认是 ./src),并且匹配内容声明文件扩展名(默认是 .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx})。
更多详情,请参阅内容声明文档。
第5步:在代码中使用 Intlayer
在整个 Nuxt 应用中使用 useIntlayer 组合式函数访问您的内容字典:
复制代码到剪贴板
<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"); // 使用名为 "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 和页面可发现性的最佳实践,因为这允许搜索引擎抓取并索引页面的所有本地化版本:
复制代码到剪贴板
<script setup lang="ts">import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale } from "vue-intlayer";// Nuxt 自动导入 useRouteconst 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 以使用布局:
复制代码到剪贴板
<template> <NuxtLayout> <NuxtPage /> </NuxtLayout></template>(可选)步骤 6b:创建带导航的布局
Nuxt 布局允许您为页面定义一个通用结构。创建一个包含语言切换器和导航的默认布局:
复制代码到剪贴板
<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 组件(如下所示)确保内部导航链接会自动本地化。
(可选)步骤 7:为您的应用添加本地化路由
当使用 nuxt-intlayer 模块时,Nuxt 会自动处理本地化路由。它会根据您的页面目录结构自动为每种语言创建路由。
示例:
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):
复制代码到剪贴板
<script setup lang="ts">import { useIntlayer } from "vue-intlayer";const content = useIntlayer("home-page");useHead({ title: content.metaTitle.value, meta: [ { name: "description", content: content.metaDescription.value, }, ],});</script><template> <h1><content.title /></h1></template>关于页面 (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 和页面可发现性 至关重要。
复制代码到剪贴板
<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>然后在整个应用中使用此组件:
复制代码到剪贴板
<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 访问器获取原始字符串值:
复制代码到剪贴板
<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 /> 组件语法以支持可视化编辑器
创建对应的内容声明:
复制代码到剪贴板
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;Git 配置
建议忽略 Intlayer 生成的文件。这样可以避免将它们提交到您的 Git 仓库中。
为此,您可以将以下指令添加到您的 .gitignore 文件中:
复制代码到剪贴板
# 忽略 Intlayer 生成的文件.intlayerVS Code 扩展
为了提升您使用 Intlayer 的开发体验,您可以安装官方的 Intlayer VS Code 扩展。
该扩展提供:
- 翻译键的 自动补全。
- 缺失翻译的 实时错误检测。
- 翻译内容的 内联预览。
- 轻松创建和更新翻译的 快速操作。
有关如何使用该扩展的更多详细信息,请参阅 Intlayer VS Code 扩展文档。