@TechUI/Locales Introduction

TechUI Locales (Internationalization Resource Pack) is the language data warehouse of the TechUI ecosystem and the core dependency driving the globalization of the entire framework.

Unlike traditional i18n solutions (which load massive JSON files at once), @techui/locales adopts the design philosophy of "Code-Splitting" and "Lazy-Loading". It encapsulates language packages as independent JavaScript modules, working with TechUI's core engine to achieve millisecond-level environment detection and on-demand loading.

One-sentence summary: On-demand loading, automatic detection, and a lightweight high-performance multi-language solution.

Supported Language

Currently, there are three built-in standard language environments covering most business scenarios:

Language Code	Description	Module Path
cn	Simplified Chinese	@techui/locales/cn
hk	Hong Kong Traditional	@techui/locales/hk
en	English	@techui/locales/en

Performance First

Async Lazy Load

This is the biggest highlight of the library.

• Smart Strategy: When the user is in a Chinese environment, the system will only make a network request for cn.js.
• Zero Waste: Resources for English or Traditional Chinese will not be loaded into the browser at all. This significantly reduces the initial Bundle Size and memory usage, allowing the application to start faster.

Auto Detection

You don't need to write complex if/else logic to determine which language package to load. Upon initialization, the system automatically "sniffs" user preferences according to the following priority:

1. Local Locking (Local Storage): Has the user manually switched languages before?
2. Browser Environment (Navigator): What is the browser's preferred language?
3. Default Fallback: If no match is found, it falls back to Simplified Chinese (cn).

Modular Structure

Internally, we have adopted a Plugin Sub-package Structure. Although you import a cn package, its source code is an aggregation of multiple micro-modules such as universal, components, and business. This means that while maintaining a massive translation library, the official team can still keep it organized and clear.

Installation and Usage

Installation

npm install @techui/locales

Scenario 1: Automatic Loading (Recommended)

In most SPAs (Single Page Applications), you do not need to explicitly import this package in your code. Simply let the framework handle it automatically during TechUIInit initialization.

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

// ✅ No need to import "@techui/locales/..."
// The framework internally dynamically imports the corresponding language file based on the current environment via import()
TechUIInit({
  // ...configuration options
});

Scenario 2: Manual/Static Import (Special Requirements)

If you are in an intranet environment (unable to request dynamic chunks), or wish to hard-bundle a specific language package into the main bundle, you can import it explicitly:

// main.js
// ⚠️ Force import of the English package; disables auto-detection and network requests
import "@techui/locales/en"; 

import TechUIInit from "techui-prime";

// Initialization will directly use the 'en' data already registered in memory
TechUIInit({ ... });

Language Switching

To maintain extreme lightweight performance, TechUI made a trade-off design: No Hot-Swap. This means switching languages requires a page refresh. We provide accompanying utility functions to handle this process.

Standard Switching Logic

import { lockLang } from "@techui/utils"; // Utility function from the utils package

const switchLanguage = (langCode) => {
  // 1. Lock user preference
  // Writes 'en', 'hk', or 'cn' to LocalStorage
  lockLang(langCode);
  
  // 2. Refresh the page
  // After reload, the Init function will prioritize reading the configuration written by lockLang
  location.reload();
};

View More Details

TechUI Multi-language has a dedicated chapter introducing it. Please jump to the i18n chapter to view it.