Internationalization and bilingual docs

Nezha has three independent resource sets: Dashboard Go messages, user/admin frontend UI, and documentation. Updating one does not automatically translate the others.

Contribute through Weblate

Prefer Nezha Hosted Weblate for routine translation to avoid conflicting with automatic synchronization. New source messages or languages still need repository integration.

Dashboard: gettext

Catalogs live under pkg/i18n/translations/<locale>/LC_MESSAGES/nezha.po and compiled nezha.mo; the template is pkg/i18n/template.pot. Use existing Localizer methods such as T, Tf, ErrorT, and N, rather than concatenating translatable sentences in handlers.

From the Dashboard root, with Bash 4+ and gettext tools available:

bash script/i18n.sh generate template
bash script/i18n.sh update zh_CN
bash script/i18n.sh compile zh_CN

Extract source text, merge PO, complete/review translations, then compile MO. Edit/review PO between the last two commands. Changing PO alone does not update embedded MO; rebuild Dashboard after compilation. For a new locale, check actual catalog directories and language registration instead of copying a frontend's locale format.

Preserve format placeholders in Tf/ErrorT and the existing plural convention for N. Do not translate JSON keys, API paths, scopes, commands, or machine-read enum values.

Frontends: i18next

Both frontends keep JSON in their own src/locales, but directories, registration, and keys may differ. User frontend initialization is src/i18n.js; admin initialization is src/lib/i18n.ts.

Update base-language and translated keys together, preserving interpolation names, plurals, and nesting. A new language needs resource import, code registration, and language-switcher verification, not just an extra JSON file.

Check long text, wrapping, date/number formatting, missing-key fallback, and retained state across language changes. Avoid fixed dimensions based on Chinese text width. Theme work also needs frontend checks.

Documentation: maintain pairs

Chinese docs/<section>/<page>.md pairs with English docs/en_US/<section>/<page>.md. For every feature update, verify:

• Matching titles, descriptions, defaults, constraints, and example semantics.
• English internal links target /en_US/ pages and actual translated anchors.
• Both language sections in docs/.vitepress/config.mts stay synchronized.
• Accurate page description; shared SEO generates canonical, hreflang, sitemap, and structured data.
• Important entry points appear in docs/public/llms.txt; structured text never promises capabilities absent from visible content.

Run npm test and git diff --check from the documentation root. Automated checks validate structure; manually review permissions, defaults, and negative statements to avoid reversing meaning in translation.