Later this week we will be releasing XenForo 2.3.10 with a couple of notable additions for developers.
In XenForo 2.3.10 we have (finally!) polished this up and converted them to CLI commands.
Here's the full help text for the command. The
So let's say you've just finished some work on your add-on and now you want to change all of your hard coded text to phrases. Just run the command with the
You will be given a list of changes, template by template (if you omit the
If phraseable text is found that already exists as a phrase, using that phrase will be suggested instead, e.g.
In some cases, you may need to add delimiters when you're writing your text in templates in order to explicitly define the start and the end of the phraseable text. A common reason to do this is where your text spans multiple lines or contains HTML.
For example if your template contains:
And you want to ensure this entire line gets phrased correctly, wrap it like this:
You'll notice from the above example that variable interpolation works too!
The key difference with file phrases is you have to wrap phraseable text with double tildes
Unfortunately, we haven't run it in XF for a while
but if you were to run it on your own add-on and pass the
The solution to this problem is to have a strong set of documentation that can provide steering to the AI agent and a point of reference to clarify certain patterns, best practices, available commands or just generally how to do things.
You can certainly write all of this yourself. You can write a
We have written a new command
Running it with no options will output files that are compatible with most non-Claude models/agents such as ChatGPT Codex or Open Code. If you're only using Claude then you can run it with the
All agents get mostly the same files with the primary differences just being in the locations they are saved or their file names. e.g. by default you will get a
I'm not going to go into full details of everything the files include, but the rough structure is like this:
Collectively these skills make working with AI agents and XenForo a lot more stable and predictable. Though, as ever with these things, it's worth keeping in mind that your mileage may vary and you should very much expect AI agents to sometimes get it wrong, or get lost. I would urge you to still review every line of code written by agents and understand what is happening!
Phrase tools
For more years than I've been at the company, we have had an internal tool which we use during development of features to help us keep on top of phrases. It scans the code base to detect strings in templates that might need to become phrases and also looks for certain delimited strings in PHP code that can also be converted to phrases.In XenForo 2.3.10 we have (finally!) polished this up and converted them to CLI commands.
Template and Template Modification phraser
Here's the full help text for the command. The
xf-dev:template-modification-phraser command is nearly identical:
Code:
Description:
Analyzes and applies phrase replacements in templates
Usage:
xf-dev:template-phraser [options]
xf-dev:phraser-template
Options:
--addon=ADDON Add-on ID to process
--template=TEMPLATE Template in type:title format
--all Process all phrasable templates for the add-on (default when --template is omitted)
--phrase-prefix=PHRASE-PREFIX Prefix for generated phrase names
--dry-run Analyze and preview only; do not apply changes
--yes Skip confirmation prompts
--json Output as JSON
--preview-lines=PREVIEW-LINES Context lines around each change [default: 2]
-h, --help Display help for the given command. When no command is given display help for the list command
-q, --quiet Do not output any message
-V, --version Display this application version
--ansi|--no-ansi Force (or disable --no-ansi) ANSI output
-n, --no-interaction Do not ask any interactive question
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debugSo let's say you've just finished some work on your add-on and now you want to change all of your hard coded text to phrases. Just run the command with the
--addon option and your development output will be scanned for strings that look like they should be phrased:You will be given a list of changes, template by template (if you omit the
--template option) and you can pick all, some or none of them to apply.If phraseable text is found that already exists as a phrase, using that phrase will be suggested instead, e.g.
In some cases, you may need to add delimiters when you're writing your text in templates in order to explicitly define the start and the end of the phraseable text. A common reason to do this is where your text spans multiple lines or contains HTML.
For example if your template contains:
HTML:
Edit note <b>{$note.title}</b>And you want to ensure this entire line gets phrased correctly, wrap it like this:
HTML:
~~Edit note <b>{$note.title}</b>~~You'll notice from the above example that variable interpolation works too!
File phraser
The file phraser works almost identically. Here's the help page:
Code:
Description:
Analyzes and applies phrase replacements in add-on PHP files
Usage:
xf-dev:file-phraser [options]
xf-dev:phraser-file
Options:
--addon=ADDON Add-on ID to process
--file=FILE Single file path relative to the add-on root
--all Process all phrasable files for the add-on (default when --file is omitted)
--phrase-prefix=PHRASE-PREFIX Prefix for generated phrase names
--dry-run Analyze and preview only; do not apply changes
--yes Skip confirmation prompts
--json Output as JSON
--preview-lines=PREVIEW-LINES Context lines around each change [default: 2]
-h, --help Display help for the given command. When no command is given display help for the list command
-q, --quiet Do not output any message
-V, --version Display this application version
--ansi|--no-ansi Force (or disable --no-ansi) ANSI output
-n, --no-interaction Do not ask any interactive question
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debugThe key difference with file phrases is you have to wrap phraseable text with double tildes
~~ for it to be phrased:Finding unused phrases
Given enough time, you may end up accumulating phrases in your add-on that become unused as you refactor code. There's a command for that too. Here's the help page:
Code:
Description:
Finds and optionally deletes unused master phrases for an add-on
Usage:
xf-dev:unused-phrase-finder [options]
Options:
--addon=ADDON Add-on ID to process
--json Output as JSON
--show-unknown Show unknown used phrase titles in text mode
--delete=DELETE Comma-separated phrase IDs or titles to delete (unused only)
--delete-all Delete all currently unused phrases
--yes Skip confirmation prompts
-h, --help Display help for the given command. When no command is given display help for the list command
-q, --quiet Do not output any message
-V, --version Display this application version
--ansi|--no-ansi Force (or disable --no-ansi) ANSI output
-n, --no-interaction Do not ask any interactive question
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debugUnfortunately, we haven't run it in XF for a while
but if you were to run it on your own add-on and pass the --delete-all option you can remove unused phrases after confirmation:XenForo AI skills installation
When working with any framework, but particularly commercially licensed frameworks like XenForo, interactions with AI can be... interesting. Although this has improved dramatically with the rise of agentic AI where AI agents can just look through your code, the probability of running into hallucinations or mistakes is still fairly high.The solution to this problem is to have a strong set of documentation that can provide steering to the AI agent and a point of reference to clarify certain patterns, best practices, available commands or just generally how to do things.
You can certainly write all of this yourself. You can write a
CLAUDE.md file (or AGENTS.md for everyone else) which provide strong steering. You can also write your own "skills" to aid the agent in performing certain tasks. But with XenForo 2.3.10 you won't have to We have written a new command
xf-dev:install-ai-agents which will automatically install a very strong set of instructions for your chosen AI agent and output those into the relevant locations. Unfortunately there are multiple file naming conventions depending on which agent/tool you are using, and this command handles that too.
Code:
Description:
Install AI agent convention files
Usage:
xf-dev:install-ai-agents [options]
Options:
-f, --force Overwrite files if they already exist
--with-claude Install default files plus Claude-compatible files
--only-claude Install only Claude-compatible files
--dry-run Show which files would be written without making changes
-h, --help Display help for the given command. When no command is given display help for the list command
-q, --quiet Do not output any message
-V, --version Display this application version
--ansi|--no-ansi Force (or disable --no-ansi) ANSI output
-n, --no-interaction Do not ask any interactive question
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debugRunning it with no options will output files that are compatible with most non-Claude models/agents such as ChatGPT Codex or Open Code. If you're only using Claude then you can run it with the
--only-claude option. Or if you're switching between multiple tools you can run it with the --with-claude option.All agents get mostly the same files with the primary differences just being in the locations they are saved or their file names. e.g. by default you will get a
AGENTS.md file rather than a CLAUDE.md file.I'm not going to go into full details of everything the files include, but the rough structure is like this:
CLAUDE.md / AGENTS.md
This is a fairly short overview of the framework, where to find certain files and the key patterns that the agent should be aware of up front. It then also outlines a number of skills and what they are for, and these are discussed below.xf-shared-policy
These are the general policies that touch both sides of development including both core and add-on development. It explains things like the development output system, thexf-make commands, and general guiding principles to help agents stay on track.xf-core-dev
Not going to be relevant for most of you, but this is a bunch of handy general conventions for core development for use by the XenForo team.xf-addon-dev
This explains things like how to know the correct add-on ID, understanding of version numbers, steering away from manually editing.xml files, and other references relevant to add-on development directly.xf-scaffold-make
This skill describes how to use thexf-make commands in more detail and some general steering of dos and don'ts related to generating development artifacts.xf-template-phrase
This describes how templates and phrases work including a brief reference of some of the language semantics we use in the XenForo template syntax.Collectively these skills make working with AI agents and XenForo a lot more stable and predictable. Though, as ever with these things, it's worth keeping in mind that your mileage may vary and you should very much expect AI agents to sometimes get it wrong, or get lost. I would urge you to still review every line of code written by agents and understand what is happening!
