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

`toGettextMessages()`

Converts the extracted messages to an object of contexts in Gettext format.

Return Value

object · All extracted message data · The format is compatible with gettext-parser

Example

{
  "": {
    "Foo": {
      "msgid": "Foo",
      "comments": {
        "reference": "src/foo.ts:42"
      }
    }
  },
  "Different context": {
    "Foo in a different context": {
      "msgid": "Foo in a different context",
      "msgid_plural": "Foos in a different context",
      "msgctxt": "Different context",
      "comments": {
        "reference": "src/bar.ts:157",
        "extracted": "Comment about Foo"
      }
    }
  }
}

`toPotString()`

Converts the extracted messages to a Gettext template string.

Return Value

string · Message template string

Example

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

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

`savePotFile(fileName)`

Saves the extracted messages as Gettext template into a file.

Parameters

Name	Type	Details
`fileName`	string	Required · Path to `.pot` file

Return Value

void

`savePotFileAsync(fileName)`

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

Parameters

Name	Type	Details
`fileName`	string	Required · Path to `.pot` file

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`
→ `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`
→ `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`
→ `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.SyntaxKind.Unknown; // = 0
ts.SyntaxKind.JS; // = 1
ts.SyntaxKind.JSX; // = 2
ts.SyntaxKind.TS; // = 3
ts.SyntaxKind.TSX; // = 4
ts.SyntaxKind.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

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.

Return Value

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

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`

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`

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`

Return Value

this

HtmlExtractors

A collection of factories for standard extractor functions

`elementAttribute(selector, textAttribute, [options])`

Parameters

Name	Type	Details
`selector`	string	Required · CSS selector
`attributeName`	string	Required · Name of the attribute that contains the message text
`options`	object	Options to configure the extractor function
→ `attributes`	object	See Argument Mapping below

Return Value

function · An extractor function that extracts content from HTML attributes.

`elementContent(selector, [options])`

Parameters

Name	Type	Details
`selector`	string	Required · CSS selector
`options`	object	Options to configure the extractor function
→ `attributes`	object	See Argument Mapping below
→ `content`	object	See Content Options below

Return Value

function · An extractor function that extracts content from HTML elements.

CSS Selectors

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`	number	Name of the attribute containing the plural message text
`context`	number	Name of the attribute containing the message context

Content Options

Name	Type	Default	Details
`trimWhiteSpace`	boolean	`true`	If set to `true`, white space at the very beginning and at the end of the content will get removed
`preserveIndentation`	boolean	`false`	If set to `true`, white space at the beginning of the line will not get removed
`replaceNewLines`	false or string	`false`	If a string is provided all new lines will be replaced with it

Getting Started

Languages

API Reference

API Reference

GettextExtractor

createJsParser([extractors])

Parameters

Return Value

createHtmlParser([extractors])

Parameters

Return Value

addMessage(message)

Parameters

Return Value

toGettextMessages()

Return Value

Example

toPotString()

Return Value

Example

savePotFile(fileName)

Parameters

Return Value

savePotFileAsync(fileName)

Parameters

Return Value

getStats()

Return Value

Properties

printStats()

Return Value

JsParser

addExtractor(extractor)

Parameters

Return Value

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

Parameters

Return Value

parseFile(fileName, [options])

Parameters

Return Value

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

Parameters

Return Value

Options

scriptKind

JsExtractors

callExpression(calleeName, options)

Parameters

Argument Mapping

Comment Options

Return Value

HtmlParser

addExtractor(extractor)

Parameters

Return Value

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

Parameters

Return Value

parseFile(fileName, [options])

Parameters

Return Value

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

Parameters

Return Value

HtmlExtractors

elementAttribute(selector, textAttribute, [options])

Parameters

Return Value

elementContent(selector, [options])

Parameters

Return Value

CSS Selectors

Options

Attribute Mapping

Content Options

Clone this wiki locally

`createJsParser([extractors])`

`createHtmlParser([extractors])`

`addMessage(message)`

`toGettextMessages()`

`toPotString()`

`savePotFile(fileName)`

`savePotFileAsync(fileName)`

`getStats()`

`printStats()`

`addExtractor(extractor)`

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

`parseFile(fileName, [options])`

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

`scriptKind`

`callExpression(calleeName, options)`

`addExtractor(extractor)`

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

`parseFile(fileName, [options])`

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

`elementAttribute(selector, textAttribute, [options])`

`elementContent(selector, [options])`