Internationalization (i18n)

Relevant source files

The following files were used as context for generating this wiki page:

• i18n/generate.go
• i18n/util.go
• web/src/i18n.js
• web/src/locales/en/data.json
• web/src/Setting.js
• README.md

Internationalization (i18n) in Casdoor is a multi-layered system designed to provide a localized user experience across both the frontend Web UI and backend server responses. The system utilizes i18next for the React-based frontend and a custom Go-based implementation for backend message translation.

The project uses Crowdin as its primary translation platform, enabling community contributions to language support. Localized strings are stored in JSON files organized by language and namespace, ensuring a structured approach to managing global content.
Sources: README.md:95-97, web/src/i18n.js:108-112

Frontend Architecture

The frontend localization is powered by the i18next and react-i18next libraries. It dynamic loads language resources from the web/src/locales directory based on the user's browser settings or manual selection.

Language Initialization

Casdoor determines the display language through a specific hierarchy:

1. Check for a language key in the browser's localStorage.
2. If not found, check for a forced language configuration in Conf.js.
3. If still not found, detect the browser's navigator.language.
4. Default to a predefined system default language.
   Sources: web/src/i18n.js:46-105

Dynamic Resource Loading

The system uses a custom backend connector to load translation files asynchronously. This prevents the initial bundle from becoming too large by only fetching the JSON file for the active language.

Backend Architecture

The backend i18n system focuses on translating error messages and server-side responses. It uses Go's embed package to include translation files directly in the binary.

Translation Logic

Backend strings follow a namespace:key format (e.g., general:Successfully added). The Translate function parses this token, looks up the corresponding value in the langMap, and returns the translated text.

Error Masking

The backend includes an enableErrorMask feature. When enabled, specific sensitive errors (like "user doesn't exist") are replaced with generic messages to prevent information leakage during authentication attempts.
Sources: i18n/util.go:34-45, i18n/util.go:70-82

i18n Tooling and Generation

Casdoor provides automated tools to synchronize localization keys between the source code and the translation files.

Key Extraction

The i18n/generate.go utility uses regular expressions to scan both frontend (.js) and backend (.go) files for translation markers:

• Frontend: i18next.t("...")
• Backend (Object): i18n.Translate(..., "...")
• Backend (Controller): c.T("...")

Resource Synchronization

New keys found in the source code are automatically added to the default en/data.json file. The tool can also apply these new keys to other supported languages while preserving existing translations.
Sources: i18n/generate.go:34-36, i18n/generate.go:132-140

Function	Category	Purpose
getAllI18nStringsFrontend	Tooling	Parses JS files for i18next.t calls.
getAllI18nStringsBackend	Tooling	Parses Go files for backend translation calls.
parseAllWords	Tooling	Orchestrates file walking and key extraction.
applyToOtherLanguage	Tooling	Merges new keys into existing language JSON files.
Sources: i18n/generate.go:40-100

Language Configuration

The system supports a wide array of languages. Manual overrides and country-specific metadata are managed in the Setting.js file.

Language	Key	Country Code
English	en	US
Español	es	ES
Français	fr	FR
Deutsch	de	DE
日本語	ja	JP
中文	zh	CN
Português	pt	PT
Sources: web/src/Setting.js:42-53

Translation Data Structure

Localized strings are stored in a nested JSON format where the first level represents the namespace (usually corresponding to a functional module) and the second level contains the key-value pairs.

{
  "general": {
    "Name": "Name",
    "Organization": "Organization",
    "Edit": "Edit"
  },
  "user": {
    "Country/Region": "Country/Region",
    "Affiliation": "Affiliation"
  }
}

Sources: web/src/locales/en/data.json:194-205, web/src/locales/en/data.json:1150-1160

Summary

Internationalization in Casdoor is a robust system that ensures consistent localization across the entire stack. By utilizing community-driven translation via Crowdin, automated key extraction for developers, and dynamic loading for performance, the project maintains high-quality global support. The backend's embedded translation map and error masking further enhance the security and professional feel of localized server responses.
Sources: README.md:95-97, i18n/util.go:25-30, web/src/i18n.js:115-125