"We should support Spanish" is a sentence that strikes fear into engineering teams. Not because translation is conceptually hard, but because retroactively adding language support to an app built entirely in English feels like it requires rearchitecting everything.
It doesn't. At least, not all at once.
There's a pragmatic middle ground between "English only" and "fully localized in 40 languages." Most teams never find it because the discussion jumps straight from "we need Spanish" to "okay, let's implement i18n across the entire codebase." That's a months-long project. There are faster ways to start.
Start With the Content, Not the UI
The typical internationalization approach starts with the UI framework. Extract every string into a translation file. Set up locale routing. Configure date and number formatting. This is the right end state, but it's the wrong starting point for most teams.
Start with user-facing content instead. The parts of your application where language actually matters to the user experience. Product descriptions. Help articles. Email notifications. Error messages. Onboarding flows.
These are the places where a non-English speaker hits a wall. They might tolerate an English navigation bar—button labels are often recognizable across languages. But a help article that explains a critical feature? An error message that tells them what went wrong? Those need to be in their language.
Translating content is a much smaller, more contained project than internationalizing an entire UI framework. And it delivers most of the user value.
Machine Translation Has Gotten Good
Five years ago, machine translation was a punchline. Google Translate could turn a French restaurant menu into surrealist poetry. Professional human translators were the only serious option.
That's changed. Modern machine translation handles most European and major Asian languages well. It's not perfect—it struggles with idioms, cultural references, and highly technical jargon. But for straightforward content like product descriptions, support articles, and transactional emails, the quality is genuinely usable.
The key is knowing where machine translation works and where it doesn't.
It works well for: factual content, technical documentation, transactional messages (order confirmations, shipping notifications), knowledge base articles, and structured data with predictable patterns.
It works poorly for: marketing copy that relies on wordplay, legal documents where precision is critical, creative content that depends on cultural context, and anything where tone is as important as meaning.
For the first category, machine translation gets you 80-90% of the way there. For the second, you still need human translators—but that's a much smaller volume of content.
Detect Before You Translate
Before you translate anything, you need to know what language your users actually want. Guessing wrong is worse than not translating at all. There are several signals.
Browser language headers are the most reliable automatic signal. Every HTTP request includes an Accept-Language header that lists the user's preferred languages. If the header says es-MX,es;q=0.9,en;q=0.8, the user prefers Mexican Spanish, then general Spanish, then English.
Account settings let users explicitly choose. This is the gold standard—direct user preference. But it only works for logged-in users who've configured their settings.
Content language detection handles user-generated input. When a user submits a support ticket or fills out a form, detecting the language of their text tells you how to respond. If they wrote in Portuguese, respond in Portuguese.
Geographic signals are a rough proxy. A user in Japan probably prefers Japanese. But this fails for expatriates, travelers, and multilingual countries like Switzerland or India. Don't force language based on location—use it as a default that users can override.
The pragmatic approach layers these signals: use account settings if available, fall back to browser headers, and detect content language for user-generated text.
What to Translate First
You can't translate everything at once. So what earns priority?
Onboarding flows are the highest priority. A user who can't understand the signup process won't become a user. If your signup, login, and initial setup are translated, you capture users who would otherwise bounce.
Transactional emails come next. Order confirmations, password resets, billing notifications—these are messages users need to understand to use your service. A password reset email in a language you don't read is useless.
Error messages might be third. Think about how frustrating it is to get an error you can read. Now imagine it's in a language you don't understand. If a payment fails and the error message is in English, a Spanish-speaking user has no idea what to do next. Translated errors reduce support ticket volume significantly.
Help documentation and support articles address self-service. If users can find answers in their language, they don't need to contact support. This scales better than hiring multilingual support staff.
Marketing pages are last in priority but first in visibility. Your homepage and pricing page are what prospective users see. But prospects who don't read English probably found you through localized search results, which means they need localized landing pages.
The Translation API
Translating content programmatically keeps the process automated:
const response = await fetch('https://api.apiverve.com/v1/translator', {
method: 'POST',
headers: {
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
text: 'Your payment was processed successfully.',
target: 'es'
})
});
const { data } = await response.json();
// data.translatedText → "Su pago fue procesado exitosamente."
// data.sourceLang → "en"
Notice the source parameter is optional. When omitted, the API auto-detects the source language. This is useful when processing user-generated content where you don't know what language they wrote in.
Storing Translations
Where do translated strings live? This depends on your architecture.
Alongside the original content is simplest. If your product descriptions are in a database, add a locale column and store translated versions as separate rows. Same content ID, different locale.
In translation files works for UI strings. JSON files keyed by locale (en.json, es.json, fr.json) are the standard i18n approach. Most frontend frameworks have built-in support for this pattern.
Generated on the fly works for content that changes frequently or where the translation doesn't need to be perfect. Real-time translation of support chat messages, for example. The user sees the translation immediately, even if it's not hand-polished.
Cached after first translation balances cost and freshness. Translate content the first time it's requested in a given language, cache the result, and serve from cache thereafter. This limits API calls while keeping translations available.
The right approach often combines these. Static UI strings in translation files. Database content with locale columns. Real-time translation for chat and user-generated content.
Languages to Start With
Choosing which languages to add first is a business decision, not a technical one.
Check your analytics. Where are your existing users? If 15% of your traffic comes from Spanish-speaking countries, Spanish is the obvious first language. If you have growing traffic from Brazil, Portuguese.
Consider your market strategy. Expanding into a specific region? Translate for that region's languages before you launch there, not after.
Think about language reach. Spanish covers 20+ countries. French covers parts of Europe, Africa, and the Americas. Mandarin covers the world's largest population. Arabic covers a wide geographic band. These high-reach languages provide the most return per translation investment.
Also consider language similarity. If you've already translated to Spanish, Portuguese is a smaller incremental effort—the languages share significant vocabulary and structure. This is one of those rare cases where the second step is genuinely easier than the first.
Translation Quality Over Time
Machine translation is a starting point, not a final state. Over time, improve translations using feedback.
Let users flag bad translations. A small "Suggest better translation" link gives bilingual users a way to contribute. Crowdsourced corrections improve quality organically.
Review high-traffic pages with human translators. Your homepage, pricing page, and checkout flow deserve professional translation. The cost is modest and the impact on conversion is measurable.
Track support tickets by language. If Spanish-speaking users consistently contact support about a specific feature, the translated documentation for that feature probably needs work.
Translation quality is a spectrum, not a binary. Shipping an 80% translation today beats shipping a perfect one six months from now. The users you'd lose in those six months aren't coming back.
Translate content with the Translation API. Detect languages with the Language Detection API. Reach a global audience without starting from scratch.
Originally published at APIVerve Blog
Top comments (0)