What the agent does
The agent reads the framework's own switches before it touches a view. In an app laid out like codeigniter4/appstarter, composer.json requires PHP 8.2 and codeigniter4/framework 4.7 with PHPUnit 10.5 for tests, and app/Config/App.php already holds the three locale settings: $defaultLocale = 'en', $negotiateLocale = false and $supportedLocales = ['en']. app/Language/en/Validation.php returns an empty array, app/Language/ is otherwise a .gitkeep, app/Config/Routes.php has one route ($routes->get('/', 'Home::index')), Home::index returns view('welcome_message'), and app/Views/welcome_message.php opens with <html lang="en"> and carries its headings, menu labels and paragraphs as literal English. .github/workflows/phpunit.yml runs vendor/bin/phpunit --coverage-text on PHP 8.2 and 8.5 with the intl extension installed, which matters because formatted placeholders in language strings need it.
The configuration change is three lines: $negotiateLocale = true, so the framework reads the request's language preferences, and $supportedLocales listing the locales the app serves, with the first entry as the fallback when nothing matches. The agent then creates app/Language/en/App.php and one file per added locale, with a key for every user-facing string it found in the view (App.title, App.tagline, App.menu.home and so on, nested where the view groups them), and replaces each literal with lang('App.title'). The <html lang> attribute becomes esc(service('request')->getLocale()), so the page declares the locale that was actually negotiated. A string with a number or a name in it uses the placeholder form ('I have {0, number} apples' with lang('App.apples', [3])), which is where the intl extension comes in.
Two routing details come with it. A {locale} placeholder in a route lets a URL choose the language ($routes->get('{locale}/', 'Home::index')), and $routes->useSupportedLocalesOnly(true) keeps an unknown segment from being treated as a locale; the plain / route stays for negotiated requests. After editing, the agent runs php spark lang:find --show-new, which scans for lang() calls and reports keys missing from the default locale's files, and then without --show-new to write them, so a key it typed in a view but forgot in App.php cannot ship as its own name on the page. A missing key in a second locale falls back along the locale chain to en, which the pull request explains so translators know an untranslated page is not a broken one.
The tests use the framework's FeatureTestTrait beside the existing tests/unit/HealthTest.php: a GET / with Accept-Language set to the second locale asserts the translated title with assertSee, a GET of the {locale}/ route does the same, a request for an unsupported language gets the fallback, and a test reads App.title through lang() with the locale set explicitly to prove the file resolves. It runs composer install and vendor/bin/phpunit on the PHP versions the workflow names, then opens the pull request. In the starter the only page is the welcome view; in a real app the agent walks every file under app/Views, every controller flash message and every validation message in app/Language/en/Validation.php, which is the file the starter leaves empty for exactly this purpose.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add internationalisation to this CodeIgniter 4 app. Read composer.json, app/Config/App.php, app/Config/Routes.php, app/Config/Routing.php, app/Controllers/Home.php, app/Views/welcome_message.php, app/Language/en/Validation.php, tests/unit/HealthTest.php and .github/workflows/phpunit.yml first. Set negotiateLocale to true and list the supported locales with en first. Create app/Language/en/App.php and a file for each other locale with a key for every user-facing string in the views, replace the literals with lang() calls, use placeholders for strings with numbers or names, and set the html lang attribute from the request's locale. Add a {locale} route for the home page with useSupportedLocalesOnly. Run php spark lang:find --show-new and fix anything it reports. Add feature tests for a negotiated request, the {locale} route, the fallback for an unsupported language, and a direct lang() lookup. Run composer install and vendor/bin/phpunit until they pass, then open a pull request listing every key added and which strings still need a translator.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request changes app/Config/App.php, app/Config/Routes.php and the views it touched, adds app/Language/en/App.php and one file per additional locale, and adds a feature test file under tests/. Its description lists every key with the English text it replaced, marks which entries in the other locale files are still the English source awaiting a translator, and quotes the lang:find and PHPUnit output from the sandbox.
A reviewer checks the key names against the team's convention, decides whether the {locale} route should become a route group that prefixes every page or stay on the home page only, and confirms that the supported locale list and the fallback order match what the product needs. Nothing in the pull request is machine-translated unless the prompt supplied the translations.
Requests without a language preference, and browsers asking for a language the app does not list, keep getting the first supported locale, so the deployed site reads exactly as before until a second locale's file is filled in.
Run it on every Linear issue labelled i18n
An automation on the Project with a linear trigger on linear.issue.labeled, i18n in config.labels, and the prompt "this issue names a view, controller or validation message set that still has literal strings; move them into the language files for every supported locale, extend the feature tests, run lang:find, and open a pull request" starts one run per labelled issue once the configuration is in place. The trigger adds the issue after the prompt and fills in no placeholder, so a new checkout page and a new error message are handled the same way, each from its own issue.
A team with several CodeIgniter apps sends this body once per repository from its own server, each POST /o/{org}/sessions with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own Config\App and its own views, so an app that already negotiates locales gets only the missing keys and the tests.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The work is wide rather than deep: every literal in every view, every flash message, every lang() key that must exist in every locale file, and the one route placeholder that silently swallows a URL segment if useSupportedLocalesOnly is off. An agent does the walk in its own sandbox, runs lang:find to catch what it missed, and drives the pages with real Accept-Language headers through the feature tests, with the output kept beside the pull request.
A reviewer gets a table of keys and source strings instead of a diff across every view, and a clear list of what still needs a translator. A team with many apps starts the same request across all of them at once.
Frequently asked questions
Will it translate the strings?
Only if the prompt supplies the translations or names a source for them. By default the files for the other locales carry the keys with the English text, and the pull request lists them as awaiting a translator, so nothing machine-written reaches the site.
How does the framework pick the locale?
With $negotiateLocale = true, the request's language preferences are matched against $supportedLocales in order, and the first entry is the fallback. A {locale} route segment overrides that for the URL that carries it, and $request->setLocale() can set it from a user preference once the app has one.
Does it need the intl extension?
Only for formatted placeholders such as {0, number} or dates; plain keys work without it. The starter's workflow already installs intl, and the agent checks the server's PHP build for it before using formatted placeholders.
What about validation messages?
They live in app/Language/<locale>/Validation.php, which the starter ships empty for en. The agent adds the rules the app overrides there and a matching file per locale, and lang:find reports any Validation. key a rule references that no file defines.
More CodeIgniter jobs
The same job on other stacks
- Add i18n to a Docusaurus Site (Docusaurus)
- Add i18n to an Electron App from a Linear Issue (Electron)
- Add i18n to an Eleventy Blog (Eleventy)