tolgee+vue-i18n实现项目国际化

2024-09-07

提到 Vue 项目实现国际化，一般会想到使用 vue-i18n 国际化插件来实现。思路是在项目本地定义并管理语言包 json 文件，在 json 文件下进行翻译条目的新增，修改和删除。

一.背景

目前在公司参与的一个前端项目，支持 3 种语言。由于是体量较大的 monorepo 项目，每种语言就有四千多个翻译条目，使得管理上会出现一些问题。

1.顺序错乱

项目依赖编辑器的 i18n Ally 插件，其中配置了每个词条自动按照 a-z 排序。但存在部分同事漏装插件的情况，导致 json 文件的词条顺序经常错乱；

2.代码容易冲突

插件安装问题其实容易解决，但是…在多人协作开发的场景下，词条 json 文件极易冲突，即使花费时间解决了冲突，也可能会无意间再次打乱 a-z 排序，导致 git diff 持续混乱；

3.词条表述需要反复调整

词条翻译质量参差，为了调整词条表述，开发测试阶段需要反复提交代码构建

二.解决方式

出现这 3 个问题，是因为语言包 json 文件都放在了项目本地进行管理，导致开发阶段（特别是代码合并的时候）需要花费精力处理。

和同事讨论后，决定给前端项目接入 tolgee 词条管理平台。

主要思路是，项目还是使用 vue-i18n 插件实现国际化，而所有的翻译条目在 tolgee 平台进行线上管理。在本地开发阶段，网页刷新时请求最新的语言包，传入 i18n 实例进行使用。线上包 build 时，会先下载 tolgee 平台的语言包到项目，再进行构建。

三.实现步骤

今天已经从零再次实现了一个简单的项目 demo：tolgee-i18n-project

1.本地开发：网页加载时先请求语言包数据，存在浏览器 localStorage 里，在 createI18n 时获取 localStorage 的语言包传入

(1)新增公共环境变量文件.env

# tolgee URL
VITE_TOLGEE_URL=https://app.tolgee.io
# tolgee PROJECT_ID
VITE_TOLGEE_PROJECT_ID=your_project_id
# tolgee API_KEY
VITE_TOLGEE_KEY=your_api_key

(2)创建自定义 Vite 插件 htmlGetLocales

新建 vite.base.ts

在开发环境，赋值 localesPromise 一个加载语言包的 Promise，加载后存入 localStorage；在生产环境，赋值 localesPromise 一个已成功的 Promise

import { loadEnv } from "vite";

export function htmlGetLocales(mode: string) {
  const env = loadEnv(mode, __dirname);
  return {
    name: "load-locales-files",
    transformIndexHtml() {
      const prodText = `
      const tempPromise = () => {
        return Promise.resolve();
      };
      window.localesPromise = tempPromise;
      `;
      const devText = `
        // 加载语言包并保存在localStorage
        const loadLocales = () => {
          const config = {
            method: 'get',
            maxBodyLength: Infinity,
            headers: {
              Accept: 'application/json',
              'X-API-Key': '${env.VITE_TOLGEE_KEY}',
            },
          };
          return fetch('${env.VITE_TOLGEE_URL}/v2/projects/${env.VITE_TOLGEE_PROJECT_ID}/translations/zh,en', config)
            .then((res) => res.json())
            .then((data) => {
              localStorage.setItem('locales', JSON.stringify(data));
            })
            .catch((res) => {console.error('语言包加载失败', res)});
        };
        // 加载语言包
        const getLocales = () => {
          return Promise.allSettled([loadLocales()]);
        };
        window.localesPromise = getLocales;
      `;
      // 是否build正式包
      const isProd = process.env.NODE_ENV === "production";
      return [
        {
          tag: "script",
          attrs: { type: "text/javascript" },
          children: isProd ? prodText : devText,
        },
      ];
    },
  };
}

在 vite.config.ts 中引入并使用

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import { htmlGetLocales } from "./vite.base.ts";

// https://vitejs.dev/config/
export default defineConfig(({ mode }) => {
  return {
    base: "./",
    plugins: [vue(), htmlGetLocales(mode)],
  };
});

(3)index.html 中引入 main.ts 的逻辑调整

先执行 localesPromise()再引入 main.ts

<script type="module">
  window.localesPromise().then(() => import("/src/main.ts"));
</script>
<!-- <script type="module" src="/src/main.ts"></script> --><!-- 注释原有的main.ts引入逻辑 -->

(4)src 下新增 i8n.ts 文件

