Merge pull request #133 from warjiang/feature/i18n-glossary

add docs for i18n-tool

ui/packages/i18n-tool/README.md

@@ -0,0 +1,43 @@
+# Install
+
+
+```shell
+npm install -g @karmada/i18n-tool
+```
+
+
+# Basic Usage
+For a whole frontend project which need to i18n, you can do as following:
+```shell
+# init config for under your project
+# here you can modify the config according to the instructions
+i18n-tool/node_modules/.bin/i18n-tool init
+
+# scan the Chinese and replace with i18n function invoke
+# generate corresponding locales files
+i18n-tool/node_modules/.bin/i18n-tool scan -c ./i18n.config.cjs
+```
+
+For a directory which need to i18n, you can specify with `-d` options 
+```shell
+i18n-tool/node_modules/.bin/i18n-tool scan -d directory/to/your/code
+```
+
+For a single file which need to i18n, you can specify with `-f` options 
+```shell
+i18n-tool/node_modules/.bin/i18n-tool scan -f path/to/your/code/file
+```
+
+# Advanced Usage
+For those advanced developer, maybe they need to specify glossaries install of automatic translation. For these kind of 
+scenarios, you can create a `glossaries.csv` under the directory of locales, the format of `glossaries.csv` should like
+```csv
+i18n-key,zh-CN,en-US
+86385379cf9cfbc2c554944f1c054a45,概览,Overview
+21a4e07b08a4efbbfe2b9d88c208836a,多云资源管理,MultiCloud Resource Management
+85fe5099f6807dada65d274810933389,集群,Cluster
+```
+after create the `glossaries.csv`, for the same i18n-key, `i18n-tool` will use the content specified in `glossaries.csv` 
+instead of automatic translation.
+
+

ui/packages/i18n-tool/package.json

@@ -12,7 +12,9 @@
     "commander": "^12.1.0",
     "debug": "^4.3.5",
     "glob": "^11.0.0",
-    "prettier": "^3.3.2"
+    "prettier": "^3.3.2",
+    "csv-parse": "^5.5.6",
+    "lodash": "^4.17.21"
   },
   "scripts": {
     "test": "vitest"

ui/packages/i18n-tool/src/scan/glossary.js

@@ -0,0 +1,29 @@
+const fs = require("node:fs")
+const {parse} = require('csv-parse/sync')
+const {omit} = require('lodash')
+
+function makeGlossaryMap(records) {
+    const _records = records || []
+    return _records.reduce((p, c) => {
+        const i18nKey = c['i18n-key']
+        const restData = omit(c, 'i18n-key')
+        return {
+            ...p,
+            [i18nKey]: restData
+        }
+    }, {})
+}
+
+function initGlossaries(glossaryFilePath) {
+    if (!fs.existsSync(glossaryFilePath)) return {}
+    const content = fs.readFileSync(glossaryFilePath).toString()
+    const records = parse(content, {
+        columns: true,
+        skip_empty_lines: true,
+    });
+    return makeGlossaryMap(records)
+}
+
+module.exports = {
+    initGlossaries
+}

ui/packages/i18n-tool/src/scan/index.js

@@ -5,6 +5,7 @@ const {getDebug, parseFiles, buildLocalFilename} = require('../utils')
 const {getDefaultOptions, parseI18nConfig} = require('../options')
 const {processAST, generateCode} = require('./ast')
 const {translate, updateLocale} = require('./translate')
+const {initGlossaries} = require('./glossary');
 const debug = getDebug('scan');
 
 async function scan(cmdOptions) {
@@ -52,11 +53,6 @@ async function scan(cmdOptions) {
     }
 
     const cnLocalePath = buildLocalFilename(options.localesDir, options.originLang)
-    let existingData = {}
-    if (needUpdateLocale) {
-        existingData = JSON.parse(fs.readFileSync(cnLocalePath, 'utf8'));
-    }
-
 
     const prettierConfig = await prettier.resolveConfig(path.join(process.cwd(), '.prettierrc'));
 
@@ -79,11 +75,34 @@ async function scan(cmdOptions) {
             }
         }
     }
+
+    // intercept updatedData
+    // for scenario of glossary, the i18n-tool should use translation in glossary first
+    const glossaryFilePath = path.join(options.localesDir, `glossaries.csv`)
+    debug("glossaryFilePath is %s", glossaryFilePath)
+    const glossaryData = initGlossaries(glossaryFilePath)
+    debug('glossaryData is %O', glossaryData);
+    /*
+    {
+        "zh-CN": {
+            updatedData but remove zh-CN column glossaries
+        },
+        "en-US": {
+            updatedData but remove en-US column glossaries
+        }
+    }
+    */
+    const groupedGlossaryData = {}
+    for (const key of Object.keys(glossaryData)) {
+        const tmp = glossaryData[key];
+        for (const lang of Object.keys(tmp)) {
+            groupedGlossaryData[lang] = groupedGlossaryData[lang] || {}
+            groupedGlossaryData[lang][key] = tmp[lang]
+        }
+    }
+    debug('groupedGlossaryData is %O', groupedGlossaryData);
     if (needUpdateLocale) {
-        fs.writeFileSync(cnLocalePath, JSON.stringify({
-            ...existingData,
-            ...updatedData,
-        }))
+        updateLocale(cnLocalePath, updatedData, groupedGlossaryData['zh-CN'])
     }
 
     if (needUpdateLocale) {
@@ -97,7 +116,7 @@ async function scan(cmdOptions) {
                 from: options.originLang,
                 to: targetLang
             })
-            updateLocale(targetLocalePath, targetLangLocale)
+            updateLocale(targetLocalePath, targetLangLocale, groupedGlossaryData[targetLang])
         }
     }
 

ui/packages/i18n-tool/src/scan/translate.js

@@ -47,13 +47,15 @@ function initTranslator(translateOpts) {
 
 }
 
-function updateLocale(localePath, newEntries) {
-     const existingData = JSON.parse(fs.readFileSync(localePath, 'utf8'));
-     const mergedData = {
-         ...existingData,
-         ...newEntries,
-     };
-     fs.writeFileSync(localePath, JSON.stringify(mergedData, null, 2), 'utf8');
+function updateLocale(localePath, newEntries, glossaries) {
+    const _glossaries = glossaries || {}
+    const existingData = JSON.parse(fs.readFileSync(localePath, 'utf8'));
+    const mergedData = {
+        ...existingData,
+        ...newEntries,
+        ..._glossaries
+    };
+    fs.writeFileSync(localePath, JSON.stringify(mergedData, null, 2), 'utf8');
 }
 
 module.exports = {