# Technical Documentation: umijs/plugins

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/umijs/plugins)

### Overview (`README.md`)

# @umijs/plugins

[](https://codecov.io/gh/umijs/plugins) [](https://github.com/umijs/plugins)

Official umi plugins and presets.

## Plugins

[plugins list](https://umijs.org/plugins/preset-react)

- plugin-access，权限管理
- plugin-analytics，统计管理
- plugin-antd，整合 antd UI 组件
- plugin-crossorigin，通常用于 JS 出错统计
- plugin-dva，整合 dva
- plugin-helmet，整合 react-helmet，管理 HTML 文档标签（如标题、描述等）
- plugin-initial-state，初始化数据管理
- plugin-layout，配置启用 ant-design-pro 的布局
- plugin-locale，国际化能力
- plugin-model，基于 hooks 的简易数据流
- plugin-request，基于 umi-request 和 umi-hooks 的请求方案

## LICENSE

MIT

---

### Overview (`packages/plugin-access/README.md`)

# @umijs/plugin-access

> Umi plugin for access management..

See our website [@umijs/plugin-access](https://umijs.org/plugins/plugin-access) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-access
```

or using yarn:

```bash
$ yarn add @umijs/plugin-access --dev
```

---

### Overview (`packages/plugin-analytics/README.md`)

# @umijs/plugin-analytics

> analytics for baidu tongji and google analytics.

See our website [@umijs/plugin-analytics](https://umijs.org/plugins/plugin-analytics) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-analytics
```

or using yarn:

```bash
$ yarn add @umijs/plugin-analytics --dev
```

---

### Overview (`packages/plugin-ant-design-pro-block/README.md`)

# @umijs/plugin-ant-design-pro-block

> @umijs/plugin-ant-design-pro-block.

See our website [@umijs/plugin-ant-design-pro-block](https://umijs.org/plugins/plugin-ant-design-pro-block) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-ant-design-pro-block
```

or using yarn:

```bash
$ yarn add @umijs/plugin-ant-design-pro-block --dev
```

---

### Overview (`packages/plugin-antd-dayjs/README.md`)

# @umijs/plugin-antd-dayjs

用于在 umi 中代替 antd-dayjs-webpack-plugin.

> @umijs/plugin-antd-dayjs

See our website [@umijs/plugin-antd-dayjs](https://umijs.org/plugins/plugin-antd-dayjs) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-antd-dayjs
```

or using yarn:

```bash
$ yarn add @umijs/plugin-antd-dayjs --dev
```

---

### Overview (`packages/plugin-antd-mobile/README.md`)

# @umijs/plugin-antd-mobile

> @umijs/plugin-antd-mobile.

See our website [@umijs/plugin-antd-mobile](https://umijs.org/plugins/plugin-antd-mobile) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-antd-mobile
```

or using yarn:

```bash
$ yarn add @umijs/plugin-antd-mobile --dev
```

---

### Overview (`packages/plugin-antd/README.md`)

# @umijs/plugin-antd

> @umijs/plugin-antd.

See our website [@umijs/plugin-antd](https://umijs.org/plugins/plugin-antd) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-antd
```

or using yarn:

```bash
$ yarn add @umijs/plugin-antd --dev
```

---

### Overview (`packages/plugin-block-devtool/README.md`)

# @umijs/plugin-block-devtool

> @umijs/plugin-block-devtool.

See our website [@umijs/plugin-block-devtool](https://umijs.org/plugins/plugin-block-devtool) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-block-devtool
```

or using yarn:

```bash
$ yarn add @umijs/plugin-block-devtool --dev
```

---

### Overview (`packages/plugin-crossorigin/README.md`)

# @umijs/plugin-crossorigin

> @umijs/plugin-crossorigin.

See our website [@umijs/plugin-crossorigin](https://umijs.org/plugins/plugin-crossorigin) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-crossorigin
```

or using yarn:

```bash
$ yarn add @umijs/plugin-crossorigin --dev
```

---

### Overview (`packages/plugin-dev-externals/README.md`)

# @umijs/plugin-dev-externals

> @umijs/plugin-dev-externals.

See our website [@umijs/plugin-dev-externals](https://umijs.org/plugins/plugin-dev-externals) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-dev-externals
```

or using yarn:

```bash
$ yarn add @umijs/plugin-dev-externals --dev
```

---

### Overview (`packages/plugin-dva/README.md`)

# @umijs/plugin-dva

> @umijs/plugin-dva.

See our website [@umijs/plugin-dva](https://umijs.org/plugins/plugin-dva) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-dva
```

or using yarn:

```bash
$ yarn add @umijs/plugin-dva --dev
```

---

### Overview (`packages/plugin-esbuild/README.md`)

# @umijs/plugin-esbuild

> @umijs/plugin-esbuild.

See our website [@umijs/plugin-esbuild](https://umijs.org/plugins/plugin-esbuild) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-esbuild
```

or using yarn:

```bash
$ yarn add @umijs/plugin-esbuild --dev
```

---

### Overview (`packages/plugin-helmet/README.md`)

# @umijs/plugin-helmet

> @umijs/plugin-ssr-helmet.

See our website [@umijs/plugin-helmet](https://umijs.org/plugins/plugin-helmet) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-helmet
```

or using yarn:

```bash
$ yarn add @umijs/plugin-helmet --dev
```

---

### Overview (`packages/plugin-initial-state/README.md`)

# @umijs/plugin-initial-state

> @umijs/plugin-initial-state.

See our website [@umijs/plugin-initial-state](https://umijs.org/plugins/plugin-initial-state) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-initial-state
```

or using yarn:

```bash
$ yarn add @umijs/plugin-initial-state --dev
```

---

### Overview (`packages/plugin-layout/README.md`)

# @umijs/plugin-layout

> @umijs/plugin-layout.

See our website [@umijs/plugin-layout](https://umijs.org/plugins/plugin-layout) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-layout
```

or using yarn:

```bash
$ yarn add @umijs/plugin-layout --dev
```

---

### Overview (`packages/plugin-locale/README.md`)

# @umijs/plugin-locale

> @umijs/plugin-locale.

See our website [@umijs/plugin-locale](https://umijs.org/plugins/plugin-locale) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-locale
```

or using yarn:

```bash
$ yarn add @umijs/plugin-locale --dev
```

---

### Overview (`packages/plugin-model/README.md`)

# @umijs/plugin-model

> @umijs/plugin-model.

See our website [@umijs/plugin-model](https://umijs.org/plugins/plugin-model) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-model
```

or using yarn:

```bash
$ yarn add @umijs/plugin-model --dev
```

---

### Overview (`packages/plugin-openapi/README.md`)

# @umijs/plugin-openapi

> @umijs/plugin-openapi.

See our website [@umijs/plugin-openapi](https://umijs.org/plugins/plugin-openapi) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-openapi
```

or using yarn:

```bash
$ yarn add @umijs/plugin-openapi --dev
```

---

### Overview (`packages/plugin-preact/README.md`)

# @umijs/plugin-preact

> @umijs/plugin-preact.

See our website [@umijs/plugin-preact](https://umijs.org/plugins/plugin-preact) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-preact
```

or using yarn:

```bash
$ yarn add @umijs/plugin-preact --dev
```

---

### Overview (`packages/plugin-qiankun/README.md`)

# @umijs/plugin-qiankun

> umi plugin for [qiankun](https://qiankun.umijs.org/).

See our website [@umijs/plugin-qiankun](https://v3.umijs.org/plugins/plugin-qiankun) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-qiankun
```

or using yarn:

```bash
$ yarn add @umijs/plugin-qiankun --dev
```

---

### Overview (`packages/plugin-request/README.md`)

# @umijs/plugin-request

> @umijs/plugin-request.

See our website [@umijs/plugin-request](https://umijs.org/plugins/plugin-request) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-request
```

or using yarn:

```bash
$ yarn add @umijs/plugin-request --dev
```

---

### Overview (`packages/plugin-sass/README.md`)

# @umijs/plugin-sass

> @umijs/plugin-sass.

See our website [@umijs/plugin-sass](https://umijs.org/plugins/plugin-sass) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-sass
```

or using yarn:

```bash
$ yarn add @umijs/plugin-sass --dev
```

---

### Overview (`packages/plugin-stylus/README.md`)

# @umijs/plugin-stylus

> @umijs/plugin-stylus.

See our website [@umijs/plugin-stylus](https://umijs.org/plugins/plugin-stylus) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-stylus
```

or using yarn:

```bash
$ yarn add @umijs/plugin-stylus --dev
```

---

### Overview (`packages/plugin-test/README.md`)

# @umijs/plugin-test

> @umijs/plugin-test.

See our website [@umijs/plugin-test](https://umijs.org/plugins/plugin-test) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/plugin-test
```

or using yarn:

```bash
$ yarn add @umijs/plugin-test --dev
```

---

### Overview (`packages/preset-ant-design-pro/README.md`)

# @umijs/preset-ant-design-pro

> @umijs/preset-ant-design-pro.

See our website [@umijs/preset-ant-design-pro](https://umijs.org/plugins/preset-ant-design-pro) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/preset-ant-design-pro
```

or using yarn:

```bash
$ yarn add @umijs/preset-ant-design-pro --dev
```

---

### Overview (`packages/preset-react/README.md`)

# @umijs/preset-react

> @umijs/preset-react.

See our website [@umijs/preset-react](https://umijs.org/plugins/preset-react) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/preset-react
```

or using yarn:

```bash
$ yarn add @umijs/preset-react --dev
```

---

### Overview (`packages/preset-umi2-compatible/README.md`)

# @umijs/preset-umi2-compatible

> @umijs/preset-umi2-compatible.

See our website [@umijs/preset-umi2-compatible](https://umijs.org/plugins/preset-umi2-compatible) for more information.

## Install

Using npm:

```bash
$ npm install --save-dev @umijs/preset-umi2-compatible
```

or using yarn:

```bash
$ yarn add @umijs/preset-umi2-compatible --dev
```

---

### Overview (`packages/plugin-ant-design-pro-block/docs/README.md`)

# @umijs/plugin-ant-design-pro-block

[](https://npmjs.org/package/umi-plugin-pro-block) [](https://npmjs.org/package/umi-plugin-ant-design-pro-block)

A plugin for deliver umi block files like ant design pro structure.

When you use `umi block demo` to download a block, if you did not use this plugin, you will get:

```diff
- src
  - mock
  - pages
+   - demo
+     - index.js
+     - _mock.js
+     - service.js
```

And if you use it, you will get:

```diff
- src
  - mock
+   - demo.js
  - service.js
+   - demo.js
  - pages
+   - demo
+     - index.js
```

Ant will replace `umi-request` to `util(s)/request.js` if it exist.

## Usage

Configure in `.umirc.js`,

```js
export default {
  plugins: ['@umijs/plugin-blocks', '@umijs/plugin-ant-design-pro-block'],
};
```

## Options

```js
{
  moveMock: false, // whether move _mock.js to mock, default to true
  moveService: false, // whether move service.js to src/services/, default to true
  modifyRequest: false, // whether modify umi-request to util(s)/request (if it exist), default to true
  autoAddMenu: false, // whether add name and icon config to route config when download a pro, default to true
}
```

## LICENSE

MIT

---

### Overview (`packages/plugin-block-devtool/docs/README.md`)

# umi-plugin-block-dev

[](https://npmjs.org/package/umi-plugin-block-dev) [](https://npmjs.org/package/umi-plugin-block-dev)

A umi plugin for develop a umi block with umi

## Layout

### blankLayout



### ant-design-pro



### ant-design-pro-user



## Usage

Configure in `.umirc.js`,

```js
export default {
  plugins: [['umi-plugin-block-dev', options]],
};
```

And you can use `create-umi` to create a umi block automatically:

```sh
$ yarn create umi --block
```

## options

```js
{
  layout: 'ant-design-pro', // or ant-design-pro-user
  menu: {
    name: 'demo',
    icon: 'home',
  },
  mockUmiRequest: true // whether to build mock data . _mock.js
}
```

### env

- BLOCK_DEV_PATH: custom block preview path
- BLOCK_DEV_MOCK_UMI_REQUEST: package mock data to build result, for build static preview site
- BLOCK_PAGES_LAYOUT: custom block Layout

## LICENSE

MIT

---

### Overview (`packages/plugin-locale/docs/README.md`)

[English](README.en-US.md)

# @umijs/plugin-locale

## Use

安装

```bash
npm i @umijs/plugin-locale --save
```

在 umirc.js，或 config/config.js 中配置

```tsx
plugins: ['@umijs/plugin-locale'];
```

配置:

```jsx
{
  locale: {
    default?: string;
    baseNavigator?: boolean;
    useLocalStorage?: boolean;
    /** title 开启国际化 */
    title?: boolean;
    antd?: boolean;
    baseSeparator?: string;
  }
}
```

```tsx
import React, { useState, useEffect } from 'react';
import { useIntl, getLocale, addLocale, getAllLocales, setLocale } from 'umi';
import styles from './index.css';

export default function () {
  const intl = useIntl();
  const [list, setList] = useState<string[]>(getAllLocales());
  const locale = getLocale();

  useEffect(() => {
    // 动态增加新语言
    addLocale('zh-TW', {
      name: '妳好，{name}',
    });
    // 刷新列表
    setList(getAllLocales());
  }, []);

  return (
    <div className={styles.normal}>
      <h1>当前语言：{locale}</h1>
      {list.map((locale) => (
        <a
          key={locale}
          onClick={() => {
            setLocale(locale);
          }}
          style={{
            margin: 8,
          }}
        >
          {locale}
        </a>
      ))}
      <button type="primary">
        {intl.formatMessage(
          {
            id: 'name',
          },
          {
            name: '旅行者',
          },
        )}
      </button>
    </div>
  );
}
```

## API

@umijs/plugin-locale 基于 react-intl 封装，支持其所有的 api，详情可以看[这里](https://github.com/formatjs/react-intl/blob/master/docs/API.md)。为了方便使用我们也添加了一些其他的功能，这里将会列举所有的 api，并且展示它的功能。

### addLocale

动态的增加语言，增加语言之后可以通过 getAllLocales 获得列表。addLocale 三个参数。

- name 语言的 key。例如 zh-TW
- message 语言的 id 列表。 例如：{ // id 列表 name: '妳好，{name}', }
- extraLocales 相应的 `momentLocale` 和 `antd` 配置

```tsx
import zhTW from 'antd/es/locale/zh_TW';

// 动态增加新语言
addLocale(
  'zh-TW',
  {
    // id 列表
    name: '妳好，{name}',
  },
  {
    momentLocale: 'zh-tw',
    antd: zhTW,
  },
);
```

### getAllLocales

获取当前获得所有国际化文件的列表，默认会在 locales 文件夹下寻找类似 en-US.(js|json|ts) 文件。

```tsx
import { getAllLocales } from 'umi';

console.log(getAllLocales()); // [en-US,zh-CN,...]
```

### getLocale

`getLocale` 将获得当前选择的语言。

```tsx
import { getLocale } from 'umi';

console.log(getLocale()); // en-US | zh-CN
```

### useIntl

useIntl 是最常用的 api,它可以获得 formatMessage 等 api 来进行具体的值绑定。

```ts
// en-US.json
export default {
  name: 'Hi, {name}',
};
```

```tsx
//page/index.tsx

import React, { useState } from 'react';
import { useIntl } from 'umi';

export default function () {
  const intl = useIntl();
  return (
    <button type="primary">
      {intl.formatMessage(
        {
          id: 'name',
          defaultMessage: '你好，旅行者',
        },
        {
          name: '旅行者',
        },
      )}
    </button>
  );
}
```

### setLocale

设置切换语言，默认会刷新页面，可以通过设置第二个参数为 false，来动态切换。

```tsx
import { setLocale } from 'umi';

// 刷新页面
setLocale('zh-TW', true);

// 不刷新页面
setLocale('zh-TW', false);
```

### <SelectLang />

选择语言的展示组件。可以通过开启 locale 插件，从 umi 中获取该组件。只有当项目依赖 antd, 同时项目 /locales 文件夹下有超过两个语言文件时才会显示。可配置的属性有：

- postLocaleData, 默认包含 "简体中文" 、"繁体中文"、 "英文" 、"葡萄牙语"四种语言配置,当需要展示其他语言时，可以通过配置 postLocaleData 来扩展，格式如下所示。
- globalIconClassName, 全球图标的样式。
- onItemClick, 切换语言时的回掉函数，默认会 setLocale。
- <[Dropdown/](https://ant.design/components/dropdown-cn/#API)> 的所有 API。

```tsx
import { SelectLang } from 'umi';

<SelectLang
  postLocaleData={locales=> ([
    ...locales,
    {
      lang: 'nl-NL', // 语言的 key 与 antd & locales 下的文件名保持一致
      label: 'Nederlands', // 下拉菜单中展示的语言名
      icon: '🇳🇱', // 下拉菜单中展示的 icon （一般为国旗
      title: 'Taal', // 鼠标浮上全球图标时展示的文案（一般为“语言”这个词的各种翻译
    }
  ])}
  onItemClick={({ key }) => alert(key)}
>
```

### 运行时配置

支持运行时对国际化做一些扩展与定制，例如自定义语言识别等。

#### getLocale

自定义语言获取逻辑，比如识别链接 `?locale=${lang}` 当做当前页面的语言。

```js
// src/app.js
import qs from 'qs';

export const locale = {
  getLocale() {
    const { search } = window.location;
    const { locale = 'zh-CN' } = qs.parse(search, { ignoreQueryPrefix: true });
    return locale;
  },
};
```

#### setLocale

自定义语言切换逻辑。其中有三个参数：

- lang: 需要切换的语言
- realReload: 是否需要刷新页面，这个是由页面调用 `setLocale(lang, true)` 透传。
- updater：是否触发组件 rerender 重渲染。

```js
// src/app.js
export const locale = {
  setLocale({ lang, realReload, updater }) {
    history.push(`/?locale=${lang}`);
    updater();
  },
};
```

## 扩展 antd 国际化

比如有一个基于 antd 的组件库 ant-c，可以通过以下方式扩展 antd 国际化：

```jsx
// pluginA.js
export default (api) => {
  api.register({
    key: 'addAntdLocales',
    fn: (args) => {
      const { ssr } = api.config;
      return [
        `ant-c/${ssr ? 'lib' : 'es'}/locale/${args.lang}_${(
          args.country || args.lang
        ).toLocaleUpperCase()}`,
      ];
    },
  });
};
```

那么在开启 `locale: { antd: true }` 后，antd 的 [ConfigProvider](https://ant.design/components/config-provider-cn/) 就会有 `antd` 与 `ant-c` 的国际化了。

## FAQ

### 为什么不要使用 formatMessage 这个语法糖？

虽然 formatMessage 使用起来会非常方便，但是它脱离了 react 的生命周期，最严重的问题就是切换语言时无法触发 dom 重新渲染。为了解决这个问题，我们切换语言时会刷新一下浏览器，用户体验很差，所以推荐大家使用 [`useIntl`](./#useIntl) 或者 [`injectIntl`](https://github.com/formatjs/react-intl/blob/master/docs/API.md#injectintl-hoc)，可以实现同样的功能。

---

### Overview (`packages/plugin-test/docs/README.md`)

# @umijs/plugin-test

## 启用方式

默认开启。

## 介绍

基于 jest 提供 `umi test` 命令。

包含以下特性，

- 支持 lerna 包，可以针对子包测试和生成覆盖率
- 支持 TypeScript
- 内置以下补丁
  - core-js/stable
  - regenerator-runtime/runtime
  - whatwg-fetch
- 支持通过 jest.config.json 和 package.json 中的 jest 属性进行配置，前者优先级更高
- jest.config.json 中的配置项支持函数的形式

## 使用

```bash
$ umi-test

# watch mode
$ umi-test -w
$ umi-test --watch

# collect coverage
$ umi-test --coverage

# print debug info
$ umi-test --debug

# test specified package for lerna package
$ umi-test --package name

# don't do e2e test
$ umi-test --no-e2e
```

## 配置

通过 jest.config.js 实现配置的目的，比如：

```js
module.exports = {
  moduleNameMapper: {
    '^umi$': require.resolve('umi'),
  },
};
```

但有时你会希望保留 umi-test 内置的配置，只做扩展，我们也函数的形式，比如：

```js
module.exports = {
  moduleNameMapper(memo) {
    return {
      ...memo,
      '^umi$': require.resolve('umi'),
    };
  },
};
```

---

### Packages Plugin Locale Docs README.En US (`packages/plugin-locale/docs/README.en-US.md`)

# @umijs/plugin-locale

## Use

installation

```bash
npm i @umijs/plugin-locale --save
```

Configure in `umirc.js`, or `config/config.js|ts`

```tsx
plugins: ['@umijs/plugin-locale'];
```

Configuration:

```jsx
{
  locale: {
    default?: string;
    baseNavigator?: boolean;
    useLocalStorage?: boolean;
    /** title 开启国际化 */
    title?: boolean;
    antd?: boolean;
    baseSeparator?: string;
  }
}
```

```tsx
import React, { useState, useEffect } from 'react';
import { useIntl, getLocale, addLocale, getAllLocales, setLocale } from 'umi';
import styles from './index.css';

export default function () {
  const intl = useIntl();
  const [list, setList] = useState<string[]>(getAllLocales());
  const locale = getLocale();

  useEffect(() => {
    // Dynamically add new languages
    addLocale('zh-TW', {
      name: '妳好，{name}',
    });
    // refresh the list
    setList(getAllLocales());
  }, []);

  return (
    <div className={styles.normal}>
      <h1>Current language:{locale}</h1>
      {list.map((locale) => (
        <a
          key={locale}
          onClick={() => {
            setLocale(locale);
          }}
          style={{
            margin: 8,
          }}
        >
          {locale}
        </a>
      ))}
      <button type="primary">
        {intl.formatMessage(
          {
            id: 'name',
          },
          {
            name: 'Traveler',
          },
        )}
      </button>
    </div>
  );
}
```

## API

`@umijs/plugin-locale` is based on react-intl package and supports all its APIs. For details, see [here](https://github.com/formatjs/react-intl/blob/master/docs/API.md)。For the convenience of use, we have also added some other functions. Here we will list all the APIs and show their functions.

### addLocale

Add languages dynamically. After adding languages, you can get the list by `getAllLocales`. `addLocale` three parameters.

- name The key of the language. E.g zh-TW
- message A list of ids for the language. E.g:{ // id 列表 name: '妳好，{name}', }
- extraLocales Corresponding `momentLocale` and `antd` configuration

```tsx
import zhTW from 'antd/es/locale/zh_TW';

// Adding new languages dynamically
addLocale(
  // name
  'zh-TW',
  // message
  {
    // id 列表
    name: '妳好，{name}',
  },
  // extraLocales
  {
    momentLocale: 'zh-tw',
    antd: zhTW,
  },
);
```

### getAllLocales

Get the current list of all internationalization files. By default, it looks for `en-US.(js|json|ts)` files in the locales folder.

```tsx
import { getAllLocales } from 'umi';

console.log(getAllLocales()); // [en-US,zh-CN,...]
```

### getLocale

`getLocale` will get the currently selected language.

```tsx
import { getLocale } from 'umi';

console.log(getLocale()); // en-US | zh-CN
```

### useIntl

useIntl is the most commonly used API, and it can obtain APIs such as formatMessage for specific value binding.

```ts
// en-US.json
export default {
  name: 'Hi, {name}',
};
```

```tsx
//page/index.tsx

import React, { useState } from 'react';
import { useIntl } from 'umi';

export default function () {
  const intl = useIntl();
  return (
    <button type="primary">
      {intl.formatMessage(
        {
          id: 'name',
          defaultMessage: '你好，旅行者',
        },
        {
          name: '旅行者',
        },
      )}
    </button>
  );
}
```

### setLocale

Set the switching language. The page will be refreshed by default. You can dynamically switch by setting the second parameter to false.

```tsx
import { setLocale } from 'umi';

// 刷新页面
setLocale('zh-TW', true);

// 不刷新页面
setLocale('zh-TW', false);
```

## Extension antd internationalization

Such as a component library based on antd ant-c, can be extended antd internationalization by the following way:

```jsx
// pluginA.js
export default (api) => {
  api.register({
    key: 'addAntdLocales',
    fn: (args) => {
      const { ssr } = api.config;
      return [
        `ant-c/${ssr ? 'lib' : 'es'}/locale/${args.lang}_${(
          args.country || args.lang
        ).toLocaleUpperCase()}`,
      ];
    },
  });
};
```

After enabling `locale: { antd: true }`, antd's [ConfigProvider](https://ant.design/components/config-provider/) will be the `antd` and `ant-c` internationalization。

## FAQ

### Why no use formatMessage?

Although formatMessage is very convenient to use, it is out of the react life cycle. The most serious problem is that it cannot trigger dom re-rendering when switching languages. In order to solve this problem, we will refresh the browser when switching languages. The user experience is poor, so it is recommended that you use [`useIntl`](./#useIntl) or [`injectIntl`](https://github.com/formatjs/react-intl/blob/master/docs/API.md#injectintl-hoc), can achieve the same thing.

---

--- METRICS ---
- Files Extracted: 32
- Estimated Token Budget: ~5915 tokens
- Canonical Reference: https://codewiki.google/github.com/umijs/plugins