feat: support multiple localize functions (#24)

Co-authored-by: Hiroki Osame <[email protected]>

Author: Benjamin Hodgson

README.md

@@ -130,23 +130,30 @@ Enable to see warnings when unused string keys are found.
 ### localizeCompiler
 Type:
 ```ts
-(
+Record<
+  string, // localizer function name (eg. __)
+  (
     this: LocalizeCompilerContext,
     localizerArguments: string[],
     localeName: string,
-) => string
+  ) => string
+>
 ```
 
 Default:
 ```ts
-function (localizerArguments) {
+{
+  __(localizerArguments) {
     const [key] = localizerArguments;
     const keyResolved = this.resolveKey();
     return keyResolved ? JSON.stringify(keyResolved) : key;
+  }
 }
 ```
 
-A function to generate a JS string to replace the `__()` call with. It gets called for each localize function call (eg. `__(...)`) for each locale.
+An object of functions to generate a JS string to replace the `__()` call with. The object key is the localize function name, and its function gets called for each localize function call (eg. `__(...)`) for each locale. This allows you to have multiple localization functions, with separate compilation logic for each of them.
+
+Note, you cannot use both `functionName` and `localizeCompiler`. Simply set the function name as a key in the `localizeCompiler` object instead.
 
 #### localizerArguments
 An array of strings containing JavaScript expressions. The expressions are stringified arguments of the original call. So `localizerArguments[0]` will be a JavaScript expression containing the translation key.

src/index.ts

@@ -12,6 +12,7 @@ import {
 	LocaleFilePath,
 	LocalizeCompiler,
 	WP5,
+	LocalizeCompilerContext,
 } from './types';
 import { loadLocales } from './utils/load-locales';
 import { interpolateLocaleToFileName } from './utils/localize-filename';
@@ -29,10 +30,13 @@ import {
 	fileNameTemplatePlaceholder,
 } from './multi-locale';
 import { callLocalizeCompiler } from './utils/call-localize-compiler';
+import { stringifyAst } from './utils/stringify-ast';
 
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const { name } = require('../package.json');
 
+const defaultLocalizerName = '__';
+
 class LocalizeAssetsPlugin<LocalizedData = string> {
 	private readonly options: Options<LocalizedData>;
 
@@ -42,7 +46,7 @@ class LocalizeAssetsPlugin<LocalizedData = string> {
 
 	private readonly localizeCompiler: LocalizeCompiler<LocalizedData>;
 
-	private readonly functionName: string;
+	private readonly functionNames: string[];
 
 	private locales: LocalesMap<LocalizedData> = {};
 
@@ -55,9 +59,6 @@ class LocalizeAssetsPlugin<LocalizedData = string> {
 
 		this.options = options;
 
-		const functionName = options.functionName ?? '__';
-		this.functionName = functionName;
-
 		this.localeNames = Object.keys(options.locales);
 		if (this.localeNames.length === 1) {
 			[this.singleLocale] = this.localeNames;
@@ -66,18 +67,12 @@ class LocalizeAssetsPlugin<LocalizedData = string> {
 		this.localizeCompiler = (
 			this.options.localizeCompiler
 				? this.options.localizeCompiler
-				: function (localizerArguments) {
-					const [key] = localizerArguments;
-
-					if (localizerArguments.length > 1) {
-						this.emitWarning(`[${name}] Ignoring confusing usage of localization function: ${functionName}(${localizerArguments.join(', ')})`);
-						return key;
-					}
-
-					const keyResolved = this.resolveKey();
-					return keyResolved ? JSON.stringify(keyResolved) : key;
+				: {
+					[this.options.functionName ?? defaultLocalizerName]: defaultLocalizeCompilerFunction,
 				}
 		);
+
+		this.functionNames = Object.keys(this.localizeCompiler);
 	}
 
 	apply(compiler: Compiler) {
@@ -154,54 +149,62 @@ class LocalizeAssetsPlugin<LocalizedData = string> {
 	private interceptTranslationFunctionCalls(
 		normalModuleFactory: NormalModuleFactory,
 	) {
-		const { locales, singleLocale, functionName } = this;
+		const { locales, singleLocale, functionNames } = this;
 		const validator = localizedStringKeyValidator(locales, this.options.throwOnMissing);
 
-		onFunctionCall(
-			normalModuleFactory,
-			functionName,
-			(parser, callExpressionNode) => {
-				const { module } = parser.state;
-				const firstArgumentNode = callExpressionNode.arguments[0];
-
-				// Enforce minimum requirement that first argument is a string
-				if (
-					!(
-						callExpressionNode.arguments.length > 0
-						&& firstArgumentNode.type === 'Literal'
-						&& typeof firstArgumentNode.value === 'string'
-					)
-				) {
-					const location = callExpressionNode.loc!.start;
-					reportModuleWarning(
-						module,
-						new WebpackError(`[${name}] Ignoring confusing usage of localization function "${functionName}" in ${module.resource}:${location.line}:${location.column}`),
-					);
-					return;
-				}
-
-				const stringKey: LocalizedStringKey = firstArgumentNode.value;
-
-				validator.assertValidLocaleString(
-					stringKey,
+		const handler = (
+			parser: WP5.javascript.JavascriptParser,
+			callExpressionNode: SimpleCallExpression,
+			functionName: string,
+		) => {
+			const { module } = parser.state;
+			const firstArgumentNode = callExpressionNode.arguments[0];
+
+			// Enforce minimum requirement that first argument is a string
+			if (
+				!(
+					callExpressionNode.arguments.length > 0
+					&& firstArgumentNode.type === 'Literal'
+					&& typeof firstArgumentNode.value === 'string'
+				)
+			) {
+				const location = callExpressionNode.loc!.start;
+				reportModuleWarning(
 					module,
-					callExpressionNode,
+					new WebpackError(`[${name}] Ignoring confusing usage of localization function "${functionName}" in ${module.resource}:${location.line}:${location.column}`),
 				);
+				return;
+			}
 
-				for (const fileDependency of this.fileDependencies) {
-					module.buildInfo.fileDependencies.add(fileDependency);
-				}
+			const stringKey: LocalizedStringKey = firstArgumentNode.value;
 
-				const replacement = (
-					singleLocale
-						? this.getLocalizedString(callExpressionNode, stringKey, module, singleLocale)
-						: this.getMarkedFunctionPlaceholder(callExpressionNode, stringKey, module)
-				);
-				toConstantDependency(parser, replacement)(callExpressionNode);
+			validator.assertValidLocaleString(
+				stringKey,
+				module,
+				callExpressionNode,
+			);
 
-				return true;
-			},
-		);
+			for (const fileDependency of this.fileDependencies) {
+				module.buildInfo.fileDependencies.add(fileDependency);
+			}
+
+			const replacement = (
+				singleLocale
+					? this.getLocalizedString(callExpressionNode, stringKey, module, singleLocale)
+					: this.getMarkedFunctionPlaceholder(callExpressionNode, stringKey, module)
+			);
+			toConstantDependency(parser, replacement)(callExpressionNode);
+
+			return true;
+		};
+
+		for (const functionName of functionNames) {
+			onFunctionCall(
+				normalModuleFactory,
+				functionName,
+				(parser, node) => handler(parser, node, functionName),
+			);
+		}
 	}
 
 	/**
@@ -256,6 +259,29 @@ class LocalizeAssetsPlugin<LocalizedData = string> {
 
 		return markLocalizeFunction(callNode);
 	}
+
+	static defaultLocalizeCompiler: LocalizeCompiler = {
+		[defaultLocalizerName]: defaultLocalizeCompilerFunction,
+	};
+}
+
+function defaultLocalizeCompilerFunction(
+	this: LocalizeCompilerContext,
+	localizerArguments: string[],
+) {
+	const [key] = localizerArguments;
+
+	if (localizerArguments.length > 1) {
+		let code = stringifyAst(this.callNode);
+		if (code.length > 80) {
+			code = `${code.slice(0, 80)}…`;
+		}
+		this.emitWarning(`[${name}] Ignoring confusing usage of localization function: ${code})`);
+		return key;
+	}
+
+	const keyResolved = this.resolveKey();
+	return keyResolved ? JSON.stringify(keyResolved) : key;
 }
 
 export = LocalizeAssetsPlugin;

src/types.ts

@@ -33,11 +33,13 @@ export interface LocalizeCompilerContext<LocalizedData = string> {
 	emitError(message: string): void;
 }
 
-export type LocalizeCompiler<LocalizedData = string> = (
-	this: LocalizeCompilerContext<LocalizedData>,
-	functionArgments: string[],
-	localeName: string,
-) => string;
+export interface LocalizeCompiler<LocalizedData = string> {
+	[functionName: string]: (
+		this: LocalizeCompilerContext<LocalizedData>,
+		functionArgments: string[],
+		localeName: string,
+	) => string;
+}
 
 export function validateOptions<LocalizedData>(options: Options<LocalizedData>): void {
 	if (!options) {
@@ -53,6 +55,14 @@ export function validateOptions<LocalizedData>(options: Options<LocalizedData>):
 		&& options.sourceMapForLocales.some(locale => !hasOwnProp(options.locales, locale))) {
 		throw new Error('sourceMapForLocales must contain valid locales');
 	}
+	if (options.localizeCompiler) {
+		if (Object.keys(options.localizeCompiler).length === 0) {
+			throw new Error('localizeCompiler can\'t be an empty object');
+		}
+		if (options.functionName) {
+			throw new Error('Can\'t use localizeCompiler and also specify functionName');
+		}
+	}
 }
 
 export { WP4, WP5 };

src/utils/call-localize-compiler.ts

@@ -1,3 +1,4 @@
+import type { Identifier } from 'estree';
 import { LocalizeCompiler, LocalizeCompilerContext } from '../types';
 import { stringifyAst } from './stringify-ast';
 
@@ -7,5 +8,6 @@ export function callLocalizeCompiler<LocalizedData>(
 	localeName: string,
 ) {
 	const callNodeArguments = context.callNode.arguments.map(stringifyAst);
-	return localizeCompiler.call(context, callNodeArguments, localeName);
+	const functionName = (context.callNode.callee as Identifier).name;
+	return localizeCompiler[functionName].call(context, callNodeArguments, localeName);
 }