feat: support missing key handler (#4414)

Author: czy88840616

packages/i18n/src/config/config.default.ts

@@ -20,4 +20,5 @@ export const i18n: I18nOptions = {
     },
   },
   localsField: 'i18n',
+  missingKeyHandler: message => message,
 };

packages/i18n/src/i18nService.ts

@@ -108,6 +108,12 @@ export class MidwayI18nServiceSingleton {
         );
       }
     }
+
+    // If still no message found, use missingKeyHandler
+    if (!msg && this.i18nConfig.missingKeyHandler) {
+      msg = this.i18nConfig.missingKeyHandler(message, options);
+    }
+
     return msg;
   }
 

packages/i18n/src/interface.ts

@@ -20,6 +20,7 @@ export interface I18nOptions {
   writeCookie: boolean;
   resolver:  RequestResolver | false,
   localsField: string;
+  missingKeyHandler?: (message: string, options?: TranslateOptions) => string;
 }
 
 export const I18N_ATTR_KEY = 'i18n:locale';

packages/i18n/test/index.test.ts

@@ -91,6 +91,92 @@ describe('test/index.test.ts', () => {
     await close(app);
   });
 
+  it('should test missingKeyHandler with default behavior', async () => {
+    const app = await createLightApp(join(__dirname, './fixtures/base-app'), {
+      globalConfig: {
+        i18n: {
+          defaultLocale: 'en_US',
+          localeTable: {
+            en_US: {
+              'hello': 'hello world'
+            }
+          }
+        }
+      }
+    });
+
+    const i18nService = await app.getApplicationContext().getAsync(MidwayI18nService);
+
+    // Test existing key
+    expect(i18nService.translate('hello')).toEqual('hello world');
+
+    // Test missing key with default missingKeyHandler (should return the key itself)
+    expect(i18nService.translate('nonexistent_key')).toEqual('nonexistent_key');
+
+    await close(app);
+  });
+
+  it('should test custom missingKeyHandler', async () => {
+    const app = await createLightApp(join(__dirname, './fixtures/base-app'), {
+      globalConfig: {
+        i18n: {
+          defaultLocale: 'en_US',
+          localeTable: {
+            en_US: {
+              'hello': 'hello world'
+            }
+          },
+          missingKeyHandler: (message, options) => {
+            return `[Missing: ${message}${options?.locale ? ` (${options.locale})` : ''}]`;
+          }
+        }
+      }
+    });
+
+    const i18nService = await app.getApplicationContext().getAsync(MidwayI18nService);
+
+    // Test existing key
+    expect(i18nService.translate('hello')).toEqual('hello world');
+
+    // Test missing key with custom missingKeyHandler
+    expect(i18nService.translate('nonexistent_key')).toEqual('[Missing: nonexistent_key]');
+    expect(i18nService.translate('nonexistent_key', { locale: 'zh_CN' })).toEqual('[Missing: nonexistent_key (zh_CN)]');
+
+    await close(app);
+  });
+
+  it('should test missingKeyHandler with groups', async () => {
+    const app = await createLightApp(join(__dirname, './fixtures/base-app'), {
+      globalConfig: {
+        i18n: {
+          defaultLocale: 'en_US',
+          localeTable: {
+            en_US: {
+              'user': {
+                'hello': 'Hello user'
+              }
+            }
+          },
+          missingKeyHandler: (message, options) => {
+            const group = options?.group || 'default';
+            return `[${group}.${message}]`;
+          }
+        }
+      }
+    });
+
+    const i18nService = await app.getApplicationContext().getAsync(MidwayI18nService);
+
+    // Test existing key in group
+    expect(i18nService.translate('hello', { group: 'user' })).toEqual('Hello user');
+
+    // Test missing key in group
+    expect(i18nService.translate('goodbye', { group: 'user' })).toEqual('[user.goodbye]');
+    expect(i18nService.translate('goodbye')).toEqual('[default.goodbye]');
+
+    await close(app);
+  });
+
   it('should test fallbacks', async () => {
     const app = await createLightApp(join(__dirname, './fixtures/base-app'), {
       globalConfig: {

site/docs/extensions/i18n.md

@@ -491,6 +491,8 @@ export default {
       },
     },
     localsField: 'i18n',
+    // 缺失翻译键的处理函数，默认返回原始键名
+    missingKeyHandler: (message, options) => message,
   }
 }
 ```
@@ -554,7 +556,43 @@ export default {
 ```
 
 
+### 缺失翻译键处理
 
+当翻译键在所有语言文件中都找不到时，i18n 组件会调用 `missingKeyHandler` 函数来处理这种情况。
+
+默认情况下，当找不到翻译时，会返回原始的键名：
+
+```typescript
+// 默认的 missingKeyHandler
+missingKeyHandler: (message, options) => message
+```
+
+例如：
+```typescript
+// 假设 "unknown_key" 在任何语言文件中都不存在
+this.i18nService.translate('unknown_key');
+// 返回: "unknown_key"
+```
+
+你可以自定义缺失键的处理方式，比如添加特殊标记、记录日志等：
+
+```typescript
+// src/config/config.default.ts
+export default {
+  i18n: {
+    missingKeyHandler: (message, options) => {
+      // 记录缺失的翻译键
+      console.warn(`Missing translation: ${message}`, options);
+
+      // 根据不同的组返回不同的格式
+      const group = options?.group || 'default';
+      const locale = options?.locale || 'default';
+
+      return `[${group}:${locale}:${message}]`;
+    }
+  }
+}
+```
 
 
 ## 常用语言

site/i18n/en/docusaurus-plugin-content-docs/current/extensions/i18n.md

@@ -493,6 +493,48 @@ export default {
       },
     },
     localsField: 'i18n',
+    // Handler for missing translation keys; returns original key by default
+    missingKeyHandler: (message, options) => message,
+  }
+}
+```
+
+
+
+### Missing translation key handling
+
+When a translation key cannot be found in any locale files, the i18n component calls the `missingKeyHandler` function to handle it.
+
+By default, when a translation is missing, the original key is returned:
+
+```typescript
+// Default missingKeyHandler
+missingKeyHandler: (message, options) => message
+```
+
+For example:
+```typescript
+// Suppose "unknown_key" does not exist in any locale files
+this.i18nService.translate('unknown_key');
+// Returns: "unknown_key"
+```
+
+You can customize how missing keys are handled, such as adding special markers or logging:
+
+```typescript
+// src/config/config.default.ts
+export default {
+  i18n: {
+    missingKeyHandler: (message, options) => {
+      // Log the missing translation key
+      console.warn(`Missing translation: ${message}`, options);
+
+      // Return different formats based on group and locale
+      const group = options?.group || 'default';
+      const locale = options?.locale || 'default';
+
+      return `[${group}:${locale}:${message}]`;
+    }
   }
 }
 ```