JSPM

English | 中文

Like native enum, but much better!

⬇️  Introduction | Features | Installation | Enum Initialization | API | Usage | Naming Conventions | Localization | Extensibility | Q&A  ⬇️

Introduction

enum-plus is an enhanced enum library that is fully compatible with the native enum and extends it with powerful features such as display text, localization, UI control binding, enum members traversal, and more useful extension methods. This lightweight, zero-dependency, TypeScript library works with any front-end framework.

With the extended display text capability, enum members can be used to generate dropdowns, checkboxes, and other UI controls with a single line of code. By using the extension methods of the enum, you can easily traverse the array of enum members, get the display text of a certain enum value, determine whether a value exists, etc. The display text of the enum member supports localization, which can return the corresponding text according to the current language environment, making the display text of the enum member more flexible and more in line with user needs.

What other exciting features are there? Please continue to explore! Or you can check out this usage video first.

Features

• Full compatibility with native enum behavior
• Support for multiple data types including number and string
• Enhanced enum members with customizable display text
• Built-in localization capabilities that integrate with any i18n library
• Streamlined conversion from enum values to human-readable display text
• Extensible design allowing unlimited custom fields on enum members
• Seamless integration with any UI libraries like Ant Design, ElementPlus, Material-UI, in a single line of code
• Complete Node.js compatibility with SSR support
• Zero dependencies - pure JavaScript implementation usable in any front-end framework
• First-class TypeScript support with comprehensive type inference
• Lightweight (only 2KB+ gzipped)

Installation

Install using npm:

npm install enum-plus

Install using pnpm:

pnpm add enum-plus

Install using bun:

bun add enum-plus

Or using yarn:

yarn add enum-plus

Enum Initialization

This section shows the various ways to initialize enums using the Enum function. Understanding these different initialization formats allows you to choose the most convenient approach for your specific use case.

1. Simple key-value Format

The simplest format is a direct mapping of keys to values. This is similar to the native enum format.

import { Enum } from 'enum-plus';

const Week = Enum({
  Sunday: 0,
  Monday: 1,
} as const);

Week.Monday; // 1

The as const type assertion is used to ensure that the enum values are treated as literal types, otherwise they will be treated as number types. If you are using JavaScript, please remove the as const.

2. Simple key-value with String Values

This format is similar to the first one, allowing you to use string values.

import { Enum } from 'enum-plus';

const Week = Enum({
  Sunday: 'Sun',
  Monday: 'Mon',
} as const);

Week.Monday; // 'Mon'

3. Standard Format (Recommended)

The standard format includes both a value and a label for each enum member. This is the most commonly used format and is recommended for most cases. This format allows you to specify a display text for each enum member, which can be used in UI components.

import { Enum } from 'enum-plus';

const Week = Enum({
  Sunday: { value: 0, label: 'I love Sunday' },
  Monday: { value: 1, label: 'I hate Monday' },
} as const);

Week.Sunday; // 0
Week.label(0); // I love Sunday

4. Label-Only Format

This is useful when you want to use the key as the value.

import { Enum } from 'enum-plus';

const Week = Enum({
  Sunday: { label: 'I love Sunday' },
  Monday: { label: 'I hate Monday' },
} as const);

Week.Sunday; // 'Sunday'
Week.label('Sunday'); // I love Sunday

5. Array Format

The array format is useful when you need to create enums dynamically, such as from API data. This allows for flexibility in custom field mapping to adapt to different data structures.

import { Enum } from 'enum-plus';

const petTypes = await getPetsData();
// [   { value: 1, key: 'dog', label: 'Dog' },
//     { value: 2, key: 'cat', label: 'Cat' },
//     { value: 3, key: 'rabbit', label: 'Rabbit' }   ];
const PetTypes = Enum(petTypes);

6. Native Enum Format

You can also create from native enums. It benefits from the native enum's auto-incrementing behavior.

import { Enum } from 'enum-plus';

enum init {
  Sunday = 0,
  Monday,
  Tuesday,
  Wednesday,
  Thursday,
  Friday,
  Saturday,
}
const Week = Enum(init);

