=== MLP2 to MLP5 (by ROBOTSTXT) ===
Contributors: javiercasares, robotstxt
Tags: multisite, multilingual, multilingualpress, migration, mlp
Requires at least: 6.7
Tested up to: 6.9
Stable tag: 1.1.2
Requires PHP: 8.2
Version: 1.1.2
License: GPL-3.0-or-later
License URI: https://www.gnu.org/licenses/gpl-3.0.txt
Network: true

Guided, safe, and reversible migration from MultilingualPress 2 to MultilingualPress 5 for WordPress Multisite.

== Description ==

MLP2 to MLP5 (by ROBOTSTXT) provides a guided, safe, and reversible migration path from MultilingualPress 2 (free) to MultilingualPress 5 (premium) on WordPress Multisite.

MultilingualPress 5 has a completely different architecture from version 2, making a direct upgrade impossible without losing all site connections and content relationships. This plugin bridges that gap with a preparation step and a six-step wizard that migrates your data without modifying or deleting the original MLP2 data at any point during the process.

**What this plugin migrates:**

* Site connections (which network sites are linked to each other)
* Language assignments (which language/locale is assigned to each site)
* Post relationships (pages, posts, and custom post types linked across sites)
* Term relationships (categories, tags, and custom taxonomy terms linked across sites)

**Key features:**

* Works with MultilingualPress 2 deactivated — only its database tables need to exist
* Safely renames MLP2 tables so that MultilingualPress 5 can activate without errors
* Fully idempotent — safe to pause and resume without creating duplicates
* Complete migration log with CSV export
* Optional cleanup step to remove MLP2 backup tables and network settings after a successful migration

== Before You Begin ==

Read this section carefully before starting the migration. Skipping steps or performing them out of order will result in a failed migration.

=== Why the Order Matters ===

MultilingualPress 5 **refuses to activate** if it detects tables with the original MLP2 naming pattern (`{prefix}mlp_*`) in the database. It shows a blocking error and does not activate. You cannot dismiss this error by ignoring it.

The correct sequence is:

1. Install this migrator plugin first (while MLP2 tables still exist under their original names).
2. Use the migrator to rename the MLP2 tables to temporary backup copies.
3. Only then install and activate MultilingualPress 5.
4. Run the migration wizard.

This plugin exists precisely to manage this sequence safely.

=== Requirements ===

* WordPress Multisite 6.7 or higher
* PHP 8.2 – 8.5
* MultilingualPress 5 installed and network-activated (after the preparation step below)
* MultilingualPress 2 database tables present in the database (the plugin itself may be deactivated or uninstalled)

=== Critical Rules ===

1. **Never install MLP5 before running the table-rename step in this plugin.** MLP5 will refuse to activate.
2. **Do not delete MLP2 tables before running the migration.** The migrator reads directly from those tables.
3. **Do not run any MLP5 database reset or cleanup.** Let the migrator handle the transition.
4. **Always create a full backup before starting.** The migration is non-destructive, but a backup is mandatory.

== Installation ==

This plugin is not distributed via the WordPress Plugin Directory. Install it manually.

=== Manual Installation ===

1. Download the plugin ZIP file.
2. In your WordPress Network Admin, go to **Plugins > Add New > Upload Plugin**.
3. Upload the ZIP file and click **Install Now**.
4. Click **Network Activate**.

Do not activate this plugin on a per-site basis. It must be network-activated.

== Using the Plugin ==

=== Complete Step-by-Step Migration Guide ===

Follow these steps in exact order. Do not skip any step, and do not proceed to the next step until the current one is complete.

**This guide covers the primary scenario: MultilingualPress 2 was deactivated (for example, due to PHP 8.4 incompatibility) and its database tables remain in the database.**

---

= Step 0 — Create a Full Backup (Mandatory) =

Before doing anything else, create a complete backup of your WordPress database and all files.

Using WP-CLI:

  wp db export backup-before-mlp-migration.sql --add-drop-table

Using a backup plugin (e.g., UpdraftPlus, BackWPup) or your hosting control panel are also valid options.

**Do not proceed without a backup. This step is not optional.**

---

= Step 1 — Deactivate MultilingualPress 2 =

If MultilingualPress 2 is still active on your network:

