msgai-cli 1.1.0 → 1.1.1

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [1.1.1](https://github.com/AlexMost/msgai/compare/v1.1.0...v1.1.1) (2026-03-01)
+
+### Bug Fixes
+
+- normalize msgctxt validation and add debug mode ([7488a78](https://github.com/AlexMost/msgai/commit/7488a782594253c4cfc46b56500ca7fa7b102766))
+
 ## [1.1.0](https://github.com/AlexMost/msgai/compare/v1.0.2...v1.1.0) (2026-03-01)
 
 ### Features

package/README.md

@@ -79,7 +79,7 @@ msgai messages.po --api-key sk-...
 Usage:
 
 ```bash
-msgai <file.po> [--dry-run] [--api-key KEY] [--source-lang LANG] [--model MODEL] [--include-fuzzy]
+msgai <file.po> [--dry-run] [--api-key KEY] [--source-lang LANG] [--model MODEL] [--include-fuzzy] [--debug]
 ```
 
 Options:
@@ -89,11 +89,18 @@ Options:
 - `--source-lang LANG`: set the source language of `msgid` strings as an ISO 639-1 code such as `en` or `uk`
 - `--model MODEL`: set the OpenAI model used for translation; default is `gpt-4o`. Only models with `json_schema` structured outputs are supported.
 - `--api-key KEY`: pass the OpenAI API key directly instead of using `OPENAI_API_KEY`
+- `--debug`: print debug logs for batch preparation, OpenAI request retries, request payloads, and raw response validation
 - `--help`: print command usage
 
+You can also enable the same debug logging with the environment variable `DEBUG=1`:
+
+```bash
+DEBUG=1 msgai messages.po
+```
+
 If no API key is provided for a non-dry run, the CLI exits with code `1` and prints an error message.
 
-On API failures such as rate limits, quota issues, or server errors, the CLI exits with code `1` and shows a status-specific message. For API error details, see [OpenAI API error codes](https://developers.openai.com/api/docs/guides/error-codes#api-errors).
+On API failures such as rate limits, quota issues, or server errors, the CLI exits with code `1` and shows a status-specific message. Validation errors for protected fields such as `msgid`, `msgid_plural`, or `msgctxt` now tell you whether a retry is reasonable and when to rerun with `--debug` or `DEBUG=1` to inspect the request/response flow. For API error details, see [OpenAI API error codes](https://developers.openai.com/api/docs/guides/error-codes#api-errors).
 
 ## 🧪 Development
 

package/dist/src/cli/index.js

@@ -6,12 +6,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const yargs_1 = __importDefault(require("yargs/yargs"));
 const helpers_1 = require("yargs/helpers");
+const debug_1 = require("../debug");
 const runTranslate_1 = require("./runTranslate");
 function parseArgs(argv) {
     try {
         const parsedArgs = (0, yargs_1.default)(argv)
             .scriptName('msgai')
-            .usage('Usage: msgai <file.po> [--dry-run] [--api-key KEY] [--source-lang LANG] [--model MODEL] [--include-fuzzy]')
+            .usage('Usage: msgai <file.po> [--dry-run] [--api-key KEY] [--source-lang LANG] [--model MODEL] [--include-fuzzy] [--debug]')
             .option('dry-run', {
             type: 'boolean',
             default: false,
@@ -37,6 +38,11 @@ function parseArgs(argv) {
             alias: 'h',
             type: 'boolean',
             default: false,
+        })
+            .option('debug', {
+            type: 'boolean',
+            default: false,
+            description: 'Print debug logs for request/response validation and batch processing',
         })
             .strictOptions()
             .version(false)
@@ -56,17 +62,19 @@ function parseArgs(argv) {
         const modelRaw = parsedArgs.model;
         const model = modelRaw != null && String(modelRaw).trim() !== '' ? String(modelRaw).trim() : undefined;
         if (positionalArgs.length > 1) {
-            return {
+            const result = {
                 dryRun: Boolean(parsedArgs['dry-run']),
                 help: Boolean(parsedArgs.help),
                 apiKey: parsedArgs['api-key'],
                 sourceLang,
                 model,
                 includeFuzzy: Boolean(parsedArgs['include-fuzzy']),
+                debug: Boolean(parsedArgs.debug),
                 error: `Unexpected argument: ${positionalArgs[1]}`,
             };
+            return result;
         }
-        return {
+        const result = {
             poFilePath: positionalArgs[0],
             dryRun: Boolean(parsedArgs['dry-run']),
             help: Boolean(parsedArgs.help),
@@ -74,25 +82,33 @@ function parseArgs(argv) {
             sourceLang,
             model,
             includeFuzzy: Boolean(parsedArgs['include-fuzzy']),
+            debug: Boolean(parsedArgs.debug),
         };
+        return result;
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         return { dryRun: false, help: false, error: message };
     }
 }
-const USAGE = 'Usage: msgai <file.po> [--dry-run] [--api-key KEY] [--source-lang LANG] [--model MODEL] [--include-fuzzy]';
+const USAGE = 'Usage: msgai <file.po> [--dry-run] [--api-key KEY] [--source-lang LANG] [--model MODEL] [--include-fuzzy] [--debug]';
 function main(argv) {
     const args = parseArgs(argv);
+    (0, debug_1.initDebugLogger)(args.debug);
+    const debugLogger = (0, debug_1.getDebugLogger)();
+    debugLogger.log('cli.main', 'Entering CLI main', { argv, args });
     if (args.error) {
+        debugLogger.log('cli.main', 'Exiting because args contained an error', { error: args.error });
         console.warn(args.error);
         console.warn(USAGE);
         return 1;
     }
     if (args.help) {
+        debugLogger.log('cli.main', 'Printing help output');
         console.log(USAGE);
         return 0;
     }
+    debugLogger.log('cli.main', 'Dispatching runTranslateCommand');
     const result = (0, runTranslate_1.runTranslateCommand)({
         poFilePath: args.poFilePath,
         dryRun: args.dryRun,
@@ -100,11 +116,14 @@ function main(argv) {
         sourceLang: args.sourceLang,
         model: args.model,
         includeFuzzy: args.includeFuzzy,
+        debug: args.debug,
     });
     if (result instanceof Promise) {
+        debugLogger.log('cli.main', 'runTranslateCommand returned a promise');
         result.then((code) => process.exit(code));
         return undefined;
     }
+    debugLogger.log('cli.main', 'runTranslateCommand returned synchronously', { exitCode: result });
     return result;
 }
 const exitCode = main((0, helpers_1.hideBin)(process.argv));

package/dist/src/cli/runTranslate.js

@@ -7,6 +7,7 @@ exports.runTranslate = runTranslate;
 exports.runTranslateCommand = runTranslateCommand;
 const node_fs_1 = __importDefault(require("node:fs"));
 const plural_forms_1 = require("plural-forms");
+const debug_1 = require("../debug");
 const po_1 = require("../po");
 const translate_1 = require("../translate");
 const validate_source_lang_1 = require("../validate-source-lang");
@@ -47,9 +48,21 @@ function getInvalidModelMessage(model) {
         `Supported model families: ${translate_1.SUPPORTED_STRUCTURED_OUTPUT_MODELS.join(', ')}.`,
     ].join(' ');
 }
-async function runTranslate(poFilePath, apiKey, sourceLang, model, includeFuzzy) {
+async function runTranslate(poFilePath, apiKey, sourceLang, model, includeFuzzy, debug) {
+    (0, debug_1.initDebugLogger)(debug);
+    const debugLogger = (0, debug_1.getDebugLogger)();
     try {
+        debugLogger.log('cli.runTranslate', 'Starting translation run', {
+            poFilePath,
+            sourceLang,
+            model: model ?? 'gpt-4o',
+            includeFuzzy: includeFuzzy === true,
+        });
         const poContent = node_fs_1.default.readFileSync(poFilePath, 'utf8');
+        debugLogger.log('cli.runTranslate', 'Read PO file', {
+            poFilePath,
+            bytes: Buffer.byteLength(poContent, 'utf8'),
+        });
         const parsedPo = (0, po_1.parsePoContent)(poContent);
         const { entries } = (0, po_1.getEntriesToTranslate)(parsedPo, { includeFuzzy });
         if (entries.length === 0) {
@@ -68,13 +81,30 @@ async function runTranslate(poFilePath, apiKey, sourceLang, model, includeFuzzy)
                 // locale not in plural-forms; rely on formula only
             }
         }
-        const options = { apiKey, sourceLanguage: sourceLang, formula, pluralSamples, model };
+        const options = { apiKey, sourceLanguage: sourceLang, formula, pluralSamples, model, debug };
+        debugLogger.log('cli.runTranslate', 'Computed translation run inputs', {
+            targetLanguage,
+            formula,
+            pluralSamples,
+            entryCount: entries.length,
+            entries,
+        });
         for (let i = 0; i < entries.length; i += TRANSLATE_BATCH_SIZE) {
             const batch = entries.slice(i, i + TRANSLATE_BATCH_SIZE);
             const batchNum = Math.floor(i / TRANSLATE_BATCH_SIZE) + 1;
             const totalBatches = Math.ceil(entries.length / TRANSLATE_BATCH_SIZE);
+            debugLogger.log('cli.runTranslate', 'Preparing translation batch', {
+                batch: batchNum,
+                totalBatches,
+                batchSize: batch.length,
+                entries: batch,
+            });
             console.log(`Translating batch ${batchNum}/${totalBatches} (${batch.length} phrase${batch.length === 1 ? '' : 's'})...`);
             const batchResults = await (0, translate_1.translateStrings)(batch, targetLanguage, options);
+            debugLogger.log('cli.runTranslate', 'Received translation batch results', {
+                batch: batchNum,
+                results: batchResults,
+            });
             for (const r of batchResults) {
                 if (typeof r.msgstr === 'string') {
                     console.log(`  ${r.msgid} => ${r.msgstr}`);
@@ -88,10 +118,17 @@ async function runTranslate(poFilePath, apiKey, sourceLang, model, includeFuzzy)
                 (0, po_1.clearFuzzyFromEntries)(parsedPo, batchResults);
             }
             node_fs_1.default.writeFileSync(poFilePath, (0, po_1.compilePo)(parsedPo));
+            debugLogger.log('cli.runTranslate', 'Wrote translated batch back to PO file', {
+                batch: batchNum,
+                poFilePath,
+            });
         }
         return 0;
     }
     catch (error) {
+        debugLogger.log('cli.runTranslate', 'Translation run failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
         const apiMessage = getApiErrorMessage(error);
         if (apiMessage != null) {
             console.warn(apiMessage);
@@ -102,8 +139,11 @@ async function runTranslate(poFilePath, apiKey, sourceLang, model, includeFuzzy)
         return 1;
     }
 }
-const USAGE = 'Usage: msgai <file.po> [--dry-run] [--api-key KEY] [--source-lang LANG] [--model MODEL] [--include-fuzzy]';
+const USAGE = 'Usage: msgai <file.po> [--dry-run] [--api-key KEY] [--source-lang LANG] [--model MODEL] [--include-fuzzy] [--debug]';
 function runTranslateCommand(args) {
+    (0, debug_1.initDebugLogger)(args.debug);
+    const debugLogger = (0, debug_1.getDebugLogger)();
+    debugLogger.log('cli.runTranslateCommand', 'Received command args', args);
     if (!args.poFilePath) {
         console.warn(USAGE);
         return 1;
@@ -113,6 +153,10 @@ function runTranslateCommand(args) {
             (0, validate_source_lang_1.validateSourceLang)(args.sourceLang);
         }
         catch (error) {
+            debugLogger.log('cli.runTranslateCommand', 'Source language validation failed', {
+                sourceLang: args.sourceLang,
+                error: error instanceof Error ? error.message : String(error),
+            });
             const message = error instanceof Error ? error.message : String(error);
             console.warn(message);
             return 1;
@@ -123,6 +167,9 @@ function runTranslateCommand(args) {
             (0, translate_1.validateModel)(args.model);
         }
         catch {
+            debugLogger.log('cli.runTranslateCommand', 'Model validation failed', {
+                model: args.model,
+            });
             console.warn(getInvalidModelMessage(args.model));
             return 1;
         }
@@ -131,20 +178,34 @@ function runTranslateCommand(args) {
         let resultApiKey;
         try {
             resultApiKey = (0, translate_1.resolveApiKey)(args.apiKey);
+            debugLogger.log('cli.runTranslateCommand', 'Resolved API key for translation run', {
+                source: args.apiKey != null && args.apiKey.trim() !== '' ? 'cli-arg' : 'env',
+            });
         }
         catch (error) {
+            debugLogger.log('cli.runTranslateCommand', 'API key resolution failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
             const message = error instanceof Error ? error.message : String(error);
             console.warn(message.replace('pass apiKey in options', 'pass --api-key'));
             return 1;
         }
-        return runTranslate(args.poFilePath, resultApiKey, args.sourceLang, args.model, args.includeFuzzy);
+        return runTranslate(args.poFilePath, resultApiKey, args.sourceLang, args.model, args.includeFuzzy, args.debug);
     }
     try {
         const poContent = node_fs_1.default.readFileSync(args.poFilePath, 'utf8');
+        debugLogger.log('cli.runTranslateCommand', 'Dry-run read PO file', {
+            poFilePath: args.poFilePath,
+            bytes: Buffer.byteLength(poContent, 'utf8'),
+        });
         const parsedPo = (0, po_1.parsePoContent)(poContent);
         const { entries } = (0, po_1.getEntriesToTranslate)(parsedPo, {
             includeFuzzy: args.includeFuzzy,
         });
+        debugLogger.log('cli.runTranslateCommand', 'Dry-run extracted entries', {
+            entryCount: entries.length,
+            entries,
+        });
         const msgidsToShow = entries.map((e) => e.msgid);
         for (const msgid of msgidsToShow) {
             console.log(msgid);
@@ -152,6 +213,9 @@ function runTranslateCommand(args) {
         return 0;
     }
     catch (error) {
+        debugLogger.log('cli.runTranslateCommand', 'Dry-run failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
         const message = error instanceof Error ? error.message : String(error);
         console.warn(`Failed to process PO file: ${message}`);
         return 1;

package/dist/src/debug.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasDebugFlag = hasDebugFlag;
+exports.initDebugLogger = initDebugLogger;
+exports.getDebugLogger = getDebugLogger;
+const debugState = {
+    enabled: false,
+};
+const debugLogger = {
+    get enabled() {
+        return debugState.enabled;
+    },
+    log(scope, message, details) {
+        if (!debugState.enabled)
+            return;
+        const prefix = `[debug] [${scope}] ${message}`;
+        if (details === undefined) {
+            console.warn(prefix);
+            return;
+        }
+        console.warn(prefix, details);
+    },
+};
+function hasDebugFlag(argv) {
+    return argv.includes('--debug');
+}
+function isDebugEnvEnabled() {
+    return process.env['DEBUG'] === '1';
+}
+function initDebugLogger(enabled) {
+    debugState.enabled = enabled === true || isDebugEnvEnabled();
+    return debugLogger;
+}
+function getDebugLogger() {
+    return debugLogger;
+}

package/dist/src/translate.js

@@ -10,6 +10,7 @@ exports.translatePayload = translatePayload;
 exports.translateItems = translateItems;
 exports.translateStrings = translateStrings;
 const openai_1 = __importDefault(require("openai"));
+const debug_1 = require("./debug");
 const loadEnv_1 = require("./loadEnv");
 function resolveApiKey(apiKey) {
     (0, loadEnv_1.loadEnv)();
@@ -211,11 +212,26 @@ function stripJsonFences(raw) {
     const match = trimmed.match(jsonBlock);
     return match ? match[1].trim() : trimmed;
 }
-function parsePayloadResponse(request, content) {
+function normalizeMsgctxt(msgctxt) {
+    return typeof msgctxt === 'string' ? msgctxt : '';
+}
+function buildProtectedFieldMismatchMessage(index, field) {
+    const entryRef = `OpenAI response translations[${index}].${field}`;
+    const retryHint = 'Retry the command once because this can be a transient structured-output formatting issue.';
+    const debugHint = 'If it keeps happening, rerun with --debug and double-check that the PO entry content matches the returned protected fields.';
+    if (field === 'msgctxt') {
+        return `${entryRef} must match the input exactly. ${retryHint} If it keeps happening, rerun with --debug and check whether empty gettext context is being returned as omitted vs empty string.`;
+    }
+    return `${entryRef} must match the input exactly. ${retryHint} ${debugHint}`;
+}
+function parsePayloadResponse(request, content, options) {
+    (0, debug_1.initDebugLogger)(options?.debug);
+    const debug = (0, debug_1.getDebugLogger)();
     if (content == null || content.trim() === '') {
         throw new Error('Empty response from OpenAI');
     }
     const raw = content.trim();
+    debug.log('translate', 'Raw OpenAI response content received', raw);
     const toParse = stripJsonFences(raw);
     let parsed;
     try {
@@ -246,13 +262,14 @@ function parsePayloadResponse(request, content) {
         const entry = t;
         const msgstr = entry.msgstr;
         const requestEntry = request.translations[i];
-        const requestContext = requestEntry.msgctxt;
-        if (entry.msgctxt !== requestContext) {
-            throw new Error(`OpenAI response translations[${i}].msgctxt must match the input exactly`);
+        const requestContext = normalizeMsgctxt(requestEntry.msgctxt);
+        const responseContext = normalizeMsgctxt(entry.msgctxt);
+        if (responseContext !== requestContext) {
+            throw new Error(buildProtectedFieldMismatchMessage(i, 'msgctxt'));
         }
         if ('msgid' in requestEntry) {
             if (entry.msgid !== requestEntry.msgid) {
-                throw new Error(`OpenAI response translations[${i}].msgid must match the input exactly`);
+                throw new Error(buildProtectedFieldMismatchMessage(i, 'msgid'));
             }
             if ('msgid_plural' in entry) {
                 throw new Error(`OpenAI response translations[${i}] must not include msgid_plural`);
@@ -263,7 +280,7 @@ function parsePayloadResponse(request, content) {
             throw new Error(`OpenAI response translations[${i}].msgstr must be a string`);
         }
         if (entry.msgid_plural !== requestEntry.msgid_plural) {
-            throw new Error(`OpenAI response translations[${i}].msgid_plural must match the input exactly`);
+            throw new Error(buildProtectedFieldMismatchMessage(i, 'msgid_plural'));
         }
         if ('msgid' in entry) {
             throw new Error(`OpenAI response translations[${i}] must not include msgid`);
@@ -283,33 +300,61 @@ async function translatePayload(payload, options) {
     if (payload.translations.length === 0) {
         return { ...payload, translations: [] };
     }
+    (0, debug_1.initDebugLogger)(options?.debug);
+    const debug = (0, debug_1.getDebugLogger)();
     const client = options?.client ??
         new openai_1.default({
             apiKey: options.apiKey,
         });
     const model = options?.model ?? DEFAULT_MODEL;
     validateStructuredOutputModel(model);
+    debug.log('translate', 'Prepared translatePayload request summary', {
+        model,
+        target_language: payload.target_language,
+        source_language: payload.source_language,
+        translation_count: payload.translations.length,
+        plural_samples: payload.plural_samples?.length ?? 0,
+    });
+    debug.log('translate', 'translatePayload request payload', payload);
+    const requestParams = {
+        model,
+        temperature: 0,
+        response_format: {
+            type: 'json_schema',
+            json_schema: TRANSLATION_RESPONSE_SCHEMA,
+        },
+        messages: [
+            { role: 'system', content: buildSystemMessage() },
+            { role: 'user', content: JSON.stringify(payload) },
+        ],
+    };
+    debug.log('translate', 'OpenAI chat.completions.create request', requestParams);
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
         try {
-            const response = await client.chat.completions.create({
-                model,
-                temperature: 0,
-                response_format: {
-                    type: 'json_schema',
-                    json_schema: TRANSLATION_RESPONSE_SCHEMA,
-                },
-                messages: [
-                    { role: 'system', content: buildSystemMessage() },
-                    { role: 'user', content: JSON.stringify(payload) },
-                ],
+            debug.log('translate', 'Sending request to OpenAI', {
+                attempt: attempt + 1,
+                max_attempts: MAX_RETRIES + 1,
+            });
+            const response = await client.chat.completions.create(requestParams);
+            debug.log('translate', 'OpenAI chat.completions.create response metadata', {
+                id: response.id,
+                model: response.model,
+                finish_reason: response.choices[0]?.finish_reason ?? null,
+                choices: response.choices.length,
             });
             const content = response.choices[0]?.message?.content ?? null;
-            return parsePayloadResponse(payload, content);
+            return parsePayloadResponse(payload, content, { debug: options?.debug });
         }
         catch (err) {
             const shouldRetry = attempt < MAX_RETRIES && isApiError(err) && isRetryableStatus(err.status);
+            debug.log('translate', 'translatePayload request failed', {
+                attempt: attempt + 1,
+                shouldRetry,
+                error: err instanceof Error ? err.message : String(err),
+            });
             if (shouldRetry) {
                 const delayMs = RETRY_DELAYS_MS[attempt] ?? RETRY_DELAYS_MS[RETRY_DELAYS_MS.length - 1];
+                debug.log('translate', 'Retrying after backoff', { delay_ms: delayMs });
                 await sleep(delayMs);
                 continue;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "msgai-cli",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "CLI that automatically translates all untranslated strings in gettext (.po) files using AI (LLM)",
   "main": "dist/src/cli/index.js",
   "bin": {
@@ -13,6 +13,7 @@
     "test:integration": "npm run build && jest -c jest.integration.config.cjs",
     "test:watch": "npm run build && jest --watch",
     "format": "prettier --write .",
+    "format:changelog": "prettier --write CHANGELOG.md",
     "lint": "eslint .",
     "lint:format": "prettier --check .",
     "prerelease": "npm run build && npm test && npm run test:integration && npm run lint && npm run lint:format",
@@ -51,7 +52,10 @@
   "homepage": "https://github.com/AlexMost/msgai#readme",
   "commit-and-tag-version": {
     "tagPrefix": "v",
-    "releaseCommitMessageFormat": "chore(release): {{currentTag}}"
+    "releaseCommitMessageFormat": "chore(release): {{currentTag}}",
+    "scripts": {
+      "postchangelog": "npm run format:changelog"
+    }
   },
   "devDependencies": {
     "@babel/core": "^7.29.0",