Quick Notes: I had to setup a dev rig for 2.1.7 for something. So I installed this on that setup and it tested out very well.
## Highlights
- **Preview → Confirm** flow with CSV logging of changes
- **Variable/placeholder protection modes:**
- **Auto (default):** protects everything inside `{...}` — both `{$vars}` and `{placeholders}`
- **List:** protects only the names you specify (one per line, **without** `$`)
- **Printf token protection:** `%s`, `%1$s`, `%02d`, `%.2f`, `%%`, etc.
- **Find options:** plain replace (case‑sensitive or insensitive) or **regex**
## Configuration
**Options (ACP → Options → [AIXF] Batch Phrase Replace):**
- **Variable protection mode**
- **Auto:** protects anything matching `{...}` where the name starts with `$` or a letter. Examples protected: `{forumTitle}`, `{$forumTitle}`, `{$user.name}`, `{count}`.
- **List:** protects only names you enter (one per line). Enter the **base name**, e.g. `forumTitle`, `username`, `user`.
- Entering `user` protects `{$user}`, `{$user.name}`, `{$user['name']}` and `{user}`.
- **Protected variables (one per line)** — used only when the mode is **List**.
**Tip:** To **disable** protection for a run, switch to **List** mode and leave the list **empty**.
## Usage
1. Open **Batch Phrase Replace** in the ACP (search for it or use your admin navigation).
2. Enter **Find** / **Replace**. For regex, include delimiters (e.g. `/\bTitle\b/iu`).
3. Pick language, add-on, or scope (admin/public/all) to narrow targets.
4. Click **Preview** to see per-phrase diffs.
5. Click **Confirm** to apply changes. A **CSV log** of updates is saved and can be downloaded.
### Example
**Phrase text (before):**
```
Hello {$forumTitle}, welcome to {forumTitle}. You have %1$d new alerts.
```
**Find:** `Title` → **Replace:** `Name` (case-insensitive)
**After:** Only the word “Title” **outside** braces changes. `{forumTitle}`, `{$forumTitle}`, and `%1$d` remain intact.
## What’s protected
- `{$variables}` in templates
- `{placeholders}` in phrases (including dotted or indexed forms)
- **Printf tokens**: `%s`, `%1$s`, `%02d`, `%.2f`, `%%`, etc.
## Known limits
- Nested `{ ... { ... } ... }` is not supported; the inner `}` ends the match.
- Protection is brace-based; if a value is **not** inside `{...}`, it can be replaced.
- Regex: invalid patterns are auto-wrapped as UTF‑8 (`/pattern/u`). Provide full delimiters if you need flags.
## Troubleshooting
**“Please enter a valid option ID.” during upgrade**
Ensure `_data/options.xml` is present and `addon.json` lists:
```
aixfBprVarProtectMode
aixfBprSkipVars
```
Then run **Tools → Rebuild caches → Rebuild add‑on data** for this add‑on and retry the upgrade.
**Nothing changed in Preview/Confirm**
- The word is probably inside `{...}` and protected. Switch to **List** mode and leave the list empty for that run, or adjust your target.
- If using regex, verify your pattern matches outside braces (tokenization already guards inside braces).
**CSV log location**
A CSV is written under XenForo’s internal data path. The UI shows the file name and provides a download action after Confirm.
# AIXF Batch Phrase Replace — Q&A
**Q: How do I protect only certain variables?**
A: Switch to **List** mode and enter base names (no `$`), one per line. Example lines:
`forumTitle`
`username`
`user` (covers `{$user}`, `{$user.name}`, `{$user['name']}` and `{user}`)
**Q: It didn’t replace text inside `{forumTitle}` — is that expected?**
A: Yes. By default (Auto mode) anything inside `{...}` is protected. To allow changes inside braces for a run, switch to **List** mode and leave the list **empty**.
**Q: Are printf tokens like `%1$s`, `%02d`, or `%%` protected?**
A: Yes. They are always protected in both modes.
**Q: Can I run regex replacements?**
A: Yes. Provide a full pattern with delimiters, e.g. `/\bTitle\b/iu`. If a bad pattern is detected, the tool will wrap it as `/pattern/u` to keep processing.
**Q: How can I limit the blast radius?**
A: Filter by **Language**, **Add-on**, or **Scope** (admin/public/all) before running Preview.
**Q: Where can I find the change log?**
A: `changelog.txt` in the package root contains version notes for 2.0.2+.
**Q: Where are logs saved?**
A: A CSV is stored under XenForo’s internal data path. The success screen provides the file name and a download button/link.
**Q: Can I undo?**
A: Use the CSV log to selectively revert phrases manually, or restore from backup. Future versions may add a “revert” helper based on the log file.
[2.0.4]
- Added protection for printf-style tokens (%s, %1$s, %02d, %.2f, %%), in both Auto and List modes.
- Changed internal token markers to avoid '%' or '{' so guards cannot collide.
