All jobs

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 RushOpens 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}`)andmsg(str`Click Count: ${this.count}`), with strbecause neither contains markup, and the class gets the@localized()decorator so it re-renders when the locale changes. A newsrc/localization.tscallsconfigureLocalizationwith the generatedsourceLocaleandtargetLocalesand aloadLocalethat dynamically imports./generated/locales/${locale}.js, and exports getLocaleandsetLocale`.

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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading