# Type Alias: ReplaceHandlerOptions (/jsdoc/pixi-vn-json/index/type-aliases/ReplaceHandlerOptions)



\> **ReplaceHandlerOptions** = `object`

Defined in: [src/translator/interfaces/ReplaceHandler.ts:21](https://github.com/DRincs-Productions/pixi-vn-json/blob/c3fc7ababe09c261f3130ab586feb49b5a221ace/src/translator/interfaces/ReplaceHandler.ts#L21)

Configuration options for a text-replacement handler registered via [TextReplaces.add](/jsdoc/pixi-vn-json/index/namespaces/TextReplaces/functions/add).

## Properties [#properties]

### description? [#description]

\> `optional` **description?**: `string`

Defined in: [src/translator/interfaces/ReplaceHandler.ts:31](https://github.com/DRincs-Productions/pixi-vn-json/blob/c3fc7ababe09c261f3130ab586feb49b5a221ace/src/translator/interfaces/ReplaceHandler.ts#L31)

An optional human-readable description of what this handler does.
Used for documentation purposes.

***

### i18nInterpolation? [#i18ninterpolation]

\> `optional` **i18nInterpolation?**: `boolean`

Defined in: [src/translator/interfaces/ReplaceHandler.ts:91](https://github.com/DRincs-Productions/pixi-vn-json/blob/c3fc7ababe09c261f3130ab586feb49b5a221ace/src/translator/interfaces/ReplaceHandler.ts#L91)

When `true`, the **first** occurrence of a matched `[key]` token is converted to the i18n
double-brace format `{{[key]}}` (exactly once). Any subsequent occurrences of `[key]` in
the same text are then replaced with the handler's return value as usual.

The transformation sequence for a matched key is:

* first occurrence: `[key]` → `{{[key]}}`
* remaining occurrences: `[key]` → handler return value

When `false` or omitted, the handler's return value directly replaces all occurrences of `[key]`.

**Recommended i18n configuration:** when this option is enabled, configure
`missingInterpolationHandler` in your i18n instance so that keys with no matching
translation are left intact rather than replaced with an empty string:

```ts title="lib/i18n.ts"
i18n.init({
    // ...
    missingInterpolationHandler(_text, value, _options) {
        return value[1];
    },
});
```

#### Default [#default]

```ts
false
```

***

### name [#name]

\> **name**: `string`

Defined in: [src/translator/interfaces/ReplaceHandler.ts:26](https://github.com/DRincs-Productions/pixi-vn-json/blob/c3fc7ababe09c261f3130ab586feb49b5a221ace/src/translator/interfaces/ReplaceHandler.ts#L26)

A unique name that identifies this handler.
Used for documentation and debugging purposes.

***

### type? [#type]

\> `optional` **type?**: `"after-translation"` | `"before-translation"`

Defined in: [src/translator/interfaces/ReplaceHandler.ts:64](https://github.com/DRincs-Productions/pixi-vn-json/blob/c3fc7ababe09c261f3130ab586feb49b5a221ace/src/translator/interfaces/ReplaceHandler.ts#L64)

When this handler should be invoked relative to the translation step.

* `"before-translation"` – the handler runs **before** onInkTranslate is called.
  Useful for pre-processing tokens, e.g. converting `[key]` into `{{key}}` for i18next.
* `"after-translation"` – the handler runs **after** onInkTranslate is called.
  Useful for substituting values that depend on the translated text.

#### Default [#default-1]

```ts
"after-translation"
```

***

### validation [#validation]

\> **validation**: `RegExp` | `"characterId"` | `"all"` | `ZodType`\<`string`>

Defined in: [src/translator/interfaces/ReplaceHandler.ts:53](https://github.com/DRincs-Productions/pixi-vn-json/blob/c3fc7ababe09c261f3130ab586feb49b5a221ace/src/translator/interfaces/ReplaceHandler.ts#L53)

Determines whether this handler should be invoked for a given `[key]` token.

* `"all"` – the handler is always invoked for every token found.
* `"characterId"` – the handler is invoked only when the key matches a registered character ID
  (i.e. the character is present in `RegisteredCharacters`).
* `RegExp` – the key string is tested against the regular expression. The handler is invoked
  only if the regex matches.
* `ZodType<string>` – the key string is validated with `schema.safeParse(key)`. The handler
  is invoked only if validation succeeds.

#### Example [#example]

```ts
// RegExp: only replace keys that look like lowercase identifiers
validation: /^[a-z_]+$/

// Zod: only replace keys that are one of a fixed set of values
import { z } from "zod"
validation: z.enum(["player", "npc", "enemy"])
```