Week.Sunday; // 0
Week.Monday; // 1
Week.Saturday; // 6
Week.label('Sunday'); // Sunday

API

💎   Picks an enum value

Enum.XXX

Works like native enum, allowing you to access enum values directly.

Week.Sunday; // 0
Week.Monday; // 1

💎   items

{ value, label, key, raw }[]

Returns a read-only array of all enum members. The array structure conforms to Ant Design component specifications, which makes it possible to generate dropdown menus, checkboxes, and other UI controls with just one line of code. For more details, please refer to the usage examples below.

💎   keys

string[]

Returns a read-only array of all enum member key(s)

💎   label

^[Function]   label(keyOrValue?: string | number): string | undefined

Gets the display text of an enum member based on a certain value or key. If localization has been set up, the localized text will be returned.

Week.label(1); // Monday
Week.label('Monday'); // Monday, here is label, not key
Week.label('Monday'); // 星期日, or show localized text if localization is set up

💎   key

^[Function]   key(value?: string | number): string | undefined

Get the key of an enum member based on the enum value, if the key is not found, return undefined.

Week.key(1); // Monday (here is key, not label)

💎   has

^[Function]   has(keyOrValue?: string | number): boolean

Determine whether a certain enum member (value or key) exists.

Week.has(1); // true
Week.has('Sunday'); // true
Week.has(9); // false
Week.has('Birthday'); // false

💎   toSelect

^[Function]   toSelect(config?: OptionsConfig): {value, label}[]

toSelect is similar to items, both return an array of all enum members. The difference is that the elements returned by toSelect only contain the label and value fields, no other extra fields. At the same time, the toSelect method allows inserting a default element at the beginning of the array, which is generally used for the default option (which means all, none, or unlimited, etc) of select control. Of course, you can customize this default option.

💎   toMenu

^[Function]   toMenu(): { key, label }[]

Returns an array of all enum members that conforms to Ant Design specifications. It's used to generate the Menu, Dropdown controls, in a single line of code.

import { Menu } from 'antd';

<Menu items={Week.toMenu()} />;

The data format is:

[
  { key: 0, label: 'Sunday' },
  { key: 1, label: 'Monday' },
];

💎   toFilter

^[Function]   toFilter(): { text, value }[]

Returns an array of enum members that can pass directly to the Ant Design Table component as filters property of a column. This is used to add a dropdown filter box in the table header to filter table data.

The data format is:

[
  { text: 'Sunday', value: 0 },
  { text: 'Monday', value: 1 },
];

💎   toValueMap

^[Function]   toValueMap(): Record<V, { text: string }>

Returns a value-to-text mapping object, which maps enum values to their display text, conforming to the Ant Design Pro specification. This is used to generate data sources for ProFormField series controls, and ProTable.

The data format is:

{
  0: { text: 'Sunday' },
  1: { text: 'Monday' },
}

💎   raw

^{[Override^1]}   raw(): Record<K, T[K]>
^{[Override^2]}   raw(keyOrValue: V | K): T[K]

The raw method is used to return the original initialization object of the enum collection, which is the object used to create the enum.

The second overload method is used to return the original initialization object of a single enum member.

The main purpose of the raw method is to get the extended custom fields of the enum members. Unlimited number of custom fields are allowed.

const Week = Enum({
  Sunday: { value: 0, label: 'Sunday', happy: true },
  Monday: { value: 1, label: 'Monday', happy: false },
} as const);

Week.raw(0).happy; // true
Week.raw(0); // { value: 0, label: 'Sunday', happy: true }
Week.raw('Monday'); // { value: 1, label: 'Monday', happy: false }
Week.raw(); // { Sunday: { value: 0, label: 'Sunday', happy: true }, Monday: { value: 1, label: 'Monday', happy: false } }

⚡️   valueType   ^{[TypeScript ONLY]}

value1 | value2 | ...

In TypeScript, provides a union type containing all enum values, enabling precise type constraints for variables and component properties. This replaces broad primitive types like number or string with exact value sets, preventing invalid assignments while enhancing both code readability and compile-time type safety.

type WeekValues = typeof Week.valueType; // 0 | 1

