Three Rules That Made a Service-Business Platform Truly Multilingual

The goal

I built a platform for small service businesses: online booking, estimates, scheduling, invoices, payments. Canada first, so English and French from day one with Spanish behind them. The goal was localization that holds up as the codebase grows, without a translator ever needing to touch backend code.

The approach

Decide where each kind of decision is allowed to live, write that down in the repository's rules file, and let both humans and coding agents read it before they touch anything.

What I built

The backend returns data, not sentences. A label like "customer name, dash, service name" is composed on the frontend from the translation file, because word order, separators, and punctuation change per language. Stored text a user typed is data and comes back unchanged.

// backend
{ customer: { firstName, lastName }, service: { name } }
// frontend, pattern lives in messages/*.json
t('projectLabel', { firstName, lastName, serviceName })

No magic strings in logic. Anything a branch compares against is a named constant declared once, in a shared package when both API and frontend need it. A misspelled literal compiles and simply never matches; an enum member does not.

One component set. Every form control comes from the in-house library, never the browser's native picker, so forms look the same on every operating system. If the wrapper lacks something, extend the wrapper.

The result

The French build reads like French, including PDFs and emails. A whole class of "why does this form look different" reports never gets filed. And the rules file turned out to be the most-read document in the repo, because the coding agents read it on every task.

Takeaways

• Display text belongs with translations, comparisons belong with enums, controls belong in the design system.
• A rule that fits in a paragraph gets followed. Keep the rules file short.
• Build for the third language from the first day and the second one is free.