1. Go to **Network Admin > Plugins**.
2. Find MultilingualPress 2 in the list.
3. Click **Network Deactivate**.

**Do not click "Delete".** The plugin files may be removed later, but the database tables must remain intact for the migration. Deleting the plugin only removes PHP files — the tables are preserved.

If MultilingualPress 2 was already deactivated (for example, because it is incompatible with your current PHP version), skip this step. The database tables remain in place regardless.

---

= Step 2 — Install and Activate MLP2 to MLP5 Migrator =

Install this plugin before installing MultilingualPress 5.

1. Download the MLP2 to MLP5 Migrator ZIP.
2. Go to **Network Admin > Plugins > Add New > Upload Plugin**.
3. Upload the ZIP and click **Install Now**.
4. Click **Network Activate**.

---

= Step 3 — Rename MLP2 Tables =

This step makes it possible for MultilingualPress 5 to activate. Without it, MLP5 will show a blocking error and refuse to start.

1. Go to **Network Admin > Settings > MLP Migrator**.
2. The page will detect your MLP2 tables and show the current system state.
3. Click **"Rename MLP2 tables (prepare for MLP5 activation)"**.
4. The plugin renames all `{prefix}mlp_*` tables to `{prefix}mlp2bak_*` backup copies.
5. The page reloads and shows: *"MLP2 tables renamed. Now go to Network Admin > Plugins and activate MultilingualPress 5."*

Your data is safe. The tables have been renamed, not deleted. Nothing has been modified.

If you need to undo this step (for example, if you decide not to proceed), use the **"Restore original table names"** link at the bottom of the page.

---

= Step 4 — Install and Activate MultilingualPress 5 =

Now that the MLP2 tables have been renamed, MultilingualPress 5 can activate without errors.

1. Obtain the MultilingualPress 5 ZIP from your license provider.
2. Go to **Network Admin > Plugins > Add New > Upload Plugin**.
3. Upload the MultilingualPress 5 ZIP file and click **Install Now**.
4. Click **Network Activate**.

MultilingualPress 5 should activate cleanly. If it still shows a compatibility error, return to **Network Admin > Settings > MLP Migrator** to verify that the rename step completed successfully.

If MLP5 was already installed and network-activated (not possible if MLP2 tables were in their original state — see above), skip this step.

---

= Step 5 — Run the Migration Wizard =

Go to **Network Admin > Settings > MLP Migrator**.

The page will confirm that the system is ready (backup tables found + MLP5 active). The wizard has six steps. Each step must be completed before the next one becomes available.

---

= Wizard Step 1 — Preflight Checks =

The wizard automatically checks:

* **MLP2 backup tables detected** — verifies that the renamed MLP2 tables exist. This is the primary requirement.
* **MultilingualPress 5 active** — verifies that MLP5 is network-activated.

**If backup tables are not found:** Return to Step 3 and run the rename step. If original MLP2 tables are no longer present either, the tables may have been deleted — restore from your backup.

**If MLP5 is not active:** Activate it first (see Step 4).

**If MLP2 is still active:** An amber warning is shown recommending you deactivate it before continuing (see Step 1). The wizard still allows you to proceed.

A backup reminder is displayed. Confirm that you completed Step 0 before clicking **Next**.

Click **Next** to proceed to Step 2.

---

= Wizard Step 2 — Analysis =

Click **Run Analysis** to scan the MLP2 backup database.

The wizard will display:

* Number of site connections found in MLP2
* Number of post relationships found in MLP2
* Number of term relationships found in MLP2
* Detected conflicts:
  * **Orphaned sites** — sites referenced in MLP2 that no longer exist in the network
  * **Orphaned posts** — posts referenced in MLP2 that no longer exist on their site
  * **Orphaned terms** — terms referenced in MLP2 that no longer exist on their site
  * **Duplicate relations** — duplicate rows in MLP2 tables

Conflicts are not blocking. They will be automatically skipped and logged during the migration with a clear explanation in the migration log.

Review the summary to understand what will be migrated. Click **Next** to proceed to Step 3.

---

= Wizard Step 3 — Site Relations =

Click **Start** to migrate site connections and language assignments.

The wizard reads all site connections from the MLP2 backup tables and writes them to MultilingualPress 5 in the correct format. Language/locale assignments for each site are also migrated.

