@orderly.network/i18n 2.12.0 → 2.12.1

package/docs/guide/integration.md

@@ -0,0 +1,223 @@
+# Integration Guide
+
+**This guide** documents props, effects, and loading strategies. For **end-to-end copy-paste recipes** (Vite `import.meta.glob`, Next.js/webpack, HTTP `public/`, sync maps, URL sync), use [Examples](./examples.md).
+
+**Overview:** `LocaleProvider` composes `**LanguageProvider`** (language list, optional HTTP `Backend`, change callbacks) and `**I18nextProvider`** from react-i18next. All of it uses the package’s **singleton `i18n`instance**. The default namespace is`**translation`** (`defaultNS`); see [Package exports](./exports.md).
+
+Follow the steps below to integrate localization in your app with the Orderly SDK.
+
+## Table of Contents
+
+- [1. Wrap Your App with LocaleProvider](#1-wrap-your-app-with-localeprovider)
+- [2. Provide Locale Data](#2-provide-locale-data)
+- [3. Extending Locale Files](#3-extending-locale-files)
+- [4. Integrate External Resources](#4-integrate-external-resources)
+
+## 1. Wrap Your App with LocaleProvider
+
+`LocaleProvider` is the main entry: it wires locale state and the i18n React context. Wrap your app (or orderly subtree) at the root.
+
+```tsx
+import { LocaleProvider } from "@orderly.network/i18n";
+
+export function App() {
+  return (
+    <LocaleProvider>
+      <YourApp />
+    </LocaleProvider>
+  );
+}
+```
+
+### Locale-only props
+
+These props are defined on `LocaleProvider` (see `localeProvider.tsx`):
+
+| Prop        | Description                                                                                                                                                                                                                                        |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `locale`    | Optional **controlled** locale. When set and different from `i18n.language`, a `useEffect` calls `i18n.changeLanguage(locale)`.                                                                                                                    |
+| `resource`  | Flat messages for `**defaultNS`** (`translation`). Used only when `**resources`is not set**; requires`locale`. Calls `i18n.addResourceBundle(locale, defaultNS, resource, true, true)`.                                                            |
+| `resources` | Static **Resources** map or **AsyncResources**. When set, **registerResources** runs in a `useEffect` (see **Behavior**). Takes precedence over `locale` + `resource`. Same contract as `ExternalLocaleProvider` / `useRegisterExternalResources`. |
+
+**Async loader and `ns`:** The `AsyncResources` type is `(lang, ns) => Promise<Record<string, string>>`. When loading goes through `**registerResources`** (from `LocaleProvider` or `useRegisterExternalResources`), the implementation calls `**await resources(localeCode, defaultNS)`** — the second argument is **always** `defaultNS` (`translation`), not an arbitrary namespace. Use the parameter if you build URLs; for multiple i18n namespaces, use the i18n API directly.
+
+### Inherited from `LanguageProvider`
+
+Pass these through `LocaleProvider` like any other `LanguageProvider` prop:
+
+| Prop                      | Description                                                                                                                                                                                                                                                                                                                                              |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `backend`                 | `BackendOptions`: `{ loadPath }` where `loadPath(lang, ns)` returns a URL `string`, `string[]`, or `undefined` for the HTTP `Backend`. Those URLs must resolve to real files (e.g. under `public/`); the package does **not** copy `dist/locales` into your app — sync manually or via a script / hook — see [HTTP backend](./examples.md#http-backend). |
+| `languages`               | Full `Language[]` for the switcher; when set as an array, replaces `defaultLanguages`.                                                                                                                                                                                                                                                                   |
+| `supportedLanguages`      | Subset of `LocaleCode[]`; builds the list from `**defaultLanguages**` entries.                                                                                                                                                                                                                                                                           |
+| `onLanguageBeforeChanged` | `(lang) => Promise<void>`. **Runs first**; then the internal `Backend` loads the next language (`loadLanguage(lang, defaultNS)`). Use for prep work before HTTP loads.                                                                                                                                                                                   |
+| `onLanguageChanged`       | `(lang) => Promise<void>` — notification on the language-change path.                                                                                                                                                                                                                                                                                    |
+| `convertDetectedLanguage` | `(browserLang: string) => LocaleCode` — optional mapping from the detector to your supported codes.                                                                                                                                                                                                                                                      |
+| `popup`                   | `PopupProps` for the language switcher: optional `mode` (`modal`, `dropdown`, or `sheet`), `className`, `style`.                                                                                                                                                                                                                                         |
+
+### Behavior (effects)
+
+- `**resources` set:\*\* `registerResources(resources, locale ?? currentLocale)` runs when `locale`, `resource`, `resources`, or the current locale from `useLocaleCode` changes. Static maps register every locale entry; async loaders fetch for the active locale code.
+- `**resources` unset** and `**resource`+`locale`:** merges the flat bundle for that locale into `defaultNS`.
+- `**locale` prop:\*\* separate effect — if `locale` is set and differs from `i18n.language`, `i18n.changeLanguage(locale)` runs.
+
+Prefer **one** primary loading approach per app (**HTTP `backend`** vs **static/async `resources`** vs `**locale` + `resource**`) to avoid overlapping bundles. You can pass `**resources` on `LocaleProvider**` instead of `ExternalLocaleProvider` — same registration path. Use `**useRegisterExternalResources**` to avoid an extra wrapper (stable `resources` reference recommended).
+
+### Loading strategies (quick reference)
+
+- **HTTP:** `backend={{ loadPath }}` — load JSON from URLs (e.g. files under `public/`). You must **place** those JSON files on disk (or CDN): **manually** copy from `node_modules/.../i18n/dist/locales`, or run a **copy script** / **Husky** hook (`npm run copyLocales`, etc.) as in [HTTP backend](./examples.md#http-backend).
+- **Bundled:** `resources` as a static map or **`AsyncResources`**. Recipes: [Async resources (Vite)](./examples.md#async-resources-vite) · [Async resources (Next.js and webpack)](./examples.md#async-resources-nextjs-and-webpack) · [Sync resources](./examples.md#sync-resources).
+- **Controlled single bundle:** `locale` + `resource` when you inject one flat table for one language.
+- **Host / external bundles:** `ExternalLocaleProvider` or `useRegisterExternalResources` — same `Resources` / `AsyncResources` as `LocaleProvider.resources`.
+
+## 2. Provide Locale Data
+
+### Default language
+
+- English (`en`) ships with the package as the built-in base bundle.
+
+### Supported locales
+
+We currently support **17** locales. The table order matches `**defaultLanguages`\*\* in the package (`constant`).
+
+| 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               |
+| `tc`        | Traditional Chinese |
+
+### CSV for translation workflows
+
+- Releases include a `dist/locale.csv` you can hand off for translation.
+- Use the [CLI](./cli.md) to convert between CSV and JSON (`csv2json`, `json2csv`, etc.).
+
+## 3. Extending locale files
+
+You can translate SDK strings and add strings for your own UI.
+
+- Use the `**extend.`\*\* key prefix for custom keys so they stay distinct from built-in keys (and align with tooling such as `separateJson` in the [CLI](./cli.md)).
+
+```json
+{
+  "extend.custom.button.label": "My Custom Button"
+}
+```
+
+## 4. Integrate external resources
+
+Use this when strings live outside this package (another bundle, CDN, or host app). `**LocaleProvider**` with `**resources**`, `**ExternalLocaleProvider**`, and `**useRegisterExternalResources**` all call the same `**registerResources**` helper.
+
+The snippets below are **minimal** (wrapper vs hook). [Examples](./examples.md) uses **`LocaleProvider` + `resources`** with full app wiring (e.g. merge SDK + extend, provider tree)—use that for production-shaped code.
+
+For **Vite**, bundling SDK locales with your `extend` JSON via `**AsyncResources`\*\* is the recommended setup — see [Async resources (Vite)](./examples.md#async-resources-vite).
+
+### `ExternalLocaleProvider`
+
+- **Async:** `(lang, ns) => Promise<Record<string, string>>` — invoked when the locale changes (same `ns` behavior as above when used through `registerResources`).
+- **Sync:** static `Resources` map; all listed locales are registered on mount.
+
+Async example:
+
+```tsx
+import {
+  AsyncResources,
+  ExternalLocaleProvider,
+  LocaleCode,
+  LocaleProvider,
+} from "@orderly.network/i18n";
+
+const resources: AsyncResources = async (lang: LocaleCode) => {
+  return import(`./locales/${lang}.json`).then(
+    (res) => res.default as Record<string, string>,
+  );
+};
+
+export function App() {
+  return (
+    <LocaleProvider>
+      <ExternalLocaleProvider resources={resources}>
+        <YourApp />
+      </ExternalLocaleProvider>
+    </LocaleProvider>
+  );
+}
+```
+
+Sync example:
+
+```tsx
+import {
+  ExternalLocaleProvider,
+  LocaleProvider,
+  Resources,
+} from "@orderly.network/i18n";
+
+const resources: Resources = {
+  en: { "extend.host.title": "Host app title" },
+  zh: { "extend.host.title": "宿主应用标题" },
+};
+
+export function App() {
+  return (
+    <LocaleProvider>
+      <ExternalLocaleProvider resources={resources}>
+        <YourApp />
+      </ExternalLocaleProvider>
+    </LocaleProvider>
+  );
+}
+```
+
+`ExternalLocaleProvider` renders only its children (no UI).
+
+### `useRegisterExternalResources`
+
+Same registration as above, without a wrapper component — call under `LocaleProvider` with a **stable** `resources` reference (`useCallback` for loaders, module scope or `useMemo` for maps):
+
+```tsx
+import {
+  LocaleProvider,
+  useRegisterExternalResources,
+} from "@orderly.network/i18n";
+import type { AsyncResources, LocaleCode } from "@orderly.network/i18n";
+
+const loader: AsyncResources = async (lang: LocaleCode) => {
+  return import(`./locales/${lang}.json`).then(
+    (res) => res.default as Record<string, string>,
+  );
+};
+
+function Bridge() {
+  useRegisterExternalResources(loader);
+  return null;
+}
+```
+
+### `registerDefaultResource`
+
+Call **before** the React tree mounts (e.g. app bootstrap) to merge keys into the **English** bundle and reduce flicker of raw keys. It uses `i18n.addResourceBundle(defaultLng, defaultNS, messages, true, true)` (deep merge with overwrite), same as other bundle registration paths:
+
+```ts
+import { registerDefaultResource } from "@orderly.network/i18n";
+
+registerDefaultResource({
+  "extend.app.loading": "Loading...",
+  "extend.app.title": "Orderly App",
+});
+```
+
+See also: [Package exports](./exports.md) · [Utils](./utils.md) · [CLI](./cli.md) · [Examples](./examples.md) ([Vite](./examples.md#async-resources-vite) · [Next/webpack](./examples.md#async-resources-nextjs-and-webpack) · [HTTP](./examples.md#http-backend) · [URL sync](./examples.md#onlanguagechanged-url-sync))

package/docs/guide/utils.md

@@ -0,0 +1,14 @@
+# Utils (integrator-facing)
+
+The `@orderly.network/i18n/utils` entry exports the following helpers:
+
+| Function                    | Purpose                                                                              |
+| --------------------------- | ------------------------------------------------------------------------------------ |
+| `parseI18nLang`             | Map browser language strings to a `LocaleCode` (from `LocaleEnum` or a custom list). |
+| `removeLangPrefix`          | Remove a leading locale segment from a pathname.                                     |
+| `getLocalePathFromPathname` | Read the locale segment from a pathname when present.                                |
+| `generatePath`              | Build a locale-prefixed path with optional search string.                            |
+
+For generated API notes on `utils.ts`, see [`../utils.md`](../utils.md) in this package’s docs.
+
+See also: [Integration guide](./integration.md) · [Examples](./examples.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orderly.network/i18n",
-  "version": "2.12.0",
+  "version": "2.12.1",
   "description": "Internationalization for orderly sdk",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -20,16 +20,20 @@
   },
   "keywords": [],
   "files": [
+    "bin",
     "dist",
-    "script"
+    "scripts",
+    "docs/guide"
   ],
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
+    "fs-extra": "^11.2.0",
     "i18next": "^24.2.2",
     "i18next-browser-languagedetector": "^8.0.4",
-    "react-i18next": "^15.4.1"
+    "react-i18next": "^15.4.1",
+    "yargs": "^17.7.2"
   },
   "devDependencies": {
     "@babel/preset-env": "^7.22.9",
@@ -39,7 +43,6 @@
     "@types/react-dom": "^18.3.0",
     "@types/fs-extra": "^11.0.4",
     "@types/jest": "^29.5.3",
-    "fs-extra": "^11.2.0",
     "babel-jest": "^29.6.1",
     "jest": "^29.6.1",
     "jest-environment-jsdom": "^29.7.0",
@@ -47,8 +50,7 @@
     "react-dom": "^18.2.0",
     "tsup": "^8.5.1",
     "typescript": "^5.1.6",
-    "yargs": "^17.7.2",
-    "tsconfig": "0.15.0"
+    "tsconfig": "0.15.1"
   },
   "peerDependencies": {
     "react": ">=18",
@@ -61,15 +63,15 @@
     "cli": "node ./bin/cli.js",
     "csv2json": "pnpm cli csv2json ./dist/locale.csv ./dist/locales",
     "json2csv": "pnpm cli json2csv ./dist/locales ./dist/locale.csv",
-    "generateCsv": "pnpm cli generateCsv ./dist/locale.csv",
+    "generateCsv": "pnpm cli generateCsv ./locales ./dist/locale.csv",
     "diffcsv": "pnpm cli diffcsv ./dist/locale1.csv ./dist/locale2.csv",
     "fillJson": "pnpm cli fillJson ./src/locale/zh.json ./dist/locale/zh.json",
     "separateJson": "pnpm cli separateJson ./locales ./dist/locales extend",
     "mergeJson": "pnpm cli mergeJson ./locales ./dist/locales",
     "mergeExtendJson": "pnpm cli mergeJson ./locales ./locales",
-    "_generateEnJson": "node ./script/generateEnJson.js",
-    "generateEnJson": "pnpm tsup && node ./script/generateEnJson.js",
-    "copyLocales": "node ./script/copyLocales.js",
-    "generateMissingKeys": "pnpm tsup && pnpm _generateEnJson && node ./script/generateMissingKeys.js"
+    "_generateEnJson": "node ./scripts/generateEnJson.js",
+    "generateEnJson": "pnpm tsup && node ./scripts/generateEnJson.js",
+    "copyLocales": "node ./scripts/copyLocales.js",
+    "generateMissingKeys": "pnpm tsup && pnpm _generateEnJson && node ./scripts/generateMissingKeys.js"
   }
 }

package/{script → scripts}/copyLocales.js

@@ -4,7 +4,7 @@ const path = require("path");
 async function copyLocales() {
   await fs.copy(
     path.resolve(__dirname, "../locales"),
-    path.resolve(__dirname, "../dist/locales")
+    path.resolve(__dirname, "../dist/locales"),
   );
 }
 

package/scripts/filterLocaleKeys.js

@@ -0,0 +1,127 @@
+const fs = require("fs");
+const path = require("path");
+
+const USAGE =
+  "Usage: node filterLocaleKeys.js (--keep|-k | --remove|-r) <prefix> [--locales-dir <dir>]";
+
+const KEEP_MODES = ["--keep", "-k"];
+const REMOVE_MODES = ["--remove", "-r"];
+const VALID_MODES = [...KEEP_MODES, ...REMOVE_MODES];
+
+const DEFAULT_LOCALES_DIR = path.join(__dirname, "..", "locales");
+
+/**
+ * Filter locale JSON files by key prefix: keep or remove keys matching the prefix.
+ * @param {"keep"|"remove"} mode - "keep": only keep keys with prefix; "remove": remove keys with prefix
+ * @param {string} prefix - Key prefix to match (e.g. "trading." or "trading")
+ * @param {string} [localesDir] - Directory containing locale JSON files (default: packages/i18n/locales)
+ */
+function filterLocaleKeys(mode, prefix, localesDir = DEFAULT_LOCALES_DIR) {
+  if (!fs.existsSync(localesDir)) {
+    console.error(`Locales directory not found: ${localesDir}`);
+    process.exit(1);
+  }
+
+  const files = fs
+    .readdirSync(localesDir)
+    .filter((name) => name.endsWith(".json"))
+    .sort();
+
+  if (files.length === 0) {
+    console.warn("No locale JSON files found.");
+    return;
+  }
+
+  for (const file of files) {
+    const filePath = path.join(localesDir, file);
+    let content;
+    try {
+      content = fs.readFileSync(filePath, "utf8");
+    } catch (err) {
+      console.error(`Failed to read file: ${filePath}`, err.message);
+      continue;
+    }
+
+    let data;
+    try {
+      data = JSON.parse(content);
+    } catch (err) {
+      console.error(`Failed to parse JSON: ${filePath}`, err.message);
+      continue;
+    }
+
+    // Match key if it starts with prefix, or equals prefix without trailing dot
+    // (e.g. prefix "trading." should match key "trading" as well as "trading.xxx")
+    const prefixBase = prefix.endsWith(".") ? prefix.slice(0, -1) : prefix;
+    const matchesPrefix = (key) => key.startsWith(prefix) || key === prefixBase;
+
+    const filtered = {};
+    for (const [key, value] of Object.entries(data)) {
+      if (mode === "keep" ? matchesPrefix(key) : !matchesPrefix(key)) {
+        filtered[key] = value;
+      }
+    }
+
+    const filteredCount = Object.keys(filtered).length;
+    if (mode === "keep" && filteredCount === 0) {
+      console.warn(
+        `Skip ${file} (no keys starting with "${prefix}" were found).`,
+      );
+      continue;
+    }
+    if (mode === "remove" && filteredCount === Object.keys(data).length) {
+      console.warn(
+        `Skip ${file} (no keys starting with "${prefix}" were found to remove).`,
+      );
+      continue;
+    }
+
+    try {
+      fs.writeFileSync(
+        filePath,
+        JSON.stringify(filtered, null, 2) + "\n",
+        "utf8",
+      );
+      if (mode === "keep") {
+        console.log(
+          `Filtered ${file}: kept ${filteredCount} keys with prefix "${prefix}".`,
+        );
+      } else {
+        const removedCount = Object.keys(data).length - filteredCount;
+        console.log(
+          `Filtered ${file}: removed ${removedCount} keys with prefix "${prefix}", kept ${filteredCount} keys.`,
+        );
+      }
+    } catch (err) {
+      console.error(`Failed to write file: ${filePath}`, err.message);
+    }
+  }
+}
+
+// Run as CLI when executed directly
+if (require.main === module) {
+  const modeArg = process.argv[2];
+  const prefix = process.argv[3];
+  const localesDirIdx = process.argv.indexOf("--locales-dir");
+  const localesDir =
+    localesDirIdx >= 0 ? process.argv[localesDirIdx + 1] : DEFAULT_LOCALES_DIR;
+
+  if (!VALID_MODES.includes(modeArg)) {
+    console.error(
+      "Error: Please specify a mode: --keep|-k (keep keys with prefix) or --remove|-r (remove keys with prefix).",
+    );
+    console.error(USAGE);
+    process.exit(1);
+  }
+
+  if (!prefix) {
+    console.error("Error: <prefix> is required.");
+    console.error(USAGE);
+    process.exit(1);
+  }
+
+  const mode = REMOVE_MODES.includes(modeArg) ? "remove" : "keep";
+  filterLocaleKeys(mode, prefix, localesDir);
+}
+
+module.exports = { filterLocaleKeys };

package/{script → scripts}/generateCsv.js

@@ -5,17 +5,17 @@ const { multiJson2Csv } = require("./json-csv-converter");
 const { defaultLanguages } = require("../dist");
 
 /** Generate a locale CSV file */
-async function generateCsv(outputPath) {
+async function generateCsv(inputDir, outputPath) {
   const headers = [""];
   const jsonList = [];
 
   for (const item of defaultLanguages) {
     headers.push(item.localCode);
     const json = await fs.readJSON(
-      path.resolve(__dirname, `../locales/${item.localCode}.json`),
+      path.resolve(inputDir, `${item.localCode}.json`),
       {
         encoding: "utf8",
-      }
+      },
     );
     jsonList.push(json);
   }

package/{script → scripts}/utils.js

@@ -32,30 +32,37 @@ function validateI18nValue(value) {
   // 2. check if placeholder format is correct (allow `{{variable}}`)
   // allow `{{variable}}` or `{{ variable }}`
   const interpolationRegex = /{{\s*[\w.-]+\s*}}/g;
-  // check if `{{` is not closed or `}}` is not opened
-  const invalidInterpolationRegex =
-    /{{[^{}]*$|^[^{}]*}}|[^{]{{|}}[^}]}|^{|}$|{[^{}]*}|}/;
-
+  const strippedInterpolation = value.replace(interpolationRegex, "");
   if (
-    value.match(invalidInterpolationRegex) &&
-    !value.match(interpolationRegex)
+    strippedInterpolation.includes("{{") ||
+    strippedInterpolation.includes("}}")
   ) {
     return { valid: false, error: i18nValidErrors.interpolation };
   }
+  // mistaken single-brace placeholders like `{user.name}` (should be `{{user.name}}`)
+  if (/\{\s*[\w.-]+\s*\}/.test(strippedInterpolation)) {
+    return { valid: false, error: i18nValidErrors.interpolation };
+  }
+  // `{` without a closing `}` on the same line segment (typo vs `{{`)
+  if (/\{[^}]*$/.test(strippedInterpolation)) {
+    return { valid: false, error: i18nValidErrors.interpolation };
+  }
 
-  // 3. check if HTML tags are correctly closed
-  const tagRegex = /<\/?([a-zA-Z0-9]+)(\s*\/?)>/g;
+  // 3. check if HTML tags are correctly closed (supports attributes, e.g. <script async src="...">)
+  const tagRegex = /<(\/?)\s*([a-zA-Z0-9][\w-]*)[^>]*>/g;
   let stack = [];
   let match;
 
   while ((match = tagRegex.exec(value)) !== null) {
-    let [, tagName, selfClosing] = match;
+    const [, slashPrefix, tagName] = match;
+    const fullTag = match[0];
+    const isClosing = slashPrefix === "/";
+    const isSelfClosing = !isClosing && /\/\s*>$/.test(fullTag.trim());
 
-    if (selfClosing === "/") {
-      // self-closing tag, no need to push to stack
+    if (isSelfClosing) {
       continue;
-    } else if (match[0].startsWith("</")) {
-      // closing tag, check if stack top matches
+    }
+    if (isClosing) {
       if (stack.length === 0 || stack.pop() !== tagName) {
         return {
           valid: false,
@@ -63,7 +70,6 @@ function validateI18nValue(value) {
         };
       }
     } else {
-      // opening tag, push to stack
       stack.push(tagName);
     }
   }