Skip to content

floratmin/gettext-extractor-svelte

BranchesTags

Repository files navigation

gettext-extractor for svelte files

This extractor extracts also all the called functions and the function definition into a separate dictionary.

Installation

npm install gettext-extractor-svelte

Usage:

import {
    SvelteGettextExtractor, 
    callExpressionExtractor, 
    ICustomJsExtractorOptions,
    FunctionExtractorBuilder
} from 'gettext-extractor-svelte';

const extractor = new SvelteGettextExtractor();
const functionExtractor = new FunctionExtractorBuilder();
const findTranslationClassExpression = functionExtractor.variableDeclaration(
    'Foo', functionExtractor.classExpression(undefined, [
        functionExtractor.methodDeclaration('bar', true)
    ])
);

const options: ICustomJsExtractorOptions = {
    arguments: {
        text: 0,
        context: 1,
        comments: 2
    },
    comments: {
        commentString: 'comment',
        props: {
            props: ['{', '}']
        }
    },
    identifierKeys: ['text', 'context'],
    translatorFunction: {
        functionExtractor: findTranslationClassExpression,
        identifier: 'translatorFunction',
        restrictToFile: './src/translator.ts'
    }
}

extractor.createSvelteParser()
    .addExtractor(callExpressionExtractor('t', options))
    .parseFilesGlob('./src/**/*.svelte');

const messages = extractor.getMessages();
const functionDict = extractor.getFunctions();
const messageDict = extractor.getMessageDictionary();

From the following svelte file named src/App.svelte:

<script lang="ts">
    import { t } from './translator-function';
    import Component from './Component.svelte';
    export let place: string;
    let caption = t(
        'FooCaption', 
        'Context', 
        {comment: 'Comment', path: 'https://www.example.com'}
    );
</script>

