@orderly.network/i18n 3.0.0-beta.1 → 3.0.0-beta.3

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": "3.0.0-beta.1",
+  "version": "3.0.0-beta.3",
   "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": "1.0.0-beta.1"
+    "tsconfig": "1.0.0-beta.3"
   },
   "peerDependencies": {
     "react": ">=18",

package/scripts/copyLocales.js

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

package/scripts/csv2json.js

@@ -0,0 +1,28 @@
+const fs = require("fs-extra");
+const path = require("path");
+const { csv2multiJson } = require("./json-csv-converter");
+const { checkFileExists } = require("./utils");
+
+/** Convert locale CSV to multiple locale JSON files */
+async function csv2json(inputPath, outputDir) {
+  const csv = fs.readFileSync(inputPath, { encoding: "utf8" });
+
+  const json = csv2multiJson(csv);
+
+  const files = [];
+
+  for (const key of Object.keys(json)) {
+    const filePath = path.resolve(outputDir, `${key}.json`);
+    await checkFileExists(filePath);
+    await fs.outputFile(filePath, JSON.stringify(json[key], undefined, 4), {
+      encoding: "utf8",
+    });
+    files.push(filePath);
+  }
+
+  console.log("csv2json success =>", files);
+}
+
+module.exports = {
+  csv2json,
+};

package/scripts/diffCsv.js

@@ -0,0 +1,175 @@
+const fs = require("fs-extra");
+const path = require("path");
+const { csv2multiJson } = require("./json-csv-converter");
+const packageJson = require("../package.json");
+
+/**
+ * https://www.jsdelivr.com/package/npm/@orderly.network/i18n?tab=files&path=dist
+ * Compare two locale CSV files
+ */
+async function diffCsv(oldFile, newFile) {
+  const oldCsv = await fs.readFile(oldFile, { encoding: "utf8" });
+  const newCsv = await fs.readFile(newFile, { encoding: "utf8" });
+
+  const oldJson = csv2multiJson(oldCsv);
+  const newJson = csv2multiJson(newCsv);
+  const diffResult = compareJsonFiles(oldJson, newJson);
+  console.log("CSV diff result:", JSON.stringify(diffResult, null, 2));
+
+  const filepath = path.resolve("LOCALE_CHANGELOG.md");
+
+  // generate .md file
+  let markdownContent = generateMarkdown(diffResult);
+
+  if (!(await fs.exists(filepath))) {
+    const title = `# Locale Changelog`;
+    markdownContent = `${title}\n\n${markdownContent}`;
+
+    await fs.writeFile(filepath, markdownContent, {
+      encoding: "utf8",
+    });
+    console.log("LOCALE_CHANGELOG.md created");
+  } else {
+    // Read existing content
+    const existingContent = await fs.readFile(filepath, { encoding: "utf8" });
+
+    // Find the position after "# Locale Changelog"
+    const titleIndex = existingContent.indexOf("# Locale Changelog");
+    if (titleIndex === -1) {
+      console.error("Could not find '# Locale Changelog' title in the file");
+      return;
+    }
+
+    const titleEndIndex = titleIndex + "# Locale Changelog".length;
+
+    // Split content and insert new content after the title
+    const beforeTitle = existingContent.slice(0, titleEndIndex);
+    const afterTitle = existingContent.slice(titleEndIndex);
+
+    // Combine all parts
+    const newContent = `${beforeTitle}\n\n${markdownContent}${afterTitle}`;
+
+    // Write back to file
+    await fs.writeFile(filepath, newContent, {
+      encoding: "utf8",
+    });
+    console.log("LOCALE_CHANGELOG.md updated");
+  }
+}
+
+// Compare function
+function compareJsonFiles(oldJson, newJson) {
+  const result = {
+    added: {},
+    removed: {},
+    updated: {},
+  };
+
+  Object.keys(newJson).forEach((lang) => {
+    result.added[lang] = {};
+    result.removed[lang] = {};
+    result.updated[lang] = {};
+
+    const oldKeys = oldJson[lang] || {};
+    const newKeys = newJson[lang];
+
+    // Find added keys
+    Object.keys(newKeys).forEach((key) => {
+      if (!(key in oldKeys)) {
+        result.added[lang][key] = newKeys[key];
+      }
+    });
+
+    // Find removed keys
+    Object.keys(oldKeys).forEach((key) => {
+      if (!(key in newKeys)) {
+        result.removed[lang][key] = oldKeys[key];
+      }
+    });
+
+    // Find updated keys (same key, different value)
+    Object.keys(newKeys).forEach((key) => {
+      if (key in oldKeys && oldKeys[key] !== newKeys[key]) {
+        result.updated[lang][key] = {
+          old: oldKeys[key],
+          new: newKeys[key],
+        };
+      }
+    });
+  });
+
+  return result;
+}
+
+// generate Markdown conent
+function generateMarkdown(diff) {
+  let mdContent = `## ${packageJson.version}\n\n`;
+
+  const addedKeysEmpty = Object.keys(diff.added).every((lang) => {
+    return Object.keys(diff.added[lang]).length === 0;
+  });
+  const removedKeysEmpty = Object.keys(diff.removed).every((lang) => {
+    return Object.keys(diff.removed[lang]).length === 0;
+  });
+  const updatedKeysEmpty = Object.keys(diff.updated).every((lang) => {
+    return Object.keys(diff.updated[lang]).length === 0;
+  });
+
+  if (addedKeysEmpty && removedKeysEmpty && updatedKeysEmpty) {
+    return `${mdContent}### No locale changes`;
+  }
+
+  // handle added content
+  if (!addedKeysEmpty) {
+    mdContent += `### Added Keys\n`;
+    Object.keys(diff.added).forEach((lang) => {
+      if (Object.keys(diff.added[lang]).length === 0) {
+        mdContent += `\n#### Language: **${lang}**\n> No added keys.\n`;
+      } else {
+        mdContent += `\n#### Language: **${lang}**\n`;
+        mdContent += `| Key | Value |\n| --- | --- |\n`;
+        Object.entries(diff.added[lang]).forEach(([key, value]) => {
+          mdContent += `| ${key} | ${value} |\n`;
+        });
+      }
+    });
+  }
+
+  // handle removed content
+  if (!removedKeysEmpty) {
+    mdContent += `\n### Removed Keys\n`;
+    Object.keys(diff.removed).forEach((lang) => {
+      if (Object.keys(diff.removed[lang]).length === 0) {
+        mdContent += `\n#### Language: **${lang}**\n> No removed keys.\n`;
+      } else {
+        mdContent += `\n#### Language: **${lang}**\n`;
+        mdContent += `| Key | Value |\n| --- | --- |\n`;
+        Object.entries(diff.removed[lang]).forEach(([key, value]) => {
+          mdContent += `| ${key} | ${value} |\n`;
+        });
+      }
+    });
+  }
+
+  // handle updated content
+  if (!updatedKeysEmpty) {
+    mdContent += `\n### Updated Keys\n`;
+    Object.keys(diff.updated).forEach((lang) => {
+      if (Object.keys(diff.updated[lang]).length === 0) {
+        mdContent += `\n#### Language: **${lang}**\n> No updates found.\n`;
+      } else {
+        mdContent += `\n#### Language: **${lang}**\n`;
+        mdContent += `| Key | Old Value | New Value |\n| --- | --- | --- |\n`;
+        Object.entries(diff.updated[lang]).forEach(([key, values]) => {
+          mdContent += `| ${key} | ${values.old} | ${values.new} |\n`;
+        });
+      }
+    });
+  }
+
+  return mdContent;
+}
+
+module.exports = {
+  diffCsv,
+};

package/scripts/fillJson.js

@@ -0,0 +1,33 @@
+const fs = require("fs-extra");
+const path = require("path");
+const { checkFileExists } = require("./utils");
+const { en } = require("../dist");
+
+/** Fill values from the input locale JSON file and generate a new locale JSON file */
+async function fillJson(inputPath, outputPath) {
+  const inputJson = await fs.readJSON(inputPath, { encoding: "utf8" });
+
+  const newJson = {};
+  const missingValues = {};
+  Object.keys(en).forEach((key) => {
+    const value = inputJson[key] || "";
+    if (!value) {
+      missingValues[key] = en[key];
+    }
+    newJson[key] = value;
+  });
+  console.log("missingValues", missingValues);
+
+  const jsonPath = path.resolve(outputPath);
+  await checkFileExists(jsonPath);
+
+  await fs.outputFile(jsonPath, JSON.stringify(newJson, null, 4), {
+    encoding: "utf8",
+  });
+
+  console.log("fillJson success =>", jsonPath);
+}
+
+module.exports = {
+  fillJson,
+};

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 };