feat(hooks): expose extraction lifecycle hooks

Author: luhc228

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.2.0
+
+### Features
+
+- Add public compilation hooks:
+  - `afterExtract` for consuming extracted translations after key extraction
+  - `renderExtractedTranslations` for customizing or skipping JS asset injection
+- Export `getI18nextExtractorWebpackPluginHooks`, `AfterExtractPayload`, and `RenderExtractedTranslationsPayload` for plugin consumers
+
 ## 0.1.4
 
 ### Features

README.md

@@ -88,6 +88,148 @@ import { i18n } from './i18n';
 console.log(i18n.t('hello'));
 ```
 
+## Hooks
+
+`rsbuild-plugin-i18next-extractor` now exposes compilation hooks so other build-time plugins can consume extracted translations or customize how the extracted payload is written back to JS assets.
+
+Exported APIs:
+
+- `getI18nextExtractorWebpackPluginHooks(compilation)`
+- `AfterExtractPayload`
+- `RenderExtractedTranslationsPayload`
+
+### `afterExtract`
+
+Called after translation keys have been extracted and locale payloads have been assembled for an entry.
+
+This hook is useful when you want to:
+
+- store extracted translations for a later build step
+- inspect extracted keys for debugging or reporting
+- feed extracted translations into another plugin
+
+Payload shape:
+
+```ts
+type AfterExtractPayload = {
+  entryName: string;
+  locales: string[];
+  files: string[];
+  extractedKeysByLocale: Record<string, string[]>;
+  extractedTranslationsByLocale: Record<string, Record<string, string>>;
+};
+```
+
+### `renderExtractedTranslations`
+
+Called before extracted translations are prepended back into JS assets.
+
+The default behavior is still:
+
+```ts
+const __I18N_EN_EXTRACTED_TRANSLATIONS__ = { ... };
+```
+
+This hook is useful when you want to:
+
+- customize the injected JS code
+- skip JS injection for some or all locales
+- redirect the extracted payload to another artifact pipeline
+
+Payload shape:
+
+```ts
+type RenderExtractedTranslationsPayload = {
+  entryName: string;
+  locale: string;
+  variableName: string;
+  extractedKeys: string[];
+  extractedTranslations: Record<string, string>;
+  targetAssetNames: string[];
+  code: string;
+  skip?: boolean;
+};
+```
+
+### Hook Example
+
+```ts
+import {
+  defineConfig,
+  type RsbuildPlugin,
+  type Rspack,
+} from '@rsbuild/core';
+import {
+  getI18nextExtractorWebpackPluginHooks,
+  pluginI18nextExtractor,
+} from 'rsbuild-plugin-i18next-extractor';
+
+function pluginObserveI18nExtraction(): RsbuildPlugin {
+  return {
+    name: 'example:observe-i18n-extraction',
+    setup(api) {
+      api.modifyBundlerChain((chain) => {
+        chain
+          .plugin('example:observe-i18n-extraction')
+          .use(
+            class ObserveI18nExtractionPlugin {
+              apply(compiler: Rspack.Compiler) {
+                compiler.hooks.compilation.tap(
+                  'example:observe-i18n-extraction',
+                  (compilation) => {
+                    const hooks =
+                      getI18nextExtractorWebpackPluginHooks(compilation);
+
+                    hooks.afterExtract.tapPromise(
+                      'example:observe-i18n-extraction',
+                      async (payload) => {
+                        console.log(payload.entryName);
+                        console.log(payload.extractedTranslationsByLocale);
+                        return payload;
+                      },
+                    );
+
+                    hooks.renderExtractedTranslations.tapPromise(
+                      'example:observe-i18n-extraction',
+                      async (payload) => {
+                        if (payload.locale === 'zh-CN') {
+                          return {
+                            ...payload,
+                            skip: true,
+                            code: '',
+                          };
+                        }
+
+                        return payload;
+                      },
+                    );
+                  },
+                );
+              }
+            },
+          );
+      });
+    },
+  };
+}
+
+export default defineConfig({
+  plugins: [
+    pluginI18nextExtractor({
+      localesDir: './locales',
+    }),
+    pluginObserveI18nExtraction(),
+  ],
+});
+```
+
+### Hook Semantics
+
+- `afterExtract` is a waterfall hook and should return the payload it wants later consumers to receive.
+- `renderExtractedTranslations` is also a waterfall hook and should return the payload it wants the default emitter to use.
+- Setting `skip: true` or returning an empty `code` string prevents that locale payload from being injected into JS assets.
+- `targetAssetNames` contains all synchronous and async JS assets that would otherwise receive the injected definitions for the current entry.
+
 ## Options
 
 ### `localesDir`

package.json

@@ -1,6 +1,6 @@
 {
   "name": "rsbuild-plugin-i18next-extractor",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "A Rsbuild plugin for extracting i18n translations using i18next-cli",
   "keywords": [
     "rsbuild",

src/I18nextExtractorWebpackPlugin.ts

@@ -2,6 +2,7 @@ import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { createFilter } from '@rollup/pluginutils';
 import type { Rspack } from '@rsbuild/core';
+import { getI18nextExtractorWebpackPluginHooks } from './hooks.js';
 import type { PluginI18nextExtractorOptions } from './options.js';
 import {
   getLocalesFromDirectory,
@@ -37,6 +38,8 @@ export class I18nextExtractorWebpackPlugin {
     });
 
     compiler.hooks.compilation.tap(this.constructor.name, (compilation) => {
+      getI18nextExtractorWebpackPluginHooks(compilation);
+
       const locales = getLocalesFromDirectory(
         compiler.context,
         this.options.localesDir,
@@ -76,6 +79,10 @@ export class I18nextExtractorWebpackPlugin {
                   .map((file) => compilation.getAsset(file))
                   .filter((file) => !!file);
 
+                const targetAssetNames = [...jsFiles, ...asyncJsFiles].map(
+                  (asset) => asset.name,
+                );
+
                 // Collect all the modules belong to current entry
                 const entryModules = new Set<string>();
                 for (const chunk of entrypoint.chunks) {
@@ -123,9 +130,12 @@ export class I18nextExtractorWebpackPlugin {
                   this.options.i18nextToolkitConfig,
                 );
 
-                // Generate i18n resource definitions for each locale
-                const i18nTranslationDefinitions: string[] = [];
+                const extractedTranslationsByLocale: Record<
+                  string,
+                  Record<string, string>
+                > = {};
 
+                // Generate i18n resource definitions for each locale
                 for (const locale of locales) {
                   const localeFilePath = resolveLocaleFilePath(
                     this.options.localesDir,
@@ -156,6 +166,8 @@ export class I18nextExtractorWebpackPlugin {
                     },
                   );
 
+                  extractedTranslationsByLocale[locale] = extractedTranslations;
+
                   // Write debug output to node_modules when DEBUG is enabled
                   if (DEBUG) {
                     try {
@@ -195,10 +207,45 @@ export class I18nextExtractorWebpackPlugin {
                       );
                     }
                   }
+                }
 
-                  i18nTranslationDefinitions.push(
-                    `const ${getLocaleVariableName(locale)} = ${JSON.stringify(extractedTranslations)};`,
-                  );
+                const hooks =
+                  getI18nextExtractorWebpackPluginHooks(compilation);
+                const afterExtractPayload = await hooks.afterExtract.promise({
+                  entryName,
+                  locales,
+                  files,
+                  extractedKeysByLocale: extractedTranslationKeys,
+                  extractedTranslationsByLocale,
+                });
+
+                const i18nTranslationDefinitions: string[] = [];
+                for (const locale of afterExtractPayload.locales) {
+                  const variableName = getLocaleVariableName(locale);
+                  const renderedPayload =
+                    await hooks.renderExtractedTranslations.promise({
+                      entryName: afterExtractPayload.entryName,
+                      locale,
+                      variableName,
+                      extractedKeys:
+                        afterExtractPayload.extractedKeysByLocale[locale] ?? [],
+                      extractedTranslations:
+                        afterExtractPayload.extractedTranslationsByLocale[
+                          locale
+                        ] ?? {},
+                      targetAssetNames,
+                      code: `const ${variableName} = ${JSON.stringify(
+                        afterExtractPayload.extractedTranslationsByLocale[
+                          locale
+                        ] ?? {},
+                      )};`,
+                    });
+
+                  if (renderedPayload.skip || !renderedPayload.code) {
+                    continue;
+                  }
+
+                  i18nTranslationDefinitions.push(renderedPayload.code);
                 }
 
                 // Replace the placeholder with actual extracted translations

src/hooks.ts

@@ -0,0 +1,52 @@
+import type { Rspack } from '@rsbuild/core';
+import { AsyncSeriesWaterfallHook } from '@rspack/lite-tapable';
+
+export interface AfterExtractPayload {
+  entryName: string;
+  locales: string[];
+  files: string[];
+  extractedKeysByLocale: Record<string, string[]>;
+  extractedTranslationsByLocale: Record<string, Record<string, string>>;
+}
+
+export interface RenderExtractedTranslationsPayload {
+  entryName: string;
+  locale: string;
+  variableName: string;
+  extractedKeys: string[];
+  extractedTranslations: Record<string, string>;
+  targetAssetNames: string[];
+  code: string;
+  skip?: boolean;
+}
+
+export interface I18nextExtractorWebpackPluginHooks {
+  afterExtract: AsyncSeriesWaterfallHook<AfterExtractPayload>;
+  renderExtractedTranslations: AsyncSeriesWaterfallHook<RenderExtractedTranslationsPayload>;
+}
+
+const compilationHooksMap = new WeakMap<
+  Rspack.Compilation,
+  I18nextExtractorWebpackPluginHooks
+>();
+
+export function getI18nextExtractorWebpackPluginHooks(
+  compilation: Rspack.Compilation,
+): I18nextExtractorWebpackPluginHooks {
+  let hooks = compilationHooksMap.get(compilation);
+
+  if (!hooks) {
+    hooks = {
+      afterExtract: new AsyncSeriesWaterfallHook<AfterExtractPayload>([
+        'payload',
+      ]),
+      renderExtractedTranslations:
+        new AsyncSeriesWaterfallHook<RenderExtractedTranslationsPayload>([
+          'payload',
+        ]),
+    };
+    compilationHooksMap.set(compilation, hooks);
+  }
+
+  return hooks;
+}

src/index.ts

@@ -1,2 +1,8 @@
 export type { PluginI18nextExtractorOptions } from './options.js';
+export type {
+  AfterExtractPayload,
+  I18nextExtractorWebpackPluginHooks,
+  RenderExtractedTranslationsPayload,
+} from './hooks.js';
+export { getI18nextExtractorWebpackPluginHooks } from './hooks.js';
 export * from './pluginI18nextExtractor.js';