This step usually completes in seconds. Results are displayed as:

* **Migrated** — successfully written to MLP5
* **Skipped** — already existed in MLP5, or referenced a site that no longer exists
* **Errors** — failed to write; check the migration log for details

Errors at this step are rare. If you see errors, download the log at Step 5 and review before continuing.

Click **Next** to proceed to Step 4.

---

= Wizard Step 4 — Content Relations =

This step migrates all post and term relationships. On large sites with thousands of relationships, this step can take several minutes.

Click **Start** to begin. A progress bar updates in real time showing:

* Total relationships to process
* Migrated (successfully written to MLP5)
* Skipped (orphaned content, duplicates, or already migrated)
* Errors

**If you need to pause:**

1. Click **Pause** — the current position is saved automatically.
2. You can close the browser or leave the page.
3. Return to **Network Admin > Settings > MLP Migrator** at any time.
4. Click **Resume** to continue from exactly where you stopped.

No data will be duplicated if you pause and resume. The migration is fully idempotent.

Wait for the progress bar to reach 100% before continuing. Click **Next** to proceed to Step 5.

---

= Wizard Step 5 — Verification =

The wizard displays a comparison report showing, for each category (site relations, post relations, term relations):

* **Expected** — count from the analysis in Step 2
* **Migrated** — successfully written to MLP5
* **Skipped** — omitted with a reason (see log)
* **Errors** — failed operations

Color coding:

* Green — migrated count matches expected and errors are zero
* Amber — some errors occurred; review the log
* Red — nothing was migrated despite records being expected; action may be required

Click **Download log (CSV)** to save the full migration log to your computer. **Save this file.** It is the only permanent record of what happened during the migration.

Review the report carefully. If the error count is unexpectedly high, stop here and investigate before proceeding to cleanup.

Click **Next** to proceed to Step 6.

---

= Wizard Step 6 — Cleanup (Optional) =

This step is optional. MultilingualPress 5 will work correctly whether or not you perform the cleanup.

Three independent cleanup actions are offered:

1. **Deactivate MultilingualPress 2 (network-wide)** — if MLP2 is still active, this deactivates it.

2. **Delete MLP2 backup database tables** — permanently drops all `{prefix}mlp2bak_*` tables from the database. **This action is irreversible.** Only proceed if:
   * You have verified that the migration completed successfully in Step 5
   * You have a backup from Step 0
   * You have downloaded the migration log

3. **Delete MultilingualPress 2 network settings** — removes MLP2-related entries from `wp_sitemeta`.

**To proceed with cleanup:**

1. Select the checkboxes for the actions you want to perform.
2. Note: option 2 (delete tables) is only available if option 1 (deactivate) is also selected.
3. Type `DELETE` (exactly, in uppercase) in the confirmation field.
4. Click **Proceed with cleanup**.

If you do not type `DELETE` exactly, the button remains disabled and no action will be taken.

---

= Step 6 — Verify MultilingualPress 5 =

After the wizard completes:

1. Browse your multisite network and verify that content is properly linked across sites in MultilingualPress 5.
2. Go to **Network Admin > Sites** and check each site's language assignment in MLP5.
3. Visit the frontend and confirm that the language switcher works correctly.
4. Check a few posts and verify that their translations are correctly linked in MLP5.

If something looks wrong, compare against the migration log (Wizard Step 5). Do not delete the backup tables until you are satisfied with the result.

---

= Step 7 — Deactivate the Migrator Plugin (Optional) =

Once you have confirmed that MLP5 is fully working:

1. Go to **Network Admin > Plugins**.
2. Find "MLP2 to MLP5 Migrator" and click **Network Deactivate**.
3. Click **Delete** to remove the plugin files.

The migration log table is preserved in the database unless you have enabled the "Delete migration log on uninstall" option in the plugin settings.

== Frequently Asked Questions ==

= Does MultilingualPress 2 need to be active during migration? =

No. MultilingualPress 2 only needs its database tables to still be present in the database. The plugin itself can be deactivated or even uninstalled. This is the primary expected scenario — for example, when MLP2 was deactivated because it is incompatible with PHP 8.4.

= Why does MultilingualPress 5 show a blocking error and refuse to activate? =

