What the agent does
The agent starts from the issue text and the repository in its own cloud sandbox, and maps where the user-facing strings live before it adds a library, because an i18n pull request that translates one screen and leaves the rest is worse than none. In an app like the apps/react-vite application in alan2207/bulletproof-react, package.json runs Vite with vitest, playwright, eslint 8 and tsc, and nothing named i18n or intl appears in dependencies. src/main.tsx renders App from src/app/index.tsx, which composes AppProvider (React Query, an ErrorBoundary, HelmetProvider and AuthLoader) around AppRouter, whose routes come from src/config/paths.ts. The strings are in the feature components: src/features/auth/components/login-form.tsx labels its inputs Email Address and Password and its button Log in, the register form beside it does the same for its fields, src/components/layouts/dashboard-layout.tsx names the side navigation items, src/app/routes/landing.tsx carries the welcome copy and a Get started button, and src/lib/auth.tsx holds the zod messages Required and Invalid email that the form shows under a field.
The agent installs i18next, react-i18next and i18next-browser-languagedetector, adds src/lib/i18n.ts that initialises i18next with English as the fallback and the detector reading localStorage then the browser language, and imports it once from src/main.tsx before App renders. Locale files go under src/locales/en/ and src/locales/<second language>/ as JSON namespaces per feature (auth, navigation, landing, validation), and the Vite config needs no plugin because the JSON is imported statically. It then replaces the literals: useTranslation('auth') in the login and register forms, t('navigation.dashboard') and its siblings in the layout, the landing copy, and the zod messages in src/lib/auth.tsx, which become keys resolved at render through the form's error display in src/components/ui/form. A small language switcher goes into the dashboard layout's user dropdown next to the existing sign-out item.
The repository's own rules shape where files go. The .eslintrc.cjs enforces import/no-restricted-paths zones so a feature may not import from another feature, which is why the i18n setup lives in src/lib and the locale files in src/locales, both importable from anywhere. Tests follow src/testing/setup-tests.ts and src/testing/test-utils.tsx: the agent extends renderApp so the i18n instance is initialised with English before rendering, keeps the existing login-form.test.tsx green by matching the same visible labels, and adds a test that switches the language and asserts the login button text changes. Then it runs the five steps of .github/workflows/react-vite-ci.yml in order: yarn build, yarn test, yarn lint, yarn check-types, and the Playwright yarn test-e2e against the mock server with .env.example-e2e.
The pull request links back to the Linear issue, lists every file whose strings moved and every string that did not, and flags the strings it could not safely extract, such as text built from API data in src/features/discussions, so the reviewer can decide whether to follow up.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "A Linear issue labelled agent says: \"Add internationalisation to the web app with react-i18next. Start with the auth forms, the navigation, the landing page and the form validation messages, add a language switcher, and keep English as the default.\" Read package.json, src/main.tsx, src/app/index.tsx, src/app/provider.tsx, src/app/router.tsx, src/config/paths.ts, src/lib/auth.tsx, src/features/auth/components/login-form.tsx and register-form.tsx, src/components/layouts/dashboard-layout.tsx, src/app/routes/landing.tsx, .eslintrc.cjs, src/testing/setup-tests.ts, src/testing/test-utils.tsx and .github/workflows/react-vite-ci.yml first. Install i18next, react-i18next and i18next-browser-languagedetector, add src/lib/i18n.ts initialised once from src/main.tsx with English as fallback, and put locale JSON under src/locales with one namespace per feature. Replace the literals in those files with t() calls, resolve the zod messages in src/lib/auth.tsx through translation keys, and add a language switcher to the dashboard layout's user menu. Keep the import zones in .eslintrc.cjs satisfied. Update src/testing/test-utils.tsx so renderApp initialises i18n, keep the existing login form test passing, and add a test that switches language and checks the login button label. Run yarn build, yarn test, yarn lint, yarn check-types and yarn test-e2e as the CI workflow does, paste the outputs in the pull request, and list the strings you left untranslated and why. Open a pull request that links the issue.",
"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 with three new dependencies in package.json and yarn.lock, src/lib/i18n.ts, a src/locales tree with two languages and four namespaces each, edits to the login and register forms, the dashboard layout, the landing route and src/lib/auth.tsx, the extended renderApp in src/testing/test-utils.tsx, and one new test. The description shows the output of each CI step from the sandbox, the Playwright run against the mock server, and a list of strings left in place with the reason for each.
The repository's React Vite CI workflow runs the same build, test, lint, type-check and end-to-end steps on the pull request. A reviewer checks that the namespaces match the feature boundaries the lint rules enforce, that the fallback language renders every key so a missing translation never shows a raw key, that the language detector reads localStorage before the browser setting so a user's choice sticks, and that the zod messages still appear under the right field. Then they merge and hand the second locale's JSON to a translator.
Run it on every Linear issue labelled agent
In the console, an automation with a linear trigger on linear.issue.labeled and the label agent starts one run per labelled issue, with the issue as its context, in the Project's repository. Changes made by an app integration never fire it, so the agent's own updates to the issue do not start new runs.
From your own server, the same run is one POST /o/{org}/sessions per issue: put the repository in resources, and add the issue's https://linear.app/<workspace>/issue/<ID> URL there too to have Rush read it through your Linear connection into the prompt. The key's webhook_url posts run.completed or run.failed when the turn finishes, with the session_url to read the result.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
Adding i18n is mostly careful, repetitive work: find every literal, choose a key, keep the tests that match on visible text passing, and not break the import rules a repository enforces. In a Rush sandbox the agent runs the full CI sequence including the Playwright suite against the mock server, and every command's output is kept in the transcript, so the pull request shows that the build, the unit tests, the lint zones and the end-to-end flows all still pass with the strings moved.
Starting from a Linear label means the issue becomes a reviewable pull request without a developer blocking a day on it. The same request works on any Vite React app; the agent reads that app's own component tree and lint configuration and puts the setup where that repository's rules allow.
Frequently asked questions
Why react-i18next rather than FormatJS or Lingui?
Because it needs no compile step or Vite plugin, which keeps vite.config.ts unchanged, and its useTranslation hook fits a codebase that already organises components by feature. The prompt names it; if your team prefers another library, change that line and the agent reads that library's setup instead.
Will the existing tests break?
The login form test looks up Email Address and Log in by label and role. The agent initialises i18n with English inside renderApp in src/testing/test-utils.tsx, so those labels render exactly as before and the test passes unchanged. The new test switches the language and asserts the button text changes, which guards the wiring.
What about strings that come from the API?
Discussion titles, comment bodies and user names are data, not UI copy, and the agent leaves them alone. It lists them in the pull request so the reviewer sees the boundary. Dates formatted with dayjs in src/utils/format.ts are called out as a follow-up, since locale-aware formatting is a separate change.
How does the import zone rule affect this?
The .eslintrc.cjs forbids a feature importing from another feature and keeps src/app above src/features. The i18n instance in src/lib and the locale JSON in src/locales sit outside every zone, so any feature may import them and yarn lint stays clean, which the CI step in the pull request shows.
More Vite + React jobs
The same job on other stacks
- Localize a VS Code Extension (VS Code Extension)
- Add i18n to a Vue 3 App from a Linear Issue (Vue)
- Add a Second Language to a Zola Site (Zola)