Multilingual Overview
The multilingual (Internationalization, or i18n for short) module of TechUI is a lightweight solution built on the global service $tService and a dynamic loading mechanism.
Unlike traditional i18n plugins that require loading all language packs at once, TechUI adopts an "on-demand asynchronous loading" strategy. The system automatically detects user environment or local cache configurations upon startup and only requests and loads the currently required language files. This significantly reduces the initial bundle size and improves application performance.
Core Features
Auto Detection and Loading
The system has built-in intelligent language environment determination logic. During the application initialization phase (before TuiProvider is mounted), the system determines the target language based on the following priority:
- Local Locked Configuration: Checks if a user's manual language preference is stored in LocalStorage (set via
lockLang). - System/Browser Language: If there is no local configuration, it automatically reads the browser's
navigator.language. - Default Fallback: If none of the above matches, it defaults to Simplified Chinese (
cn).
Asynchronous On-Demand Strategy
TechUI language packs are designed as independent JavaScript modules (located in @techui/locales).
- When a user is in a Chinese environment, the system only executes
import("@techui/locales/cn"). - English or Traditional Chinese resources will not be loaded, thereby saving network bandwidth and memory usage.
Modular Management
To solve the problem of language pack files becoming too large and difficult to maintain as a project iterates, TechUI adopts a Plugin sub-package structure. For example, in the plugins.cn directory, translation files are split into:
universal.js: Common vocabulary (OK, Cancel, Back, etc.).components.js: Internal text for UI components.login.js: Business module text.dateTime.js: Date and time related text.
During the final compilation, these sub-packages are aggregated into a single entry file (such as cn.js). This ensures maintainability during development while balancing loading efficiency at runtime.
Support Range
TechUI officially provides built-in support for the following three standard language environments:
| Language Code | Description | Corresponding Module File |
|---|---|---|
| cn | Simplified Chinese | @techui/locales/cn |
| hk | Traditional Chinese (Hong Kong) | @techui/locales/hk |
| en | English | @techui/locales/en |
Limitations
No Hot-Swap Support To maintain a lightweight architecture and high performance, the TechUI multilingual system does not support real-time language switching without refreshing the page. When a user triggers a language switch, location.reload() must be called to reload the page, ensuring that the new language pack is correctly loaded and applied to all reactive states and component instances.