@orderly.network/i18n 2.1.0 → 2.1.1

package/README.md

@@ -2,35 +2,115 @@
 
 Internationalization and cli tools for Orderly SDK. Based on i18next ecosystem.
 
-## Integration
+## Integration Guide
 
-### 1. Wrap LocaleProvider
+Follow these steps to integrate localization support in your app using Orderly SDK:
 
-The LocaleProvider is the core component that provides locale resources to your app. You must wrap you app with LocaleProvider.
+### 1. Wrap Your App with LocaleProvider
 
-### 2. Provide Resources
+The LocaleProvider is the core component that supplies localized resources to your application. Make sure to wrap your app’s root component with LocaleProvider.
 
-- By default, English (en) is included.
-- If you want to support other languages besides English, you need to explicitly import it from the i18n package and pass it to the resources prop of LocaleProvider.
-- Currently, we provider English (en) and Chinese (zh) locale files.
-- You can also extend the built-in messages by merging them with your own locale files.
-- With each release we will generate csv files (dist/locale.csv) for easy translation and we provide a cli to convert between csv and json files.
-- It can translate not only the ui in the SDK, but also other components you write outside of the SDK.
+```tsx
+import { LocaleProvider } from "@orderly.network/i18n";
 
-### Example
+<LocaleProvider>
+  <YourApp />
+</LocaleProvider>;
+```
+
+### 2. Provide Locale Data
+
+#### Default Language
+
+- English (`en`) is included by default.
+
+#### Supported Locales
+
+We currently support **8 locales**, located in the `dist/locales` directory:
+
+| Locale Code | Language   |
+| ----------- | ---------- |
+| `en.json`   | English    |
+| `zh.json`   | Chinese    |
+| `ja.json`   | Japanese   |
+| `es.json`   | Spanish    |
+| `ko.json`   | Korean     |
+| `vi.json`   | Vietnamese |
+| `de.json`   | German     |
+| `fr.json`   | French     |
+
+> We plan to add more languages in future updates.
+
+#### CSV for Easy Translation
+
+- Each release generates a `dist/locale.csv` file to simplify translation workflows.
+- We provide a CLI tool to convert between CSV and JSON formats.
+
+### 3. Extending Locale Files
+
+You can localize both the SDK UI and your own custom components.
+
+- When adding custom keys, prefix them with `extend.` to avoid conflicts with default keys.
+
+```json
+{
+  "extend.custom.button.label": "My Custom Button"
+}
+```
+
+## Example
+
+Here's a complete example of how to set up the i18n integration:
 
-Here’s a complete example of how to set up the i18n integration:
+### Async load locale files
 
 ```typescript
 import { FC, ReactNode } from "react";
 import { WalletConnectorProvider } from "@orderly.network/wallet-connector";
 import { OrderlyAppProvider } from "@orderly.network/react-app";
-import {
-  LocaleProvider,
-  Resources,
-  LocaleCode,
-  zh,
-} from "@orderly.network/i18n";
+import { LocaleProvider, LocaleEnum, LocaleCode } from "@orderly.network/i18n";
+
+const OrderlyProvider: FC<{ children: ReactNode }> = (props) => {
+  const onLanguageChanged = async (lang: LocaleCode) => {};
+
+  // please copy build-in locale files to you public/locales
+  // and copy you extend locale files to public/locales/extend
+  const loadPath = (lang: LocaleCode) => {
+    const _lang = parseI18nLang(lang);
+    if (_lang === LocaleEnum.en) {
+      // because en is built-in, we need to load the en extend only
+      return `/locales/extend/${_lang}.json`;
+    }
+    return [`/locales/${_lang}.json`, `/locales/extend/${_lang}.json`];
+  };
+
+  return (
+    <LocaleProvider
+      onLanguageChanged={onLanguageChanged}
+      backend={{ loadPath }}
+    >
+      <WalletConnectorProvider>
+        <OrderlyAppProvider
+          brokerId="orderly"
+          brokerName="Orderly"
+          networkId="testnet"
+        >
+          {props.children}
+        </OrderlyAppProvider>
+      </WalletConnectorProvider>
+    </LocaleProvider>
+  );
+};
+```
+
+### Sync Load locale data
+
+```typescript
+import { FC, ReactNode } from "react";
+import { WalletConnectorProvider } from "@orderly.network/wallet-connector";
+import { OrderlyAppProvider } from "@orderly.network/react-app";
+import { LocaleProvider, LocaleCode, Resources } from "@orderly.network/i18n";
+import zh from "@orderly.network/i18n/locales/zh.json";
 
 // extend or overrides English translations
 const extendEn = {
@@ -42,10 +122,8 @@ const extendZh = {
   "extend.trading": "交易",
 };
 
-type ExtendLocaleMessages = typeof extendEn;
-
 // define language resources
-const resources: Resources<ExtendLocaleMessages> = {
+const resources: Resources = {
   en: extendEn,
   zh: {
     ...zh,
@@ -54,10 +132,10 @@ const resources: Resources<ExtendLocaleMessages> = {
 };
 
 const OrderlyProvider: FC<{ children: ReactNode }> = (props) => {
-  const onLocaleChange = (locale: LocaleCode) => {};
+  const onLanguageChanged = (locale: LocaleCode) => {};
 
   return (
-    <LocaleProvider resources={resources} onLocaleChange={onLocaleChange}>
+    <LocaleProvider resources={resources} onLanguageChanged={onLocaleChange}>
       <WalletConnectorProvider>
         <OrderlyAppProvider
           brokerId="orderly"
@@ -72,7 +150,7 @@ const OrderlyProvider: FC<{ children: ReactNode }> = (props) => {
 };
 ```
 
