All jobs

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

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

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

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

The same job on other stacks

Keep reading