JS Parser for gettext-extractor

Extract comments provided by a string or an object in the translator function.

1import { callExpressionExtractor, ICustomJsExtractorOptions } 
2    from '@floratmin/gettext-extractor-js-parser';
3import { GettextExtractor } from 'gettext-extractor';
4
5const options: ICustomJsExtractorOptions = {
6    arguments: {
7        text: 0,
8        textPlural: 1,
9        comments: 2,
10        context: 3,
11    },
12    comments: {
13        commentString: 'comment',
14        props: {
15            props: ['{', '}']
16        }
17    }
18};
19
20const extractor = new GettextExtractor();
21
22extractor
23    .createJsParser()
24    .addExtractor(callExpressionExtractor('_', options))
25    .parseFilesGlob('src/**/*.@(ts|js|tsx|jsx)');

callExpressionExtractor(calleeName, options)

Parameters

Name	Type	Details
calleeName	string or string[]	Required · Name(s) of the function(s)
options	object	Options to configure the extractor function
→ arguments	object	Required · See Argument Mapping below
→ comments	object	See Comment Options below
→ content	object	See Content Options below

Argument Mapping

Name	Type
text	number	Required · Position of the argument containing the message text
textPlural	number	Position of the argument containing the plural message text
context	number	Position of the argument containing the message context
comments	number	Position of the argument containing the comments string or object

Comment Options

If ommitted the comment is expected to be a string. If fallback is true, the comment has to be an object, otherwise it can be a string or an object.

Name	Type	Default	Details
commentString	string	comment	Key for providing plain comments
props	object		Each key under props has a value of an array with two strings. In the comment object we can provide key value pairs under each key defined under props. Each of these keys gets wrapped in between the provided two strings. Then after a semicolon the value is concatenated.
throwWhenMalformed	boolean	true	If set to true, throws an error when in the comment object any value is not a plain string
fallback	boolean	false	If set to true, an omitted argument fallbacks to the next argument if the next argument is of different type

If not trough commentString or props specified keys are used in the comment object, then these keys (concatenated with dots when they are nested) are added to the comments with a semicolon followed by the value of the key.

Content Options

Name	Type	Default	Details
trimWhiteSpace	boolean	false	If set to true, white space at the very beginning and at the end of the content will get removed Normally this behaves like .trim(), however if preseveIndentation is true, the indentation of the first line is kept as well.
preserveIndentation	boolean	true	If set to false, white space at the beginning of the line will get removed
replaceNewLines	false or string	false	If a string is provided all new lines will be replaced with it

Return Value

function · An extractor function that extracts messages from call expressions.

Example

With the example settings from the usage example and the following functions

1// We can provide comments as string
2const string1 = _(
3    'Foo',
4    'Plural',
5    'Comment',
6    'Context'
7);
8// Or we can provide comments as object
9const string2 = _(
10    'Hello {PLACE}',
11    'Plural',
12    {
13        comment: 'Comment',
14        props: {
15            PLACE: 'The place of interest'
16        },
17        path: 'https://www.example.com',
18        nested: {
19            key1: 'Key1',
20            key2: 'Key2'
21        }
22    }
23);
24// When type of argument does not match declared type, then all following arguments are ignored
25const string3 = _(
26    'Foo2',
27    {
28        comment: 'Comment'
29    },
30    'Context'
31)
32// We can omit empty arguments with `null`, `undefined` or `0`
33const string4 = _(
34    'Foo3',
35    null,
36    null,
37    'Context'
38);

We extract the following messages

1[
2    {
3        text: 'Foo',
4        textPlural: 'Plural',
5        coments: ['Comment'],
6        context: 'Context'
7    },
8    {
9        text: 'Hello {PLACE}',
10        textPlural: 'Plural',
11        comments: [
12            'Comment',
13            'path: https://www.example.com',
14            '{PLACE}: The place of interest',
15            'nested.key1: Key1',
16            'nested.key2: Key2'
17        ]
18    },
19    {
20        text: 'Foo2'
21    },
22    {
23        text: 'Foo3',
24        context: 'Context'
25    }
26]

If we have the option fallback: true set:

1const options: ICustomJsExtractorOptions = {
2    arguments: {
3        text: 0,
4        textPlural: 1,
5        comments: 2,
6        context: 3,
7    },
8    comments: {
9        commentString: 'comment',
10        props: {
11            props: ['{', '}']
12        },
13        fallback: true
14    }
15};
16

and the following functions

1const string1 = (worldPlace: string) => _(
2    'Hello {PLACE}', 
3    'Plural', 
4    {
5        comment: 'Comment', 
6        props: {
7            PLACE: 'The place of interest'
8        }, 
9        path: 'http://www.example.com', 
10        nested: {
11            key1: 'Key1',
12            key2: 'Key2'
13        }
14    },
15    'Context',
16    {
17        PLACE: worldPlace
18    }
19);
20// when omitting the second argument the third argument can take the place of the second argument 
21// if the arguments are of different type. If there are more arguments, they also change their
22// place accordingly.
23const string2 = _(
24    'Foo',
25    {
26        comment: 'No Plural here.'
27    }
28);
29// omit comment object
30const string3 = _(
31    'Foo2',
32    'Plural',
33    'Context'
34);
35// skip textPlural and comment object, allowed placeholders are `null`, `undefined` or `0`
36const string4 = _(
37    'Foo3',
38    null,
39    null,
40    'Context'
41);
42// if argument is not string or comment object than rest of arguments are ignored
43const string5 = (props: {PROPS: string}) => _(
44    'My {PROPS}',
45    {
46        props: {
47            PROPS: 'Some props'
48        }
49    },
50    props
51);

we extract the following messages

1[
2    {
3        text: 'Hello {PLACE}',
4        textPlural: 'Plural',
5        comments: [
6            'Comment',
7            'path: http://www.example.com',
8            '{PLACE}: The place of interest',
9            'nested.key1: Key1',
10            'nested.key2: Key2'
11        ],
12        context: 'Context'
13    },
14    {
15        text: 'Foo',
16        comments: [
17            'No Plural here.'
18        ],
19    },
20    {
21        text: 'Foo2',
22        textPlural: 'Plural',
23        context: 'Context'
24    },
25    {
26        text: 'Foo3',
27        context: 'Context'
28    },
29    {
30        text: 'My {PROPS}',
31        comments: [
32            '{PROPS}: Some props'
33        ]
34    }
35]

If any argument is not a string or comment object then the parsing is cut off starting from this argument. If there are other arguments in between these arguments, their position is not considered in the fallback.