Skip to content

Commit 6571ab6

Browse files
shijistarshijistar
committed
feat: implement unit tests for plugin-next-internalional
1 parent 2f85f75 commit 6571ab6

File tree

21 files changed

+1205
-243
lines changed

21 files changed

+1205
-243
lines changed

‎packages/plugin-next-international/README.md‎

Lines changed: 137 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -2,94 +2,77 @@
22

33
[English](./README.md) | [中文](./README.zh-CN.md) | [CHANGELOG](./CHANGELOG.md)
44

5-
# @enum-plus/plugin-i18next
5+
# @enum-plus/plugin-next-international
66

7-
[![npm version](https://img.shields.io/npm/v/@enum-plus/plugin-i18next.svg)](https://www.npmjs.com/package/@enum-plus/plugin-i18next)
8-
[![license](https://img.shields.io/npm/l/@enum-plus/plugin-i18next.svg)](https://www.npmjs.com/package/@enum-plus/plugin-i18next)
7+
[![npm version](https://img.shields.io/npm/v/@enum-plus/plugin-next-international.svg)](https://www.npmjs.com/package/@enum-plus/plugin-next-international)
8+
[![license](https://img.shields.io/npm/l/@enum-plus/plugin-next-international.svg)](https://www.npmjs.com/package/@enum-plus/plugin-next-international)
99

10-
> Integrates with [i18next](https://www.i18next.com) to enable internationalization of enum labels.
10+
> Integrates [next-international](https://next-international.vercel.app) to achieve internationalization of enum labels
1111
1212
## Introduction
1313

14-
`@enum-plus/plugin-i18next` is a plugin for [enum-plus](https://github.com/shijistar/enum-plus) that automatically integrates with [i18next](https://www.i18next.com/) to achieve internationalization of enum labels. It allows you to use i18next localization keys in your enum definitions, which are dynamically displayed as translated text for the current language.
14+
`@enum-plus/plugin-next-international` is a plugin for [enum-plus](https://github.com/shijistar/enum-plus) that automatically integrates with [next-international](https://next-international.vercel.app) to achieve internationalization of enum labels. It allows you to use next-international localization keys in your enum definitions, which are dynamically displayed as translated text for the current language.
1515

16-
> This plugin does not support automatic UI updates after switching languages, which requires integration with front-end frameworks (such as React, Vue, etc.). Please consider using the [@enum-plus/plugin-react](https://github.com/shijistar/enum-plus/tree/main/packages/plugin-react) or [@enum-plus/plugin-i18next-vue](https://github.com/shijistar/enum-plus/tree/main/packages/plugin-i18next-vue) plugins.
16+
> ⚠️ Please note that this plugin only supports client-side environments and does not support server-side rendering.
1717
1818
## Installation
1919

2020
```bash
21-
npm install @enum-plus/plugin-i18next
21+
npm install @enum-plus/plugin-next-international
2222
```
2323

24-
Import the `@enum-plus/plugin-i18next` plugin and install it in the entry file of your application:
24+
Import the `@enum-plus/plugin-next-international` plugin and install it in the entry file of your application:
2525

2626
```js
27-
import i18nPlugin from '@enum-plus/plugin-i18next';
27+
import { clientI18nPlugin } from '@enum-plus/plugin-next-international';
2828
import { Enum } from 'enum-plus';
2929

30-
Enum.install(i18nPlugin);
30+
Enum.install(clientI18nPlugin);
3131
```
3232

3333
## Plugin Options
3434

3535
When installing the plugin, you can pass a configuration object to set global options for the plugin:
3636

3737
```ts
38-
Enum.install(i18nextPlugin, {
38+
Enum.install(clientI18nPlugin, {
3939
localize: {
40-
// Set the i18next instance, defaults to the global i18next instance if necessary
41-
instance: i18next,
42-
// Options to pass to the i18next.t method
43-
tOptions: {
44-
// Set the namespace
45-
ns: 'my-namespace',
46-
// Set the default value for the return value
47-
defaultValue: '-',
48-
// Other options supported by the i18next.t method
49-
// Please refer to https://www.i18next.com/translation-function/essentials#overview-options
50-
},
40+
/**
41+
* Localized output result, default is 'text'
42+
*
43+
* - `text`: Returns a plain text string that does not change with language
44+
* - `component`: Returns a React component instance that automatically updates the displayed
45+
* content when the language is switched
46+
*/
47+
mode: 'text',
5148
},
52-
});
53-
```
54-
55-
`tOptions` also supports a function form to dynamically generate options, and can even directly return the final translated text.
56-
57-
```ts
58-
// Use function form to dynamically generate tOptions
59-
Enum.install(i18nextPlugin, {
60-
localize: {
61-
tOptions: (key) => {
62-
if (key === 'week.sunday') {
63-
return { ns: 'my-namespace' };
64-
}
65-
return { ns: 'translation' }; // Default namespace
66-
},
67-
},
68-
});
69-
```
70-
71-
You can even return a string directly in `tOptions` as the final translated text to have full control over the behavior of the `localize` method.
72-
73-
```ts
74-
Enum.install(i18nextPlugin, {
75-
localize: {
76-
tOptions: (key) => {
77-
if (key === 'week.sunday') {
78-
return 'Sunday'; // Directly return the translated text
79-
}
80-
return instance.t(key); // Return the default translation in other cases
81-
},
49+
isMatch: {
50+
defaultSearchField: 'label', // Default search field for isMatch method, default is 'label'
8251
},
8352
});
8453
```
8554

8655
## Basic Usage
8756

57+
### Enum Labels Respond to Language Changes
58+
8859
You can achieve internationalization of enum labels by using localization keys in the enum definition.
8960

61+
- **Using Text Mode (Default)**
62+
9063
```js
64+
import { clientI18nPlugin } from '@enum-plus/plugin-next-international';
9165
import { Enum } from 'enum-plus';
66+
import { useChangeLocale } from './path/to/client';
67+
68+
// index.js
69+
Enum.install(clientI18nPlugin, {
70+
localize: {
71+
mode: 'text',
72+
},
73+
});
9274

75+
// SomeComponent.js
9376
const WeekEnum = Enum(
9477
{
9578
Monday: { value: 1, label: 'week.monday' },
@@ -106,3 +89,105 @@ i18next.changeLanguage('zh-CN');
10689
WeekEnum.label(1); // 星期一
10790
WeekEnum.name; // 周
10891
```
92+
93+
- **Using Component Mode**
94+
95+
```js
96+
import { clientI18nPlugin } from '@enum-plus/plugin-next-international';
97+
import { Enum } from 'enum-plus';
98+
import { useChangeLocale } from './path/to/client';
99+
100+
// index.js
101+
Enum.install(clientI18nPlugin, {
102+
localize: {
103+
mode: 'component',
104+
},
105+
});
106+
107+
// SomeComponent.js
108+
const changeLanguage = useChangeLocale();
109+
const WeekEnum = Enum(
110+
{
111+
Monday: { value: 1, label: 'week.monday' },
112+
Tuesday: { value: 2, label: 'week.tuesday' },
113+
},
114+
{
115+
name: 'weekDays.name', // Optional enum type name
116+
}
117+
);
118+
119+
WeekEnum.label(1); // A ReactElement, displaying "Monday", that updates on language change
120+
WeekEnum.name; // A ReactElement, displaying "Week", that updates on language change
121+
122+
changeLanguage('zh-CN');
123+
WeekEnum.label(1); // A ReactElement, displaying "星期一", that updates on language change
124+
WeekEnum.name; // A ReactElement, displaying "周", that updates on language change
125+
```
126+
127+
From the generated enum UI components, when the language changes, the labels will automatically update:
128+
129+
```tsx
130+
import { Button, Select } from 'antd';
131+
import { useChangeLocale } from './path/to/client';
132+
133+
const changeLanguage = useChangeLocale();
134+
135+
<Select options={WeekEnum.items} defaultValue={WeekEnum.Monday} />;
136+
// Selected and displayed: Monday
137+
138+
<Button onClick={() => changeLanguage('zh-CN')}>切换到中文</Button>;
139+
140+
// When the button is clicked, the Select component will automatically update to display "星期一"
141+
```
142+
143+
### Dropdown Search
144+
145+
In `component` mode, since the enum's `label` has become a component instance rather than a string type, it cannot be directly used for text search. You can use the `isMatch` or `isMatchCaseSensitive` methods to filter enum items.
146+
147+
```tsx
148+
import { Select } from 'antd';
149+
150+
<Select options={WeekEnum.items} filterOption={WeekEnum.isMatch} />;
151+
```
152+
153+
## Other API
154+
155+
### isMatch
156+
157+
The `isMatch` method is used to filter enum items based on a search text, supporting fuzzy matching of the enum item's `label`, ignoring case sensitivity.
158+
159+
<sup>**_[Method]_**</sup> &nbsp; `isMatch(searchText: string, item: EnumItem): boolean`
160+
161+
- Dropdown Search
162+
163+
```tsx
164+
import { Select } from 'antd';
165+
166+
<Select options={WeekEnum.items} filterOption={WeekEnum.isMatch} />;
167+
```
168+
169+
- Regular filtering
170+
171+
```ts
172+
const results = WeekEnum.filter((item) => WeekEnum.isMatch('mon', item)); // Filters enum items whose label contains 'mon', ignoring case
173+
```
174+
175+
### isMatchCaseSensitive
176+
177+
The `isMatchCaseSensitive` method is used to filter enum items based on a search text, supporting fuzzy matching of the enum item's `label`, with case sensitivity.
178+
179+
<sup>**_[Method]_**</sup> &nbsp; `isMatchCaseSensitive(searchText: string, item: EnumItem): boolean`
180+
181+
- Dropdown Search
182+
183+
```tsx
184+
import { Select } from 'antd';
185+
186+
<Select options={WeekEnum.items} filterOption={WeekEnum.isMatchCaseSensitive} />;
187+
```
188+
189+
- Regular filtering
190+
191+
```ts
192+
const results = WeekEnum.filter((item) => WeekEnum.isMatchCaseSensitive('Mon', item)); // Filters enum items whose label contains 'Mon', with case sensitivity
193+
```

0 commit comments

Comments
 (0)