MLP5 detects the presence of tables named `{prefix}mlp_*` and refuses to activate, showing the message: *"It seems that an old version of MultilingualPress is installed in this website."* This is a hard block, not a warning. Use the **Rename MLP2 tables** action in this plugin (Step 3 above) before attempting to activate MLP5.

= Can I pause and resume the migration? =

Yes. The content relations step (Wizard Step 4) supports pause and resume. If the browser is closed or the server times out, return to the wizard and click Resume. No data will be duplicated — the migration is fully idempotent.

= What does "Skipped" mean in the results? =

Skipped records are normal and expected. Common reasons:

* The relationship already exists in MLP5 (idempotency)
* The post or term no longer exists on one of the linked sites
* The site was deleted from the network after the MLP2 data was created
* A locale string used in MLP2 is not recognized by MLP5

All skipped records are logged with a specific reason. Download the CSV log from Wizard Step 5 to review them.

= Is it safe to run the migration more than once? =

Yes. Running the migration multiple times will not create duplicate data in MLP5. Records already migrated are detected and logged as "Skipped".

= What are the {prefix}mlp2bak_* tables? =

These are the renamed copies of your original MLP2 tables. This plugin renames them from `{prefix}mlp_*` to `{prefix}mlp2bak_*` during Step 3. The data is untouched — only the table names change. These backup tables are what the migration wizard reads from. You can safely delete them after a successful migration using Wizard Step 6.

= What data is modified or deleted during migration? =

None during the migration itself. The preparation step (Step 3) renames tables but does not modify any data. The optional cleanup in Wizard Step 6 is the only action that deletes data, and it requires explicit confirmation by typing "DELETE".

= Can I use this plugin without MultilingualPress 5 installed? =

You can install this plugin and run the table-rename step (Step 3) without MLP5 present. However, MLP5 must be installed and network-activated before running the migration wizard. The wizard will not allow you to proceed to Step 2 without it.

= What PHP versions are supported? =

PHP 8.2 through 8.5. Note that MultilingualPress 2 is not compatible with PHP 8.4 or higher, which is the most common reason to use this migrator.

== Compatibility ==

* WordPress: 6.7 – 6.9
* PHP: 8.2 – 8.5
* Requires: MultilingualPress 5 (premium, any recent version)
* Compatible with: MultilingualPress 2 (latest release from WordPress.org)

== Changelog ==

= 1.1.2 =

_Release date: 2026-03-02_

* `update.json` is now included in the distributable ZIP so the auto-updater manifest ships alongside the plugin files.

= 1.1.1 =

_Release date: 2026-03-02_

* Fixed: Wizard Step 1 (Preflight Checks) incorrectly showed "Original tables still present — rename step not done" after Cleanup (Step 6) dropped the backup tables.

= 1.1.0 =

_Release date: 2026-03-02_

* MLP2 sitemeta keys (`inpsyde_multilingual*`) are now renamed to `mlp2bak_inpsyde_multilingual*` during table preparation instead of being deleted, making the operation fully reversible.
* Restoring original table names also restores the original sitemeta keys.
* Cleanup step (Step 6) now also deletes the backed-up sitemeta keys.
* Fixed: `mlp_migrator_log` (plugin's own table) was incorrectly listed as an MLP2 table requiring renaming.

= 1.0.0 =

_Release date: 2026-02-27_

* First production release. Complete six-step migration wizard.
* Table preparation, preflight checks, analysis, site relations, content relations (AJAX batch), verification with CSV export, and optional cleanup.
* Supports `multilingual_linked` as alternative MLP2 content relations table.
* Spanish (es_ES) translation included.

= Previous versions =

See the full changelog at changelog.txt.

== Compliance ==

This plugin adheres to the following security measures and review protocols for each version:

* [WordPress Plugin Handbook](https://developer.wordpress.org/plugins/)
* [WordPress Plugin Security](https://developer.wordpress.org/plugins/wordpress-org/plugin-security/)
* [WordPress APIs Security](https://developer.wordpress.org/apis/security/)
* [WordPress Coding Standards](https://github.com/WordPress/WordPress-Coding-Standards)
* [Plugin Check (PCP)](https://wordpress.org/plugins/plugin-check/)