Nuxt i18n模块实现动态多语言加载的最佳实践

2025-07-07 15:47:33作者：明树来

引言

在现代Web应用开发中，国际化(i18n)支持已成为基本需求。本文将深入探讨如何在Nuxt.js项目中，通过i18n模块实现从API动态加载多语言消息的完整解决方案。这种方案不仅支持服务器端渲染(SSR)，还能灵活应对多语言、多站点的复杂业务场景。

核心架构设计

目录结构优化

首先需要对项目目录进行合理规划，建议采用以下结构：

pages/
  [locale]/
    index.vue
    about.vue
  [locale]/products/
    [id].vue

这种结构通过动态路由参数[locale]来支持多语言路径，同时保持代码组织清晰。

基础配置

创建i18n.config.ts配置文件，关键配置包括：

export default {
  legacy: false,          // 不使用Vue I18n的legacy API
  strategy: 'no_prefix',  // URL不强制带语言前缀
  locale: 'en-US',        // 默认语言
  defaultLocale: 'en-US', // 回退语言
  detectBrowserLanguage: false // 禁用浏览器语言自动检测
}

关键技术实现

语言检测机制

实现自定义语言检测器serverDetector.ts，支持从多种来源确定当前语言：

URL查询参数优先
其次检查Cookie
最后解析HTTP头部
默认使用配置的defaultLocale

export default defineI18nLocaleDetector((event, config) => {
  let locale = config.defaultLocale;
  
  // 从查询参数获取
  const query = tryQueryLocale(event, {lang: ''});
  if (query) locale = query.toString();
  
  // 从Cookie获取
  const cookie = tryCookieLocale(event, {lang: '', name: 'i18n_locale'});
  if (cookie) locale = cookie.toString();
  
  // 从HTTP头部获取
  const header = tryHeaderLocale(event, {lang: ''});
  if (header) locale = header.toString();
  
  event.context.locale = locale;
  return locale;
});

动态加载语言数据

实现loadLocaleMessageFromApi工具函数，从后端API按需加载语言包：

export default async (url: string, locale: string, fetchInstance: any) => {
  // 解析子域名确定站点渠道
  let subDomain = 'www'; // 默认渠道
  
  // 获取当前渠道对应的语言包
  const {data} = await fetchInstance('/api/translation/all', {
    params: {
      channel_sub_domain: subDomain,
      locale_code: locale
    }
  });
  
  return data?.[0]?.data || null;
};

插件初始化

在Nuxt插件i18n.ts中完成初始化工作：

验证请求语言是否有效
加载默认语言数据
处理无效语言重定向

export default defineNuxtPlugin(async nuxtApp => {
  const i18n = nuxtApp.$i18n;
  const route = useRoute();
  
  // 验证语言是否支持
  const {data: channel} = await useFetchData('/api/settings/storefront');
  const validLocale = channel.value.currentChannel.locales.some(
    l => l.code === route.params.locale
  );
  
  // 加载语言数据
  const toLocale = validLocale ? route.params.locale : 
    channel.value.currentChannel.defaultLocale.code || 'en-US';
  const data = await loadLocaleMessageFromApi(useRequestURL(), toLocale, $fetch);
  
  if (data) {
    i18n.setLocale(toLocale);
    i18n.setLocaleMessage(toLocale, data);
  }
  
  // 无效语言重定向
  if (!validLocale) {
    const correctPath = route.path.replace('/' + route.params.locale, '');
    window.location.href = useRequestURL().origin + correctPath;
  }
});

语言切换方案

完全重载方案

适合内容变化较大的场景，确保完全刷新：

const switchLocale = async (e, code) => {
  e.preventDefault();
  if (i18n.locale.value === code) return;
  
  // 临时克隆当前语言数据避免闪烁
  i18n.setLocaleMessage(code, cloneData(i18n.messages.value[i18n.locale.value]));
  i18n.setLocale(code);
  
  // 完全重载页面
  window.location.href = getLocalLink(code);
};

无刷新切换方案

保持应用状态，仅替换语言数据：

const switchLocale = async (code) => {
  if (i18n.locale.value === code) return;
  
  // 异步加载新语言数据
  const message = await loadLocaleMessageFromApi(
    useRequestURL().origin, code, $fetch
  );
  
  i18n.setLocaleMessage(code, message);
  i18n.setLocale(code);
  
  // 更新路由
  await router.replace({
    name: route.name,
    params: { locale: isDefaultLocale ? '' : code }
  });
};

性能优化建议

缓存控制：配置路由规则，确保缓存考虑语言因素
请求优化：在fetch插件中添加语言相关头部
子域名处理：自动识别当前站点渠道
错误处理：统一处理401等错误状态

export const optHandle = (nuxtApp, setHeaderResponseLocale) => {
  return {
    onRequest({options}) {
      const locale = nuxtApp.$i18n?.locale.value || '';
      
      // 添加语言相关头部
      if (locale) {
        options.headers = {
          ...options.headers,
          'Accept-Language': locale,
          'x-response-locale': setHeaderResponseLocale ? locale : undefined
        };
      }
      
      // 添加渠道标识
      options.headers = {
        ...options.headers,
        'x-channel': getCurrentChannel(),
        'request-id': uuidv4()
      };
    },
    onResponseError({response}) {
      if (response.status === 401) {
        navigateTo('/auth/login');
      }
    }
  };
};