README

A developer tool for replacing WordPress translation text domains in PHP, JavaScript, and block.json files.

Why This Tool Exists
Getting Started
- Installation
- First Run
Command Line Usage
- Options
- Examples
Configuration via composer.json
Alternatives
Links

Why This Tool Exists

This tool was created for a common WordPress development workflow: reusing existing plugins or libraries inside another plugin or theme.

A well-known example is Action Scheduler, which explicitly states:

"Action Scheduler is designed to be used and released in plugins."

That is exactly where translation issues can appear.

When you embed a reusable library, it often keeps its own text domain (for example action-scheduler). If your plugin uses another text domain (for example my-plugin), WordPress will not automatically treat those strings as part of your plugin's translations.

In practice, this means your plugin can be translated, but embedded library strings may remain untranslated for users.

This package solves that build-time problem by replacing the embedded library text domain with your plugin's text domain across your source files. For example:

vendor/bin/wptdr --dir=src --search=action-scheduler --replace=my-plugin

After this replacement, all translatable strings consistently use your plugin's domain, so they can be handled in one translation flow. This is especially useful for teams distributing plugins/themes that bundle reusable WordPress components.

Getting Started

Installation

To start replacing text domains in your WordPress plugin or theme, require SolveBeam WordPress Text Domain Replacer in Composer:

composer require solvebeam/wp-text-domain-replacer --dev

First Run

To replace text domains in your project, use the wptdr command from the vendor/bin/ directory:

vendor/bin/wptdr \
  --dir=src \
  --search=old_domain \
  --replace=new_domain

This will scan your src directory for any occurrence of the text domain old_domain in PHP files, JavaScript files, and block.json files, and replace them with new_domain.

Command Line Usage

Options

`--dir=DIRECTORY`

Specifies the directory to scan for text domain replacements. Defaults to the current working directory if not provided.

Example: --dir=src or --dir=.

`--search=DOMAIN`

The text domain to search for. You can specify multiple search domains by repeating this option.

Example: --search=old_domain or --search=old_domain --search=legacy_domain

`--replace=DOMAIN`

The text domain to replace with. This is required.

Example: --replace=new_domain

`--exclude=PATTERN`

Exclude directories or files by name. You can specify multiple patterns by repeating this option.

Example: --exclude=node_modules --exclude=vendor

Examples

Basic replacement in current directory:

vendor/bin/wptdr --search=old_domain --replace=new_domain

Replace in specific directory:

vendor/bin/wptdr --dir=src --search=old_domain --replace=new_domain

Replace multiple text domains:

vendor/bin/wptdr \
  --dir=src \
  --search=old_domain \
  --search=legacy_domain \
  --replace=new_domain

Replace while excluding directories:

vendor/bin/wptdr \
  --dir=. \
  --search=old_domain \
  --replace=new_domain \
  --exclude=vendor \
  --exclude=node_modules

Add to Composer scripts:

{
  "scripts": {
    "update-text-domain": "wptdr --dir=src --search=old_domain --replace=new_domain"
  }
}

Then run with:

composer update-text-domain

Configuration via composer.json

Instead of passing all options via command line, you can also configure the text domain replacer in your composer.json file. This is useful for keeping your configuration in one place and simplifying your Composer scripts.

Setup

Add a new extra section to your composer.json:

{
  "extra": {
    "solvebeam-wp-text-domain-replacer": {
      "dir": "src",
      "search": [
        "old_domain",
        "legacy_domain"
      ],
      "replace": "new_domain",
      "exclude": [
        "vendor",
        "node_modules"
      ]
    }
  }
}

Running with Configuration

Once configured in composer.json, you can run the tool without any options:

vendor/bin/wptdr

The tool will automatically load the configuration from composer.json and apply it.

Overriding Configuration

Command-line options always take precedence over composer.json configuration. This allows you to override specific settings when needed:

# Use composer.json config but override the directory
vendor/bin/wptdr --dir=tests

# Use composer.json config but override the replacement domain
vendor/bin/wptdr --replace=another_domain

# Use composer.json config but replace different domains
vendor/bin/wptdr --search=other_domain

Alternatives

Here is a list of alternatives that we found:

solvebeam / wp-text-domain-replacer

Maintainers

Package info

Statistics

Security