# Add Localization to a Lit Web Component with @lit/localize

Yes. An agent wires @lit/localize into your Lit component in runtime mode, extracts the strings to XLIFF, builds a second locale, adds a locale test, and opens a PR.

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

## What the agent does

The agent starts by finding every string a user reads, because that list is the whole job. In a project like lit/lit-element-starter-ts, `src/my-element.ts` renders a heading from `sayHello(this.name)`, which returns `Hello, ${name}`, and a button that reads `Click Count: ${this.count}`, both inside a `LitElement` with `@customElement` and `@property` decorators on `lit` 3. `tsconfig.json` is strict with `experimentalDecorators`, `rootDir` of `src` and `outDir` at the package root, so `my-element.js` lands beside `package.json` and is what `rollup.config.js`, `dev/index.html` and the Eleventy docs consume. Tests in `src/test/my-element_test.ts` use `@open-wc/testing` and assert the shadow DOM text under `@web/test-runner` in both Lit modes. `npm run lint` runs ESLint and `lit-analyzer` in strict mode.

It installs `@lit/localize` as a dependency and `@lit/localize-tools` as a dev dependency, and writes `lit-localize.json` with `en` as `sourceLocale`, one target locale to prove the path, `tsConfig` pointing at the existing file, `output.mode` set to `runtime`, `output.outputDir` under `src/generated/locales`, `output.localeCodesModule` at `src/generated/locale-codes.ts`, and `interchange.format` set to `xliff` with `xliff` as the directory. Both strings become `msg(str\`Hello, ${name}\`)` and `msg(str\`Click Count: ${this.count}\`)`, with `str` because neither contains markup, and the class gets the `@localized()` decorator so it re-renders when the locale changes. A new `src/localization.ts` calls `configureLocalization` with the generated `sourceLocale` and `targetLocales` and a `loadLocale` that dynamically imports `./generated/locales/${locale}.js`, and exports `getLocale` and `setLocale`.

`lit-localize extract` writes `xliff/es-419.xlf` with two `trans-unit` entries; the agent fills their `target` elements and runs `lit-localize build`, which writes the locale module and the codes module. The `build` script becomes `lit-localize build && tsc` so a clone builds without a manual step, and the generated TypeScript is committed so the test runner and the docs see it. Because `rollup.config.js` bundles to a single `--file` and a dynamic import makes Rollup emit a second chunk, which it refuses to do with `output.file`, the agent sets `inlineDynamicImports` in that config so `npm run docs` and `checksize` keep working, and notes the few hundred bytes the locale adds to the size check.

The test file gains a case that calls `setLocale` with the target locale, awaits it and `updateComplete`, and asserts the translated heading with `assert.shadowDom.equal`, then switches back so the existing tests still see `Hello, World!`. `dev/index.html` gets two buttons that call `setLocale` so a person can see the switch. The agent runs `npm run build`, `npm run lint`, `npm test` in both `dev` and `prod` modes with the Playwright browsers the runner config names, and `npm run docs`, before opening the pull request with a short section added to `README.md` on extracting and building translations.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add localization to this Lit TypeScript component with @lit/localize in runtime mode. Read package.json, tsconfig.json, rollup.config.js, web-test-runner.config.js, web-dev-server.config.js, .eslintrc.json, .gitignore, src/my-element.ts, src/test/my-element_test.ts and dev/index.html first. Install @lit/localize and @lit/localize-tools, write lit-localize.json with en as the source locale and es-419 as a target, runtime output under src/generated/locales with a locale-codes module, and XLIFF interchange in an xliff directory. Wrap the heading and the button label in msg with str templates and add the localized decorator. Add src/localization.ts that calls configureLocalization with a loadLocale that imports the generated modules and exports getLocale and setLocale. Run lit-localize extract, fill in the Spanish targets, run lit-localize build, make the build script run lit-localize build before tsc, and commit the generated files. Set inlineDynamicImports in rollup.config.js so the single-file bundle still builds. Add a test that switches locale and asserts the translated heading, add locale buttons to dev/index.html, run build, lint, test in both modes and docs, then 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 that adds `lit-localize.json`, `src/localization.ts`, `xliff/es-419.xlf` and the two generated files under `src/generated`, and changes `src/my-element.ts`, `src/test/my-element_test.ts`, `dev/index.html`, `rollup.config.js`, `package.json`, `package-lock.json` and `README.md`. The description lists the two message ids, shows the translated shadow DOM from the new test, and gives the before and after numbers from `npm run checksize`.

