@orderly.network/i18n 3.0.4 → 3.1.0-alpha.0

package/docs/guide/integration.md

@@ -137,12 +137,12 @@ For host apps, bundling SDK locales with your `extend` JSON via `LocaleProvider`
 
 Async external resources are also registered as preloaders while their provider is mounted. Calls to the package singleton `i18n.changeLanguage(locale)` wait for those mounted external resources to load the target locale before the language is switched. This keeps plugin/host extension bundles lazy by locale while ensuring the first render after the language switch already has the target external messages registered.
 
-#### Async example (recommended for external packages)
+#### Recommended async provider
 
-For external SDK packages or plugin packages, ship a provider like
-`package-template/src/i18n/provider.tsx`: preload the default English messages,
-load non-English JSON chunks lazily with statically analyzable imports, and wrap
-the package subtree with `ExternalLocaleProvider`.
+For external SDK packages or plugin packages, ship a package-local provider:
+preload the default English messages, load non-English JSON chunks lazily with
+statically analyzable imports, and wrap the package subtree with
+`ExternalLocaleProvider`.
 
 This keeps the host app in charge of the root `LocaleProvider` while your package contributes its own translation resources to the shared singleton `i18n` instance. Use explicit per-locale dynamic imports so webpack/Next can resolve locale JSON chunks reliably. Vite accepts the same pattern.
 
@@ -206,7 +206,7 @@ The exported `LocaleProvider` above is your package-local provider. It is not th
 
 `LocaleMessages` should be the package's English/default message map, and `./locales/<locale>.json` should contain the translated package messages for that locale. If your package supports only a subset of languages, keep the full `Record<LocaleEnum, ...>` shape but leave unsupported loaders as `undefined`; `importLocaleJsonModule(undefined)` safely returns an empty resource object.
 
-Sync example:
+#### Static resources example
 
 ```tsx
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orderly.network/i18n",
-  "version": "3.0.4",
+  "version": "3.1.0-alpha.0",
   "description": "Internationalization for orderly sdk",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -50,7 +50,7 @@
     "react-dom": "^18.2.0",
     "tsup": "^8.5.1",
     "typescript": "^5.1.6",
-    "tsconfig": "1.0.4"
+    "tsconfig": "1.1.0-alpha.0"
   },
   "peerDependencies": {
     "react": ">=18",

package/scripts/mergeAiLocaleChunks.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * Merge translated chunk JSON files into locales/fa.json and locales/he.json.
+ * Expects files named fa-00.json … fa-NN.json (and he-00.json …) under chunkDir.
+ *
+ * Usage (from packages/i18n):
+ *   node scripts/mergeAiLocaleChunks.js ./locales/_ai_translate_chunks/fa locales/fa.json --fallback-en
+ *   node scripts/mergeAiLocaleChunks.js ./locales/_ai_translate_chunks/he locales/he.json --fallback-en
+ *
+ * Without --fallback-en: throws if any key from en.json is missing in merged chunks.
+ */
+const fs = require("fs-extra");
+const path = require("path");
+
+async function merge(chunkDir, outFile, enPath, fallbackEn) {
+  const files = (await fs.readdir(chunkDir))
+    .filter((f) => f.endsWith(".json"))
+    .sort();
+
+  if (!files.length) {
+    throw new Error(`No JSON chunks under ${chunkDir}`);
+  }
+
+  const merged = {};
+  for (const f of files) {
+    const part = await fs.readJSON(path.join(chunkDir, f));
+    Object.assign(merged, part);
+  }
+
+  const en = await fs.readJSON(enPath);
+  const missing = Object.keys(en).filter((k) => !(k in merged));
+
+  if (missing.length) {
+    if (!fallbackEn) {
+      throw new Error(
+        `Missing ${missing.length} keys (e.g. ${missing.slice(0, 5).join(", ")}) for ${path.basename(outFile)}`,
+      );
+    }
+    for (const k of missing) {
+      merged[k] = en[k];
+    }
+    console.warn(
+      `[mergeAiLocaleChunks] ${missing.length} keys fell back to English in ${path.basename(outFile)}`,
+    );
+  }
+
+  const sorted = {};
+  for (const k of Object.keys(en)) {
+    sorted[k] = merged[k];
+  }
+
+  await fs.outputJSON(outFile, sorted, { spaces: 2 });
+  console.log("wrote", outFile);
+}
+
+async function main() {
+  const [, , chunkDir, outFile, flag] = process.argv;
+  if (!chunkDir || !outFile) {
+    console.error(
+      "Usage: node scripts/mergeAiLocaleChunks.js <chunkDir> <outFile> [--fallback-en]",
+    );
+    process.exit(1);
+  }
+  const fallbackEn = flag === "--fallback-en";
+  const enPath = path.resolve(__dirname, "../locales/en.json");
+  await merge(
+    path.resolve(chunkDir),
+    path.resolve(outFile),
+    enPath,
+    fallbackEn,
+  );
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/scripts/splitEnLocaleChunks.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * Split locales/en.json into smaller JSON files so each part can be pasted into Cursor / another LLM
+ * for Persian (fa) or Hebrew (he) translation without calling external translation APIs.
+ *
+ * Usage (from packages/i18n):
+ *   node scripts/splitEnLocaleChunks.js [chunkSize] [outDir]
+ *
+ * Defaults: chunkSize=80, outDir=locales/_ai_translate_chunks/en
+ */
+const fs = require("fs-extra");
+const path = require("path");
+
+async function main() {
+  const chunkSize = Number(process.argv[2]) || 80;
+  const outDir = path.resolve(
+    process.argv[3] ||
+      path.join(__dirname, "../locales/_ai_translate_chunks/en"),
+  );
+  const enPath = path.resolve(__dirname, "../locales/en.json");
+  const en = await fs.readJSON(enPath);
+  const keys = Object.keys(en).sort();
+
+  await fs.ensureDir(outDir);
+  let idx = 0;
+  for (let i = 0; i < keys.length; i += chunkSize, idx++) {
+    const slice = keys.slice(i, i + chunkSize);
+    const chunk = {};
+    for (const k of slice) {
+      chunk[k] = en[k];
+    }
+    const name = `en-${String(idx).padStart(2, "0")}.json`;
+    await fs.outputJSON(path.join(outDir, name), chunk, { spaces: 2 });
+    console.log("wrote", name, Object.keys(chunk).length, "keys");
+  }
+  console.log("done =>", outDir);
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});