@floratmin/gettext-extractor-js-parser NPM

JS Parser for gettext-extractor

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

import { callExpressionExtractor, ICustomJsExtractorOptions } 
    from '@floratmin/gettext-extractor-js-parser';
import { GettextExtractor } from 'gettext-extractor';

const options: ICustomJsExtractorOptions = {
    arguments: {
        text: 0,
        textPlural: 1,
        comments: 2,
        context: 3,
    },
    comments: {
        commentString: 'comment',
        props: {
            props: ['{', '}']
        }
    }
};

const extractor = new GettextExtractor();

extractor
    .createJsParser()
    .addExtractor(callExpressionExtractor('_', options))
    .parseFilesGlob('src/**/*.@(ts|js|tsx|jsx)');

`callExpressionExtractor(calleeName, options)`

Parameters

Name	Type	Details
`calleeName`	string orstring[]	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 removedNormally 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

// We can provide comments as string
const string1 = _(
    'Foo',
    'Plural',
    'Comment',
    'Context'
);
// Or we can provide comments as object
const string2 = _(
    'Hello {PLACE}',
    'Plural',
    {
        comment: 'Comment',
        props: {
            PLACE: 'The place of interest'
        },
        path: 'https://www.example.com',
        nested: {
            key1: 'Key1',
            key2: 'Key2'
        }
    }
);
// When type of argument does not match declared type, then all following arguments are ignored
const string3 = _(
    'Foo2',
    {
        comment: 'Comment'
    },
    'Context'
)
// We can omit empty arguments with `null`, `undefined` or `0`
const string4 = _(
    'Foo3',
    null,
    null,
    'Context'
);

We extract the following messages

[
    {
        text: 'Foo',
        textPlural: 'Plural',
        coments: ['Comment'],
        context: 'Context'
    },
    {
        text: 'Hello {PLACE}',
        textPlural: 'Plural',
        comments: [
            'Comment',
            'path: https://www.example.com',
            '{PLACE}: The place of interest',
            'nested.key1: Key1',
            'nested.key2: Key2'
        ]
    },
    {
        text: 'Foo2'
    },
    {
        text: 'Foo3',
        context: 'Context'
    }
]

If we have the option fallback: true set:

const options: ICustomJsExtractorOptions = {
    arguments: {
        text: 0,
        textPlural: 1,
        comments: 2,
        context: 3,
    },
    comments: {
        commentString: 'comment',
        props: {
            props: ['{', '}']
        },
        fallback: true
    }
};

and the following functions

const string1 = (worldPlace: string) => _(
    'Hello {PLACE}', 
    'Plural', 
    {
        comment: 'Comment', 
        props: {
            PLACE: 'The place of interest'
        }, 
        path: 'http://www.example.com', 
        nested: {
            key1: 'Key1',
            key2: 'Key2'
        }
    },
    'Context',
    {
        PLACE: worldPlace
    }
);
// when omitting the second argument the third argument can take the place of the second argument 
// if the arguments are of different type. If there are more arguments, they also change their
// place accordingly.
const string2 = _(
    'Foo',
    {
        comment: 'No Plural here.'
    }
);
// omit comment object
const string3 = _(
    'Foo2',
    'Plural',
    'Context'
);
// skip textPlural and comment object, allowed placeholders are `null`, `undefined` or `0`
const string4 = _(
    'Foo3',
    null,
    null,
    'Context'
);
// if argument is not string or comment object than rest of arguments are ignored
const string5 = (props: {PROPS: string}) => _(
    'My {PROPS}',
    {
        props: {
            PROPS: 'Some props'
        }
    },
    props
);

we extract the following messages

[
    {
        text: 'Hello {PLACE}',
        textPlural: 'Plural',
        comments: [
            'Comment',
            'path: http://www.example.com',
            '{PLACE}: The place of interest',
            'nested.key1: Key1',
            'nested.key2: Key2'
        ],
        context: 'Context'
    },
    {
        text: 'Foo',
        comments: [
            'No Plural here.'
        ],
    },
    {
        text: 'Foo2',
        textPlural: 'Plural',
        context: 'Context'
    },
    {
        text: 'Foo3',
        context: 'Context'
    },
    {
        text: 'My {PROPS}',
        comments: [
            '{PROPS}: Some props'
        ]
    }
]

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.

gettext gettext-extractor

gettext-extractor

@everything-registry/sub-chunk-329 @zalastax/nolb-_flo

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago