# Add i18n to an AdonisJS App

Yes. An agent installs @adonisjs/i18n, moves your Edge and validation strings into language files, adds a locale middleware and tests, and opens a PR.

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

## What the agent does

The agent starts from what the app renders today, because the strings it has to move live in templates, validators and one middleware, not in a single file. In an app made from the `hypermedia` kit in adonisjs/starter-kits, `package.json` is on `@adonisjs/core` 7.5, `@adonisjs/auth` 10, `@adonisjs/session` 8, `@adonisjs/shield` 9, `@vinejs/vine` 4 and `edge.js` 6, with `engines.node` at 24 or later and a `pnpm-lock.yaml` at lockfile version 9. `adonisrc.ts` lists the providers and four preloads (`#start/routes`, `#start/kernel`, `#start/validator`, `#start/view`), and `start/kernel.ts` runs bodyparser, session, shield, `initialize_auth_middleware` and the kit's own `silent_auth_middleware` on every routed request. There is no i18n provider, no `resources/lang` directory and no locale anywhere: every layout under `resources/views/components/layouts` hard-codes `<html lang="en-us">`.

Then it lists the strings. `pages/home.edge` has the welcome copy and three link rows, `pages/auth/login.edge` and `signup.edge` have titles, subtitles, field labels, placeholders and the button text that Alpine swaps for "One moment…" while submitting, `pages/dashboard.edge` has the empty-state heading, `components/layouts/app.edge` builds its nav from `@let(nav = [{ label: 'Dashboard', ... }])`, and `theme_toggle.edge` carries two `aria-label` variants. Validation text is separate: `app/validators/user.ts` defines `signupValidator` and `loginValidator` with `email().maxLength(254)`, a password of 8 to 32 characters, `sameAs('password')` and a `unique` check on `users.email`, and `components/field/error.edge` prints whatever message VineJS produced, in English, from `$context.errors`.

The agent runs `node ace add @adonisjs/i18n`, which registers `@adonisjs/i18n/i18n_provider` in `adonisrc.ts`, adds a `metaFiles` entry for `resources/lang/**/*.{json,yaml,yml}` so the build copies the files, writes `config/i18n.ts` and `app/middleware/detect_user_locale_middleware.ts`, and adds that middleware to `router.use` in `start/kernel.ts`. It sets `defaultLocale` to `en`, `formatter` to `formatters.icu()`, `loaders` to `loaders.fs({ location: app.languageFilesPath() })` and `supportedLocales` to the locales the prompt names. It writes `resources/lang/en/messages.json` with keys grouped by template (`home.lead`, `auth.login.title`, `auth.signup.submit`, `layout.logout`), fills the same keys for each new locale, and replaces each literal in Edge with `{{ t('messages.auth.login.title') }}`. The `lang` attribute becomes `{{ i18n.locale }}`. The middleware's `getRequestLocale` reads `Accept-Language` by default; the agent makes it read an `app_locale` cookie first, so the small language switcher it adds beside the theme toggle in `marketing.edge` and `app.edge` can set one with a `POST /locale` route.

Validation gets its own file. `resources/lang/en/validator.json` carries a `shared` block with `fields` for `email`, `password`, `fullName` and `passwordConfirmation` and `messages` for `required`, `email`, `minLength`, `maxLength`, `sameAs` and `database.unique`, so the `{field}` placeholder renders the translated field name. The middleware already sets `RequestValidator.messagesProvider` to `ctx.i18n.createMessagesProvider()`, so `request.validateUsing(loginValidator)` in `session_controller.ts` picks the right language with no controller change. Finally the agent writes `tests/functional/i18n.spec.ts` with Japa: a `GET /login` with `Accept-Language: fr` must contain the French title, a `POST /signup` with a bad email and the same header must contain the French `email` message, and a request with an unsupported language must fall back to English. It runs `pnpm install`, `pnpm lint`, `pnpm typecheck` and `node ace test functional` in its sandbox before opening the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add internationalization to this AdonisJS app with @adonisjs/i18n, with English as the default locale and French as the second one. Read package.json, adonisrc.ts, start/kernel.ts, start/routes.ts, app/validators/user.ts, app/controllers, resources/views and tests/bootstrap.ts first. Run node ace add @adonisjs/i18n, set supportedLocales to en and fr in config/i18n.ts, move every user-facing string in the Edge templates and layouts into resources/lang/en/messages.json with keys named after the template they come from, translate them into resources/lang/fr/messages.json, replace the literals with t() calls, set the html lang attribute from the current locale, and add a validator.json for both locales covering the fields and rules used in app/validators/user.ts. Make detect_user_locale_middleware prefer an app_locale cookie over Accept-Language and add a POST /locale route plus a small switcher next to the theme toggle. Write Japa functional tests for the French login page, a French validation error and the English fallback. Run pnpm lint, pnpm typecheck and node ace test functional, and open a pull request that lists every string you moved. Do not change the auth flow or any route name.",
  "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

