feat(i18n): add local translation command

Add npm run translateLocal to run the existing Phoenix and Markdown viewer
translation passes against http://localhost:4310/translate. Make the URL
configurable through CORE_AI_TRANSLATE_URL while preserving the hosted
default, and send Basic authorization only when a key is configured.

Propagate translation failures through the Gulp task instead of leaving
async Promise wrappers unresolved. Document local and hosted usage.

Validation: syntax, ESLint, whitespace and npm task discovery pass. Isolated
smoke checks cover endpoint routing, authorization, payloads, failures and
both translation passes. No live translation batch or locale writes.

Author: abose

docs/02-Adding-Translations.md

@@ -35,11 +35,25 @@ Each `src/nls/<locale>` folder contains similar files, plus a few additional one
 ## Autogenerated and Manual translations
 When any string changes are made to `src/nls/root/strings.js` , it will automatically be scanned by GitHub Actions and the corresponding translations will be generated. A pull request will be raised with the new translations.
 
-You can also run the translation command locally if you have the AWS/GCP keys with the command. This is mostly FYI for phoenix internal devs.
+Internal developers can run both the Phoenix and Markdown viewer translation passes using the
+hosted core.ai service. Set `CORE_AI_TRANSLATE_API_KEY`, then run:
+
 ```bash
 npm run _translateStrings
 ```
 
+To use a local translation service running at `http://localhost:4310/translate`, run:
+
+```bash
+npm run translateLocal
+```
+
+The local service must accept the same request/response format as the hosted service. Both commands
+update the existing locale files and translation metadata. `CORE_AI_TRANSLATE_API_KEY` is sent as
+Basic authorization when set; an unauthenticated local service does not need it. The local command
+works on Windows, macOS and Linux using the existing `cross-env` dependency. Other endpoints can
+be selected by setting `CORE_AI_TRANSLATE_URL` when running `npm run _translateStrings`.
+
 ### Skipping auto translate
 For some strings we may not want to translate them. For Example, for the keyboard shortcut string key `"KEYBOARD_CTRL": "Ctrl"`
 we don't want it translated to any language. Just add another key appending `_DO_NOT_TRANSLATE` to the key to disable automatic translations Eg. `"KEYBOARD_CTRL_DO_NOT_TRANSLATE": "true"` just below the original key. 

gulpfile.js/index.js

@@ -430,12 +430,12 @@ function releaseProd() {
     });
 }
 
-function translateStrings() {
-    return new Promise(async (resolve)=>{ // eslint-disable-line
-        await Translate.translate();
-        await Translate.translateMdviewer();
-        resolve();
-    });
+/** Translate both Phoenix and Markdown viewer locales using the configured service.
+ * @return {Promise<void>} Rejects if either translation pass fails.
+ */
+async function translateStrings() {
+    await Translate.translate();
+    await Translate.translateMdviewer();
 }
 
 function _listFilesInDir(dir) {

gulpfile.js/translateStrings.js

@@ -22,6 +22,7 @@
 const fs = require('fs');
 const path = require('path');
 const CORE_AI_TRANSLATE_API_KEY = process.env.CORE_AI_TRANSLATE_API_KEY;
+const CORE_AI_TRANSLATE_URL = process.env.CORE_AI_TRANSLATE_URL || "https://translate.core.ai/translate";
 
 // A global accumulator object initialized to zero
 const globalUtilizationMetrics = {
@@ -102,20 +103,20 @@ function getTranslationrequest(stringsToTranslate, lang) {
 }
 
 /**
- * Sends translation payload to the specified API and returns the result.
+ * Send the translation payload to the configured service, with credentials when supplied.
  *
  * @param {object} apiInput - The translation payload object.
  * @returns {Promise<any>} The JSON-parsed response from the API.
  */
 async function getTranslation(apiInput) {
-    const url = "https://translate.core.ai/translate";
+    const headers = { "Content-Type": "application/json" };
+    if (CORE_AI_TRANSLATE_API_KEY) {
+        headers.authorization = `Basic ${CORE_AI_TRANSLATE_API_KEY}`;
+    }
     try {
-        const response = await fetch(url, {
+        const response = await fetch(CORE_AI_TRANSLATE_URL, {
             method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                "authorization": `Basic ${CORE_AI_TRANSLATE_API_KEY}`
-            },
+            headers: headers,
             body: JSON.stringify(apiInput)
         });
 
@@ -378,23 +379,23 @@ async function _processLang(lang, config) {
 
 // ---- Phoenix NLS translation ----
 
+/** Translate Phoenix locales through the configured service, propagating request failures to Gulp.
+ * @return {Promise<void>} Resolves when all Phoenix locales have been processed.
+ */
 async function translate() {
-    console.log("please make sure that core.ai lang translation service credentials are available as env vars.");
-    return new Promise(async (resolve)=>{
-        const nlsDir = 'src/nls';
-        let langs = _getAllNLSFolders(nlsDir);
-        console.log(langs);
-        const config = {
-            nlsDir,
-            sourceStrings: rootStrings,
-            format: 'js',
-            errorsFile: 'src/nls/errors.txt'
-        };
-        for(let lang of langs){
-            await _processLang(lang, config);
-        }
-        resolve();
-    });
+    console.log("Using translation service:", CORE_AI_TRANSLATE_URL);
+    const nlsDir = 'src/nls';
+    const langs = _getAllNLSFolders(nlsDir);
+    console.log(langs);
+    const config = {
+        nlsDir,
+        sourceStrings: rootStrings,
+        format: 'js',
+        errorsFile: 'src/nls/errors.txt'
+    };
+    for (const lang of langs) {
+        await _processLang(lang, config);
+    }
 }
 
 // ---- mdviewer translation ----
@@ -476,9 +477,13 @@ async function translateMdviewer() {
     // Copy translated flat JSON → nested locale files for mdviewer runtime
     console.log("[mdviewer] Copying translations to locales folder...");
     for (let lang of langs) {
-        if (lang === 'root') continue;
+        if (lang === 'root') {
+            continue;
+        }
         const flatStrings = _getJson(path.join(mdNlsDir, lang, 'strings.json'));
-        if (!Object.keys(flatStrings).length) continue;
+        if (!Object.keys(flatStrings).length) {
+            continue;
+        }
         const nested = _unflattenObject(flatStrings);
         fs.writeFileSync(
             path.join(localesDir, `${lang}.json`),

package.json

@@ -84,6 +84,7 @@
         "serveExternal": "npm install --prefix src-node && node serve-proxy.js . -p 8000 -a 0.0.0.0 --log-ip -c-1",
         "createJSDocs": "node build/api-docs-generator.js && git add docs",
         "_translateStrings": "gulp translateStrings",
+        "translateLocal": "cross-env CORE_AI_TRANSLATE_URL=http://localhost:4310/translate gulp translateStrings",
         "_minify": "r.js -o require.min.config.js && echo this is untested see https://stackoverflow.com/questions/14337970/minifying-requirejs-javascript-codebase-to-a-single-file"
     },
     "licenses": [