How to Add Custom Locales for Internationalization (i18n) in Ant Design

To add custom locales for internationalization in Ant Design, create a JavaScript object that implements the Locale interface, then pass it to the ConfigProvider component via the locale prop to override the default English strings throughout your application.

Ant Design's internationalization system centers on a centralized Locale object consumed by the ConfigProvider component. Whether you need to support a regional dialect not included in the standard distribution or override specific component strings, you can add custom locales for internationalization by implementing the Locale interface and injecting your object into the React context tree.

Understanding the Locale Architecture

The Locale Interface

The foundation of Ant Design's i18n system is the Locale interface defined in components/locale/index.tsx. This TypeScript interface specifies the exact structure required for all component strings, including properties for Pagination, DatePicker, TimePicker, Calendar, Table, Modal, and a global object for shared terms.

ConfigProvider and LocaleProvider

The ConfigProvider component in components/config-provider/index.tsx serves as the entry point for custom locales. When you provide a locale prop, ConfigProvider internally wraps your application with LocaleProvider (see lines 36-42 of components/config-provider/index.tsx). This provider creates a LocaleContext that descendant components consume to render localized strings.

Step-by-Step: Creating a Custom Locale

Step 1: Define the Locale Object

Create a new file that exports an object matching the Locale interface. Use components/locale/en_US.ts as a reference template to ensure you include all required fields.

Your custom locale must include:

• locale: A string identifier (e.g., 'zh-tw-custom')
• Pagination: Strings for pagination controls
• DatePicker and TimePicker: Calendar and time selection labels
• Calendar: Month/year navigation strings
• global: Shared placeholders and action labels
• Table: Filter, sort, and selection labels

Step 2: Import Component Locales

Import locale objects from specific Ant Design components or underlying rc-components to ensure consistency with the component logic while customizing only the strings.

// src/locale/zh_TW_custom.ts
import Calendar from 'antd/es/calendar/locale/zh_TW';
import DatePicker from 'antd/es/date-picker/locale/zh_TW';
import TimePicker from 'antd/es/time-picker/locale/zh_TW';
import Pagination from '@rc-component/pagination/lib/locale/zh_TW';
import type { Locale } from 'antd/es/locale';

Step 3: Export Your Custom Locale

Construct and export your complete locale object:

const customLocale: Locale = {
  locale: 'zh-tw-custom',
  Pagination,
  DatePicker,
  TimePicker,
  Calendar,
  global: {
    placeholder: '請選擇',
    close: '關閉',
    sortable: '可排序',
  },
  Table: {
    filterTitle: '篩選菜單',
    filterConfirm: '確定',
    filterReset: '重置',
    selectAll: '選擇全部',
    selectInvert: '反向選擇',
  },
  // Add other component sections as needed
};

export default customLocale;

For library authors distributing the locale, add the file path to your package.json exports field so consumers can import it directly:

{
  "exports": {
    "./locale/zh_TW_custom": "./src/locale/zh_TW_custom.ts"
  }
}

Implementing the Custom Locale in Your Application

Using ConfigProvider

Wrap your application root with ConfigProvider and pass your custom locale object to the locale prop. This injects the locale into the React context tree, making it available to all Ant Design components.

import React from 'react';
import { ConfigProvider, Button, Table } from 'antd';
import customLocale from './locale/zh_TW_custom';

function App() {
  return (
    <ConfigProvider locale={customLocale}>
      <div>
        <Button type="primary">Click Me</Button>
        <Table 
          columns={columns} 
          dataSource={data}
          // Table will use customLocale.Table.filterTitle, etc.
        />
      </div>
    </ConfigProvider>
  );
}

export default App;

According to the source code in components/config-provider/index.tsx (lines 90-94), the ConfigProvider merges your locale object with the internal context, ensuring that all descendant components receive the localized strings.

Accessing Locale Inside Components

To read the current locale object within a custom component, use the useLocale hook exported from antd. This hook is defined in components/locale/useLocale.ts and re-exported from components/locale/index.tsx (line 18).

import { useLocale, Button } from 'antd';

function MyComponent() {
  const locale = useLocale();
  
  return (
    <Button>
      {locale?.global?.placeholder ?? 'Select an option'}
    </Button>
  );
}

The hook returns the Locale object provided by the nearest ConfigProvider, or undefined if no provider exists above the component.

Summary

• Ant Design's i18n system relies on a Locale object passed to ConfigProvider that gets injected into LocaleContext for all child components.
• Create custom locales by implementing the Locale interface from components/locale/index.tsx, using components/locale/en_US.ts as a template.
• Apply the locale by importing your custom object and passing it to the locale prop of ConfigProvider at your application root.
• Access locale data programmatically using the useLocale hook exported from antd, which reads from LocaleContext via components/locale/useLocale.ts.

Frequently Asked Questions

What is the difference between LocaleProvider and ConfigProvider?

LocaleProvider is the legacy API for setting internationalization in Ant Design versions prior to 4.0. In current versions, ConfigProvider in components/config-provider/index.tsx automatically wraps your application with LocaleProvider when you pass a locale prop (lines 36-42). You should always use ConfigProvider for new projects, as it handles both theming and localization in a single component.

Can I extend an existing Ant Design locale instead of creating one from scratch?

Yes. You can import an existing locale from antd/locale/en_US (or any other language) and use the spread operator to override specific properties while keeping the rest. This approach ensures you maintain compatibility with future Ant Design updates for components you haven't customized. For example: const customLocale = { ...enUS, Table: { ...enUS.Table, filterTitle: 'Custom Filter' } };.

How do I handle missing translations in my custom locale?

Ant Design falls back to its built-in English locale (components/locale/en_US.ts) for any properties you omit in your custom locale object. This fallback mechanism is handled automatically by the LocaleProvider when merging your custom object with the default context. However, for complete user experience, you should provide all required fields listed in the Locale interface, especially locale, Pagination, DatePicker, TimePicker, Calendar, global, and Table.

Is useLocale available in all versions of Ant Design?

The useLocale hook was introduced in Ant Design 4.x and is available in all subsequent versions. It is exported from components/locale/index.tsx (line 18) and re-exported from the main antd package entry point. If you are using Ant Design 3.x or earlier, you must use the legacy LocaleProvider API and access locale data through props or context consumers rather than this hook.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}