# Add i18n with Gettext to a Phoenix LiveView App from a Linear Issue

Yes. An agent reads the labelled Linear issue, wraps your LiveView templates in gettext, extracts the .pot, sets the locale from settings or the browser, opens a PR.

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

## What the agent does

The agent starts from the Linear issue and the repository in its own sandbox and measures how much of the app already speaks Gettext, because Phoenix generates the plumbing but not the use of it. In an app like fly-apps/live_beats, `lib/live_beats_web/gettext.ex` defines `LiveBeatsWeb.Gettext` with `use Gettext, otp_app: :live_beats`, `lib/live_beats_web.ex` imports it into every view, component and LiveView, and `gettext` 0.20.0 is locked in `mix.lock` beside Phoenix 1.7.12. Yet `priv/gettext/` holds only `errors.pot` and `en/LC_MESSAGES/errors.po`, and the single call in a template is `ngettext("%{count} song", "%{count} songs", @songs_count)` in `lib/live_beats_web/live/profile_live.ex`. Everything else is a literal: Sign in to your account and Sign in with GitHub in `sign_in_live.ex`, Profile Settings, Username and Email (from GitHub) in `settings_live.ex`, Listen, Stop Listening, Upload Songs and No music in `profile_live.ex`, Close sidebar in `layouts/live.html.heex`, the Settings and Sign out links in `layouts.ex`, and the labels inside `core_components.ex`.

It wraps those strings, and the ones in the components, in `gettext` and `ngettext`, keeping interpolations as `%{name}` bindings so word order can change per language, and runs `mix gettext.extract --merge` to produce `priv/gettext/default.pot` and `en/LC_MESSAGES/default.po`. For the locale the issue names it adds `priv/gettext/<locale>/LC_MESSAGES/default.po` and `errors.po`; where the issue supplies translations it fills them in, and where it does not it leaves `msgstr` empty and says so, since Gettext falls back to the source string. `config/dev.exs` already lists `priv/gettext/.*(po)$` among live-reload patterns, so edits to translations reload in development without a change there.

Then it decides where the locale comes from, which is the part a LiveView app gets wrong most often. A plug in the `:browser` pipeline of `router.ex` reads `accept-language` and stores the choice in the session, and because a LiveView runs in its own process after the WebSocket connects, an `on_mount` hook added next to `LiveBeatsWeb.UserAuth` and `LiveBeatsWeb.Nav` in both `live_session` blocks calls `Gettext.put_locale/2` from the session on every mount. Since the app has accounts, the issue's preferred source is the user: the agent adds a `locale` field to the `users` schema in `lib/live_beats/accounts/user.ex` with a migration, a select next to `username`, `email` and `profile_tagline` in the settings form, and the hook prefers the user's choice over the browser's. `root.html.heex` gets `lang` from the current locale instead of the hard-coded `en`.

To check it, the agent runs `mix format`, starts a PostgreSQL server in its sandbox because the `test` alias in `mix.exs` runs `ecto.create` and `ecto.migrate` before the suite, sets placeholder values for `LIVE_BEATS_GITHUB_CLIENT_ID` and `LIVE_BEATS_GITHUB_CLIENT_SECRET`, which `config/dev.exs` fetches at boot, and runs `mix test`. It adds LiveView tests beside `settings_live_test.exs` that mount a view with the new locale and assert on a translated string, and one for the settings form saving the locale.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "A Linear issue labelled agent says: \"Add i18n to the app. Wrap all user-facing strings in the LiveViews, layouts and components with Gettext, add a pt_BR locale, and let a signed-in user pick their language in settings, falling back to the browser's Accept-Language.\" Do the work in this repository: read lib/live_beats_web.ex, lib/live_beats_web/gettext.ex, the live views, layouts and core components, and the settings form first. Extract and merge the .pot and .po files, add the locale field and migration, set the locale in a plug and in an on_mount hook for the live sessions, set the html lang attribute from it, add tests, run mix test, and open a pull request that links back to the issue.",
  "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 links the issue and touches the templates and components where strings lived, adds `priv/gettext/default.pot`, the `en` and new-locale `.po` files, a migration and the `locale` field on the user schema, the settings select, a locale plug, an `on_mount` hook wired into both `live_session` blocks, the `lang` attribute in the root layout, and tests. The `errors` domain files the app already had are merged, not replaced.

