vite-i18n-langtool 插件文档

介绍

vite-i18n-langtool 是一个用于提取 Vue、TypeScript 和 JavaScript 项目中的国际化语言内容的 Vite 插件。它通过解析代码中的特定方法（例如 t() 或 $t()）或自定义标记来提取文本，生成 UUID，并输出一个包含所有提取文本的 JSON 文件。

该插件支持热更新 (HMR) 以及文件监听，可以在开发过程中自动更新语言文件。

安装

首先，确保你已经安装了 Vite 项目。然后通过 npm 或 yarn 安装插件：

npm install vite-i18n-langtool --save-dev

或者使用 yarn：

yarn add vite-i18n-langtool --dev

配置

你可以在 vite.config.js 或 vite.config.ts 文件中配置此插件。以下是插件的配置项：

import { defineConfig } from 'vite'
import viteI18nLangtool from 'vite-i18n-langtool'

export default defineConfig({
  plugins: [
    viteI18nLangtool({
      files: [".vue", ".ts", ".tsx"],   // 匹配文件后缀
      funRegName: ["$t", "t"],           // 提取方法
      strReg: "<t",                      // 匹配字段
      jsonOutPath: "public/lang/zh-cn.json", // 输出语言文件路径
      ignoreDir: ["node_modules", "dist"],  // 忽略的目录
      ignoreFiles: [],                  // 忽略的文件
      outlog: false,                    // 是否输出日志
      showMapFile: false,               // 是否在终端输出匹配内容
      hmr: "ws",                        // WebSocket 热更新
      creactWsLangPath: "src/lang/hmr.js"  // 创建 HMR 文件
    })
  ]
})

配置项说明

| 配置项 | 类型 | 默认值 | 说明 | | ------------------ | ------------- | ---------------------------------- | ------------------------------------------------------------ | | files | string[] | [".vue", ".ts", ".tsx"] | 匹配需要提取文本的文件后缀 | | funRegName | string[] | ["$t", "t"] | 用于提取文本的函数名，例如 t() 或 $t() | | strReg | string | <t | 匹配自定义文本提取标记，例如 <t=要提取的文本> | | jsonOutPath | string | public/lang/zh-cn.json | 输出的语言文件路径 | | ignoreDir | string[] | ["node_modules", "dist", "public"] | 忽略的目录 | | ignoreFiles | string[] | [] | 忽略的文件 | | outlog | boolean | false | 是否输出日志到文件 | | showMapFile | boolean | false | 是否在终端输出匹配内容 | | hmr | "ws" | "none" | ws | 是否启用热更新，支持 ws 或 none | | creactWsLangPath | string | undefined | 是否创建 HMR 热更新监听文件，指定 .js 或 .ts 文件路径 |

插件功能

1. 文本提取

插件会自动扫描指定文件中的文本，使用 t() 或 $t() 函数，或者自定义的 strReg 配置来提取需要翻译的文本。每个提取的文本都会生成一个唯一的 UUID。

<div>{{ t('文本') }}</div>
<div>{{ $t('文本') }}</div>
<div>{{ t('你好！{name}',{name:'vite-i18n-langtool'}) }}</div>
<div>{{ t('我是多重文本！{text}',{text:t('我是二次文本，{text}',{text:'没有了'})}) }}</div>
<div>{{ t(text) }}</div>
<div>{{ t(text1,{age:'10'}) }}</div>

<script setup>
  //.....
  const text = '<t=文本03'
  const text1 = '<t=年龄：{age}'
</script>

2. 输出语言文件

插件会将提取的所有文本存储在指定的 JSON 文件中，并以 UUID 作为键，文本内容作为值。例如：

{
  "123456": "欢迎使用",
  "789101": "你好，世界"
  // ····
}

3 HMR (热更新) hmr='ws' 通过ws传输更新 阻止jsonOutPath文件变化页面自动刷新

