Initialization Configuration

TechUI's multi-language system relies on the global service TuiService for initialization. In most cases, there is no need to manually write complex loading logic, as the system automatically adapts the most appropriate language package based on the environment.

Automatic Initialization

When the application starts and calls TechUIInit, the internal initI18n method is executed automatically. The default workflow is as follows:

1. Language Detection: Calls getSysLang() to determine the target language (e.g., 'cn'). This function prioritizes reading configurations from local storage, falling back to the browser's environment language.
2. Cache Check: Uses tLang.load() to check if language data already exists in memory.
3. Dynamic Loading:
   • If no data exists: Dynamically imports the corresponding language package file (e.g., @techui/locales/cn) based on the target language.
   • If data exists: Skips dynamic loading and uses the existing data (usually occurring when a language pack is manually imported).
4. State Mounting: Mounts the final language data to the global reactive state $tState.locale for component use.

Code Example

Under normal circumstances, you only need to initialize TechUI as usual without extra code:

// main.js
import TechUIInit from "techui-prime";

const params = {
  // ... other configurations
};

// initI18n() is called internally automatically
TechUIInit(params);

Manual Import

In specific scenarios, such as intranet environments where dynamic imports are unavailable or when a specific language pack must be bundled into the main bundle, you can explicitly import the language pack in your entry file.

Mechanism: When you explicitly import a language pack, that file internally calls tLang.register to store the data in memory. Since initI18n detects that the data is already present, it will not initiate a network request.

Usage Example:

// main.js

// Force the English pack, disabling auto-detection
import "@techui/locales/en"; 

import TechUIInit from "techui-prime";

// Initialization will directly use the English data imported above
TechUIInit({ ... });

Note: Manual imports increase the size of the main bundle. Unless necessary, the default asynchronous loading method is recommended.

Language Locking

TechUI provides matching utility functions to handle active language switching and preference memory for users.

Locking Language (lockLang)

When a user switches languages in the interface, the lockLang function should be called. This function writes the selected language code (such as 'en') into the browser's LocalStorage.

Function Signature: lockLang(lang: 'cn' | 'hk' | 'en')

Getting System Language (getSysLang)

During initialization, the system uses this function to decide which language to load based on the following priority:

1. LocalStorage: Checks for records written by lockLang.
2. Navigator: Checks the browser's navigator.language.
3. Default: Returns 'cn' by default.

Full Switching Logic

Since TechUI does not support hot-reloading for multiple languages, the standard switching process is: Lock Language -> Refresh Page.

import { lockLang } from "@techui/utils";

const handleLanguageChange = (langCode) => {
  // 1. Write user selection to local storage
  lockLang(langCode);
  
  // 2. Refresh page to trigger initI18n to re-read configuration
  setTimeout(() => {
    location.reload();
  }, 300);
};

Following this method, after the page refreshes, initI18n will read the latest local configuration via getSysLang and load the user-selected language pack.