All jobs

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

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

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

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

The same job on other stacks

Keep reading