API Reference

Public API of the Gettext Extractor library.

Note: For TypeScript users, .d.ts files are included in the package.

GettextExtractor

`createJsParser([extractors])`

Creates a parser for JavaScript, TypeScript and JSX sources.

Parameters

Name	Type	Details
`extractors`	array	Extractor functions which will be used with this parser. They can also be added to the parser later, by using `addExtractor`.

Return Value

JsParser

`createHtmlParser([extractors])`

Creates a parser for HTML sources.

Parameters

Name	Type	Details
`extractors`	array	Extractor functions which will be used with this parser. They can also be added to the parser later, by using `addExtractor`.

Return Value

HtmlParser

`addMessage(message)`

Manually add a message to the extracted messages.

Parameters

Name	Type	Details
`message`	object	Message data
→ `text`	string	Required · Message string
→ `textPlural`	string	Plural version of the message string
→ `context`	string	Message context · if empty or omitted, the message will be added without a context
→ `references`	string[]	Array of file references where the message was extracted from Usually in the format `<filename>:<linenumber>`
→ `comments`	string[]	Array of comments for this message

Return Value

void

`getMessages()`

Gets all extracted messages

Return Value

array · List of message objects, properties are described below

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

`getContexts()`

Gets all contexts and their messages

Return Value

array · List of context objects, properties are described below

Name	Type	Details
`name`	string	Name of the context
`messages`	array	Array of message objects (same properties as for `getMessages()`)

`getMessagesByContext(context)`

Gets the messages from a context

Parameters

Name	Type	Details
`context`	string	Required · Context name

Return Value

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

`getPotString([headers])`

Converts the extracted messages to a Gettext template string.

Parameters

Name	Type	Details
`headers`	object	Dictionary of PO headers to set · by default `Content-Type` is already set to `text/plain; charset=UTF-8`

Return Value

string · Message template string

Example

#: src/foo.ts:42
msgid "Foo"
msgstr ""

#. A comment
#: src/bar.ts:157
msgctxt "Different context"
msgid "Foo in a different context"
msgid_plural "Foos in a different context"
msgstr[0] ""
msgstr[1] ""

`savePotFile(fileName, [headers])`

Saves the extracted messages as Gettext template into a file.

Parameters

Name	Type	Details
`fileName`	string	Required · Path to `.pot` file
`headers`	object	Dictionary of PO headers to set · by default `Content-Type` is already set to `text/plain; charset=UTF-8`

Return Value

void

`savePotFileAsync(fileName, [headers])`

Saves the extracted messages as Gettext template into a file asynchronously.

Parameters

Name	Type	Details
`fileName`	string	Required · Path to `.pot` file
`headers`	object	Dictionary of PO headers to set · by default `Content-Type` is already set to `text/plain; charset=UTF-8`

Return Value

Promise

`getStats()`

Gets statistics about the extracted messages.

Return Value

object · Object containing statistics data

Properties

Name	Type
`numberOfParsedFiles`	number
`numberOfParsedFilesWithMessages`	number
`numberOfMessages`	number
`numberOfPluralMessages`	number
`numberOfMessageUsages`	number
`numberOfContexts`	number

`printStats()`

Prints statistics about the extracted messages.

Return Value

void

JsParser

All public methods of the parser return the parser instance itself, so it can be used as fluent API:

extractor
    .createJsParser()
    .addExtractor(/* extractor function */)
    .parseFile('foo.jsx')
    .parseFilesGlob('src/**/*.js');

`addExtractor(extractor)`

Adds an extractor function to the parser after it has been created.

Parameters

Name	Type	Details
`extractor`	function	Required · Extractor function to be added to the parser

Return Value

this

`parseString(source, [fileName], [options])`

Parses a source code string and extracts messages.

Parameters

Name	Type	Details
`source`	string	Required · Source code string
`fileName`	string	File name used for references (file and line number) if omitted, no references will be added to the catalog
`options`	object	Parse options
→ `lineNumberStart`	number	Number of the first line in the source · Default is `1`
→ `transformSource`	function	Function that takes the source as string and returns a string · Can be useful for custom pre-processing
→ `scriptKind`	enum	Language variation details below

Return Value

this

`parseFile(fileName, [options])`

Reads and parses a single file and extracts messages.

Parameters

Name	Type	Details
`fileName`	string	Required · Path to the file to parse
`options`	object	Parse options
→ `lineNumberStart`	number	Number of the first line in the source · Default is `1`
→ `transformSource`	function	Function that takes the source as string and returns a string · Can be useful for custom pre-processing
→ `scriptKind`	enum	Language variation details below

Return Value

this

`parseFilesGlob(pattern, [globOptions], [options])`

Reads and parses all files that match a glob pattern and extracts messages.

Parameters

