跳到主要内容

语言包

语言包是JitI18N国际化框架的核心组件，负责提供多语言翻译配置和自动化翻译处理。它基于DOM监听和文本替换机制实现页面内容的实时国际化，支持文本节点翻译、属性翻译、动态内容监听和语言切换等功能。

语言包元素分层结构为Meta（languages.Meta） → Type（languages.NormalType） → 实例，开发者可通过JitAI的可视化开发工具快捷地创建语言包实例元素。

当然，开发者也可以创建自己的Type元素，或者在自己的App中改写JitAi官方提供的languages.NormalType元素，以实现自己的封装。

快速开始​

基础配置示例​

推荐目录结构
languages/
├── EN/
│   ├── e.json
│   └── languages.json
└── zhCN/
    ├── e.json
    └── languages.json
EN/e.json
{
    "title": "English",
    "frontBundleEntry": "./languages.json",
    "type": "languages.NormalType"
}
EN/languages.json
{
    "entries": {
        "登录": "Login",
        "用户名": "Username",
        "密码": "Password",
        "确定": "Confirm",
        "取消": "Cancel"
    },
    "ignoreRules": [
        {
            "type": "class",
            "value": "no-translate",
            "mode": "exact"
        }
    ],
    "translateAttributes": [
        "data-tooltip",
        "data-hint"
    ]
}
使用语言包
// 初始化语言包
const app = getRuntimeApp();
await app.i18n.init('languages.EN');

// 切换语言
await app.i18n.switchLanguage('languages.zhCN');

// 获取当前语言
const currentLang = app.i18n.currentLanguage;

配置属性说明​

参数名类型说明默认值必填
entriesRecord<string, string>翻译词条映射表，键为原文，值为译文{}是
ignoreRulesIgnoreRule[]忽略翻译的规则配置数组[]否
translateAttributesstring[]需要翻译的HTML属性名称列表[]否

IgnoreRule 配置：

参数名类型说明默认值必填
type'class' | 'id' | 'attribute' | 'selector'忽略规则类型-是
valuestring匹配值-是
mode'exact' | 'contains' | 'startsWith' | 'endsWith' | 'regex'匹配模式'exact'否

方法​

getInstance​

获取I18N单例实例，通常用于直接访问I18N功能。

返回值​

I18N - I18N单例实例

使用示例​

获取I18N实例
import I18N from 'languages.Meta';

const i18n = I18N.getInstance();
await i18n.init('languages.EN');

init​

初始化指定语言包并启动自动翻译功能。

参数详解​

参数名类型说明默认值必填
langstring语言包元素的fullName-是

返回值​

Promise<void>

使用示例​

初始化语言包
await app.i18n.init('languages.EN');

switchLanguage​

切换到指定语言包，会先还原当前翻译内容再应用新语言包。

参数详解​

参数名类型说明默认值必填
langstring目标语言包的fullName-是
forceboolean是否强制切换（即使是相同语言）true否

返回值​

Promise<void>

使用示例​

语言切换
// 切换到中文
await app.i18n.switchLanguage('languages.zhCN');

// 强制刷新当前语言
await app.i18n.switchLanguage('languages.EN', true);

destroy​

销毁I18N实例，停止监听并清除所有缓存。

使用示例​

销毁实例
app.i18n.destroy();

属性​

currentLanguage​

当前激活的语言包fullName，只读属性。

获取当前语言
const lang = app.i18n.currentLanguage; // 'languages.EN'

高级特性​

忽略规则配置​

通过ignoreRules可以灵活控制哪些元素不进行翻译。

多种忽略规则示例
{
    "ignoreRules": [
        {
            "type": "class",
            "value": "no-translate",
            "mode": "exact"
        },
        {
            "type": "class", 
            "value": "code-",
            "mode": "startsWith"
        },
        {
            "type": "id",
            "value": "logo"
        },
        {
            "type": "attribute",
            "value": "data-no-i18n"
        },
        {
            "type": "selector",
            "value": "pre code"
        },
        {
            "type": "class",
            "value": "anticon-.*",
            "mode": "regex"
        }
    ]
}

自定义属性翻译​

除了默认的 placeholder、title、alt、aria-label 属性外，可以配置额外的属性进行翻译。

属性翻译配置
{
    "translateAttributes": [
        "data-tooltip",
        "data-hint", 
        "data-confirm-text",
        "aria-describedby"
    ]
}

动态内容处理​

语言包会自动监听DOM变化，对动态添加的内容进行实时翻译，特别优化了弹窗、提示等动态组件的翻译效果。

动态内容翻译示例
// 动态添加的元素会自动翻译
const div = document.createElement('div');
div.textContent = '确定';
document.body.appendChild(div); // 会自动翻译为 "Confirm"

// Antd组件动态内容也会被翻译
Modal.confirm({
    title: '确认删除', // 自动翻译
    content: '此操作不可恢复', // 自动翻译
});

多语言包合并​

当应用继承多个包含语言包的父应用时，会自动合并所有语言包的配置。

检查合并效果
// 获取最终合并的语言配置
const langElement = await app.getElement('languages.EN');
console.log(langElement.entries); // 包含所有继承的翻译条目