在开发环境，获取的是本地存储的语言包；在生产环境，使用的是 src/locales 文件夹下的语言包

import { createI18n } from "vue-i18n";

const en = import.meta.glob("./locales/en.json", {
  eager: true,
  import: "default",
});
const zh = import.meta.glob("./locales/zh.json", {
  eager: true,
  import: "default",
});
type MessageSchema = typeof en;

// 获取本地存储语言包
const getStorageLocles = () => {
  const locales = JSON.parse(localStorage.getItem("locales") || "{}");
  return {
    en: locales.en,
    zh: locales.zh,
  };
};

const messages =
  import.meta.env.MODE === "production"
    ? { en: Object.values(en)[0] as any, zh: Object.values(zh)[0] as any }
    : getStorageLocles();

const i18n = createI18n<MessageSchema, "en" | "zh">({
  legacy: false,
  messages: messages,
  locale: "zh",
});

export default i18n;

2.生产环境：pnpm build 时先下载语言包文件

(1)编写 node 脚本，实现语言包下载功能

先安装 axios、dotenv、unzipper。

1	pnpm i axios

1	pnpm i --save-dev dotenv

1	pnpm i --save-dev unzipper

新增脚本文件 getDataExport.mjs

使用 axios 下载语言包 zip 文件，并解压到 src/locales

import axios from "axios";
import fs from "fs";
import path from "path";
import unzipper from "unzipper";
import dotenv from "dotenv";

// 加载根目录下.env文件
dotenv.config({ path: ".env" });

// locales文件目录
const localesDir = `src/locales`;

// 线上包只获取REVIEWED的翻译条目
const params =
  process.env.NODE_ENV === "production" ? "?filterState=REVIEWED" : "";

const config = {
  method: "get",
  maxBodyLength: Infinity,
  responseType: "stream",
  url: `${process.env.VITE_TOLGEE_URL}/v2/projects/${process.env.VITE_TOLGEE_PROJECT_ID}/export${params}`,
  headers: {
    Accept: "application/json",
    "X-API-Key": process.env.VITE_TOLGEE_KEY,
  },
};

// 清空文件夹
function emptyDirectorySync(dirPath) {
  const files = fs.readdirSync(dirPath);
  files.forEach((file) => {
    const filePath = path.join(dirPath, file);
    const stat = fs.statSync(filePath);
    if (stat.isDirectory()) {
      // 递归删除子文件夹
      emptyDirectorySync(filePath);
      fs.rmdirSync(filePath);
    } else {
      // 删除文件
      fs.unlinkSync(filePath);
    }
  });
}

// 解压文件,移动语言包到对应目录
const extractZip = async (fileData, outputDir) => {
  return new Promise((resolve, reject) => {
    fileData.data
      .pipe(unzipper.Extract({ path: outputDir }))
      .on("close", () => {
        resolve();
      })
      .on("error", (error) => {
        console.error("Error extracting ZIP file:", error);
        reject(error);
      });
  });
};

// 下载并解压语言包
const downloadAndExtractZip = async (outputDir) => {
  try {
    // 创建输出目录（如果不存在）
    if (!fs.existsSync(outputDir)) {
      fs.mkdirSync(outputDir, { recursive: true });
    } else {
      emptyDirectorySync(outputDir);
    }
    // 下载语言包ZIP文件
    const response = await axios(config);
    // 解压到对应文件夹
    await extractZip(response, outputDir);
    console.log("Successfully loaded locales");
  } catch (error) {
    console.error("Error downloading or extracting ZIP file:", error);
  }
};

downloadAndExtractZip(localesDir);

(2)新增自定义 Vite 插件 downloadLocales

在 vite.base.ts 文件添加自定义插件

import { execSync } from "child_process";

export function downloadLocales() {
  return {
    name: "download-locales-files",
    configResolved(config: any) {
      if (config.command === "build") {
        try {
          const res = execSync(`node getDataExport.mjs`);
          console.log(res.toString());
        } catch (error) {
          console.error(error);
        }
      }
    },
  };
}

这个插件会在 build 时先执行 getDataExport.mjs 脚本

最后将写好的插件引入 vite.config.ts 中使用

1	plugins: [..., downloadLocales()]

3.补充

在 package.json 加入 scripts 命令，使得开发过程中随时可以通过 pnpm getLocales 下载语言包（主要是方便 vscode 的 i18n Ally 插件，有翻译条目的预览效果）

"scripts": {
    ...
    "getLocales": "node getDataExport.mjs"
}