当前位置：首页 > 文章列表 > 文章 > 前端 > Nuxt3动态加载i18n多语言配置实践

Nuxt3动态加载i18n多语言配置实践

2026-05-27 14:09:38 0浏览收藏

本文深入解析了在 Nuxt 3 中突破配置同步限制、实现真正动态多语言支持的完整方案：通过预设静态 locale 结构保障路由国际化正常工作，再结合插件与 `setLocaleMessage` 在运行时按需加载并热更新远程翻译资源，完美兼容 CMS 驱动场景、客户端语言切换、SSR 及 SSG，让多语言不再受限于构建时配置，而是随内容实时响应、灵活可扩展。

Nuxt 3 中动态从 API 加载 i18n 多语言配置的完整实践方案

本文详解如何在 Nuxt 3 中绕过 defineNuxtConfig 的同步限制，通过插件 + setLocaleMessage 动态加载并注入远程 locales 和翻译资源，兼容路由国际化、语言切换与 SSR/SSG 场景。

本文详解如何在 Nuxt 3 中绕过 `defineNuxtConfig` 的同步限制，通过插件 + `setLocaleMessage` 动态加载并注入远程 locales 和翻译资源，兼容路由国际化、语言切换与 SSR/SSG 场景。

在 Nuxt 3 中集成 @nuxtjs/i18n 时，若需从 CMS（如 Prismic）或自定义 API 动态获取 locales 列表及对应翻译资源，直接在 nuxt.config.ts 中硬编码 locales 显然不适用——因为配置阶段无法执行异步操作。而简单地在插件中赋值 $i18n.locales = [...] 也无法触发路由系统重初始化，导致 /en/、/zh/ 等前缀路由失效。正确的解法是分两层动态注入：

预设静态 locales 结构（供路由系统识别路径），
运行时按需加载并注入翻译消息（setLocaleMessage），同时支持语言切换时热更新。

✅ 正确实现步骤

1. 预设最小化 locales（必需）

在 nuxt.config.ts 中声明所有可能的 locale code（即使内容暂空），确保 i18n 路由器能正确解析 URL 前缀：

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n'],
  i18n: {
    lazy: true,
    langDir: 'locales',
    strategy: 'prefix_except_default',
    locales: [
      { code: 'en-US', name: 'English', iso: 'en-US' },
      { code: 'zh-TW', name: '繁體中文', iso: 'zh-TW' },
      { code: 'pl-PL', name: 'Polski', iso: 'pl-PL' },
      // 注意：无需 file 字段，因翻译将动态加载
    ],
    defaultLocale: 'en-US',
    detectBrowserLanguage: false, // 避免与动态逻辑冲突
  }
})

⚠️ 关键点：locales 数组必须包含所有目标语言的 code，否则 useI18n().locales 不会返回完整列表，前端下拉菜单和路由生成均会出错。

2. 创建动态翻译加载工具函数

封装可复用的异步加载逻辑，支持按语言码请求翻译 JSON 并注入：

// utils/i18n.ts
export const fetchAndApplyTranslations = async (
  lang: string,
  setLocaleMessage: (locale: string, messages: Record) => void
) => {
  try {
    // 假设 API 返回纯 JSON 格式翻译对象，如 { "hello": "你好", "welcome": "欢迎" }
    const translations = await $fetch>(`/api/locales?lang=${lang}`)
    if (translations && Object.keys(translations).length > 0) {
      setLocaleMessage(lang, translations)
      console.log(`✅ Translations loaded for ${lang}`)
    } else {
      console.warn(`⚠️ Empty translations received for ${lang}`)
    }
  } catch (error) {
    console.error(`❌ Failed to fetch translations for ${lang}:`, error)
  }
}

3. 初始化插件：首次访问加载当前语言

在插件中调用上述函数，确保首屏渲染即使用服务端/客户端最新翻译：

// plugins/i18n.client.ts （仅客户端执行，避免 SSR 时 $fetch 报错）
import { fetchAndApplyTranslations } from '~/utils/i18n'

export default defineNuxtPlugin(async (nuxtApp) => {
  const { $i18n } = nuxtApp
  // 确保 locale 已初始化（如通过 cookie / header / query）
  const currentLang = $i18n.locale.value || 'en-US'
  await fetchAndApplyTranslations(currentLang, $i18n.setLocaleMessage)
})

? 提示：若需 SSR 支持，请改用 plugins/i18n.server.ts + useAsyncData 在页面级加载，但注意 setLocaleMessage 仅在客户端生效，服务端渲染仍依赖 vueI18n 配置的初始消息。

4. 语言切换时动态加载新语言

在组件中监听语言变更，并触发对应翻译加载：

5. 后端 API 示例（供参考）

确保你的 /api/locales 接口返回标准 JSON 格式：

// server/api/locales.get.ts
export default defineEventHandler(async (event) => {
  const lang = getQuery(event).lang as string
  const supported = ['en-US', 'zh-TW', 'pl-PL']
  if (!supported.includes(lang)) {
    throw createError({ status: 400, message: 'Unsupported locale' })
  }
  // 此处可对接 Prismic、数据库等
  return {
    hello: lang === 'zh-TW' ? '你好' : lang === 'pl-PL' ? 'Witaj' : 'Hello',
    welcome: lang === 'zh-TW' ? '欢迎' : lang === 'pl-PL' ? 'Witamy' : 'Welcome'
  }
})