Next-Intl 项目中部分翻译路由的实践与思考

前言

在构建多语言网站时，我们常常会遇到页面内容并非在所有支持的语言中都可用的情况。Next-Intl 作为一个流行的国际化解决方案，在处理完全翻译的路由方面表现出色，但对于部分翻译的路由场景，开发者需要自行实现一些解决方案。本文将深入探讨在 Next-Intl 项目中处理部分翻译路由的实践经验和思考。

部分翻译路由的挑战

当网站支持多种语言（如英语、法语、西班牙语等）但并非所有页面都完全翻译时，开发者面临几个主要挑战：

1. 链接渲染问题：需要根据当前语言环境条件性地显示或隐藏链接
2. 路径定义问题：即使某些语言没有翻译，也必须为所有语言定义路径以满足类型要求
3. 替代链接问题：需要确保只生成实际存在翻译的替代链接

解决方案探索

1. 链接组件的条件渲染

对于链接渲染，开发者可以采取两种主要方式：

直接条件渲染：

{["en", "fr", "es"].includes(locale) && (
  <Link href="/about-us">{t("Footer.about_us")}</Link>
)}

封装自定义链接组件：

const LocalizedLink = ({ availableLocales, ...props }) => {
  const locale = useLocale();
  if (!availableLocales.includes(locale)) return null;
  return <Link {...props} />;
}

2. 路径定义的优雅处理

对于路径定义，可以创建一个辅助函数来处理部分翻译的情况：

const makePartiallyLocalizedPathname = (
  paths: {
    [key in Exclude<Language, "en">]?: string;
  } & { en: string },
): Record<Language, string> => {
  return {
    en: paths.en,
    fr: paths.fr ?? paths.en,
    es: paths.es ?? paths.en,
    // 其他语言...
  };
};

3. 替代链接的自定义处理

对于替代链接，开发者可以禁用 Next-Intl 的默认行为，转而实现自己的替代链接生成逻辑。这通常涉及：

1. 在中间件中禁用默认的替代链接
2. 使用站点地图或其他自定义方式生成替代链接
3. 为不可用的语言返回 404 页面

实践中的完整解决方案

在实际项目中，可以构建一个完整的解决方案来处理部分翻译路由：

1. 定义可用路径名对象，明确指定每个路由在哪些语言中可用
2. 创建适配器函数将这些部分定义转换为 Next-Intl 所需的完整路径名格式
3. 实现路径匹配和语言可用性检查的实用函数

关键实现包括：

// 定义实际可用的路径名
export const availablePathnames = {
  "/": {
    en: "/",
    fr: "/",
    es: "/",
    // 不包括某些语言
  },
  "/gift": {
    en: "/gift",
    fr: "/cadeau", // 法语有特殊路径
  },
  // 其他路由...
};

// 路径匹配函数
export const getMatchedPathname = (pathname: string) => {
  const matchedPathname = Object.keys(availablePathnames).find((path) => {
    const regexStr = path.replace(/\[.*?\]/g, "[^/]*");
    return new RegExp(`^${regexStr}$`).test(pathname);
  });
  return matchedPathname ?? null;
};

// 获取路径名支持的语言
export const getLocalesForPathname = (pathname: string) => {
  const matchedPathname = getMatchedPathname(pathname);
  if (!matchedPathname) return languages;
  
  const available = availablePathnames[matchedPathname];
  if (typeof available !== "object" || Array.isArray(available)) {
    return languages;
  }
  return Object.keys(available) as Language[];
};

未来发展方向

Next-Intl 团队已经计划在 v4 版本中引入对部分路径名定义的支持。虽然最初考虑使用 null 值来标记不可用的语言路径，但最终决定暂不采用这种方案，原因包括：

1. 中间件目前无法可靠地返回 404 页面
2. 需要额外处理不可用语言的链接
3. 功能实现可能不够完整，容易造成用户困惑

因此，目前推荐开发者继续在应用层面处理部分翻译路由的情况。

最佳实践建议

1. 禁用默认替代链接：使用自定义实现（如站点地图）来控制哪些语言版本应该被索引
2. 处理不可用语言：为不可用的语言返回 404 页面
3. 封装链接组件：创建自定义链接组件来处理语言可用性检查
4. 保持路径一致性：在内部始终使用基础路径（如英语路径）作为参考点

结语

处理部分翻译的路由是多语言网站开发中的常见挑战。虽然 Next-Intl 目前没有内置的完整解决方案，但通过合理的架构设计和自定义实现，开发者可以构建出健壮的多语言路由系统。随着 Next-Intl v4 的发布，部分路径名定义将得到更好的支持，进一步简化开发者的工作。

对于复杂的动态路由场景（如博客文章），可能需要结合内容管理系统或数据库查询来确定实际可用的语言版本，这也是未来可以探索的优化方向。