The run's record holds the extract and build output, the test runs in Chromium, Firefox and WebKit for both Lit modes, the lint run and the docs build, so the claim that nothing else changed is backed by the same suite the repository already trusts.

Before merging, a reviewer decides which target locales to add to `lit-localize.json`, whether the XLIFF files go to translators or stay hand-edited, and whether a `locale` attribute on the element would suit the app better than the exported `setLocale`. The element's public properties and events are unchanged.

## Run it on every component library adding a second language

A team with several component packages starts one run per repository from its own server: one `POST /o/{org}/sessions` each, 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 instead of a second pull request. Each run reads its own templates and wraps the strings that package renders.

Once the setup exists, an automation on the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and the prompt "if this pull request adds user-facing text outside msg, or changes a message so lit-localize extract would add or alter a trans-unit, run the extract and comment with the diff of the xliff directory" catches untranslated strings before merge. The trigger puts the pull request after the prompt; only work by an owner, member or collaborator fires it, never a fork's.

## Why run it on Rush?

Localization setup fails in the tooling before it fails in the component: an untagged template with an expression makes `lit-localize` error, a dynamic import breaks a single-file Rollup build, and generated files that are ignored by git break the first clean clone. The agent runs the extract, the build, the bundle and the tests in its own sandbox, hits each of those in turn and fixes them before the pull request exists.

The sandbox keeps every command and the three-browser test output with the run, and the pull request cites them. For a team with a dozen component packages, each gets its own run, machine and record, and the reviewer reads one list of message ids per package.

## Frequently asked questions

### Why runtime mode rather than transform mode?

Runtime mode ships one build with one small module per locale and switches without a reload, which fits a component that other apps embed and whose locale they choose. Transform mode produces a whole build per locale and the app picks one at load time; it is smaller per locale but means the consumer hosts several bundles. The agent sets runtime mode as asked and notes the alternative.

### Why str on the templates?

`msg` accepts a plain string, an `html` template or a `str` template. The heading and the button each contain an expression and no markup, and `@lit/localize` refuses an untagged template literal with an expression because it cannot tell where the placeholder goes. `str` keeps the expression as a placeholder in the XLIFF file so translators can move it.

### Why commit the generated locale modules?

`tsc` compiles them, the test runner imports them and the docs bundle inlines them, so a clone that lacks them fails three ways. Committing them and running `lit-localize build` as the first step of `npm run build` means both a fresh clone and a stale one end up with the same output. A reviewer who prefers generated files out of git can ignore them and rely on the build script alone.

### Does the existing test suite still pass?

Yes, in both modes. The source locale is `en`, so until `setLocale` is called `msg` returns the original strings and the four existing assertions see `Hello, World!` and `Click Count: 0` as before. The new test switches to the target locale, asserts the Spanish heading and switches back.

## More Lit jobs

- [Add a React Wrapper to a Lit Component](https://getrush.ai/run/add-react-wrapper/lit/)
- [Add an npm Release Workflow to a Lit Component](https://getrush.ai/run/add-release-workflow/lit/)
- [Add Server-Side Rendering to a Lit Component](https://getrush.ai/run/add-ssr/lit/)

## The same job on other stacks

- [Add i18n to an mdBook Site](https://getrush.ai/run/add-i18n/mdbook/)
- [Add i18n to a MkDocs Site](https://getrush.ai/run/add-i18n/mkdocs/)
- [Add i18n to an Obsidian Plugin](https://getrush.ai/run/add-i18n/obsidian-plugin/)

## 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/)