const weekValue: typeof Week.valueType = 1; // ✅ Type correct, 1 is a valid week enum value
const weeks: (typeof Week.valueType)[] = [0, 1]; // ✅ Type correct, 0 and 1 are valid week enum values
const badWeekValue: typeof Week.valueType = 8; // ❌ Type error, 8 is not a valid week enum value
const badWeeks: (typeof Week.valueType)[] = [0, 8]; // ❌ Type error, 8 is not a valid week enum value

Note: This is a TypeScript type only and cannot be called at runtime. Calling it at runtime will throw an exception.

⚡️   keyType   ^{[TypeScript ONLY]}

key1 | key2 | ...

Similar to valueType, provides an union type of all enum key(s)

type WeekKeys = typeof Week.keyType; // 'Sunday' | 'Monday'

const weekKey: typeof Week.keyType = 'Monday';
const weekKeys: (typeof Week.keyType)[] = ['Sunday', 'Monday'];

Note: This is a TypeScript type only and cannot be called at runtime. Calling it at runtime will throw an exception.

⚡️   rawType   ^{[TypeScript ONLY]}

{ value: V, label: string, [...] }

Provides a type of the original initialization object of the Enum collection.

Note: This is a TypeScript type only and cannot be called at runtime. Calling it at runtime will throw an exception.

Usage

Picks enum values, consistent with native enums

const Week = Enum({
  Sunday: { value: 0, label: 'Sunday' },
  Monday: { value: 1, label: 'Monday' },
} as const);

Week.Sunday; // 0
Week.Monday; // 1

Supports JSDoc comments on enum members

Supports inline documentation through JSDoc, allowing developers to view detailed comments by simply hovering over enum values in the editor.

const Week = Enum({
  /** Represents Sunday */
  Sunday: { value: 0, label: 'Sunday' },
  /** Represents Monday */
  Monday: { value: 1, label: 'Monday' },
} as const);

Week.Monday; // Hover over Monday

You can see that this hover functionality reveals both documentation and enum values simultaneously, without leaving your current position in the code.

Gets a read-only enum members array

Week.items; // The output is:
// [
//  { value: 0, label: 'Sunday', key: 'Sunday', raw: { value: 0, label: 'Sunday' } },
//  { value: 1, label: 'Monday', key: 'Monday', raw: { value: 1, label: 'Monday' } },
// ]

Gets the first enum value

Week.items[0].value; // 0

Checks if a value is a valid enum value

Week.has(1); // true
Week.items.some((item) => item.value === 1); // true
1 instanceof Week; // true

instanceof operator

1 instanceof Week; // true
'1' instanceof Week; // true
'Monday' instanceof Week; // true

Supports traversing enum members array

Week.items.length; // 2
Week.items.map((item) => item.value); // [0, 1], ✅ Traversable
Week.items.forEach((item) => {}); // ✅ Traversable
for (const item of Week.items) {
  // ✅ Traversable
}
Week.items.push({ value: 2, label: 'Tuesday' }); // ❌ Not allowed, read-only
Week.items.splice(0, 1); // ❌ Not allowed, read-only
Week.items[0].label = 'foo'; // ❌ Not allowed, read-only

Gets enum display text by value (or key)

Week.label(1); // Monday, here is label, not key
Week.label(Week.Monday); // Monday, here is label, not key
Week.label('Monday'); // Monday, get display text by key

Gets enum key by value

Week.key(1); // 'Monday'
Week.key(Week.Monday); // 'Monday'
Week.key(9); // undefined, because it does not exist

Extends custom fields with unlimited numbers

const Week = Enum({
  Sunday: { value: 0, label: 'Sunday', active: true, disabled: false },
  Monday: { value: 1, label: 'Monday', active: false, disabled: true },
} as const);

Week.raw(0).active; // true
Week.raw(Week.Sunday).active; // true
Week.raw('Sunday').active; // true

Converts to UI controls

