John De Goes’ blog

---

This started with a very specific ask to our architecture persona: find a way to add English, Spanish, Portuguese, and French to the UI, with as little friction as possible and no new spend.

The constraints were clear:

• Reuse our existing Next.js + TypeScript stack
• Keep it zero-cost
• Make it simple enough to maintain as a small team

Personas as our operating system

We run through explicit personas rather than generic titles.

• Jeff represents product leadership, responsible for turning goals into well-scoped, testable work
• Chuck owns architecture, finding the simplest solution that fits our stack and risk profile
• Alice is CTO, guarding system coherence as new capabilities come in
• Mike is lead engineer, focused on surgical changes and zero-regression engineering
• Antoine is head of translations, an expert linguist across English, Spanish, Portuguese, and French with a legal/financial lens

This structure lets us talk clearly about product, UX, DevOps, AI, and quality without stepping on each other’s toes.

The technical call: local JSON + next-intl

Chuck proposed a deliberately simple strategy:

• Keep all translations as local JSON files in the repo
• Use Next.js App Router with next-intl for locale handling, messages, and formatting
• Use English as the source language, with separate message files for Spanish, Portuguese, and French
• Avoid any paid localization platform and keep everything inside the existing codebase and deployment flow

He considered the “no-library” route, but for the number of screens we have, next-intl gave us better ergonomics while staying free and lightweight.

From architecture to execution with agents

Once we had Chuck’s recommendation, I asked Jeff to turn it into two things: a detailed engineering task and an instruction set for our coding agent, tailored for Mike.

Jeff responded with:

• A ticket describing the goal (UI in four languages), scope (core UI surfaces only), non-goals (no usernames/IDs, no SEO project, no new SaaS), and acceptance criteria
• A prompt for Claude Code instructing “Mike” to add next-intl, wire up en/es/pt/fr, integrate Antoine’s translations, add a Settings language selector, persist the chosen locale, and ship it all in a new branch with a PR

Antoine’s role was explicitly embedded: his reviewed translations are the primary source wherever they exist; AI-generated text is only a first draft, never the final word on sensitive copy.

One prompt, one branch, one day

I then ran Jeff’s instructions in Claude Code. From there, the flow was straightforward:

1. The agent inspected the App Router layout and existing copy patterns
2. It added next-intl and four message files for English, Spanish, Portuguese, and French
3. It mapped Antoine’s translations into the JSON dictionaries, leaving English as fallback where needed
4. It replaced hardcoded strings in the scoped UI with translation keys, added a Settings language selector, and wired up locale persistence
5. It pushed a feature branch, ran checks, and opened a PR summarizing changes and listing remaining English fallbacks

All of this landed in a single day, fully within our existing repository and workflows.

QA loops: human judgment, sharper prompts

We didn’t treat QA as a final gate; we treated it as a feedback engine.

• I manually tested the product in English, Spanish, Portuguese, and French, checking layout, clarity, and sensitive copy
• I reported findings back to Jeff and Chuck in our Perplexity space
• They refined the instructions for Claude Code—highlighting edge cases, tightening wording expectations, and calling out layout or truncation issues
• The agent iterated on the same branch, pushing targeted fixes

This loop—manual QA → refined instructions → code updates—let us keep quality high without slowing down the overall delivery.

What this says about how we build

Localization was the test case, but the underlying pattern is what matters:

• We start from constraints (languages, cost, speed) rather than from tools
• We use personas to keep ownership crystal clear across product, architecture, translation, engineering, and QA
• We put AI inside the process, not above it: product frames the work, agents write code, humans test and refine
• We treat localization as engineering, with proper keys, scope, and acceptance criteria—not as an afterthought

Four languages, one day, zero new platforms.
That’s the standard we’re holding ourselves to as we continue building.