如果是启用 HMR.Hot，插件会在所有语言提取通过 WebSocket 将更新推送到浏览器，从而无需重新加载页面。

//开发模式下 - 通过ws更新语言库 也可以直接生成文件
import.meta.hot?.on('lang-update', setLang)

3.2 HMR (刷新更新) hmr='none' 不做阻止处理-页面会出现刷新

如果是默认 HMR，插件不会做处理 WebSocket 处理自定义的，默认会自动重新刷新页面。

4. 日志输出

当启用 outlog 配置时，插件会将提取日志输出到 jsonOutPath 相同目录 log.json 文件，方便开发者查看哪些文本被提取和处理。

5. 忽略文件和目录

通过配置 ignoreDir 和 ignoreFiles，插件可以跳过某些目录和文件的文本提取。

开发模式下的使用

在开发模式下，插件会自动监听文件的变化，并在文件发生变化时触发相应的更新。如果启用了 hmr=ws，语言文件会通过 WebSocket 推送到浏览器端。

如果需要手动触发 HMR 更新，可以在代码中使用 import.meta.hot.on('lang-update', (data) => {}) 来监听并更新语言数据。

打包时的处理

在打包过程中，插件会确保语言文件包含在构建产物中。语言文件会被写入到指定的路径，并且会根据配置生成语言映射文件。

public/lang/zh-cn.json  打包后 [dist]/lang/zh-cn.json

常见问题

1. 为什么语言文件没有更新？

如果你发现语言文件没有更新，可能是因为没有启用 HMR 或者 hmr 配置为 none。确保正确配置了 HMR，并且在文件变化时触发更新。

2. 如何避免某些文件被提取？

你可以通过配置 ignoreDir 和 ignoreFiles 来忽略某些目录或文件。

3. 开发下如何触发语言更新？ ws 模式下

在开发模式下，项目内你可以自动接收语言文件的更新

import.meta.hot.on('lang-update', setLang);

结语

vite-i18n-langtool 插件提供了一个强大的工具来帮助开发者提取、管理和更新国际化语言文件。它的配置灵活，支持热更新和详细的日志记录，适合用于中大型 Vue 或 TypeScript 项目的国际化开发。

vite-i18n-langtool Plugin Documentation

Introduction

vite-i18n-langtool is a Vite plugin designed to extract internationalization language content from Vue, TypeScript, and JavaScript projects. It parses specific methods in the code (such as t() or $t()) or custom tags to extract text, generate UUIDs, and output a JSON file containing all the extracted texts.

The plugin supports Hot Module Replacement (HMR) and file watching, allowing automatic updates of language files during development.

Installation

First, ensure that you have a Vite project. Then install the plugin via npm or yarn:

npm install vite-i18n-langtool --save-dev

Alternatively, you can use yarn:

yarn add vite-i18n-langtool --dev

Configuration

You can configure the plugin in your vite.config.js or vite.config.ts file. Below is an example configuration:

import { defineConfig } from 'vite'
import viteI18nLangtool from 'vite-i18n-langtool'

export default defineConfig({
  plugins: [
    viteI18nLangtool({
      files: [".vue", ".ts", ".tsx"],   // File extensions to match
      funRegName: ["$t", "t"],           // Text extraction functions
      strReg: "<t",                      // Custom tag for matching text
      jsonOutPath: "public/lang/zh-cn.json", // Output language file path
      ignoreDir: ["node_modules", "dist"],  // Directories to ignore
      ignoreFiles: [],                  // Files to ignore
      outlog: false,                    // Whether to output logs
      showMapFile: false,               // Whether to show matching content in terminal
      hmr: "ws",                        // WebSocket Hot Module Replacement
      creactWsLangPath: "src/lang/hmr.js"  // Create HMR listener file
    })
  ]
})

Configuration Options

