README

Forces WordPress plugins to use their bundled translations instead of the global translations downloaded from translate.wordpress.org.

How It Works

This library hooks into WordPress's load_textdomain_mofile filter. When WordPress tries to load a .mo file from the global wp-content/languages/plugins/ directory, the filter redirects it to the plugin's own bundled languages/ directory instead.

Requirements

PHP >= 7.2.5
WordPress

Installation

Add the package to your plugin's lib/composer.json:

{
    "require": {
        "publishpress/bundled-translations": "^1.0"
    }
}

Then run:

composer update

Usage

In your plugin's main PHP file, include the library and instantiate it:

// Include the library
$bundledTranslationsPath = '/publishpress/bundled-translations/core/include.php';

if (file_exists(__DIR__ . '/lib/vendor' . $bundledTranslationsPath)) {
    require_once __DIR__ . '/lib/vendor' . $bundledTranslationsPath;
} elseif (defined('MY_PLUGIN_LIB_VENDOR_PATH') && file_exists(MY_PLUGIN_LIB_VENDOR_PATH . $bundledTranslationsPath)) {
    require_once MY_PLUGIN_LIB_VENDOR_PATH . $bundledTranslationsPath;
}

// Initialize bundled translations
add_action('plugins_loaded', function() {
    if (class_exists('PublishPress\BundledTranslations\BundledTranslations')) {
        $bundledTranslations = new PublishPress\BundledTranslations\BundledTranslations(
            'plugin-text-domain',
            __DIR__ . '/languages',
            __FILE__
        );
        $bundledTranslations->init();
    }
}, 10);

Translation updates

Bundled files do not receive translation updates from translate.wordpress.org. When the site language or the current user's language is a non-English locale shipped in the plugin's languages/ directory, the library can show one admin warning to users who can install plugins. The warning links to PublishPress Hub, which delivers those translation updates.

The warning stays off until the plugin enables it and lists the admin screen ids for its own pages. It is skipped when PublishPress Hub is active (PUBLISHPRESS_HUB_VERSION is defined). Dismissing it hides the warning for that user on that site.

add_filter('publishpress_bundled_translations_hub_notice_enabled', function ($enabled, $domain) {
    if ($domain === 'plugin-text-domain') {
        return true;
    }

    return $enabled;
}, 10, 2);

add_filter('publishpress_bundled_translations_hub_notice_screens', function ($screens, $domain) {
    if ($domain !== 'plugin-text-domain') {
        return $screens;
    }

    $screens[] = 'toplevel_page_plugin-slug';
    $screens[] = 'plugin-slug_page_plugin-settings';

    return $screens;
}, 10, 2);

Disabling

The library can be disabled in two ways:

Via PHP Constant

Add to wp-config.php or anywhere before the plugin loads:

define('PUBLISHPRESS_BUNDLED_TRANSLATIONS_ENABLED', false);

Via WordPress Filter

add_filter('publishpress_bundled_translations_enabled', '__return_false');

// Disable for a specific domain/plugin
add_filter('publishpress_bundled_translations_enabled', function($enabled, $domain, $pluginFile) {
    if ($domain === 'plugin-text-domain') {
        return false;
    }
    return $enabled;
}, 10, 3);

Running tests

Install dependencies at the repository root:
```
composer install
```
Configure the environment for WPBrowser’s WPLoader: copy .env.example to .env and set the variables for your local WordPress test install and database (see the comments in .env.example).
Link the dummy plugin to this tree — integration tests load the library from tests/Support/Data/DummyPlugin/lib/vendor/. That install must be a Composer path symlink so it tracks your edits under core/. From the repo root:
```
composer update-dummy
```
…or:
```
cd tests/Support/Data/DummyPlugin/lib && composer install
```
Edit code — change core/ for the library; add or extend Codeception/WPBrowser specs under tests/ (integration Cests live in tests/Integration/).
Rebuild test actors if you change suite modules (e.g. tests/Integration.suite.yml):
```
composer codecept build
```

Run the suite:

composer test Integration

Run one Cest file or method, for example:

composer test Integration BundledTranslationsCest
composer test Integration BundledTranslationsCest:constructorTrimsTrailingSlashFromLanguagesDir

License

GPL-3.0-or-later

publishpress / bundled-translations

Package info

Security

Statistics