Name	Type	Details
`pattern`	string	Required · Glob pattern · see node-glob for details
`globOptions`	object	Options for node-glob · details in the node-glob docs
`options`	object	Parse options
→ `lineNumberStart`	number	Number of the first line in the source · Default is `1`
→ `transformSource`	function	Function that takes the source as string and returns a string · Can be useful for custom pre-processing
→ `scriptKind`	enum	Language variation details below

Return Value

this

Options

`scriptKind`

This value specifies whether the source is TypeScript, JSX, etc. By default, the TypeScript parser infers the type from the file extension. Therefore you should only have to provide it if you're using parseString without a file name or if your files have unconventional file extensions.

The enum values can be imported from the typescript package. The available options are:

const ts = require('typescript');

ts.ScriptKind.Unknown; // = 0
ts.ScriptKind.JS; // = 1
ts.ScriptKind.JSX; // = 2
ts.ScriptKind.TS; // = 3
ts.ScriptKind.TSX; // = 4
ts.ScriptKind.External; // = 5

JsExtractors

A collection of factories for standard extractor functions

`callExpression(calleeName, options)`

Parameters

Name	Type	Details
`calleeName`	string	Required · Name of the function
`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	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

Comment Options

If omitted, it will extract all comments on the same line (i.e. sameLineLeading and sameLineTrailing).

Name	Type	Default	Details
`sameLineLeading`	boolean	`false`	If set to `true`, all comments that are on the same line and appear before the expression will get extracted
`otherLineLeading`	boolean	`false`	If set to `true`, all comments that are on previous lines above the expression will get extracted
`sameLineTrailing`	boolean	`false`	If set to `true`, all comments that are on the same line and appear after the expression will get extracted
`regex`	RegExp		If provided, comments are only extracted if their text matches this regular expression. If the regex has capturing groups, the first one will be used for extraction of the comment.

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 `preserveIndentation` is `true`, the indentation of the first content 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.

`htmlTemplate(htmlParser)`

Parameters

Name	Type	Details
`htmlParser`	object	Required · HtmlParser instance

Return Value

function · An extractor function that runs every string through the provided HtmlParser.

HtmlParser

All public methods of the parser return the parser instance itself, so it can be used as fluent API:

extractor
    .createHtmlParser()
    .addExtractor(/* extractor function */)
    .parseFile('foo.jsx')
    .parseFilesGlob('src/**/*.js');

`addExtractor(extractor)`

Adds an extractor function to the parser after it has been created.

Parameters

Name	Type	Details
`extractor`	function	Required · Extractor function to be added to the parser

Return Value

this

`parseString(source, [fileName], [options])`

Parses a source code string and extracts messages.

Parameters

Name	Type	Details
`source`	string	Required · Source code string
`fileName`	string	File name used for references (file and line number) if omitted, no references will be added to the catalog
`options`	object	Parse options
→ `lineNumberStart`	number	Number of the first line in the source · Default is `1`
→ `transformSource`	function	Function that takes the source as string and returns a string · Can be useful for custom pre-processing

Return Value

this

`parseFile(fileName, [options])`

Reads and parses a single file and extracts messages.

Parameters

Name	Type	Details
`fileName`	string	Required · Path to the file to parse
`options`	object	Parse options
→ `lineNumberStart`	number	Number of the first line in the source · Default is `1`
→ `transformSource`	function	Function that takes the source as string and returns a string · Can be useful for custom pre-processing

Return Value

this

`parseFilesGlob(pattern, [globOptions], [options])`

Reads and parses all files that match a glob pattern and extracts messages.

Parameters

Name	Type	Details
`pattern`	string	Required · Glob pattern · see node-glob for details
`globOptions`	object	Options for node-glob · details in the node-glob docs
`options`	object	Parse options
→ `lineNumberStart`	number	Number of the first line in the source · Default is `1`
→ `transformSource`	function	Function that takes the source as string and returns a string · Can be useful for custom pre-processing

For selecting HTML elements, the extractor function factories use (a subset of) CSS selectors. The following selectors (and any valid combination of them) are supported:

Tag foo
Id #foo
Class .foo
Attribute
- Existence [foo]
- Exact value [foo=bar]
- Starting with [foo^=bar]
- Ending in [foo$=bar]
- Contains [foo*=bar]

Note: Multiple independent selectors can be delimited by a comma as you can do in CSS.

Options

Attribute Mapping

Name	Type	Details
`textPlural`	string	Name of the attribute containing the plural message text
`context`	string	Name of the attribute containing the message context
`comment`	string	Name of the attribute containing the comment

Content Options

Name	Type	Default (content)	Default (attributes)	Details
`trimWhiteSpace`	boolean	`true`	`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 `preserveIndentation` is `true`, the indentation of the first content line is kept as well.
`preserveIndentation`	boolean	`false`	`true`	If set to `true`, white space at the beginning of the line will not get removed
`replaceNewLines`	false or string	`false`	`false`	If a string is provided all new lines will be replaced with it

Getting Started

Languages

API Reference