xw-i18n

xw-i18n 是一个基于 Vue-i18n 封装的 多语言管理插件，同时它还是一个基于 Node.js 开发的 命令行工具。

安装

npm install xw-i18n --save

一、多语言管理插件

• 旨在为 Vue 3 项目提供灵活、可扩展的国际化支持。它不仅支持项目中多个语言的加载和切换，还通过调用接口动态加载语言文档，确保项目能灵活应对语言环境的变化。该插件支持多种语言环境的配置，并提供了易于使用的 API，帮助开发者快速集成和管理国际化内容。

主要功能

• 语言切换：通过 changeLang 方法动态切换语言，并自动从接口加载相应的语言文件。
• 自动加载语言文件：根据配置的语言接口动态加载语言资源文件，支持从远程服务器获取翻译内容。
• 回退语言支持：如果当前语言文件加载失败，插件会自动回退到指定的回退语言（如 en_US），确保 UI 始终可用。
• 语言列表管理：支持获取项目可用的所有语言，并允许开发者自由切换。
• 本地存储支持：用户选择的语言会被保存在浏览器的 localStorage 中，刷新页面时自动恢复。
• Loading 动画：切换语言时会展示加载中的提示，提升用户体验。

使用方法（ 支持 vue2、vue3 以及多页面 html ）

• 以 Vue3 项目为例，下方为入口文件 main.js 引入方式

<!-- main.js -->

import { createApp } from 'vue';
import registerI18n from 'xw-i18n';
import router from './router';
import App from './App';
<!-- fallbackMessage：本地的回退语言包，当接口获取语言包失败时，则使用该语言包。该语言包可以通过xw-i18n的命令行工具自动拉取和更新，下面会介绍到 -->
import fallbackMessage from './locale/default.json';
import getLocationParams from './utils/query-params.js';

const app = createApp(App);

<!-- 由于 xw-i18n 内是通过接口请求的国际版CGM后台所同步的语言包，因此是个异步过程，下方 app.use 需要采用异步函数的形式编写 -->
(async () => {
    <!-- registerI18n 内部会使用 app.use(i18n)，因此 -->
    const i18n = await registerI18n(app, {
        // 接口地址，必传，可根据环境传入对应接口地址
        baseURL: import.meta.env.VITE_APP_BASE_API,
        // 项目编码；可在国际版CGM后台管理系统的【语言管理-项目列表】查看对应项目的项目代码，必传
        projectCode: 'EIFU',
        // 初始语言，不传默认'en_US'
        locale: getLocationParams().lang,
        // 项目本地的语言包，格式为 { en_US: {...}, zh_CN: {...}, ... }，非必传，若配置该字段，则会与远程语言包进行合并
        // messages,
        // 回退语言，不传默认'en_US'
        fallbackLocale: 'en_US',
        // 回退语言包，非必传
        fallbackMessage,
    });
    app.use(router).mount('#app');
})();





<!-- ./utils/query-params.js -->

// 截取url参数
export default function () {
    const params = {};
    const [, paramsString] = window.location.href.split('?');
    (paramsString || '').split('&').forEach((str) => {
        const [key, value] = (str.split('#')[0] || '').split('=');
        params[key] = value;
    });
    return params;
}

• 页面使用方法

<div>
    <p>测试翻译文案: {{ $t('eifu.doc.name') }}</p>
    <p>该项目下所有语言的列表: {{ languages }}</p>
    <p>当前语言code: {{ currentLang }}</p>
    <p>当前语言的名称: {{ currentLangName }}</p>
    <button @click="changeSystemLang('de_DE')">切换语言</button>
</div>

<script>
import { ref, computed, watch } from 'vue';
import { useI18n, getLanguageList, changeLang } from 'xw-i18n';

export default {
    setup() {
        const i18n = useI18n();
        <!-- 逻辑层使用 $t -->
        const $t = i18n.global.t || ((s) => s);
        console.log($t('eifu.doc.version'));
        <!-- 该项目下所有语言的列表 -->
        const languages = getLanguageList();
        <!-- 当前语言code -->
        const currentLang = ref(i18n.global.locale);
        <!-- 当前语言的名称 -->
        const currentLangName = computed(() => (languages.find(({ code }) => code === currentLang.value) || {}).name || currentLang);

        const changeSystemLang = (val) => {
            changeLang(val).then(() => {
                currentLang.value = val;
                // do something else
            }).catch(() => {});
        };

        return {
            languages,
            currentLang,
            currentLangName,
            changeSystemLang,
        };
    },
};
</script>

二、命令行工具

• 旨在为多语言国际化（i18n）项目提供高效的语言包管理和动态更新功能。它封装了常见的国际化需求，支持通过命令行工具自动拉取和更新不同环境下的语言包，并将其自动写入指定的项目目录中，从而实现动态更新回退语言包的效果，避免了手动操作的繁琐。快速便捷的切换项目语言。

主要功能

• 自动下载翻译语言包：支持从指定环境（dev、test、pre、prod）或自定义下载地址拉取语言包。
• 支持多语言：您可以指定需要下载的语言包（如 en_US, de_DE 等）。
• 自动保存到项目文件夹：将语言包保存到项目的指定路径中，支持自定义保存路径和文件名。
• 回退语言包支持：通过插件提供的回退语言包功能，确保项目中没有遗漏的翻译内容。

使用方法

以 Vue 项目为例，下方为 package.json 文件的局部配置。推荐新增 updateLocale 快捷命令，并将 "serve" 指令更改为 "npm run updateLocale && vue-cli-service serve"，那么每次启动项目时，都会自动更新本地的回退语言包。

<!-- package.json -->

{
    ...

    "scripts": {
        "updateLocale": "node xw-i18n update EIFU",
        "serve": "npm run updateLocale && vue-cli-service serve",
        "build": "vue-cli-service build",
        "build:dev": "vue-cli-service build --mode development",
        "build:test": "vue-cli-service build --mode testing",
        "build:pre": "vue-cli-service build --mode pre",
        "build:prod": "vue-cli-service build --mode production",
        "lint": "vue-cli-service lint"
    },

    ...
}

node xw-i18n update <app-code> -l <lang> -e <env> -p <path> -n <name> -s <suffix> -a

• -p, --path <path>   语言包保存的路径地址。默认: /src/locale
• -n, --name <name>   语言包的名称。默认: default
• -s, --suffix <suffix>   语言包的文件后缀。默认: .json
• -e, --env <env>   从哪个环境拉取语言包? 可选: dev | test | pre | prod
• -http, --http <http>   自定义拉取语言包的下载地址，配置该参数则会忽略 -e, --env 参数
• -l, --lang <lang>   将哪个语言包作为默认语言包? 可选: <app-code>对应的项目已配置的语言 key（例如 en_US | de_DE ...）默认: "en_US"
• -a, --all   是否将所有语言包写入到项目目录，配置了该参数则会忽略 -l, --lang <lang> 和 -n, --name <name> 参数

执行上面的命令后，会在项目中的 src/locale 中保存一份最新的回退语言包 default.json，默认为 en_US 语言，如果已存在 default.json 文件，则会替换； 当然，你也可以参照上述配置参数修改文件保存的路径、文件名称以及语言类型等等。

注意： 如果运行 node xw-i18n update <app-code> -l <lang> -e <env> -p <path> -n <name> 报错，提示 Error: Cannot find module 'F:\xxx\xw-i18n'，那么你可以尝试将它修改成这样 node node_modules/xw-i18n/bin update <app-code> -l <lang> -e <env> -p <path> -n <name>

Node 版本要求

>= 14.0.0