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



\> **ReplaceHandlerOptions** = `object`

Defined in: [src/handlers/interfaces/ReplaceHandler.ts:21](https://github.com/DRincs-Productions/pixi-vn-json/blob/336c45bc1f677c3b088aac058f0a457afc7cf32e/src/handlers/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/handlers/interfaces/ReplaceHandler.ts:31](https://github.com/DRincs-Productions/pixi-vn-json/blob/336c45bc1f677c3b088aac058f0a457afc7cf32e/src/handlers/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/handlers/interfaces/ReplaceHandler.ts:78](https://github.com/DRincs-Productions/pixi-vn-json/blob/336c45bc1f677c3b088aac058f0a457afc7cf32e/src/handlers/interfaces/ReplaceHandler.ts#L78)

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]`.

Default [#default]

```ts
false
```

***

name [#name]

\> **name**: `string`

Defined in: [src/handlers/interfaces/ReplaceHandler.ts:26](https://github.com/DRincs-Productions/pixi-vn-json/blob/336c45bc1f677c3b088aac058f0a457afc7cf32e/src/handlers/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/handlers/interfaces/ReplaceHandler.ts:64](https://github.com/DRincs-Productions/pixi-vn-json/blob/336c45bc1f677c3b088aac058f0a457afc7cf32e/src/handlers/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
"before-translation"
```

***

validation [#validation]

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

Defined in: [src/handlers/interfaces/ReplaceHandler.ts:53](https://github.com/DRincs-Productions/pixi-vn-json/blob/336c45bc1f677c3b088aac058f0a457afc7cf32e/src/handlers/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"])
```