Umi.js国际化功能使用指南

概述

Umi.js作为企业级前端应用框架，提供了完善的国际化(i18n)支持方案。本文将详细介绍如何在Umi项目中正确配置和使用国际化功能，避免常见的依赖冲突问题。

核心概念

Umi.js提供了两种国际化实现方式：

1. 基础版(umi)：需要手动配置国际化插件
2. 全功能版(@umijs/max)：内置国际化支持

开发者需要根据项目需求选择适合的版本，两者不可混用。

配置步骤

1. 选择版本

在项目package.json中明确选择使用：

• umi（基础版）
• 或@umijs/max（全功能版）

两者不可同时存在，否则会导致依赖冲突。

2. 基础版配置

如果选择基础版umi，需要手动安装和配置国际化插件：

1. 安装必要依赖：

npm install @umijs/plugins

2. 在.umirc.ts中配置：

import { defineConfig } from 'umi';

export default defineConfig({
  plugins: [
    '@umijs/plugins/dist/locale',
  ],
  locale: {
    default: 'zh-CN',
    antd: true,
    baseNavigator: true,
  },
});

3. 全功能版配置

如果选择@umijs/max，国际化功能已内置，只需配置：

// config/config.ts
export default {
  locale: {
    default: 'zh-CN',
    antd: true,
  },
};

使用国际化

配置完成后，在组件中使用：

import { useIntl } from 'umi';

function MyComponent() {
  const intl = useIntl();
  
  return (
    <div>
      {intl.formatMessage({ id: 'welcome' })}
    </div>
  );
}

常见问题解决

1. "useIntl未导出"错误：

   • 确认已正确配置国际化插件
   • 检查是否同时安装了umi和@umijs/max

2. 依赖冲突：

   • 删除package.json中冲突的依赖项
   • 执行npm install或yarn install重新安装

最佳实践

1. 小型项目建议使用@umijs/max，开箱即用
2. 需要高度定制化的大型项目可选择基础版umi
3. 保持语言资源文件与代码分离，便于维护
4. 为团队制定统一的国际化key命名规范

通过本文介绍的方法，开发者可以轻松在Umi项目中实现国际化功能，同时避免常见的配置问题。