@orderly.network/i18n 2.12.0 → 2.12.1-alpha.0

package/README.md

@@ -1,334 +1,47 @@
 # @orderly.network/i18n
 
-Internationalization and cli tools for Orderly SDK. Based on i18next ecosystem.
+Internationalization and CLI tools for Orderly SDK. Based on i18next ecosystem.
 
-## Integration Guide
+## Quick start
 
-Follow these steps to integrate localization support in your app using Orderly SDK:
-
-### 1. Wrap Your App with LocaleProvider
-
-The LocaleProvider is the core component that supplies localized resources to your application. Make sure to wrap your app’s root component with LocaleProvider.
+Install the package, wrap your app root with `LocaleProvider`, and you get English by default.
 
 ```tsx
 import { LocaleProvider } from "@orderly.network/i18n";
 
-<LocaleProvider>
-  <YourApp />
-</LocaleProvider>;
-```
-
-### 2. Provide Locale Data
-
-#### Default Language
-
-- English (`en`) is included by default.
-
-#### Supported Locales
-
-We currently support **16 locales**
-
-| Locale Code | Language   |
-| ----------- | ---------- |
-| `en`        | English    |
-| `zh`        | Chinese    |
-| `ja`        | Japanese   |
-| `es`        | Spanish    |
-| `ko`        | Korean     |
-| `vi`        | Vietnamese |
-| `de`        | German     |
-| `fr`        | French     |
-| `ru`        | Russian    |
-| `id`        | Indonesian |
-| `tr`        | Turkish    |
-| `it`        | Italian    |
-| `pt`        | Portuguese |
-| `uk`        | Ukrainian  |
-| `pl`        | Polish     |
-| `nl`        | Dutch      |
-
-#### 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:
-
-### 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, LocaleEnum, LocaleCode } from "@orderly.network/i18n";
-
-const OrderlyProvider: FC<{ children: ReactNode }> = (props) => {
-  const onLanguageChanged = async (lang: LocaleCode) => {};
-
-  // please copy build-in locale files (@orderly.network/i18n/locales) to you public/locales
-  // and copy you extend locale files to public/locales/extend
-  const loadPath = (lang: LocaleCode) => {
-    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`];
-  };
-
+export function App() {
   return (
-    <LocaleProvider
-      onLanguageChanged={onLanguageChanged}
-      backend={{ loadPath }}
-    >
-      <WalletConnectorProvider>
-        <OrderlyAppProvider
-          brokerId="orderly"
-          brokerName="Orderly"
-          networkId="testnet"
-        >
-          {props.children}
-        </OrderlyAppProvider>
-      </WalletConnectorProvider>
+    <LocaleProvider>
+      <YourApp />
     </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";
-import ja from "@orderly.network/i18n/locales/ja.json";
-import ko from "@orderly.network/i18n/locales/ko.json";
-
-// extend or overrides English translations
-const extendEn = {
-  "extend.trading": "Trading",
-};
-
-// extend or overrides chinese translations
-const extendZh = {
-  "extend.trading": "交易",
-};
-
-// extend or overrides japanese translations
-const extendJa = {
-  "extend.trading": "取引",
-};
-
-// extend or overrides korean translations
-const extendKo = {
-  "extend.trading": "거래",
-};
-
-// define language resources
-const resources: Resources = {
-  en: extendEn,
-  zh: {
-    ...zh,
-    ...extendZh,
-  },
-  ja: {
-    ...ja,
-    ...extendJa,
-  },
-  ko: {
-    ...ko,
-    ...extendKo,
-  },
-};
-
-const OrderlyProvider: FC<{ children: ReactNode }> = (props) => {
-  const onLanguageChanged = (locale: LocaleCode) => {};
-
-  return (
-    <LocaleProvider resources={resources} onLanguageChanged={onLocaleChange}>
-      <WalletConnectorProvider>
-        <OrderlyAppProvider
-          brokerId="orderly"
-          brokerName="Orderly"
-          networkId="testnet"
-        >
-          {props.children}
-        </OrderlyAppProvider>
-      </WalletConnectorProvider>
-    </LocaleProvider>
-  );
-};
-```
-
-### Add custom languages
-
-We also support adding more custom languages
-
-```typescript
-import { FC, ReactNode } from "react";
-import { WalletConnectorProvider } from "@orderly.network/wallet-connector";
-import { OrderlyAppProvider } from "@orderly.network/react-app";
-import {
-  LocaleProvider,
-  Resources,
-  LocaleEnum,
-  LocaleCode,
-  Language,
-} from "@orderly.network/i18n";
-
-// japanese locale
-const ja = {
-  "extend.ja": "日本語",
-};
-
-// korean locale
-const ko = {
-  "extend.ko": "한국어",
-};
-
-// define language resources
-const resources: Resources = {
-  ja,
-  ko,
-};
-
-// custom languages
-const languages: Language[] = [
-  { localCode: LocaleEnum.en, displayName: "English" },
-  { localCode: LocaleEnum.ja, displayName: "日本語" },
-  { localCode: LocaleEnum.ko, displayName: "한국어" },
-];
-
-const OrderlyProvider: FC<{ children: ReactNode }> = (props) => {
-  const onLanguageChanged = (locale: LocaleCode) => {};
-
-  return (
-    <LocaleProvider
-      resources={resources}
-      languages={languages}
-      onLanguageChanged={onLanguageChanged}
-    >
-      <WalletConnectorProvider>
-        <OrderlyAppProvider
-          brokerId="orderly"
-          brokerName="Orderly"
-          networkId="testnet"
-        >
-          {props.children}
-        </OrderlyAppProvider>
-      </WalletConnectorProvider>
-    </LocaleProvider>
-  );
-};
-```
-
-## CLI
-
-## Usage
-
-The package provides a CLI tool for managing Internationalization files.
-
-```bash
-npx @orderly.network/i18n <command> [options]
-```
-
-## Commands
-
-### csv2json
-
-Convert a locale CSV file to multiple locale JSON files.
-
-```bash
-npx @orderly.network/i18n csv2json <input> <outputDir>
-```
-
-Example:
-
-```bash
-npx @orderly.network/i18n csv2json ./dist/locale.csv ./dist/locales
-```
-
-### json2csv
-
-Convert multiple locale JSON files to a single locale CSV file.
-
-```bash
-npx @orderly.network/i18n json2csv <inputDir> <output>
-```
-
-Example:
-
-```bash
-npx @orderly.network/i18n json2csv ./locales ./dist/locale.csv
-```
-
-### diffcsv
-
-Compare two locale CSV files to find differences.
-
-```bash
-npx @orderly.network/i18n diffcsv <oldFile> <newFile>
-```
-
-Example:
-
-```bash
-npx @orderly.network/i18n diffcsv ./dist/locale1.csv ./dist/locale2.csv
-```
-
-### fillJson
-
-Fill values from an input locale JSON file and generate a new locale JSON file.
-
-```bash
-npx @orderly.network/i18n fillJson <input> <output>
+}
 ```
 
-Example:
-
-```bash
-npx @orderly.network/i18n fillJson ./src/locale/zh.json ./dist/locale/zh.json
-```
+For multiple locales, custom keys, Vite bundling, HTTP loading, or the CLI, see the **Documentation** links below.
 
-### separateJson
+## Documentation
 
-Separate JSON files into default and extend key values based on a specified key.
+| Topic                                                             | Link                                                     |
+| ----------------------------------------------------------------- | -------------------------------------------------------- |
+| AI / Agent integration                                            | [docs/guide/AGENTS.md](./docs/guide/AGENTS.md)           |
+| Package exports                                                   | [docs/guide/exports.md](./docs/guide/exports.md)         |
+| Integration (providers, locales, extend keys, external resources) | [docs/guide/integration.md](./docs/guide/integration.md) |
+| Utils (paths and locale helpers)                                  | [docs/guide/utils.md](./docs/guide/utils.md)             |
+| Examples (recommended AsyncResources + alternatives)              | [docs/guide/examples.md](./docs/guide/examples.md)       |
+| CLI (`i18n` binary)                                               | [docs/guide/cli.md](./docs/guide/cli.md)                 |
 
-```bash
-npx @orderly.network/i18n separateJson <inputDir> <outputDir> <separateKey>
-```
+**Suggested reading order:** Agents start with [AGENTS](./docs/guide/AGENTS.md). Otherwise: [Integration](./docs/guide/integration.md) (API and behavior) → [Examples](./docs/guide/examples.md) (copy-paste recipes as needed) → [CLI](./docs/guide/cli.md) / [Utils](./docs/guide/utils.md) when relevant.
 
-Example:
+Generated API notes for `src/` live under `packages/i18n/docs/` in the monorepo only (not published in the npm package). The **user guide** under `docs/guide/` is included in the package so links above work after `npm install`.
 
-```bash
-npx @orderly.network/i18n separateJson ./locales ./dist/locales extend
-```
+### Package exports (summary)
 
-### mergeJson
+| Export                            | Description                                                                                                  |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `@orderly.network/i18n`           | Main entry: providers, hooks, `i18n`, resource helpers, types — see [exports guide](./docs/guide/exports.md) |
+| `@orderly.network/i18n/locales/*` | Built-in locale JSON files                                                                                   |
+| `@orderly.network/i18n/constant`  | Constants (`LocaleEnum`, `defaultLanguages`, …)                                                              |
+| `@orderly.network/i18n/utils`     | Utilities — see [Utils](./docs/guide/utils.md)                                                               |
 
-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
-```
+The default i18n namespace is **`translation`** (`defaultNS`).

package/bin/cli.js

@@ -2,13 +2,14 @@
 
 const yargs = require("yargs/yargs");
 const { hideBin } = require("yargs/helpers");
-// 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");
+const { generateCsv } = require("../scripts/generateCsv");
+const { json2csv } = require("../scripts/json2csv");
+const { csv2json } = require("../scripts/csv2json");
+const { diffCsv } = require("../scripts/diffCsv");
+const { fillJson } = require("../scripts/fillJson");
+const { separateJson } = require("../scripts/separateJson");
+const { mergeJson } = require("../scripts/mergeJson");
+const { filterLocaleKeys } = require("../scripts/filterLocaleKeys");
 main();
 
 async function main() {
@@ -23,6 +24,10 @@ async function main() {
     inputDir,
     outputDir,
     separateKey,
+    keep,
+    remove,
+    prefix,
+    localesDir,
   } = argv;
 
   const command = _[0];
@@ -38,9 +43,9 @@ async function main() {
     case "diffcsv":
       await diffCsv(oldFile, newFile);
       break;
-    // case "generateCsv":
-    //   await generateCsv(output);
-    //   break;
+    case "generateCsv":
+      await generateCsv(inputDir, output);
+      break;
     case "fillJson":
       await fillJson(input, output);
       break;
@@ -50,6 +55,9 @@ async function main() {
     case "mergeJson":
       await mergeJson(inputDir, outputDir);
       break;
+    case "filterKeys":
+      filterLocaleKeys(remove ? "remove" : "keep", prefix, localesDir);
+      break;
     default:
       console.log("Invalid command");
       break;
@@ -87,9 +95,9 @@ function getArgv() {
       },
       (argv) => {
         console.log(
-          `Converting ${argv.input} to locale JSON files, output directory: ${argv.outputDir}`
+          `Converting ${argv.input} to locale JSON files, output directory: ${argv.outputDir}`,
         );
-      }
+      },
     )
 
     // json2csv command
@@ -112,9 +120,9 @@ function getArgv() {
       },
       (argv) => {
         console.log(
-          `Converting locale JSON files: ${argv.inputDir} to locale CSV: ${argv.output}`
+          `Converting locale JSON files: ${argv.inputDir} to locale CSV: ${argv.output}`,
         );
-      }
+      },
     )
 
     // diffcsv command
@@ -136,27 +144,32 @@ function getArgv() {
       },
       (argv) => {
         console.log(
-          `Comparing locale CSV files: ${argv.oldFile} and ${argv.newFile}`
+          `Comparing locale CSV files: ${argv.oldFile} and ${argv.newFile}`,
         );
-      }
+      },
     )
 
     // 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 <inputDir> <output>",
+      "Generate a locale CSV file from locale JSON files",
+      (yargs) => {
+        return yargs
+          .positional("inputDir", {
+            describe: "Input directory for locale JSON files",
+            type: "string",
+            demandOption: true,
+          })
+          .positional("output", {
+            describe: "Output path for the locale CSV file",
+            type: "string",
+            demandOption: true,
+          });
+      },
+      (argv) => {
+        console.log(`Generating locale CSV file at: ${argv.output}`);
+      },
+    )
 
     // fillJson command
     .command(
@@ -177,9 +190,9 @@ function getArgv() {
       },
       (argv) => {
         console.log(
-          `Filling values from the input locale JSON file: ${argv.input} and generating a new locale JSON file: ${argv.output}`
+          `Filling values from the input locale JSON file: ${argv.input} and generating a new locale JSON file: ${argv.output}`,
         );
-      }
+      },
     )
 
     // separateJson command
@@ -206,9 +219,9 @@ function getArgv() {
       },
       (argv) => {
         console.log(
-          `Separating json files into multiple files: ${argv.inputDir} to ${argv.outputDir} with key: ${argv.key}`
+          `Separating json files into multiple files: ${argv.inputDir} to ${argv.outputDir} with key: ${argv.key}`,
         );
-      }
+      },
     )
 
     // mergeJson command
@@ -231,9 +244,51 @@ function getArgv() {
       },
       (argv) => {
         console.log(
-          `Merging JSON files from ${argv.inputDir} to ${argv.outputDir}`
+          `Merging JSON files from ${argv.inputDir} to ${argv.outputDir}`,
+        );
+      },
+    )
+
+    // filterKeys command (filterLocaleKeys script)
+    .command(
+      "filterKeys [options]",
+      "Filter locale JSON keys by prefix: keep or remove keys matching the prefix (operates on packages/i18n/locales by default)",
+      (yargs) => {
+        return yargs
+          .option("keep", {
+            alias: "k",
+            type: "boolean",
+            describe: "Keep only keys that start with the given prefix",
+          })
+          .option("remove", {
+            alias: "r",
+            type: "boolean",
+            describe: "Remove keys that start with the given prefix",
+          })
+          .option("prefix", {
+            type: "string",
+            demandOption: true,
+            describe: "Key prefix to match (e.g. trading. or trading)",
+          })
+          .option("locales-dir", {
+            type: "string",
+            describe:
+              "Directory containing locale JSON files (default: packages/i18n/locales)",
+          })
+          .check((argv) => {
+            if (argv.keep === argv.remove) {
+              throw new Error(
+                "Please specify exactly one of --keep|-k or --remove|-r",
+              );
+            }
+            return true;
+          });
+      },
+      (argv) => {
+        console.log(
+          `Filtering locale keys: ${argv.remove ? "removing" : "keeping"} keys with prefix "${argv.prefix}"`,
         );
-      }
+      },
     );
 
   return argv.argv;

package/dist/{constant-D_rlt5w0.d.mts → constant-DkvDyddr.d.mts}

@@ -1,6 +1,7 @@
 import * as react from 'react';
 
 declare const en: {
+    "tradingPoints.points": string;
     "notification.campaign": string;
     "notification.delisting": string;
     "notification.general": string;
@@ -130,42 +131,6 @@ declare const en: {
     "errorBoundary.refresh": string;
     "dmm.maker": string;
     "dmm.taker": string;
-    "tradingPoints.points": string;
-    "tradingPoints.startsIn": string;
-    "tradingPoints.days": string;
-    "tradingPoints.hours": string;
-    "tradingPoints.minutes": string;
-    "tradingPoints.seconds": string;
-    "tradingPoints.learnMore": string;
-    "tradingPoints.stagePoints": string;
-    "tradingPoints.stageRanking": string;
-    "tradingPoints.referralCode": string;
-    "tradingPoints.referralLink": string;
-    "tradingPoints.currentPoints": string;
-    "tradingPoints.ranking": string;
-    "tradingPoints.myPoints": string;
-    "tradingPoints.thisWeek": string;
-    "tradingPoints.lastWeek": string;
-    "tradingPoints.all": string;
-    "tradingPoints.tradePoints": string;
-    "tradingPoints.tradePointsTooltip": string;
-    "tradingPoints.tradeNow": string;
-    "tradingPoints.pnlPoints": string;
-    "tradingPoints.pnlPointsTooltip": string;
-    "tradingPoints.referralPoints": string;
-    "tradingPoints.referralPointsTooltip": string;
-    "tradingPoints.copyLink": string;
-    "tradingPoints.faq.title": string;
-    "tradingPoints.faq.whatArePoints.question": string;
-    "tradingPoints.faq.whatArePoints.answer": string;
-    "tradingPoints.faq.allocation.question": string;
-    "tradingPoints.faq.allocation.answer": string;
-    "tradingPoints.faq.distribution.question": string;
-    "tradingPoints.faq.distribution.answer": string;
-    "tradingPoints.faq.pnl.question": string;
-    "tradingPoints.faq.pnl.answer": string;
-    "tradingPoints.faq.referral.question": string;
-    "tradingPoints.faq.referral.answer": string;
     "tradingLeaderboard.leaderboard": string;
     "tradingLeaderboard.campaigns": string;
     "tradingLeaderboard.ongoing": string;
@@ -226,6 +191,10 @@ declare const en: {
     "affiliate.referralCode.label": string;
     "affiliate.referralCode.bound": string;
     "affiliate.referralCode.notExist": string;
+    "affiliate.referralCode.bind.modal.title": string;
+    "affiliate.referralCode.bind.modal.description": string;
+    "affiliate.referralCode.bind.input.placeholder": string;
+    "affiliate.referralCode.bind.skip": string;
     "affiliate.process.title": string;
     "affiliate.process.step1.title": string;
     "affiliate.process.step1.description": string;
@@ -287,6 +256,7 @@ declare const en: {
     "affiliate.direct": string;
     "affiliate.directInclBonus": string;
     "affiliate.indirect": string;
+    "affiliate.referredBy": string;
     "affiliate.referrals": string;
     "affiliate.referralCode.edit.modal.title": string;
     "affiliate.referralCode.create": string;
@@ -1300,6 +1270,8 @@ interface LocaleMessages extends EnType, ExtendLocaleMessages {
 type Resources<T extends {} = {}> = {
     [key in LocaleCode]?: Partial<LocaleMessages & T>;
 };
+/** Async loader for a single locale/namespace message table (see `useRegisterExternalResources`, ExternalLocaleProvider, LocaleProvider `resources`). */
+type AsyncResources = (lang: LocaleCode, ns: string) => Promise<Record<string, string>>;
 declare module "i18next" {
     interface CustomTypeOptions {
         resources: {
@@ -1327,7 +1299,7 @@ type PopupProps = {
     /** popup style */
     style?: React.CSSProperties;
 };
-type LocaleContextState = {
+type LanguageContextState = {
     /**
      * custom languages
      */
@@ -1345,8 +1317,8 @@ type LocaleContextState = {
      */
     popup?: PopupProps;
 };
-declare const LocaleContext: react.Context<LocaleContextState>;
-declare const useLocaleContext: () => LocaleContextState;
+declare const LanguageContext: react.Context<LanguageContextState>;
+declare const useLanguageContext: () => LanguageContextState;
 
 declare enum LocaleEnum {
     /** English */
@@ -1390,4 +1362,4 @@ declare const defaultNS = "translation";
 declare const i18nLocalStorageKey = "orderly_i18nLng";
 declare const i18nCookieKey = "orderly_i18nLng";
 
-export { type LocaleCode as L, type PopupMode as P, type Resources as R, type LocaleContextState as a, type Language as b, type PopupProps as c, LocaleContext as d, type LocaleMessages as e, LocaleEnum as f, defaultLanguages as g, defaultLng as h, defaultNS as i, i18nLocalStorageKey as j, i18nCookieKey as k, en as l, useLocaleContext as u };
+export { type AsyncResources as A, type LocaleCode as L, type PopupMode as P, type Resources as R, type LanguageContextState as a, type Language as b, type PopupProps as c, LanguageContext as d, type LocaleMessages as e, LocaleEnum as f, defaultLanguages as g, defaultLng as h, defaultNS as i, i18nLocalStorageKey as j, i18nCookieKey as k, en as l, useLanguageContext as u };