Script tool

The Script tool runs a user-provided ES5 JavaScript program for every part in the stream. The script receives the current part as a part object and can read and modify block source and target text. It is an escape hatch for bespoke transformations that no built-in tool covers.

Inside the script, part.type identifies the part and part.block exposes the block (with id, translatable, source, and targets). Helper functions are available: emit(part) forwards a part, skip() drops the current part, and log(msg) writes a message to standard error. When the script neither emits nor skips, the part passes through with any in-place text edits applied. The script is provided inline or read from a .js file.

This tool runs code the recipe chooses, so it is gated. It is exec-class: the script is recipe-supplied, file reads a path the recipe names, and a recipe is bound by entering a directory. kapi therefore asks once per project, before anything else happens with it, and remembers the answer; an unattended run with nobody to ask refuses rather than assumes. KAPI_TRUST_EXEC=1 grants it where the pipeline author — not the repository being processed — is the one deciding. The same classification withholds this tool from the agent surface, from the engine API, and from any recipe arriving inside a .kpz. See AD-038.

IDscript

SourceBuilt-in

Categorytext-processing

Cardinalitymonolingual

Tagsconfigurable

Parameters

Parameter	Type	Default	Description
`allowSourceMutation`	boolean	false	Permit the script to modify the source text (off by default; source is read-only)
`code`	string		Inline ES5 JavaScript code
`scriptFile`	string		Path to a .js file
`source`	string	inline	Script source mode

Configure it live

Configuration

Loading form…

Examples

Trim trailing whitespace from source text

Modify source text in place with an inline script.

source: inline
code: |
  if (part.type === 'block') {
    var s = part.block.source[0].content.text;
    part.block.source[0].content.text = s.replace(/\s+$/, '');
  }

Load a script from a file

Run a script stored alongside the project.

source: file
scriptFile: ./scripts/transform.js

Processing notes

Each tool instance owns its own runtime and runs single-threaded over its input.
A part passes through unchanged when the script neither emits a part nor calls skip.

Limitations

The engine supports ES5 JavaScript only.
Only block source and target text changes are applied back; other modifications to the part are not persisted.

← Back to the Tool Reference