• Enum.items can be consumed as control data sources (using Select as an example).

  React-based UI libraries

  Ant Design | Arco Design Select

  import { Select } from 'antd';
  
  <Select options={Week.items} />;

  Material-UI Select

  import { MenuItem, Select } from '@mui/material';
  
  <Select>
    {Week.items.map((item) => (
      <MenuItem key={item.value} value={item.value}>
        {item.label}
      </MenuItem>
    ))}
  </Select>;

  Kendo UI Select

  import { DropDownList } from '@progress/kendo-react-dropdowns';
  
  <DropDownList data={Week.items} textField="label" dataItemKey="value" />;

  Vue-based UI libraries

  ElementPlus Select

  <el-select>
    <el-option v-for="item in Week.items" v-bind="item" />
  </el-select>

  Ant Design Vue | Arc Design Select

  <a-select :options="Week.items" />

  Vuetify Select

  <v-select :items="Week.items" item-title="label" />

  Angular-based UI libraries

  Angular Material Select

  <mat-select>
    <mat-option *ngFor="let item of Week.items" [value]="item.value">{{ item.label }}</mat-option>
  </mat-select>

  NG-ZORRO Select

  <nz-select>
    <nz-option *ngFor="let item of Week.items" [nzValue]="item.value">{{ item.label }}</nz-option>
  </nz-select>

• The toSelect method is similar to items, allows adding a default option at the beginning of the array. The default option can be a boolean value or a custom object.

  • If set to a boolean value, the default option is { value: '', label: 'All' }, the display name only supports English. If you need localization, please parse and process the built-in resource key enum-plus.options.all in the localization method. For more details about localization, please refer to the Localization section.
  • If set to an object, you can customize the value and display text of the default option, and the display text will automatically support localization.

  <Select options={Week.toSelect({ firstOption: true })} />
  // [
  //  { value: '', label: 'All' },
  //  { value: 0, label: 'Sunday' },
  //  { value: 1, label: 'Monday' }
  // ]
  
  // Add custom option at the top
  <Select options={Week.toSelect({ firstOption: { value: 0, label: 'Unlimited' } })} />

• toMenu method is used to generate data sources for Ant Design Menu, Dropdown components.

import { Menu } from 'antd';

<Menu items={Week.toMenu()} />;

• toFilter method is used to add a dropdown filter box in the Ant Design Table header to filter table data.

import { Table } from 'antd';

const columns = [
  {
    title: 'week',
    dataIndex: 'week',
    filters: Week.toFilter(),
  },
];
// Add column filter at table header
<Table columns={columns} />;

• toValueMap method is used to generate data sources for binding the Ant Design Pro ProFormField series controls, and ProTable.

import { ProFormCheckbox, ProFormRadio, ProFormSelect, ProFormTreeSelect, ProTable } from '@ant-design/pro-components';

<ProFormSelect valueEnum={Week.toValueMap()} />; // Select
<ProFormCheckbox valueEnum={Week.toValueMap()} />; // Checkbox
<ProFormRadio.Group valueEnum={Week.toValueMap()} />; // Radio
<ProFormTreeSelect valueEnum={Week.toValueMap()} />; // TreeSelect
<ProTable columns={[{ dataIndex: 'week', valueEnum: Week.toValueMap() }]} />; // ProTable

Merge two enums (or extend an enum)

const myWeek = Enum({
  ...Week.raw(),
  Friday: { value: 5, label: 'Friday' },
  Saturday: { value: 6, label: 'Saturday' },
});

Narrowing the number type to enum value sequences   ^{[TypeScript ONLY]}

By leveraging the valueType type constraint, you can narrow variable types from broad primitives like number or string to precise enum value unions. This type narrowing not only prevents invalid assignments at compile time, but also enhances code readability and self-documentation while providing stronger type safety guarantees.

const weekValue: number = 8; // 👎 Any number can be assigned to the week enum, even if it is wrong
const weekName: string = 'Birthday'; // 👎 Any string can be assigned to the week enum, even if it is wrong

const goodWeekValue: typeof Week.valueType = 1; // ✅ Type correct, 1 is a valid week enum value
const goodWeekName: typeof Week.keyType = 'Monday'; // ✅ Type correct, 'Monday' is a valid week enum name

