TechUI Docs

简中

EN

简中

EN

主题

@TechUI/Locales 简介 ​

TechUI Locales (国际化资源包) 是 TechUI 生态系统的语言数据仓库，也是驱动整个框架实现全球化的核心依赖。

与传统的 i18n 方案（一次性加载庞大的 JSON）不同，@techui/locales 采用 "Code-Splitting"（代码分割） 与 "Lazy-Loading"（懒加载） 的设计哲学。它将语言包封装为独立的 JavaScript 模块，配合 TechUI 的核心引擎，实现了毫秒级的环境侦测与按需加载。

一句话总结：按需加载、自动侦测、轻量级的高性能多语言方案。

支持的语言环境 ​

目前官方内置了三种标准语言环境，覆盖了绝大多数业务场景：

语言代码描述对应模块路径
cn简体中文 (Simplified Chinese)@techui/locales/cn
hk繁体中文 (Hong Kong Traditional)@techui/locales/hk
en英语 (English)@techui/locales/en

核心特性 性能优先 ​

异步按需加载 (Async Lazy Load) ​

这是该库最大的亮点。

  • 智能策略：当用户处于中文环境时，系统只会网络请求 cn.js。
  • 零浪费：英文或繁体中文的资源完全不会被加载到浏览器中。这显著减少了首屏的资源体积 (Bundle Size) 和内存占用，让应用启动更快。

自动侦测 (Auto Detection) ​

您无需编写复杂的 if/else 逻辑来判断加载哪个语言包。初始化时，系统会自动按以下优先级“嗅探”用户偏好：

  1. 本地锁定 (Local Storage)：用户之前是否手动切换过语言？
  2. 浏览器环境 (Navigator)：浏览器的首选语言是什么？
  3. 默认兜底：如果都未匹配，则回退到简体中文 (cn)。

模块化结构 (Modular) ​

在包内部，我们采用了 Plugin 分包结构。虽然您引入的是一个 cn 包，但其源码是由 universal (通用)、components (组件)、business (业务) 等多个微模块聚合而成。这意味着官方在维护庞大的翻译库时，依然能保持条理清晰。

安装与使用 ​

安装 ​

bash
npm install @techui/locales

场景一：自动加载 (推荐) ​

在绝大多数 SPA (单页应用) 中，您不需要在代码中显式引入此包。 只需在 TechUIInit 初始化时，让框架自动去处理。

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

// ✅ 无需 import "@techui/locales/..."
// 框架内部会自动根据当前环境，动态 import() 对应的语言文件
TechUIInit({
  // ...配置项
});

场景二：手动/静态引入 (特殊需求) ​

如果您处于内网环境（无法请求动态 chunks），或者希望将特定语言包死打包进主 bundle 中，可以显式引入：

javascript
// main.js
// ⚠️ 强制引入英文包，不再进行自动侦测和网络请求
import "@techui/locales/en"; 

import TechUIInit from "techui-prime";

// 初始化时会直接使用内存中已注册的 'en' 数据
TechUIInit({ ... });

语言切换与锁定 ​

为了保持极致的轻量化，TechUI 做了一个权衡设计：不支持热重载 (No Hot-Swap)。 这意味着切换语言必须刷新页面。我们提供了配套的工具函数来处理这一流程。

标准切换逻辑 ​

javascript
import { lockLang } from "@techui/utils"; // 工具函数来自 utils 包

const switchLanguage = (langCode) => {
  // 1. 锁定用户偏好
  // 将 'en', 'hk', 'cn' 写入 LocalStorage
  lockLang(langCode);
  
  // 2. 刷新页面
  // 页面重载后，Init 函数会优先读取 lockLang 写入的配置
  location.reload();
};

查看更多细节 ​

TechUI多语言，有独立的章节介绍，请跳转至 i18n 章节进行查看