This document provides a technical guide for adding new language translations and updating existing translations in the memos application. It covers the localization file structure, the i18next implementation, and the data flow between locale files and React components.
The memos frontend utilizes i18next with a custom lazy-loading plugin to manage translations. This architecture ensures that only the required language files are fetched, optimizing the initial load performance.
Sources: web/src/i18n.ts6-50 web/src/i18n.ts58-77 web/src/utils/i18n.ts25-52 web/src/utils/i18n.ts95-101
i18n instance is configured in web/src/i18n.ts. It uses the LazyImportPlugin to handle dynamic loading of JSON files from the locales directory web/src/i18n.ts79-93LazyImportPlugin implementation uses dynamic import() to fetch the required JSON file based on the matchedLanguage resolved by findNearestMatchedLanguage web/src/i18n.ts61-76findNearestMatchedLanguage, which checks the locales list, explicit fallbacks (e.g., mapping zh-HK to zh-Hant), and finally defaults to en web/src/i18n.ts52-56 web/src/utils/i18n.ts25-52applyLocaleEarly() is called during the initial page load to set the document language based on localStorage or browser settings web/src/utils/i18n.ts107-111Each locale file is a structured JSON object. The English file (en.json) serves as the "Source of Truth" for all keys.
| Category | Purpose | Example Keys |
|---|---|---|
about | App metadata | description, github-repository |
auth | Login/Registration | sign-in-tip, create-your-account |
common | Shared UI labels | save, cancel, delete, settings |
editor | Memo composer UI | any-thoughts, focus-mode, audio-recorder |
memo | Memo actions/filters | delete-confirm, visibility.private |
inbox | Notification system | memo-comment, no-unread |
Sources: web/src/locales/en.json2-16 web/src/locales/en.json17-42 web/src/locales/en.json80-183 web/src/locales/en.json187-219
The application uses TypeScript to ensure translation keys used in the code actually exist in the JSON files.
TLocale type: A union type of all supported locale strings derived from the locales array web/src/i18n.ts96useTranslate hook: Returns a typed t function that provides autocompletion and validation for valid keys web/src/utils/i18n.ts64-67Create a new file in web/src/locales/ named after the ISO 639-1 or IETF language tag. For example:
vi.json for Vietnamese web/src/locales/vi.json1pt-BR.json for Brazilian Portuguese web/src/locales/pt-BR.json1tr.json for Turkish web/src/locales/tr.json1Copy the content of en.json and translate the values. Maintain the exact key structure and interpolation placeholders like {{provider}}, {{count}}, or {{time}}.
common.sign-in-with using {{provider}} web/src/locales/ja.json102 or memo.count-memos-in-date using {{count}} web/src/locales/ko.json184editor.format or memo.visibility web/src/locales/ja.json169-184 web/src/locales/ko.json209-214Add the new locale code to the locales array in web/src/i18n.ts in alphabetical order web/src/i18n.ts6-50
The LocaleSelect component (used in UserMenu or settings) allows users to switch languages. It calls loadLocale, which updates the i18next state and persists the choice to localStorage.
Sources: web/src/components/LocaleSelect.tsx1-20 web/src/utils/i18n.ts95-101 web/src/i18n.ts58-77
To use translations in a component, use the useTranslate hook:
Sources: web/src/utils/i18n.ts64-67
{{duration}} or {{time}} in the translated string if they exist in the source web/src/locales/en.json195 web/src/locales/en.json208locales array in web/src/i18n.ts sorted alphabetically to maintain consistency in UI selectors web/src/i18n.ts6-50import() in the LazyImportPlugin web/src/i18n.ts63i18next will use the fallbackLng (English) web/src/i18n.ts89-92applyLocaleEarly() is being called in the application entry point web/src/utils/i18n.ts107-111LocaleSelect are generated using the Intl.DisplayNames API. If a name appears as a raw code, check the browser's support for that locale web/src/utils/i18n.ts114-124Sources: web/src/i18n.ts1-96 web/src/utils/i18n.ts1-124 web/src/locales/en.json1-219
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.