const badWeekValue: typeof Week.valueType = 8; // ❌ Type error, 8 is not a valid week enum value
const badWeekName: typeof Week.keyType = 'Birthday'; // ❌ Type error, 'Birthday' is not a valid week enum name

type FooProps = {
  value?: typeof Week.valueType; // 👍 Component property type constraint, prevent erroneous assignment, and also prompts which values are valid
  names?: (typeof Week.keyType)[]; // 👍 Component property type constraint, prevent erroneous assignment, and also prompts which values are valid
};

Custom field mapping

In 5. Array Format section, we know that you can build an enum from dynamic data from the backend, but it is very likely that the field names of dynamic data are not value, label, key, but other field names. In this case, you can pass in a custom option to map these to other field names.

import { Enum } from 'enum-plus';

const petTypes = await getPetsData();
// [   { id: 1, code: 'dog', name: 'Dog' },
//     { id: 2, code: 'cat', name: 'Cat' },
//     { id: 3, code: 'rabbit', name: 'Rabbit' }   ];
const PetTypes = Enum(petTypes, {
  getValue: 'id',
  getLabel: 'name',
  getKey: 'code', // getKey is optional
});
Week.items; // The output is:
// [   { value: 1, label: 'Dot', key: 'dog' },
//     { value: 2, label: 'Cat', key: 'cat' },
//     { value: 3, label: 'Rabbit', key: 'rabbit' }   ]

getValue, getLabel, getKey can also be a function to handle more complex business logic, for example:

const PetTypes = Enum(petTypes, {
  getValue: (item) => item.id,
  getLabel: (item) => `${item.name} (${item.code})`,
  getKey: (item) => item.code,
});

Handling Name Conflicts?

When working with enums, a common edge case occurs when an enum member's key conflicts with built-in method names. While we typically access enum values through Week.XXX notation, complications arise when these keys overlap with enum methods.

The enum library provides several utility methods like label, key, and toSelect. When an enum member shares a name with these methods, the enum member takes precedence, effectively overriding the utility method. However, this doesn't mean you lose access to those methods - they remain available through the items collection, ensuring all functionality is preserved regardless of naming conflicts. Please refer to the code example below:

const Week = Enum({
  foo: { value: 1 },
  bar: { value: 2 },
  keys: { value: 3 }, // Naming conflict
  label: { value: 4 }, // Naming conflict
} as const);

Week.keys; // 3, enum member has higher priority and will override the method
Week.label; // 4, enum member has higher priority and will override the method
// You can still access these methods through Enum.items 🙂
Week.items.keys; // ['foo', 'bar', 'keys', 'label']
Week.items.label(1); // 'foo'

For an even more extreme edge case where the items property itself conflicts with an enum member name, a solution is still available. In such scenarios, you can access the items array through a Symbol-based alias field that guarantees access regardless of naming conflicts. Consider the following example:

import { ITEMS } from 'enum-plus';

const Week = Enum({
  foo: { value: 1 },
  bar: { value: 2 },
  items: { value: 3 }, // Naming conflict
} as const);

Week.items; // 3, enum member has higher priority and will override items
Week[ITEMS]; // ITEMS is an alias Symbol
// [
//  { value: 1, key: 'foo', label: 'foo' },
//  { value: 2, key: 'bar', label: 'bar' },
//  { value: 3, key: 'items', label: 'items' }
// ]
// Equivalent to the original Week.items 🙂

Naming Convention Best Practices

1. Enum Type Naming: Use PascalCase and append with the Enum suffix (e.g., WeekEnum, ColorEnum).
2. Enum Member Naming: Use PascalCase for enum members(e.g., WeekEnum.Sunday, ColorEnum.Red). This naming style highlights the immutability and static nature of enum members, and ensures they appear at the top in IDE IntelliSense suggestions for easier selection.
3. Semantic Clarity: Ensure enum and member names have clear semantics. Good semantic naming serves as self-documentation, making code intent explicit and reducing cognitive overhead.
4. Single Responsibility Principle: Each enum type should represent a single, cohesive set of related constants. Avoiding overlapping responsibilities between different enum types.
5. Provide JSDoc Comments: Provide JSDoc comments for each enum member and the enum type itself, explaining their purpose and usage. Comprehensive documentation enables IDE hover tooltips and improves code readability and maintainability.
6. Internationalization Architecture: Plan for internationalization from the outset by leveraging the library’s built-in localization features. A well-designed internationalization architecture minimizes future refactoring and facilitates global scalability.