The pull request adds `config/i18n.ts`, `app/middleware/detect_user_locale_middleware.ts`, `resources/lang/en/messages.json`, `resources/lang/en/validator.json`, their `fr` counterparts and `tests/functional/i18n.spec.ts`; it edits `adonisrc.ts`, `start/kernel.ts`, `start/routes.ts`, the layouts and pages under `resources/views`, and `package.json` with its lockfile. The description is a table of every key with the English text it replaced and the file it came from, followed by the lint, typecheck and test output.

A reviewer reads the French strings, since the agent is translating and a native speaker should confirm tone and the ICU plural forms. They also check that the switcher's cookie uses the same `path` and `samesite` settings as the theme cookie in `resources/js/app.js`, that no `t()` key is missing (a missing one renders as `translation missing: fr, messages.…`, which the tests would surface), and that `supportedLocales` lists only locales with a complete `messages.json`.

## Run it on every Linear issue labelled i18n

An automation on the Project with a `linear` trigger on `linear.issue.labeled` and `i18n` among its labels runs this prompt whenever a localization issue is labelled, with the issue appended after the prompt. The agent reads the locale from the issue ("Add Spanish" adds `es` to `supportedLocales` and writes `resources/lang/es`), so the prompt text stays the same across languages. The automation starts at most `max_runs_per_hour` runs in an hour, and an edit made by a Linear app integration does not fire it.

A team adding the first locale to several apps made from the same kit sends this body once per repository from its own server, 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 it already started. Each run reads its own templates: an app with extra pages gets extra keys, and one that already has `resources/lang` gets the new locale added to it rather than a second setup.

## Why run it on Rush?

The move from literals to keys touches every template and is easy to get subtly wrong on a laptop: one forgotten string stays English in one language, one key typo renders a `translation missing` message in production. In its sandbox the agent runs the real `node ace add` codemods, boots the app and asserts each page in each locale with Japa, so the pull request arrives with that evidence and not a promise.

The run keeps every command and its output: the install, the generated middleware, the lint and typecheck runs, the test results. A reviewer who wants to know why a string was keyed a certain way can read the step that did it, and the same request runs across every AdonisJS app a team owns at once.

## Frequently asked questions

### Does it change URLs to add a locale prefix?

No. The locale is detected per request from the `app_locale` cookie and then `Accept-Language`, which is what `detect_user_locale_middleware` is for, so `/login` stays `/login` in every language and no route in `start/routes.ts` is renamed. A prefixed scheme such as `/fr/login` is a routing change the prompt leaves out.

### Are validation errors translated too?

Yes. The middleware the package generates sets `RequestValidator.messagesProvider` to `ctx.i18n.createMessagesProvider()`, so every `request.validateUsing` call reads `resources/lang/<locale>/validator.json`. The agent fills the `shared.fields` and `shared.messages` blocks for the rules `app/validators/user.ts` uses, and the `{field}` placeholder resolves to the translated field name.

### Can I use YAML instead of JSON for the language files?

Yes. The `fs` loader reads `.json`, `.yaml` and `.yml`, and the `metaFiles` pattern the add command writes already covers all three; YAML needs the `yaml` package installed. The agent writes JSON because the kit has no YAML dependency, and converting later is a file rename plus that one install.

### What happens for a browser that asks for a language I do not support?

The request falls back to `defaultLocale`, `en`. A regional tag such as `fr-CA` resolves to `fr` when `fr` is supported, and `fallbackLocales` in `config/i18n.ts` can map one locale to another explicitly. One of the tests sends an unsupported `Accept-Language` and asserts the English page.

### Does the theme toggle keep working?

Yes. The toggle's logic is in `resources/js/app.js` and the `app_theme` cookie; only its two `aria-label` strings move into `messages.json`, rendered through `t()` in `theme_toggle.edge`. The locale switcher the agent adds uses the same pattern, a form that posts to `/locale` and sets its own cookie.

## More AdonisJS jobs

- [Add Password Reset to an AdonisJS App](https://getrush.ai/run/add-password-reset/adonisjs/)
- [Add Rate Limiting to an AdonisJS API](https://getrush.ai/run/add-rate-limiting/adonisjs/)
- [Add Request ID Logging to an AdonisJS App](https://getrush.ai/run/add-request-id-logging/adonisjs/)

## The same job on other stacks

- [Add i18n to an Angular App](https://getrush.ai/run/add-i18n/angular/)
- [Add a Second Language to an Astro Site](https://getrush.ai/run/add-i18n/astro/)
- [Add i18n to a Blazor Web App](https://getrush.ai/run/add-i18n/blazor/)

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