What the agent does
The agent reads the extension and the localization sample that ships beside it. In an extension like helloworld-sample in microsoft/vscode-extension-samples, package.json declares engines.vscode ^1.100.0, one contributed command extension.helloWorld with the hard-coded title Hello World, main at ./out/extension.js, and scripts compile (tsc -p ./), watch and lint (eslint 9 with typescript-eslint). src/extension.ts registers the command and calls vscode.window.showInformationMessage('Hello World!'); the console.log on activation is for developers and stays English. The same repository's l10n-sample shows the target shape: "l10n": "./l10n" in the manifest, command titles written as %extension.sayHello.title% and resolved from package.nls.json and package.nls.ja.json, strings in code wrapped in vscode.l10n.t('Hello') and vscode.l10n.t('Hello {done}', { done: 'FINISHED' }), a l10n/bundle.l10n.ja.json with the translations, @vscode/l10n-dev as a dev dependency, and a README that gives the commands to export the bundle and to generate a pseudo-locale.
From that the agent makes four changes in helloworld-sample. The command title becomes %extension.helloWorld.title% with the English text in a new package.nls.json, and the manifest gets "l10n": "./l10n". The message in extension.ts becomes vscode.l10n.t('Hello World!'), with a comment for translators where a string's meaning is not obvious from the text. npx @vscode/l10n-dev export -o ./l10n ./src then writes l10n/bundle.l10n.json from the code, which is the file translators work from, and @vscode/l10n-dev joins devDependencies so the export is repeatable from package.json.
Then it adds the first language. The prompt asks for Japanese, so the agent writes package.nls.ja.json and l10n/bundle.l10n.ja.json with the same keys as the English files, in the style of the ja files in l10n-sample, and marks the translation as a draft for a native speaker in the pull request. It also runs npx @vscode/l10n-dev generate-pseudo over the bundle and package.nls.json, which produces qps-ploc files; those are not committed, but the run shows every string gets replaced, which is how a string that was missed in the export shows up.
The proof is in the checks. npm run compile and npm run lint pass, a second l10n-dev export run produces no diff, so the committed bundle matches the code, and the Japanese files parse and carry every key the English ones do, which the agent checks with a short script rather than by eye. The README's running section gains a line on switching VS Code's display language to see the translation, with the pseudo-locale pack as the way to test without one.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Localize this VS Code extension. Read package.json, src/extension.ts, tsconfig.json, eslint.config.mjs and the README first, and use the l10n-sample in this repository as the model. Move every contributed command title to a %key% resolved from a new package.nls.json, add the l10n property to the manifest, wrap every user-facing string in extension.ts in vscode.l10n.t with a comment where the meaning is not obvious, and leave developer console logging in English. Add @vscode/l10n-dev as a dev dependency, export l10n/bundle.l10n.json with it, then add Japanese as the first translation in package.nls.ja.json and l10n/bundle.l10n.ja.json with the same keys, marked as a draft for a native speaker. Run npm run compile and npm run lint, re-run the export to show no diff, generate the pseudo-locale once to show every string is covered without committing those files, check the Japanese files carry every key, document how to see the translation in the README, and open a pull request.",
"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
What comes back is a pull request on its own branch with package.json (the %key% title, the l10n property and the new dev dependency), package.nls.json, package.nls.ja.json, l10n/bundle.l10n.json, l10n/bundle.l10n.ja.json, the vscode.l10n.t call in src/extension.ts, the README line, and the regenerated package-lock.json. The tsconfig.json and the lint config are untouched.
The description lists every string it found and where it went, shows the export command and the empty diff on the second run, and pastes the pseudo-locale output for one string so a reviewer sees the mechanism works end to end. The compile and lint results are in the transcript at GET /o/{org}/sessions/{id}/messages beside the commands.
Before merging, a reviewer asks a Japanese speaker to read the two ja files, runs the extension with the display language set to Japanese or with the pseudo-locale language pack, and decides whether to add the export command as an npm script so the next string is not forgotten. A follow-up message to the same session adds another language with the same keys.
Run it on every Linear issue labelled i18n
A team that tracks localization in Linear starts one run per issue from an automation with a linear trigger on the i18n label. The automation adds the issue after this prompt, so a string the issue points at or a second language it asks for beside Japanese is what the agent reads, and the run starts in the repository the automation names.
Each run opens its own pull request from its own sandbox, and an automation run has its own max_runs_per_hour cap. The pull request links the issue, and its description lists each string and each file so the translator's review is a read of two JSON files.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
The work in localizing an extension is not the API call; it is finding every string, keeping the manifest keys and the bundle keys in step, and proving nothing was missed. The agent does the finding by reading the sources, uses the tooling the repository already demonstrates for the export, and treats a clean second export and a pseudo-localized run as the test, in its own sandbox with the real dev dependencies installed.
The pull request carries that proof in the transcript: the export, the empty diff, the pseudo-locale output and the compile and lint runs sit beside the commands that produced them. Several extensions can be handled at once, each in its own sandbox, with one pull request each.
Frequently asked questions
Does this need a minimum VS Code version?
The vscode.l10n API and the l10n manifest property are part of the VS Code API the l10n-sample in the same repository builds against, and helloworld-sample already declares engines.vscode ^1.100.0, which is above that. The agent checks the engine in package.json and says so in the pull request.
Who writes the Japanese text?
The agent drafts it, following the style of the existing ja files in l10n-sample, and marks it as a draft for a native speaker in the pull request. The structure, the keys and the placeholders are what the run guarantees; the wording is for a reviewer who speaks the language.
How do I test it without speaking the language?
@vscode/l10n-dev generate-pseudo produces qps-ploc files where every string is visibly altered, and VS Code's Pseudo Language Language Pack switches the editor to that locale. The agent runs the generator once to show every string is covered and leaves committing those files to the team.
What about strings in a subprocess the extension spawns?
l10n-sample shows that case with cli.ts and the @vscode/l10n package, passing vscode.l10n.uri to the child process. helloworld-sample spawns nothing, so the pull request notes the pattern and does not add the dependency.