<body>
    <h1>{caption}</h1>
    <p>{t('Foo')}</p>
    {#each [t('Bar'), t('Baz')] as text}
        <p>{text}</p>
        <Component label="{t('Bax', 'Context', {comment: 'Comment'})}">
            {t(
                'Hello {PLACE}', 
                'Context', 
                { 
                    comment: 'Multiline\nComment', 
                    props: {PLACE: 'The place where you are'},
                    messageformat: 'This could be a messageformat function'
                },
                {PLACE: place}
            )}
        </Component>
    {/each}
</body>

and the following translation function in file src/translator.ts:

let foo = class Bar {
    bar(translationObject: any) {
        return 'I am translated';
    }
}

we extract the following messages:

[
    {
        text: 'FooCaption',
        context: 'Context',
        comments: [
            'Comment',
            'path: https://www.example.com'
        ],
        references: [
            'src/App.svelte:5'
        ],
    },
    {
        text: 'Foo',
        references: [
            'src/App.svelte:14'
        ],
    },
    {
        text: 'Bar',
        references: [
            'src/App.svelte:15'
        ],
    },
    {
        text: 'Baz',
        references: [
            'src/App.svelte:15'
        ],
    },
    {
        text: 'Bax',
        context: 'Context',
        comments: [
            'Comment',
        ],
        references: [
            'src/App.svelte:17'
        ],
    },
    {
        text: 'Hello {PLACE}',
        context: 'Context',
        comments: [
            'Multiline',
            'Comment',
            'messageformat: This could be a messageformat function',
            '{PLACE}: The place where you are'
        ],
        references: [
            'src/App.svelte:18'
        ],
    },
]

the following functions:

{
    'src/App.svelte': [
        {
            functionString: `_(
        'FooCaption',
        'Context',
        {comment: 'Comment', path: 'https://www.example.com'}
    )`,
            functionData: {
                functionName: '_',
                functionArgs: []
            },
            identifier: '{"text":"FooCaption","context":"Context"}',
            startChar: 162,
            endChar: 273
        },                
        {
            functionString: "_('Foo')",
            functionData: {
                functionName: '_',
                functionArgs: []
            },
            identifier: '{"text":"Foo"}',
            startChar: 324,
            endChar: 332
        },
        {
            functionString: "_('Bar')",
            functionData: {
                functionName: '_',
                functionArgs: []
            },
            identifier: '{"text":"Bar"}',
            startChar: 350,
            endChar: 358
        },
        {
            functionString: "_('Baz')",
            functionData: {
                functionName: '_',
                functionArgs: []
            },
            identifier: '{"text":"Baz"}',
            startChar: 360,
            endChar: 368
        },
        {
            functionString: "_('Bax')",
            functionData: {
                functionName: '_',
                functionArgs: []
            },
            identifier: '{"text":"Bax"}',
            startChar: 428,
            endChar: 436
        },
        {
            functionString: `_(
                'Hello {PLACE}',
                'Context',
                {
                    comment: 'Multiline\\nComment',
                    props: {PLACE: 'The place where you are'},
                    messageformat: 'This could be a messageformat function'
                },
                {PLACE: place}
            )`,
            functionData: {
                functionName: '_',
                functionArgs: ['{PLACE: place}']
            },
            identifier: '{"text":"Hello {PLACE}","context":"Context"}',
            startChar: 486,
            endChar: 820
        } 
    ],
    'src/translator.ts': [
        {
            functionString:
`bar(translationObject: any) {
        return 'I am translated';
    }`,
            identifier: 'translatorFunction',
            definition: true, // marks that this entry is an extracted translation function
            startChar: 26,
            endChar: 95
        }
    ]
}

and the mapping of identifiers to text as an object

{
    '{"text":"Foo"}': 'Foo',
    '{"text":"Bar"}': 'Bar',
    '{"text":"Baz"}': 'Baz',
    '{"text":"Bax"}': 'Bax',
    '{"text":"FooCaption","context":"Context"}': 'FooCaption',
    '{"text":"Hello {PLACE}","context":"Context"}': 'Hello {PLACE}'
}

Additional methods for SvelteGettextExtractor

  createSvelteParser()

Create parser for parsing .svelte files

Return Value

SvelteParser · Can be used in the same way as parser created with createJsParser(), except the following added parse option:

Name Type Details
options object Additional parse option
translatorFunctions TTranslatorFunction | TTranslatorFunction[] Translation Function Definition to extract functions.

  getFunctions()

Gets all parsed function calls

Return Value

object · Dictionary with keys of file name and values of a list of function objects with properties as described below

Name Type Details
functionString string String of the function call in the source code
functionData object Object containing keys functionName and functionArgs
→ functionName string Name of the called function
→ functionArgs string[] Arguments without arguments defining text, textPlural, context and comment
identifier string Identifier string constructed trough options.identifierKeys
definition true When set marks that string is part of translation function definition
startChar number Index where the function call string starts
endChar number Index where the function call string ends

  getLastAddedFunctions()

Receive array of functions, which got added in the last call of parseJsString, parseSvelteString.

Return Value

array · Same as values of dictionary described in getFunctions()

  getFunctionsByFileName(fileName)

Gets all parsed function calls in a file

Parameters

Name Type Details
fileName string Required · Name of file
Return Value

array · Same as values of dictionary described in getFunctions()

  saveFunctionJSON(fileName)

Save functions dictionary as a JSON file.

Parameters

Name Type Details
fileName string Required · Name of file

Return Value

void

  saveFunctionJSONAsync(fileName)

Save functions dictionary as a JSON file asynchronously.

Parameters

Name Type Details
fileName string Required · Name of file

Return Value

Promise

  getMessageDictionary()

Recieve a dictionary mapping message text to function identifiers.

Return Value

object · Dictionary with identifier strings as keys and message text as value

  getMessagesWithId()

Recieve array of messages with identifier.

Return Value
Name Type Details
text string Message string
textPlural string Plural version of the message string
context string Message context
references string[] Array of file references where the message was extracted from
comments string[] Array of comments for this message
identifier string Identifier string constructed trough options.identifierKeys

  getLastAddedMessages()

Receive array of messages with identifier, which got added in the last call of parseJsString, parseSvelteString or parseHtmlString.

Return Value

array · List of message objects (same properties as for getMessagesWithId())

  getTransformedMessages<T = any>(func: (messages: IMessage[]) => T)

Transform message object with custom function.

Parameters

Name Type Details
func (messages: IMessage[]) => T Required · Transformer function
Return Value

T · Depends on your function

For all other available options please look at the package gettext-extractor

JS Parser for gettext-extractor

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

import { callExpressionExtractor, ICustomJsExtractorOptions } 
    from 'gettext-extractor-svelte';
import { GettextExtractor } from 'gettext-extractor'; // Works also with SvelteGettextExtractor

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 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
→ identifierKeys <'text' | 'textPlural' | 'context'>[] Fields for constructing ids to map messages to functions, defaults to all. At least one of these keys should match each message function. Defaults to ['text', 'context']
→ translatorFunction object See Translator Function Options below
→ content object See Content Options below
Argument Mapping
Name Type Details
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
Function Extractor Options
Name Type Default Details
functionExtractor FunctionExtractor The function extractor describing the typescript nodes of the function to extract
identifier string The identifier under which the function will be added to the dict
restrictToFile string When set than only the specified file will be parsed for the function
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.

JS Node Parser for gettext-extractor

Extracts nodes provided by TTranslatorFunction or by providing TTranslatorFunction[] on each .parseString or .parseSvelteString method call.

import { nodeExtractor, TTranslatorFunction, FunctionExtractorBuilder, SvelteGettextExtractor } from 'gettext-extractor-svelte';

const functionExtractor = new FunctionExtractorBuilder();
const importDeclaration = functionExtractor.importDeclaration(
    './translations',
    functionExtractor.importClause(
        't'
    ),
    true,
);

const translatorFunctions: TTranslatorFunction[] = [
    {
        identifier: 'translationFunctionImport',
        functionName: 't',
        functionExtractor: importDeclaration
    }
];

const extractor = new SvelteGettextExtractor();

extractor.createJsParser()
    .addExtractor(nodeExtractor())
    .parseString('import t from "./translations";', 'src/app.js', {translatorFunctions});

extractor.getFunctions() === {
    'src/app.js': [
        {
            functionString: 'import t from "./translations";',
            functionData: {
                functionName: 't',
                functionArgs: []
            },
            startChar: 0,
            endChar: 31,
            identifier: 'translationFunctionImport',
            definition: true
        }
    ]
}; // true

nodeExtractor(translatorFunction)

Parameters

Name Type Details
translatorFunction TTranslatorFunction or TTranslatorFunction[] See Translator Function Options below
Function Extractor Options
Name Type Default Details
functionExtractor FunctionExtractor The function extractor describing the typescript nodes of the function to extract
identifier string The identifier under which the function will be added to the dict
restrictToFile string When set than only the specified file will be parsed for the function

Function Extractor Builder

import {
    FunctionExtractorBuilder
} from 'gettext-extractor-svelte';

const functionExtractor = new FunctionExtractorBuilder();

Methods for FunctionExtractorBuilder

  objectLiteralExpression(properties?, getPos?)

Marks object literal expressions

Parameters

Name Type Default Details
properties FunctionExtractor [] List of function extractors defining the properties of the object
getPos boolean false Return start and end position in call expression to extract node as string
Return Value

FunctionExtractor

  variableDeclaration(variableName, initializer?, getPos?)

Marks variable declarations

Parameters

Name Type Default Details
variableName string Required · Name of declared variable
initializer FunctionExtractor Function extractor defining the initializer
getPos boolean false Return start and end position in call expression to extract node as string
Return Value

FunctionExtractor

  propertyAssignment(keyName, initializer?, getPos?)

Marks property assignment

Parameters

Name Type Default Details
keyName string Required · Name of property
initializer FunctionExtractor Function extractor defining the initializer
getPos boolean false Return start and end position in call expression to extract node as string
Return Value

FunctionExtractor

  methodDeclaration(methodName, getPos?)

Marks method declaration

Parameters

Name Type Default Details
methodName string Required · Name of method
getPos boolean false Return start and end position in call expression to extract node as string
Return Value

FunctionExtractor

  arrowFunction(getPos?)

Marks arrow function

Parameters

Name Type Default Details
getPos boolean false Return start and end position in call expression to extract node as string
Return Value

FunctionExtractor

  propertyDeclaration(propertyName, initializer?, getPos?)

Marks property declaration

Parameters

Name Type Default Details
propertyName string Required · Name of property
properties FunctionExtractor Function extractor defining the initializer
getPos boolean false Return start and end position in call expression to extract node as string
Return Value

FunctionExtractor

  functionDeclaration(functionName, getPos?)

Marks function declaration

Parameters

Name Type Default Details
functionName string Required · Name of function declaration
getPos boolean false Return start and end position in call expression to extract node as string
Return Value

FunctionExtractor

  functionExpression(functionName?, getPos?)

Marks function expression

Parameters

Name Type Default Details
functionName string Name of function expression
getPos boolean false Return start and end position in call expression to extract node as string
Return Value

FunctionExtractor

  classDeclaration(className, members?, getPos?)

Marks class declarations

Parameters

Name Type Default Details
className string Required · Name of class
members FunctionExtractor[] Array of function extractors defining the members of the class
getPos boolean false Return start and end position in call expression to extract node as string
Return Value

FunctionExtractor

  classExpression(className?, members?, getPos?)

Marks class expression

Parameters

Name Type Default Details
className string Name of class
members FunctionExtractor[] Array of function extractors defining the members of the class
getPos boolean false Return start and end position in call expression to extract node as string
Return Value

FunctionExtractor

  getAccessor(accessorName, body?, getPos?)

Marks get accessor

Parameters

Name Type Default Details
accessorName string Required · Name of accessor
body FunctionExtractor Function extractor defining the body of the get accessor
getPos boolean false Return start and end position in call expression to extract node as string
Return Value

FunctionExtractor

  setAccessor(accessorName, body?, getPos?)

Marks set accessor

Parameters

Name Type Default Details
accessorName string Required · Name of accessor
body FunctionExtractor Function extractor defining the body of the set accessor
getPos boolean false Return start and end position in call expression to extract node as string
Return Value

FunctionExtractor

  expressionStatement(identifier, right?, getPos?)

Marks expression statement

Parameters

Name Type Default Details
identifier string Required · Name of identifier on the left side of expression statement
right FunctionExtractor Function extractor defining the right side of the expression statement
getPos boolean false Return start and end position in call expression to extract node as string
Return Value

FunctionExtractor

  labeledStatement(statement?, getPos?)

Marks labeled statement

Parameters

Name Type Default Details
statement FunctionExtractor Function extractor for defining the right side of the labeled statement
getPos boolean false Return start and end position in call expression to extract node as string
Return Value

FunctionExtractor

  importDeclaration(moduleSpecifier, importClause?, getPos?)

Marks import declaration

Parameters

Name Type Default Details
moduleSpecifier string Required · Name of module imported in this declaration
importClause FunctionExtractor Function extractor defining the import clause
getPos boolean false Return start and end position in call expression to extract node as string
Return Value

FunctionExtractor

  importClause(name?, elements?, getPos?)

Marks import clause

Parameters

Name Type Default Details
name string Name of main import in this clause
elements FunctionExtractor[] List of function extractors defining the imported elements
getPos boolean false Return start and end position in call expression to extract node as string
Return Value

FunctionExtractor

  importSpecifier(name, getPos?)

Marks import specifier

Parameters

Name Type Default Details
name string Name of import in this specifier
getPos boolean false Return start and end position in call expression to extract node as string
Return Value

FunctionExtractor

  variableStatment(declarations?, getPos?)

Marks variable statement

Parameters

Name Type Default Details
declarations FunctionExtractor[] List of variable declared in this statement
getPos boolean false Return start and end position in call expression to extract node as string
Return Value

FunctionExtractor

  newExpression(name, getPos?)

Marks new expression

Parameters

Name Type Default Details
name string Name of new expression
getPos boolean false Return start and end position in call expression to extract node as string
Return Value

FunctionExtractor

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

4 stars

Watchers

3 watching

Forks

1 fork
Report repository

Releases 1

v5.1.0 Latest
Oct 5, 2023

Packages

No packages published

Languages