Internationalization

Relevant source files

• web/src/components/LocaleSelect.tsx
• web/src/components/Settings/PreferencesSection.tsx
• web/src/helpers/consts.ts
• web/src/i18n.ts
• web/src/locales/de.json
• web/src/locales/en.json
• web/src/locales/es.json
• web/src/locales/fr.json
• web/src/locales/hi.json
• web/src/locales/hr.json
• web/src/locales/it.json
• web/src/locales/ja.json
• web/src/locales/ko.json
• web/src/locales/nl.json
• web/src/locales/pt-BR.json
• web/src/locales/ru.json
• web/src/locales/sv.json
• web/src/locales/tr.json
• web/src/locales/vi.json
• web/src/locales/zh-Hans.json
• web/src/locales/zh-Hant.json
• web/src/types/i18n.d.ts
• web/src/types/modules/setting.d.ts

This document describes the internationalization (i18n) system used in the Memos frontend, including supported languages, translation file structure, locale loading mechanisms, and how to add or modify translations. For backend configuration settings related to server locale, see Settings and Configuration UI.

Supported Languages

The Memos frontend supports 39+ languages with translation files managed as JSON resources. All supported locales are defined in web/src/i18n.ts6-40 as the locales array:

Region	Locales
European	de, en, en-GB, es, fr, it, nl, pl, pt-PT, cs, hr, hu, nb, ru, sl, sv, uk
Asian	zh-Hans, zh-Hant, ja, ko, hi, id, th, vi, mr, fa
Middle Eastern	ar, tr
Other	ca, gl, ka-GE, pt-BR

The system includes fallback logic for locale variants. For example, zh-HK and zh-TW fall back to zh-Hant, while zh falls back to zh-Hans web/src/i18n.ts42-46

Sources: web/src/i18n.ts6-46

System Architecture

Architecture Summary:

The i18n system uses i18next with a custom lazy-loading backend that dynamically imports translation files only when needed. The LazyImportPlugin web/src/i18n.ts48-61 performs asynchronous imports from ./locales/${language}.json, reducing initial bundle size by ~200KB+.

Key design decisions:

• Lazy Loading: Translation files are loaded on-demand via dynamic import() statements, not bundled initially
• Fallback Chains: Similar locales fallback to each other (e.g., zh-HK → zh-Hant → en)
• Two-Level Persistence: Locale preference is stored in both localStorage (immediate) and user settings (server-side)
• Instant UI Updates: loadLocale() applies the locale globally before persisting to the backend

Sources: web/src/i18n.ts1-78 web/src/components/LocaleSelect.tsx1-42

Translation File Structure

Translation files are JSON documents with a hierarchical namespace structure. Each file follows the same schema for consistency.

Namespace Organization

Key Namespaces:

Namespace	Purpose	Example Keys
common	Frequently used terms across app	save, cancel, delete, confirm, settings
memo	Memo-related UI strings	delete-confirm, visibility, comment.self
setting	Settings page sections	account-section.title, sso-section.create-sso
editor	Memo editor interface	any-thoughts, save, saving, focus-mode
message	Toast/notification messages	copied, update-succeed, archived-successfully
auth	Authentication pages	sign-in-tip, sign-up-tip, create-your-account

Nested Keys and Interpolation

Translation keys support nested objects and variable interpolation:

Access patterns in code:

• Nested: t("memo.comment.self") → "Comments"
• Interpolated: t("common.sign-in-with", { provider: "GitHub" }) → "Sign in with GitHub"
• Dynamic keys: t(\memo.visibility.${visibility.toLowerCase()}`)` → "Private"

Sources: web/src/locales/en.json1-467 web/src/locales/zh-Hans.json1-469

Locale Loading Process

Loading Flow Details:

1. Initial Load web/src/i18n.ts66-74:

   • i18next detects browser language via navigator API
   • Falls back using the configured fallbackLng chains
   • Lazy loads the matched translation file

2. User Selection web/src/components/LocaleSelect.tsx15-20:

   • LocaleSelect component triggers loadLocale()
   • UI updates immediately for responsive feel
   • Parent component receives onChange callback

3. Persistence web/src/components/Settings/PreferencesSection.tsx23-35:

   • loadLocale() stores in localStorage for instant recall
   • updateUserGeneralSetting mutation persists to backend
   • generalSetting.locale field stores the preference

4. Lazy Import web/src/i18n.ts48-61:

   • Custom LazyImportPlugin implements i18next BackendModule interface
   • Uses dynamic import() with template string: import(\./locales/${matchedLanguage}.json`)`
   • Nearest match algorithm handles locale variants (e.g., en-US → en)

Sources: web/src/i18n.ts48-74 web/src/components/LocaleSelect.tsx1-42 web/src/components/Settings/PreferencesSection.tsx23-35

Adding New Translations

Translation Workflow

Step-by-Step Guide

1. Add Locale Code

Add the locale identifier to the locales array in alphabetical order web/src/i18n.ts6-40:

2. Create Translation File

Create web/src/locales/{locale}.json using en.json as the reference template. The file must include all namespaces:

3. Translate String Values

• Keep all keys in English (structure must match en.json)
• Translate only the values to the target language
• Preserve interpolation placeholders: {{variable}}
• Maintain HTML entities if present

Example from zh-Hans.json:

4. Handle Special Cases

• Plurals: Some locales may need different plural forms
• Date/Time: Keep format strings (e.g., {{date}}) intact
• Technical Terms: Consider keeping some terms in English if commonly used

5. Configure Fallbacks (Optional)

For locale variants, add fallback configuration web/src/i18n.ts42-46:

6. Test Translation

• Build the application: pnpm build
• Select the new locale in Settings → Preferences → Language
• Navigate through all pages to verify translations
• Check for missing keys (will display English fallback)

Sources: web/src/i18n.ts6-46 web/src/locales/en.json1-467

Using Translations in Components

Basic Usage with useTranslate Hook

Translation with Interpolation

This renders: "Alice has a comment on your My First Memo."

Dynamic Key Selection

Translation in Form Validation

Sources: web/src/components/Settings/PreferencesSection.tsx19 web/src/locales/en.json1-467

Locale Selection UI

The LocaleSelect component provides a dropdown for language selection integrated with the preferences section.

Component Structure

Integration Points

The LocaleSelect component is rendered in the Preferences Section web/src/components/Settings/PreferencesSection.tsx74-76:

When a user changes the language:

1. LocaleSelect.handleSelectChange() web/src/components/LocaleSelect.tsx15-20 is called
2. loadLocale(locale) applies the change immediately to i18n instance
3. props.onChange(locale) notifies parent component
4. PreferencesSection.handleLocaleSelectChange() web/src/components/Settings/PreferencesSection.tsx23-35 persists to user settings
5. updateUserGeneralSetting mutation saves to backend with updateMask: ["locale"]
6. UI re-renders with new translations

Locale Display Names

The getLocaleDisplayName() utility web/src/components/LocaleSelect.tsx32 formats locale codes into human-readable names:

• en → "English"
• zh-Hans → "中文 (简体)"
• zh-Hant → "中文 (繁體)"
• pt-BR → "Português (Brasil)"
• en-GB → "English (UK)"

Sources: web/src/components/LocaleSelect.tsx1-42 web/src/components/Settings/PreferencesSection.tsx23-76

Translation Key Reference

The most frequently used translation keys across the application:

Key	Usage Context	Example Value (EN)
common.save	Save buttons	"Save"
common.cancel	Cancel buttons	"Cancel"
common.delete	Delete buttons	"Delete"
common.confirm	Confirmation dialogs	"Confirm"
memo.delete-confirm	Memo deletion warning	"Are you sure you want to delete this memo?"
message.update-succeed	Success toast	"Update succeeded"
message.copied	Clipboard success	"Copied"
editor.save	Editor save button	"Save"
editor.any-thoughts	Editor placeholder	"Any thoughts..."
setting.account-section.title	Settings section header	"Account Information"

Sources: web/src/locales/en.json1-467