| Option Name | Type | Default Value | Description | | ------------------- | ------------- | ------------------------------------ | ------------------------------------------------------------ | | files | string[] | [".vue", ".ts", ".tsx"] | File extensions to match for text extraction | | funRegName | string[] | ["$t", "t"] | Function names to extract text, e.g., t() or $t() | | strReg | string | <t | Custom tag for text extraction, e.g., <t=Text to extract> | | jsonOutPath | string | public/lang/zh-cn.json | Path to output the language file | | ignoreDir | string[] | ["node_modules", "dist", "public"] | Directories to ignore | | ignoreFiles | string[] | [] | Files to ignore | | outlog | boolean | false | Whether to output logs to a file | | showMapFile | boolean | false | Whether to output matching content in terminal | | hmr | "ws" | "none" | ws | Whether to enable HMR, supports ws or none | | creactWsLangPath | string | undefined | Path to create HMR listener file (.js or .ts file path) |

Plugin Features

1. Text Extraction

The plugin will automatically scan specified files for text using the t() or $t() functions or custom strReg configuration for text extraction. Each extracted text will generate a unique UUID.

<div>{{ t('Text') }}</div>
<div>{{ $t('Text') }}</div>
<div>{{ t('Hello, {name}',{name:'vite-i18n-langtool'}) }}</div>
<div>{{ t('I am nested text! {text}',{text:t('I am secondary text, {text}',{text:'No more'})}) }}</div>
<div>{{ t(text) }}</div>
<div>{{ t(text1,{age:'10'}) }}</div>

<script setup>
  //.....
  const text = '<t=Text03'
  const text1 = '<t=Age: {age}'
</script>

2. Output Language File

The plugin will store all extracted texts in a specified JSON file, using UUIDs as keys and text content as values. For example:

{
  "123456": "Welcome",
  "789101": "Hello, World"
  // ····
}

3. HMR (Hot Module Replacement)

HMR ('ws' mode): Through WebSocket, updates are pushed to the browser without refreshing the page.

When HMR is enabled (hmr='ws'), the plugin will push language updates to the browser through WebSocket, so the page does not need to be reloaded.

// In development mode - WebSocket will update the language library, or generate the file directly
import.meta.hot?.on('lang-update', setLang)

HMR ('none' mode): The page will be refreshed when the language file changes.

In the default HMR mode, the plugin does not block WebSocket handling, and the page will automatically refresh when the language file is updated.

4. Log Output

When the outlog option is enabled, the plugin will output the extraction logs to a log.json file in the same directory as jsonOutPath, making it easier for developers to see which texts were extracted and processed.

5. Ignore Files and Directories

By configuring ignoreDir and ignoreFiles, the plugin can skip text extraction for certain directories and files.

Usage in Development Mode

In development mode, the plugin will automatically watch for file changes and trigger updates when files change. If HMR is enabled with hmr='ws', language files will be pushed to the browser via WebSocket.

If you need to manually trigger an HMR update, you can listen for updates with import.meta.hot.on('lang-update', (data) => {}) in your code.

Processing During Build

During the build process, the plugin will ensure that the language files are included in the build output. The language files will be written to the specified path, and a language mapping file will be generated according to the configuration.

public/lang/zh-cn.json  => [dist]/lang/zh-cn.json after build

FAQ

1. Why isn't the language file updating?

If you find that the language file is not updating, it may be because HMR is not enabled, or the hmr option is set to none. Make sure HMR is correctly configured and triggered on file changes.

2. How can I avoid extracting texts from certain files?

You can configure ignoreDir and ignoreFiles to exclude certain directories or files from text extraction.

3. How to trigger language updates in development mode using WebSocket?

In development mode with WebSocket, the language file can be automatically updated:

import.meta.hot.on('lang-update', setLang);

Conclusion

The vite-i18n-langtool plugin provides a powerful tool for developers to extract, manage, and update internationalization language files. Its flexible configuration, support for hot updates, and detailed log output make it an excellent choice for medium to large Vue or TypeScript projects that require internationalization.

Let me know if you need any further adjustments!