Localization

While enum-plus doesn't include built-in internationalization capabilities, it offers flexible localization through the optional localize parameter. This allows you to implement a custom localization function that transforms enum label values into appropriate translated text based on the current language context. The language state management remains your responsibility, with your localize method determining which localized text to return. For production applications, we strongly recommend leveraging established internationalization libraries such as i18next rather than creating custom solutions.

Below is a simple example for illustration purposes. Note that the first approach is not recommended for production use due to its limited flexibility - it serves only to demonstrate the basic concept.

import { Enum } from 'enum-plus';
import i18next from 'i18next';
import Localize from './Localize';

let lang = 'zh-CN';
const setLang = (l: string) => {
  lang = l;
};

// 👎 Not a good example, just for demonstration - not recommended for production
const sillyLocalize = (content: string) => {
  if (lang === 'zh-CN') {
    switch (content) {
      case 'enum-plus.options.all':
        return '全部';
      case 'week.sunday':
        return '星期日';
      case 'week.monday':
        return '星期一';
      default:
        return content;
    }
  } else {
    switch (content) {
      case 'enum-plus.options.all':
        return 'All';
      case 'week.sunday':
        return 'Sunday';
      case 'week.monday':
        return 'Monday';
      default:
        return content;
    }
  }
};
// 👍 Recommended to use i18next or other internationalization libraries
const i18nLocalize = (content: string | undefined) => i18next.t(content);
// 👍 Or encapsulate it into a basic component
const componentLocalize = (content: string | undefined) => <Localize value={content} />;

const Week = Enum(
  {
    Sunday: { value: 0, label: 'week.sunday' },
    Monday: { value: 1, label: 'week.monday' },
  } as const,
  {
    localize: sillyLocalize,
    // localize: i18nLocalize, // 👍  Recommended to use i18n
    // localize: componentLocalize, // 👍  Recommended to use component
  }
);
setLang('zh-CN');
Week.label(1); // 星期一
setLang('en-US');
Week.label(1); // Monday

For applications with consistent localization needs, the Enum.localize method offers a convenient way to set localization globally rather than configuring each enum individually. When enum-specific localization options are provided during initialization, these will override the global settings.

Enum.localize = i18nLocalize;

Extensibility

While Enum provides a comprehensive set of built-in methods, you can extend its functionality with custom methods using the Enum.extends API. These extensions are globally applied to all enum instances, including those created before the extension was applied, and take effect immediately without requiring any manual setup.

App.ts

Enum.extends({
  toMySelect(this: ReturnType<typeof Enum>) {
    return this.items.map((item) => ({ value: item.value, title: item.label }));
  },
  reversedItems(this: ReturnType<typeof Enum>) {
    return this.items.reverse();
  },
});

Week.toMySelect(); // [{ value: 0, title: 'Sunday' }, { value: 1, title: 'Monday' }]

If you are using TypeScript, you probably need to further extend the enum type declaration to get better type hints. Create or edit a declaration file in your project (e.g., global.d.ts) and extend the global type. This file can be placed in the root directory of the project or any other directory, just make sure TypeScript can find it.

global.d.ts

import type { EnumItemInit } from 'enum-plus';
import type { EnumItemClass } from 'enum-plus/lib/enum-item';

declare global {
  export interface EnumExtension<T, K, V> {
    toMySelect: () => { value: V; title: string }[];
    reversedItems: () => EnumItemClass<EnumItemInit<V>, K, V>[];
  }
}

Please note that you are not required to import types such as EnumItemInit and EnumItemClass, they are only used in this example to provide better type hints.

EnumExtension is a generic interface that accepts three type parameters, which are:

• T: Initialization object of the enum type (e.g., the object passed to Enum())
• K: Key of the enum member (e.g., Sunday, Monday)
• V: Value of the enum members