The description counts the strings it wrapped per file, lists any it left alone on purpose, such as the GitHub provider name, and says which translations are filled and which are empty and why. It quotes the `mix test` summary from its sandbox and notes the one manual step: a user with no saved locale sees the browser's language until they choose one in settings.

Before merging, a reviewer reads a handful of wrapped strings for interpolation mistakes, checks the migration's default for existing users, and opens the settings page in the new locale to see the select, the saved choice and the translated title bar.

## Run it on every Linear issue labelled i18n

In the console, an automation in the Project with a `linear` trigger on `linear.issue.labeled` and the label `i18n` starts one run per labelled issue, with the issue added after the saved prompt and the Project's repository cloned. The trigger fills in no placeholder; the saved prompt says to do what the issue describes and open a pull request that links back. Changes made by an app integration never fire it, so the agent's own updates to the issue start nothing, and an automation's runs are capped by its own `max_runs_per_hour`.

A second issue for the next locale is one more label: the run finds the `.pot` already extracted, adds one `.po` directory, fills what the issue gives it, runs the suite and opens its own pull request, with the transcript showing exactly which files it touched.

## Why run it on Rush?

Internationalising a LiveView app is mostly diligence, wrapping every string without breaking an interpolation, plus one piece of knowledge: the locale set in a plug does not reach the LiveView process, so it must be set again on mount. The agent reads the router, the live sessions and the existing hooks before it writes, and the tests it adds mount a view in the new locale rather than only checking the plug.

On Rush the extraction, the migration and the full suite run in the agent's own sandbox with a real database, and the transcript keeps the commands and their output next to the diff, so a reviewer can see that `mix test` passed before reading a single wrapped string. Several locales or several apps can each have their own run and their own pull request.

## Frequently asked questions

### Why is a plug not enough to set the locale?

The plug sets it for the HTTP request that renders the first page. The LiveView then connects over a WebSocket and runs in a new process, where the locale is the default again. The `on_mount` hook reads the session the plug wrote and calls `Gettext.put_locale/2` in that process, so every render after the connect is translated.

### What happens to strings with no translation yet?

Gettext returns the source string, so an empty `msgstr` shows the English text rather than a blank. The pull request says which entries are empty, and filling them is an edit to one `.po` file that live-reloads in development.

### Does it translate the existing errors domain?

It merges it. `mix gettext.extract --merge` updates `errors.pot` and `en/LC_MESSAGES/errors.po` alongside the new `default` domain, and the new locale gets an `errors.po` too, so changeset messages can be translated the same way as the templates.

### Where does a signed-out visitor's language come from?

From the `accept-language` header, read by the new plug and narrowed to the locales the app ships; anything else falls back to `en`. A signed-in user's saved choice wins over the header, and the sign-in page itself is translated from the header before any account exists.

## More Phoenix LiveView jobs

- [Add Prometheus Metrics to a Phoenix LiveView App](https://getrush.ai/run/add-prometheus-metrics/phoenix-liveview/)
- [Add Live Search to a Phoenix LiveView Page from a Linear Issue](https://getrush.ai/run/add-song-search/phoenix-liveview/)
- [Add Structured Logging to a Phoenix LiveView App](https://getrush.ai/run/add-structured-logging/phoenix-liveview/)

## The same job on other stacks

- [Add i18n to a React App from a Linear Issue](https://getrush.ai/run/add-i18n/react/)
- [Add i18n to a React Router App](https://getrush.ai/run/add-i18n/react-router/)
- [Add Translations to a SolidJS App With @solid-primitives/i18n](https://getrush.ai/run/add-i18n/solidjs/)

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