Localizing an existing React app: lessons from Linguana
Localizing an existing React app involves more than translating strings. Learn how to handle discovery, context, dynamic text, review, and releases.
- Build
The compiler finds text
Missing - Translate
AI under a spend cap
Needs review - Review
People approve or edit
Ready - Publish
A versioned release
Live
Key takeaways
- Existing React applications contain visible text beyond headings and paragraphs.
- Static copy, dynamic messages, and rich text need different treatment.
- A translation should pass review before it becomes a published release.
To localize an existing React app, begin with a complete user journey, identify its visible text, preserve message structure, and test the translated result in the application. Connecting an AI model is only one part of that work.
Building Linguana's compiler, runtime, and review workflow has made several engineering constraints clear. The lessons below come from the architecture and documented behavior in this repository. They are not a customer case study or a claim about an unrecorded migration.
What makes an existing React app difficult to localize?#
An existing application rarely stores every user-facing sentence in one place. A checkout screen can contain headings, field placeholders, validation messages, button labels, image descriptions, and accessible names. A screenshot alone does not reveal all of them.
The first lesson is to inventory the experience before choosing a translation provider. Include loading, empty, error, and success states. Write down which text comes from source code and which arrives through an API. They need different discovery paths.
Static text and dynamic messages are different jobs#
A literal heading is a straightforward extraction candidate. A message containing a quantity, date, or person's name also carries structure. Translating sentence fragments independently can put words in the wrong order or leave a variable without the context needed to interpret it.
Linguana discovers supported static text during a build. Messages with values use explicit APIs, and rich text uses explicit handling. That is why we describe the product as avoiding translation keys for static copy, rather than promising zero code changes throughout an application.
import { useTranslation } from "react-i18next";
export function Hero() {
const { t } = useTranslation("home");
return <h1>{t("hero.title")}</h1>;
}// locales/en/home.json
{ "hero": { "title": "Plan your next trip" } }export function Hero() {
return <h1>Plan your next trip</h1>;
}The compiler finds “Plan your next trip” at build time. No key, no locale file, no wrapper.
Keep a complete message together when it contains a value. Explain what the value represents. Preserve placeholders through translation and reject output that changes the message contract. Review plural behavior in the target locale rather than assuming English's singular and plural patterns apply everywhere.
Context is part of the message#
The word “Open” can describe an action or a state. A translator needs to know which meaning applies. A nearby source file name alone does not always answer the question.
Linguana's context profiles describe product knowledge, audience, tone, and locale conventions. Glossaries give required terms a defined form. These are inputs to the translation workflow, not decorations added after the text is generated.
This also affects reuse. Identical wording does not always mean identical intent. Safe translation-memory reuse needs compatible context and glossary rules. The objective is to reuse a valid decision without silently applying it to a different meaning.
Saving a translation and publishing it are separate decisions#
A reviewer needs space to edit wording without changing the live application immediately. In Linguana, saving wording creates a version. Publication selects a catalog release, and an earlier release remains available for restoration.
- v12French and SpanishMonLive
- v13Arabic addedWedDraft
- v14Pricing copy editsFriDraft
Every release is an immutable catalog version.
Test that separation during your pilot. Save a change, confirm the published application still uses the previous release, then publish deliberately. Finally, restore the earlier release and check the result. An operational recovery path belongs in the evaluation.
Test the layout, not only the text#
A translation can be structurally valid and still make a button difficult to use. Longer wording reveals fixed-width assumptions. Right-to-left layouts expose problems that an English screenshot cannot show.
Use actual translations in the running screen. Check wrapping, focus order, dialogs, form errors, and accessible labels. Review formatting for dates, numbers, and currency. Do not replace a real-language review with a single visual spot check.
Start with one flow and a bounded budget#
Choose a flow that includes enough variation to reveal problems without making the first integration unmanageable. Onboarding is often useful because it combines instructions, inputs, errors, and completion states.
Run local discovery first. Review the extracted text, configure one target language, and inspect the estimate before starting paid translation. Linguana's framework setup and CLI introduction explain the integration paths.
Success means a user can complete the translated flow and your team can safely update it. Record what the compiler misses, what requires explicit handling, and what a reviewer changes. Those observations give you a concrete basis for expanding localization across the application.