@automattic/i18n-check-webpack-plugin

    1.0.1 • Public • Published

    i18n-check-webpack-plugin

    A Webpack plugin to check that WordPress i18n hasn't been mangled by Webpack optimizations.

    Installation

    Generally you'll install this via your package manager, e.g.

    npm install --save-dev @automattic/i18n-check-webpack-plugin
    

    Usage

    This goes in the plugins section of your Webpack config, e.g.

    {
    	plugins: [
    		new I18nCheckWebpackPlugin(),
    	],
    };

    Parameters recognized by the plugin are:

    • filter: Allows for specifying which source modules to process for i18n strings. The default is to process all files with extensions js, jsx, ts, tsx, cjs, and mjs.

      The value may be a function, which will be passed the file path relative to [Webpack's context] and which should return true if the file should be processed, or a string or RegExp to be compared with the relative file path, or an array of such strings, RegExps, and/or functions.

    • expectDomain: Set to the expected text domain that should be used in the output assets. If the assets use some other domain, an error will be generated.

    • warnOnly: Set true to produce warnings rather than errors when issues are found.

    • extractorOptions: Supply options for GettextExtractor.

      • babelOptions: Supply options for Babel.
      • functions: Supply a custom list of i18n functions to recognize.

    Known problematic code patterns

    These are some code patterns that are known to cause translations to be mangled.

    Lost comments due to expression movement

    To avoid the minifier dropping or misplacing the translator comments, it's best to keep the comment as close to the function call as possible. For example, in

    const a, b, c;
    
    /* translators: This is a bad example. */
    const example = __( 'Example', 'domain' );

    the minifier will combine those into a single const statement and misplace the comment on the way. To fix it, move the comment to the variable declaration instead of the const statement:

    const a, b, c;
    
    const
    	/* translators: This is a good example. */
    	example = __( 'Example', 'domain' );

    In some cases even the assignment may be dropped. In that case, you can attach the comment directly to the function call, or inside a multi-line function call:

    const example =
    	/* translators: This is a good example. */
    	__( 'Example', 'domain' );
    
    const example2 = __(
    	/* translators: This is a good example. */
    	'Example',
    	'domain'
    );
    
    const example3 = __( /* translators: This won't work. The comment must be on a line after the `__(`. */ 'Example', 'domain' );

    Similarly in jsx, a comment placed like this may wind up misplaced:

    <Tag
    	/* translators: This is a bad example. */
    	property={ __( 'Here's another example', 'domain' ) }
    />

    Instead put it inside the property:

    <Tag
    	property={
    		/* translators: This is an example of how to do it right. */
    		__( 'Here's another example', 'domain' )
    	}
    />

    Conditional function call compaction

    When a conditional calls the same function in each branch with only one argument different, Terser will transform it to a single call with the condition inside the argument. For example, either of these

    example = flag ? __( 'Flag is set', 'domain' ) : __( 'Flag is not set', 'domain' );
    if ( flag ) {
    	example = __( 'Flag is set', 'domain' );
    } else {
    	example = __( 'Flag is not set', 'domain' );
    }

    will become

    example = __( flag ? 'Flag is set' : 'Flag is not set', 'domain' );

    which will result in neither string being detected for translation.

    You can fix this by making the calls less similar, for example by adding a dummy argument to one call

    example = flag ? __( 'Flag is set', 'domain' ) : __( 'Flag is not set', 'domain', /* dummy arg to avoid bad minification */ 0 );

    or by specifying an unnecessary context in one call (or a different context in both)

    example = flag ? __( 'Flag is set', 'domain' ) : _x( 'Flag is not set', '', 'domain' );
    example = flag ? _x( 'Flag is set', 'Something', 'domain' ) : _x( 'Flag is not set', 'Something different', 'domain' );

    Pruned branches and common strings

    In some cases, such as when process.env.NODE_ENV is tested or when ES module tree-shaking is done, code paths can be known to be unreachable. For example, only one branch in the following will be kept:

    if ( process.env.NODE_ENV === 'production' ) {
    	console.log( __( 'This is production mode', 'domain' ) );
    } else {
    	console.log( __( 'This is development mode', 'domain' ) );
    }

    The plugin tries to detect this sort of thing and avoid reporting the translations from the pruned branch as having been mangled. But this can fail if the relevant strings are still used untranslated:

    if ( value === 'foo' ) {
    	if ( process.env.NODE_ENV === 'development' ) {
    		console.log( __( 'Found a value', 'domain' ), __( 'foo', 'domain' ) );
    	}
    	// Then do some other stuff...
    }

    In production mode the one use of __( 'foo', 'domain' ) is dropped, but the plugin will think it was only mangled because the string 'foo' is still present.

    You can fix this by including a unique context which will not appear elsewhere in the code:

    if ( value === 'foo' ) {
    	if ( process.env.NODE_ENV === 'development' ) {
    		console.log( __( 'Found a value', 'domain' ), _x( 'foo', 'The value "foo"', 'domain' ) );
    	}
    	// Then do some other stuff...
    }

    Caveats

    Certain situations cannot be detected by the plugin:

    • If the string is used in multiple places, and only one place is mangled, the mangling of that one place may not be detected.
    • If the string literal itself is mangled, it may be considered as being in a pruned branch.

    Security

    Need to report a security vulnerability? Go to https://automattic.com/security/ or directly to our security bug bounty site https://hackerone.com/automattic.

    License

    i18n-check-webpack-plugin is licensed under GNU General Public License v2 (or later)

    Keywords

    none

    Install

    npm i @automattic/i18n-check-webpack-plugin

    Homepage

    jetpack.com

    DownloadsWeekly Downloads

    6

    Version

    1.0.1

    License

    GPL-2.0-or-later

    Unpacked Size

    59.9 kB

    Total Files

    10

    Last publish

    Collaborators

    • t2dw4t
    • ehg_
    • wwa
    • sirreal
    • elazzabi
    • royho
    • obliviousharmony
    • luismulinari
    • macbre
    • quasistar
    • mjangda
    • matticbot
    • djalmaaraujo
    • brunobasto
    • a8c
    • nickdaugherty
    • blowery
    • noahtallen
    • hanifn
    • sgomes
    • tyxla
    • bms
    • rrinat
    • netsuso
    • saroshaga
    • parkcityj
    • nejclovrencic
    • sirbrillig
    • samiff
    • chriszarate
    • rogertheriault
    • robersongomes
    • johngodley