# Localize a VS Code Extension

Yes. An agent moves your VS Code extension's command titles and messages to package.nls.json and vscode.l10n, adds a translation, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-i18n/vscode-extension/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

## 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.

## More VS Code Extension jobs

- [Add Keyboard Shortcuts to a VS Code Extension](https://getrush.ai/run/add-keybindings/vscode-extension/)
- [Add Output Channel Logging to a VS Code Extension](https://getrush.ai/run/add-output-channel-logging/vscode-extension/)
- [Add a Release Workflow for a VS Code Extension](https://getrush.ai/run/add-release-workflow/vscode-extension/)

## The same job on other stacks

- [Add i18n to a Vue 3 App from a Linear Issue](https://getrush.ai/run/add-i18n/vue/)
- [Add a Second Language to a Zola Site](https://getrush.ai/run/add-i18n/zola/)
- [Add i18n to an AdonisJS App](https://getrush.ai/run/add-i18n/adonisjs/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
