ADR-0020: Internationalization (Vietnamese + English)¶
Metadata¶
Status: Accepted (2026-10-14) · Date: 2026-10-14 · Deciders: nguyenhuuca · Tags: i18n, frontend, api-contract, email Related PRD: PRD-i18n · Related Plan: plan-i18n · Supersedes: N/A
Tech Strategy: ⚠️ Adds new frontend dependencies (i18next, react-i18next, i18next-browser-languagedetector), which are not in the Golden Path. If this ADR is accepted, .claude/rules/tech-strategy.md must be updated, as task FE-1 does.
Context¶
The UI mixes the two languages. Navigation chrome is in English ("Home", "Library", "Settings"), while content labels are in Vietnamese ("Phát", "Xoá", "Xem sau").
Survey of the codebase on 2026-10-14:
Frontend
- About 40 non-test
.jsxfiles contain roughly 230–280 hardcoded strings. - There is no i18n library.
index.htmlhardcodeslang="en". - Formatting is hardcoded too:
commentUtils.jsrelative time is always English ("2m ago").ExploreViewusesIntl.NumberFormat('en')."{n} video"has no plural handling.
- Notification titles are rendered on the frontend (
utils/notificationText.js, in Vietnamese). The DB stores only a JSON payload, so no data migration is needed. - 21 test files assert on literal UI strings (about 60 assertions).
Backend
- No
MessageSourceand noLocaleResolver;Accept-Languageis ignored. CustomExceptionmessages are free text, mostly English and some Vietnamese.client.jsshowserror.messagedirectly.- Emails:
- The magic link email (
templates/email/invite.htmland its subject) is English only. - The password-change email is built in code in Vietnamese (
PasswordLoginServiceImpl~L234–248).
- The magic link email (
- The default collection name
"Xem sau"is stored as data invideo_collections.name. user_settingsexists (ADR-0016) but has no locale column.
The owner chose (2026-10-14):
react-i18next.- Default language taken from the browser.
- Scope covers user UI, API error messages, emails and the Admin pages.
Decision Drivers¶
- Two languages now. Adding a third later must not need a refactor.
- Guests can switch language too. Logged-in users keep their choice across devices.
- Emails go out without a browser (for example the async password-change notice), so the backend must know the user's language without a request.
- No new infrastructure. Translations ship inside the bundle and the JAR.
- Tests must not break every time a translation is reworded.
Decisions¶
D1. Frontend: i18next + react-i18next, bundled resources¶
- Add
i18next,react-i18nextandi18next-browser-languagedetector. - Resources are static JSON imports in
webapp/src/i18n/locales/{vi,en}/<namespace>.json. Namespaces arecommon,feed,library,auth,comments,notifications,settings,adminanderrors. - There is no HTTP backend and no lazy loading. Both languages together are about 300 keys, a few KB gzipped.
- Plurals use i18next suffixes (
_one/_other). Vietnamese uses_otheronly, per CLDR. - Interpolation uses
{{name}}. React already escapes output, soescapeValue: false. - Dates, numbers and relative time use
Intl.*with the current language:Intl.RelativeTimeFormatreplaces the hand-written "2m ago".Intl.NumberFormat(lng, { notation: 'compact' }).
Rejected alternative: an in-house useT() hook. It has no dependency, but the owner preferred the standard library for plurals, detection and future languages.
D2. Language resolution order (frontend)¶
- The user's saved choice, from
localStorage['lang'], which the switcher writes. - For logged-in users,
user_settings.localefrom the server, when set. It is applied after login and overrides (1). - The browser language:
navigator.languagestarting withvigivesvi, anything else givesen. - Fallback is
en.
supportedLngs: ['vi', 'en'] and nonExplicitSupportedLngs: true, so vi-VN maps to vi. On every change the app sets document.documentElement.lang.
D3. API contract: Accept-Language¶
api/client.jssendsAccept-Language: <current lng>on every request.- The backend uses
AcceptHeaderLocaleResolverwith supported locales[vi, en]and defaulten. - CORS already allows all headers, and
Accept-Languageis a CORS-safelisted header anyway.
D4. Backend messages: MessageSource + message keys¶
- Add
messages.properties(English, the default) andmessages_vi.propertiesinsrc/main/resources/i18n/, both UTF-8. CustomExceptiongains an optionalmessageKeyandargs.RestExceptionHandlerresolves the key withLocaleContextHolder.getLocale().- Without a key, the existing
messageis returned unchanged, so migration can be incremental.
- Response shape:
ResultErrorInfo.messageis now localized. A new stablecodefield holds the message key, for clients and tests. - Only messages users can see are migrated:
- Validation, collection and comment errors.
- Auth and password errors (
PasswordPolicyandPasswordLoginServiceImplcodes already exist). - Rate limiting.
- Internal and system errors stay in English.
D5. Persisted preference: user_settings.locale¶
- Migration:
ALTER TABLE user_settings ADD COLUMN locale VARCHAR(5) NULL. NULL means "not chosen, follow the browser". GET/PATCH /user/settingsexposeslocale. The allowed values arevi,enand null.- The frontend PATCHes when a logged-in user switches language, and applies the server value after login.
D6. Emails use the recipient's locale, never the current thread¶
- The email locale is
user_settings.locale, then the request locale (at magic-link sign-up, before any settings exist), thenen. - The locale is passed explicitly into
MailService. The code never readsLocaleContextHolderthere, because async and virtual threads do not carry it. - Templates are split per locale:
templates/email/invite_vi.htmlandinvite_en.html. The template body has too much layout to stay readable as message keys. Subjects and the password-change body move toMessageSource.
D7. Stored names stay data and are translated on display¶
- The default collection keeps
name = 'Xem sau'in the DB, for uniqueness and because it cannot be renamed. - The frontend shows
t('library.watchLater')whenisDefaultis true. - User-generated content (titles, comments, collection names) is never translated.
D8. Test strategy¶
src/test-setup.jsinitializes i18n synchronously withlng: 'vi'and the real resources. Most existing Vietnamese assertions keep working. Assertions on English chrome ("Home") are updated to the Vietnamese value or switched to role/key-based queries.- CI guards:
- A key-parity test:
viandenhave identical key sets per namespace, and no value is empty. - The same check for
messages.propertiesagainstmessages_vi.propertiesin JUnit.
- A key-parity test:
- Each switched component gets at least one test that renders in
en.
Consequences¶
Positive
- Every user-facing string lives in one place per language.
- Adding a language means adding JSON and properties files only.
- Errors and emails match the user's language.
Negative / costs
- Three new frontend dependencies, about 20 KB gzipped, plus an update to tech-strategy.md.
- Touches about 40 components and 21 test files, so the diff is large. It is phased by area to keep PRs reviewable.
ResultErrorInfogains a field. This is additive, so existing clients are unaffected.
Risks
- Cloudflare caching. If any API error or GET response is edge-cached, the language would leak between users. Mitigation: send
Vary: Accept-Languageon localized responses, and verify that/apiJSON is not cached at the edge (QA-1). - Missing keys at runtime. Mitigated by the parity tests. Set
saveMissing: falseandreturnNull: false, and fall back toen. - Admin-only strings are lower value. They are translated last (FE-5) and can be deferred without blocking the rest.
Compliance¶
- Spring
MessageSourceandLocaleResolverare part of Spring Boot, so the backend stays on the Golden Path. - One Liquibase migration (D5); no
ddl-auto. - No secrets and no new infrastructure.