If you want to provide more friendly type hints in the extension methods, you may need to use these type parameters. However these are all optional, if you don't need them, you can omit them.

Compatibility

• Browser Environments:

  • Modern Bundlers: With bundlers supporting the exports field (Webpack 5+, Vite, Rollup), enum-plus targets ES2020. For broader browser support, transpile to earlier syntax using @babel/preset-env during your build process.

  • Legacy Bundlers: For tools without exports field support (like Webpack 4), enum-plus automatically falls back to the main field entry point, which targets ES2016.

  • Polyfill Strategy: enum-plus ships without polyfills to minimize bundle size. For legacy browser support, incorporate:

    • core-js
    • @babel/preset-env with appropriate useBuiltIns settings
    • Alternative polyfill implementations

• Node.js Compatibility: enum-plus requires a minimum of ES2016 features, compatible with Node.js v7.x and above.

Q&A

1. How to implement internationalization based on i18next?

Please refer to the code example below:

main.tsx

import { createRoot } from 'react-dom/client';
import { Enum } from 'enum-plus';
import i18next from 'i18next';
import App from './App';
import Locale from './components/Locale';
import LocaleProvider from './components/LocaleProvider';
import enUS from './locales/en-US';
import zhCN from './locales/zh-CN';

i18next.init({
  lng: localStorage.getItem('my_lang'),
  fallbackLng: 'en-US',
  supportedLngs: ['en-US', 'zh-CN'],
  resources: {
    'en-US': { translation: enUS },
    'zh-CN': { translation: zhCN },
  },
});
i18next.on('languageChanged', (lang) => {
  localStorage.setItem('my_lang', lang);
});

// 👀 Here is the key code, set globally through Enum.localize method, use Locale component to output localized text
Enum.localize = (key?: string) => <Locale value={key} />;

const root = createRoot(document.getElementById('root'));
root.render(
  <LocaleProvider>
    <App />
  </LocaleProvider>
);

components/LocaleProvider.tsx

import type { FC, ReactNode } from 'react';
import { createContext, useEffect, useState } from 'react';
import i18next from 'i18next';

export const LocaleContext = createContext<{
  lang: string;
  setLang: (lang: string) => void;
}>({});

const LocaleProvider: FC<{ children: ReactNode }> = ({ children }) => {
  const [lang, setLang] = useState(i18next.language);

  useEffect(() => {
    i18next.changeLanguage(lang);
  }, [lang]);
  return <LocaleContext.Provider value={{ lang, setLang }}>{children}</LocaleContext.Provider>;
};
export default LocaleProvider;

components/Locale.tsx

import { useContext } from 'react';
import i18next from 'i18next';
import { LocaleContext } from './LocaleProvider';

export default function Localize({ value }: { value: string }) {
  const { lang } = useContext(LocaleContext);
  return <>{i18next.t(value, { lng: lang })}</>;
}

2. Why does the search function of the antd dropdown not work after localization?

This occurs because Ant Design's dropdown search functionality performs string matching against the label property. When using React components for labels (after localization), the string matching fails since it's comparing against component objects rather than primitive strings.

The solution is to extend an enum with a filterOption method to help the Select component customize the search function, which will allow it to support the search functionality correctly.

You can refer to the code example below:

import { Select } from 'antd';
import { Enum, type EnumItemClass } from 'enum-plus';

Enum.extends({
  filterOption: (search?: string, option?: EnumItemClass<number | string>) => {
    const label = $t(option?.raw?.label ?? '') ?? option?.value;
    return !search || label?.toUpperCase().includes(search.toUpperCase());
  },
});

// <Select options={WeekEnum.items} filterOption={WeekEnum.filterOption} />;

Contributing

If you would like to contribute to this project, please follow the CONTRIBUTING guidelines outlined in the repository. Feel free to submit issues, pull requests, or suggestions for improvements. Your contributions are greatly appreciated!

If you find a security issue, please follow the Security Policy to report it responsibly.

If you find this project useful, please consider giving it a star ⭐️ on GitHub. It helps others discover the project and encourages further development.