-### Add more languages
+### Add custom languages
 
 We also support adding more custom languages
 
@@ -83,7 +161,6 @@ import { OrderlyAppProvider } from "@orderly.network/react-app";
 import {
   LocaleProvider,
   Resources,
-  zh,
   LocaleEnum,
   LocaleCode,
   Language,
@@ -101,7 +178,6 @@ const ko = {
 
 // define language resources
 const resources: Resources = {
-  en,
   ja,
   ko,
 };
@@ -114,13 +190,13 @@ const languages: Language[] = [
 ];
 
 const OrderlyProvider: FC<{ children: ReactNode }> = (props) => {
-  const onLocaleChange = (locale: LocaleCode) => {};
+  const onLanguageChanged = (locale: LocaleCode) => {};
 
   return (
     <LocaleProvider
       resources={resources}
       languages={languages}
-      onLocaleChange={onLocaleChange}
+      onLanguageChanged={onLanguageChanged}
     >
       <WalletConnectorProvider>
         <OrderlyAppProvider
@@ -159,7 +235,7 @@ npx @orderly.network/i18n csv2json <input> <outputDir>
 Example:
 
 ```bash
-npx @orderly.network/i18n csv2json ./dist/locale.csv ./dist/locale
+npx @orderly.network/i18n csv2json ./dist/locale.csv ./dist/locales
 ```
 
 ### json2csv
@@ -167,13 +243,13 @@ npx @orderly.network/i18n csv2json ./dist/locale.csv ./dist/locale
 Convert multiple locale JSON files to a single locale CSV file.
 
 ```bash
-npx @orderly.network/i18n json2csv <input> <output>
+npx @orderly.network/i18n json2csv <inputDir> <output>
 ```
 
 Example:
 
 ```bash
-npx @orderly.network/i18n json2csv ./dist/locale/en.json,./dist/locale/zh.json ./dist/locale.csv
+npx @orderly.network/i18n json2csv ./locales ./dist/locale.csv
 ```
 
 ### diffcsv
@@ -190,30 +266,44 @@ Example:
 npx @orderly.network/i18n diffcsv ./dist/locale1.csv ./dist/locale2.csv
 ```
 
-### generateCsv
+### fillJson
 
-Generate a locale CSV file from your source files.
+Fill values from an input locale JSON file and generate a new locale JSON file.
 
 ```bash
-npx @orderly.network/i18n generateCsv <output>
+npx @orderly.network/i18n fillJson <input> <output>
 ```
 
 Example:
 
 ```bash
-npx @orderly.network/i18n generateCsv ./dist/locale.csv
+npx @orderly.network/i18n fillJson ./src/locale/zh.json ./dist/locale/zh.json
 ```
 
-### fillJson
+### separateJson
 
-Fill values from an input locale JSON file and generate a new locale JSON file.
+Separate JSON files into default and extend key values based on a specified key.
 
 ```bash
-npx @orderly.network/i18n fillJson <input> <output>
+npx @orderly.network/i18n separateJson <inputDir> <outputDir> <separateKey>
 ```
 
 Example:
 
 ```bash
-npx @orderly.network/i18n fillJson ./src/locale/zh.json ./dist/locale/zh.json
+npx @orderly.network/i18n separateJson ./locales ./dist/locales extend
+```
+
+### mergeJson
+
+Merge default and extend JSON files back into one file.
+
+```bash
+npx @orderly.network/i18n mergeJson <inputDir> <outputDir>
+```
+
+Example:
+
+```bash
+npx @orderly.network/i18n mergeJson ./dist/locales1 ./dist/locales2
 ```

package/bin/cli.js

@@ -2,24 +2,35 @@
 
 const yargs = require("yargs/yargs");
 const { hideBin } = require("yargs/helpers");
-const { generateCsv } = require("../script/generateCsv");
+// const { generateCsv } = require("../script/generateCsv");
 const { json2csv } = require("../script/json2csv");
 const { csv2json } = require("../script/csv2json");
 const { diffCsv } = require("../script/diffCsv");
 const { fillJson } = require("../script/fillJson");
+const { separateJson } = require("../script/separateJson");
+const { mergeJson } = require("../script/mergeJson");
 main();
 
 async function main() {
   const argv = getArgv();
 
-  const { _, input, output, oldFile, newFile, outputDir } = argv;
+  const {
+    _,
+    input,
+    output,
+    oldFile,
+    newFile,
+    inputDir,
+    outputDir,
+    separateKey,
+  } = argv;
 
   const command = _[0];
   // console.log("argv", argv);
 
   switch (command) {
     case "json2csv":
-      await json2csv(input, output);
+      await json2csv(inputDir, output);
       break;
     case "csv2json":
       await csv2json(input, outputDir);
@@ -27,12 +38,18 @@ async function main() {
     case "diffcsv":
       await diffCsv(oldFile, newFile);
       break;
-    case "generateCsv":
-      await generateCsv(output);
-      break;
+    // case "generateCsv":
+    //   await generateCsv(output);
+    //   break;
     case "fillJson":
       await fillJson(input, output);
       break;
+    case "separateJson":
+      await separateJson(inputDir, outputDir, separateKey);
+      break;
+    case "mergeJson":
+      await mergeJson(inputDir, outputDir);
+      break;
     default:
       console.log("Invalid command");
       break;
@@ -77,13 +94,13 @@ function getArgv() {
 
     // json2csv command
     .command(
-      "json2csv <input> <output>",
+      "json2csv <inputDir> <output>",
       "Convert locale JSON files to a locale CSV file",
       (yargs) => {
         return yargs
-          .positional("input", {
+          .positional("inputDir", {
             describe:
-              "Path to locale JSON file(s) (supports multiple files, separated by commas)",
+              "Input directory for locale JSON files (all JSON files in the directory will be converted)",
             type: "string",
             demandOption: true,
           })
@@ -94,11 +111,8 @@ function getArgv() {
           });
       },
       (argv) => {
-        const inputFiles = argv.input.split(","); // Parse multiple input files
         console.log(
-          `Converting locale JSON files: ${inputFiles.join(
-            ", "
-          )} to locale CSV: ${argv.output}`
+          `Converting locale JSON files: ${argv.inputDir} to locale CSV: ${argv.output}`
         );
       }
     )
@@ -128,21 +142,21 @@ function getArgv() {
     )
 
     // generateCsv command
-    .command(
-      "generateCsv <output>",
-      "Generate a locale CSV file",
-      (yargs) => {
-        return yargs.positional("output", {
-          describe: "Output path for the locale CSV file",
-          type: "string",
-          // Required
-          demandOption: true,
-        });
-      },
-      (argv) => {
-        console.log(`Generating locale CSV file at: ${argv.output}`);
-      }
-    )
+    // .command(
+    //   "generateCsv <output>",
+    //   "Generate a locale CSV file",
+    //   (yargs) => {
+    //     return yargs.positional("output", {
+    //       describe: "Output path for the locale CSV file",
+    //       type: "string",
+    //       // Required
+    //       demandOption: true,
+    //     });
+    //   },
+    //   (argv) => {
+    //     console.log(`Generating locale CSV file at: ${argv.output}`);
+    //   }
+    // )
 
     // fillJson command
     .command(
@@ -166,7 +180,61 @@ function getArgv() {
           `Filling values from the input locale JSON file: ${argv.input} and generating a new locale JSON file: ${argv.output}`
         );
       }
-    ).argv;
+    )
+
+    // separateJson command
+    .command(
+      "separateJson <inputDir> <outputDir> <separateKey>",
+      "Separate json file default and extend key values based on the key",
+      (yargs) => {
+        return yargs
+          .positional("inputDir", {
+            describe: "Input directory for locale JSON files",
+            type: "string",
+            demandOption: true,
+          })
+          .positional("outputDir", {
+            describe: "Output directory for locale JSON files",
+            type: "string",
+            demandOption: true,
+          })
+          .positional("separateKey", {
+            describe: "Key to separate the json files",
+            type: "string",
+            demandOption: true,
+          });
+      },
+      (argv) => {
+        console.log(
+          `Separating json files into multiple files: ${argv.inputDir} to ${argv.outputDir} with key: ${argv.key}`
+        );
+      }
+    )
+
+    // mergeJson command
+    .command(
+      "mergeJson <inputDir> <outputDir>",
+      "Merge default and extend JSON files back into one file",
+      (yargs) => {
+        return yargs
+          .positional("inputDir", {
+            describe:
+              "Input directory containing both default and extend JSON files",
+            type: "string",
+            demandOption: true,
+          })
+          .positional("outputDir", {
+            describe: "Output directory for merged JSON files",
+            type: "string",
+            demandOption: true,
+          });
+      },
+      (argv) => {
+        console.log(
+          `Merging JSON files from ${argv.inputDir} to ${argv.outputDir}`
+        );
+      }
+    );
 
-  return argv;
+  return argv.argv;
 }