msgai-cli 1.0.2 → 1.1.1

package/CHANGELOG.md

@@ -1,8 +1,36 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+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.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+## [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
+
+- **cli:** add --model option for translation ([61a2ed8](https://github.com/AlexMost/msgai/commit/61a2ed8502a0f90bbb09a1715bbb58d0ddabe01e))
+- use structured outputs for translations ([c57e75b](https://github.com/AlexMost/msgai/commit/c57e75bda4229923dfca1daf1b8146a50f1d9b7f))
+
+## 1.0.2 (2026-02-27)
+
+### Bug Fixes
+
+- **po:** preserve PO file order in `getEntriesToTranslate` ([55ba8d8](https://github.com/AlexMost/msgai/commit/55ba8d8c4c43d26adf4d1e23fa5dac2bebbf2052))
+
+## 1.0.1 (2026-02-27)
+
+### Documentation
+
+- run formatter after each change and verify formatting in agent workflow ([1a1d909](https://github.com/AlexMost/msgai/commit/1a1d9097f9a88f6b260f5564fc6c800b52ea95a3))
+
+### Chores
+
+- clean `dist` folder before each build ([0e65234](https://github.com/AlexMost/msgai/commit/0e652342d076867d1795b69ca1cb07d7988b92d2))
+- fix formatting ([0cb5742](https://github.com/AlexMost/msgai/commit/0cb5742452f37f03a292f70ff6acc433f6f3666f))
 
 ## 1.0.0 (2026-02-27)
 
@@ -17,16 +45,3 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - **ci:** use github.event.workflow_run.conclusion in release-please ([0892b17](https://github.com/AlexMost/msgai/commit/0892b17aad1ec95a4e96a8208cb31d197264830f))
 - **ci:** use RELEASE_PLEASE_TOKEN so release-please can create PRs ([204c6cd](https://github.com/AlexMost/msgai/commit/204c6cdf88d480decae841f91c9fae168c4c0ce9))
 - use console.warn instead of console.error for pipeline compatibility ([8b30ebf](https://github.com/AlexMost/msgai/commit/8b30ebffba7c7447db3f51d931398938c39b6b85))
-
-## [Unreleased]
-
-## [1.0.0] - 2025-02-27
-
-### Added
-
-- CLI to translate untranslated strings in gettext (`.po`) files using AI (OpenAI LLM)
-- `msgai <file.po>`: translate empty `msgstr` entries and write back to the file
-- `--dry-run`: list untranslated `msgid` values without API calls or file changes
-- `--source-lang LANG`: specify source language (ISO 639-1); optional, model can infer
-- `--include-fuzzy`: include fuzzy entries for re-translation and clear fuzzy flag
-- `--api-key KEY` and `OPENAI_API_KEY` environment variable for API authentication

package/README.md

@@ -1,71 +1,169 @@
 # msgai
 
-`msgai` is a Node.js CLI that **automatically translates all untranslated strings in gettext (`.po`) files using AI (LLM)**. It reads your `.po` file, detects entries with empty or missing translations, sends them to an LLM (OpenAI), and writes the translations back into the file.
+`msgai` is an AI-powered CLI for translating gettext `.po` files. It finds untranslated entries, sends them to an LLM, and writes the translated strings back into the same file.
 
-**Install:** `npm install -g msgai-cli` (then run `msgai`).
+## 🤖 Project Purpose
 
-## Usage
+`msgai` is built for teams that already use gettext and want a simple way to translate missing strings without building a separate localization workflow.
 
-### Commands
+Main features:
 
-- `msgai <file.po>`: translates all untranslated `msgid` / `msgid_plural` entries in the file using AI and updates the `.po` file in place.
-- `msgai <file.po> --dry-run`: only lists untranslated `msgid` values (no API calls, no file changes).
-- `msgai --help`: prints command usage.
+- `📝` Works directly with gettext `.po` files
+- `🤖` Translates only untranslated entries using AI
+- `🧠` Uses OpenAI `gpt-4o` by default for translation
+- `🏷️` Respects gettext context (`msgctxt`) when translating entries
+- `🔁` Supports singular and plural translations
+- `⚠️` Skips fuzzy entries by default
+- `🧭` Can infer source language or use `--source-lang`
+- `💻` Runs as a small CLI that updates files in place
 
-### Fuzzy entries
+## ⚙️ How It Works
 
-- By default, entries marked as **fuzzy** in the `.po` file (e.g. `#, fuzzy`) are **skipped** and not sent for translation.
-- **`--include-fuzzy`**: include fuzzy entries. They are sent to the LLM with empty `msgstr` (like untranslated strings). After the translation is applied, the fuzzy flag is removed from those entries in the `.po` file.
+1. Read the `.po` file and parse its entries.
+2. Find entries with empty or missing translations.
+3. Send those strings to OpenAI `gpt-4o` for translation while preserving gettext context such as `msgctxt`.
+4. Write the translated values back into the same `.po` file.
 
-### Source language
+The translation API uses OpenAI `json_schema` structured outputs. Only models that support `json_schema` structured outputs are valid for `msgai`.
 
-- **`--source-lang LANG`**: source language of `msgid` strings as an ISO 639-1 code (e.g. `en`, `uk`). If omitted, the model will infer the source language. Invalid codes cause the CLI to exit with an error.
+<details>
+<summary>Supported model families</summary>
 
-### API key (for translation)
+- `gpt-4o`
+- `gpt-4o-mini`
+- `gpt-4.1`
+- `gpt-4.1-mini`
+- `gpt-4.1-nano`
+- `gpt-5`
+- `gpt-5-mini`
+- `gpt-5-nano`
+- `gpt-5-pro`
+- `gpt-5.1`
+- `gpt-5.2`
+- `gpt-5-codex`
+- `gpt-5.1-codex`
+- `gpt-5.1-codex-mini`
+- `gpt-5.1-codex-max`
+- `gpt-5.2-codex`
 
-When running without `--dry-run`, the CLI needs an OpenAI API key. You can pass it in either of these ways:
+Dated snapshots are accepted where the model family supports them.
 
-- **Environment variable**: set `OPENAI_API_KEY` (e.g. in your shell or a `.env` file in the current directory).
-- **CLI option**: pass `--api-key KEY` (e.g. `msgai messages.po --api-key sk-...`).
+</details>
 
-If neither is set, the CLI exits with code 1 and a message asking you to set the key.
+By default, entries marked as `fuzzy` are skipped. If you use `--include-fuzzy`, `msgai` will translate those entries too and remove the fuzzy flag after applying the result.
 
-On API errors (e.g. rate limit, quota, server errors), the CLI shows a status-specific message and exits with code 1. For error code reference, see [OpenAI API error codes](https://developers.openai.com/api/docs/guides/error-codes#api-errors).
+## 📦 Install
 
-## Development environment
+Install the CLI globally:
 
-### Requirements
+```bash
+npm install -g msgai-cli
+```
+
+Set your OpenAI API key before running translations:
+
+```bash
+export OPENAI_API_KEY=your_api_key_here
+```
+
+You can also pass the key directly:
+
+```bash
+msgai messages.po --api-key sk-...
+```
+
+`OPENAI_API_KEY` can be loaded from your environment or from a `.env` file in the current directory.
+
+## 💻 CLI Usage
+
+Usage:
+
+```bash
+msgai <file.po> [--dry-run] [--api-key KEY] [--source-lang LANG] [--model MODEL] [--include-fuzzy] [--debug]
+```
+
+Options:
+
+- `--dry-run`: list untranslated `msgid` values only, with no API calls and no file changes
+- `--include-fuzzy`: include fuzzy entries for translation and clear their fuzzy flag after translation
+- `--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. 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
 
-- Node.js 20+ (recommended latest LTS)
-- npm 10+
+Requirements:
 
-### Setup
+- Node.js `20+`
+- npm `10+`
+
+Install dependencies:
 
 ```bash
 npm install
 ```
 
-### Commit messages
+Useful scripts:
+
+- `npm run build`: compile TypeScript to `dist/`
+- `npm test`: build the project and run Jest tests
+- `npm run test:integration`: run integration tests
+- `npm run test:watch`: run tests in watch mode
+- `npm run lint`: run ESLint
+- `npm run lint:format`: check formatting with Prettier
+- `npm run format`: format the repository with Prettier
+- `npm run release:dry-run`: preview the `commit-and-tag-version` release without writing files
+- `npm run release`: run release checks, update `CHANGELOG.md`, bump the npm version, create a release commit, and create a local tag
+
+This repo follows [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages.
+
+### Release Flow
+
+Maintainer releases are local-first and use `commit-and-tag-version`. The release command does not publish to npm or push tags for you.
 
-This repo follows [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages: use `feat:` for new features, `fix:` for bug fixes, optional scope (e.g. `feat(cli):`), and `BREAKING CHANGE:` or `!` for major changes. This drives version bumps and CHANGELOG updates via release-please.
+Preview the next release:
 
-### Scripts
+```bash
+npm run release:dry-run
+```
+
+Create the release locally:
+
+```bash
+npm run release
+```
 
-- `npm run build`: compile TypeScript to `dist/`.
-- `npm test`: build project and run Jest tests.
-- `npm run test:watch`: build project and run Jest in watch mode.
-- `npm run format`: format code with Prettier.
-- `npm run lint:format`: check formatting with Prettier.
+This command:
 
-## Publishing
+- runs `build`, unit tests, integration tests, lint, and formatting checks through the `prerelease` lifecycle hook
+- lets `commit-and-tag-version` infer `major`, `minor`, or `patch` from Conventional Commits since the latest `v*` tag
+- updates `CHANGELOG.md`
+- creates `chore(release): X.Y.Z`
+- creates a local annotated tag `vX.Y.Z`
 
-Releases are driven by [release-please](https://github.com/googleapis/release-please): it opens a **Release PR** that bumps the version and updates `CHANGELOG.md` from conventional commits. After the Release PR is merged, release-please creates the release tag on `main`.
+For reliable version bumps and changelog entries, keep commits in Conventional Commit format.
 
-**Release-please setup:** In the repo go to **Settings → Actions → General → Workflow permissions** and set to **Read and write** and enable **Allow GitHub Actions to create and approve pull requests**. You can then use the default `GITHUB_TOKEN` (no secret). If you see "Error adding to tree" or PR creation blocked, add a Personal Access Token as secret `RELEASE_PLEASE_TOKEN` (classic: `repo` + `workflow` scope; fine-grained: Contents + Pull requests + Workflows write).
+If you need to override the inferred bump manually:
 
-**Publishing to npm (local):**
+```bash
+npm run release -- --release-as minor
+```
 
-1. Pull `main` with the new release tag.
-2. Run `npm publish`.
+After the local release is created:
 
-Before publishing, `prepublishOnly` runs build, unit tests, integration tests, lint, and format checks. Set `OPENAI_API_KEY` so integration tests pass.
+```bash
+git push --follow-tags
+npm publish
+```

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] [--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,
@@ -28,11 +29,20 @@ function parseArgs(argv) {
             .option('source-lang', {
             type: 'string',
             description: 'Source language of msgid strings (ISO 639-1 code, e.g. en, uk). If omitted, the model will detect it.',
+        })
+            .option('model', {
+            type: 'string',
+            description: 'OpenAI model to use for translation. Default: gpt-4o',
         })
             .option('help', {
             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)
@@ -49,53 +59,71 @@ function parseArgs(argv) {
         const sourceLang = sourceLangRaw != null && String(sourceLangRaw).trim() !== ''
             ? String(sourceLangRaw).trim().toLowerCase()
             : undefined;
+        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),
             apiKey: parsedArgs['api-key'],
             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] [--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,
         apiKey: args.apiKey,
         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");
@@ -41,9 +42,27 @@ function getApiErrorMessage(err) {
             return null;
     }
 }
-async function runTranslate(poFilePath, apiKey, sourceLang, includeFuzzy) {
+function getInvalidModelMessage(model) {
+    return [
+        `Invalid --model "${model}". msgai only supports OpenAI models with json_schema structured outputs.`,
+        `Supported model families: ${translate_1.SUPPORTED_STRUCTURED_OUTPUT_MODELS.join(', ')}.`,
+    ].join(' ');
+}
+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) {
@@ -62,13 +81,30 @@ async function runTranslate(poFilePath, apiKey, sourceLang, includeFuzzy) {
                 // locale not in plural-forms; rely on formula only
             }
         }
-        const options = { apiKey, sourceLanguage: sourceLang, formula, pluralSamples };
+        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}`);
@@ -82,10 +118,17 @@ async function runTranslate(poFilePath, apiKey, sourceLang, 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);
@@ -96,8 +139,11 @@ async function runTranslate(poFilePath, apiKey, sourceLang, includeFuzzy) {
         return 1;
     }
 }
-const USAGE = 'Usage: msgai <file.po> [--dry-run] [--api-key KEY] [--source-lang LANG] [--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;
@@ -107,29 +153,59 @@ 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;
         }
     }
+    if (args.model != null) {
+        try {
+            (0, translate_1.validateModel)(args.model);
+        }
+        catch {
+            debugLogger.log('cli.runTranslateCommand', 'Model validation failed', {
+                model: args.model,
+            });
+            console.warn(getInvalidModelMessage(args.model));
+            return 1;
+        }
+    }
     if (!args.dryRun) {
         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.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);
@@ -137,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

@@ -3,11 +3,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_STRUCTURED_OUTPUT_MODELS = void 0;
 exports.resolveApiKey = resolveApiKey;
+exports.validateModel = validateModel;
 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)();
@@ -19,6 +22,42 @@ function resolveApiKey(apiKey) {
     throw new Error('OpenAI API key not set. Set OPENAI_API_KEY in the environment or pass apiKey in options.');
 }
 const DEFAULT_MODEL = 'gpt-4o';
+const SUPPORTED_STRUCTURED_OUTPUT_MODEL_PATTERNS = [
+    /^gpt-4o(?:-\d{4}-\d{2}-\d{2})?$/,
+    /^gpt-4o-mini(?:-\d{4}-\d{2}-\d{2})?$/,
+    /^gpt-4\.1(?:-\d{4}-\d{2}-\d{2})?$/,
+    /^gpt-4\.1-mini(?:-\d{4}-\d{2}-\d{2})?$/,
+    /^gpt-4\.1-nano(?:-\d{4}-\d{2}-\d{2})?$/,
+    /^gpt-5(?:-\d{4}-\d{2}-\d{2}|-chat-latest)?$/,
+    /^gpt-5-mini(?:-\d{4}-\d{2}-\d{2})?$/,
+    /^gpt-5-nano(?:-\d{4}-\d{2}-\d{2})?$/,
+    /^gpt-5-pro(?:-\d{4}-\d{2}-\d{2})?$/,
+    /^gpt-5\.1(?:-\d{4}-\d{2}-\d{2}|-chat-latest)?$/,
+    /^gpt-5\.2(?:-\d{4}-\d{2}-\d{2}|-chat-latest)?$/,
+    /^gpt-5-codex$/,
+    /^gpt-5\.1-codex$/,
+    /^gpt-5\.1-codex-mini$/,
+    /^gpt-5\.1-codex-max$/,
+    /^gpt-5\.2-codex$/,
+];
+exports.SUPPORTED_STRUCTURED_OUTPUT_MODELS = [
+    'gpt-4o',
+    'gpt-4o-mini',
+    'gpt-4.1',
+    'gpt-4.1-mini',
+    'gpt-4.1-nano',
+    'gpt-5',
+    'gpt-5-mini',
+    'gpt-5-nano',
+    'gpt-5-pro',
+    'gpt-5.1',
+    'gpt-5.2',
+    'gpt-5-codex',
+    'gpt-5.1-codex',
+    'gpt-5.1-codex-mini',
+    'gpt-5.1-codex-max',
+    'gpt-5.2-codex',
+];
 /** Error codes: https://developers.openai.com/api/docs/guides/error-codes#api-errors */
 const MAX_RETRIES = 3;
 const RETRY_DELAYS_MS = [1000, 2000, 4000];
@@ -34,20 +73,94 @@ function isApiError(err) {
 function isRetryableStatus(status) {
     return status === 429 || status === 500 || status === 503;
 }
+function isSupportedStructuredOutputModel(model) {
+    return SUPPORTED_STRUCTURED_OUTPUT_MODEL_PATTERNS.some((pattern) => pattern.test(model));
+}
+function validateStructuredOutputModel(model) {
+    if (isSupportedStructuredOutputModel(model))
+        return;
+    throw new Error(`Model "${model}" is not supported. This package requires an OpenAI Chat Completions model with json_schema structured outputs. Supported model families: ${exports.SUPPORTED_STRUCTURED_OUTPUT_MODELS.join(', ')}.`);
+}
+function validateModel(model) {
+    validateStructuredOutputModel(model);
+}
+const TRANSLATION_RESPONSE_SCHEMA = {
+    name: 'translation_payload',
+    strict: true,
+    schema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['translations'],
+        properties: {
+            translations: {
+                type: 'array',
+                items: {
+                    anyOf: [
+                        {
+                            type: 'object',
+                            additionalProperties: false,
+                            required: ['msgid', 'msgstr'],
+                            properties: {
+                                msgid: { type: 'string' },
+                                msgstr: { type: 'string' },
+                            },
+                        },
+                        {
+                            type: 'object',
+                            additionalProperties: false,
+                            required: ['msgid', 'msgctxt', 'msgstr'],
+                            properties: {
+                                msgid: { type: 'string' },
+                                msgctxt: { type: 'string' },
+                                msgstr: { type: 'string' },
+                            },
+                        },
+                        {
+                            type: 'object',
+                            additionalProperties: false,
+                            required: ['msgid_plural', 'msgstr'],
+                            properties: {
+                                msgid_plural: { type: 'string' },
+                                msgstr: {
+                                    type: 'array',
+                                    items: { type: 'string' },
+                                },
+                            },
+                        },
+                        {
+                            type: 'object',
+                            additionalProperties: false,
+                            required: ['msgid_plural', 'msgctxt', 'msgstr'],
+                            properties: {
+                                msgid_plural: { type: 'string' },
+                                msgctxt: { type: 'string' },
+                                msgstr: {
+                                    type: 'array',
+                                    items: { type: 'string' },
+                                },
+                            },
+                        },
+                    ],
+                },
+            },
+        },
+    },
+};
 function buildSystemMessage() {
     return `You are a deterministic translation engine for gettext PO entries.
 
+Return exactly one JSON object that matches the provided response schema.
+
 Your task:
 For each input entry, produce a translation in the corresponding "msgstr" field.
 Each output entry MUST correspond exactly to the matching input entry.
-Do not change, remove, or reorder any "msgid" or "msgid_plural" values.
+Do not change, remove, or reorder any "msgid", "msgid_plural", or "msgctxt" values.
 Only fill the "msgstr" field.
-If an entry has "msgctxt", leave it unchanged and return it in the output (so same msgids for different contexts are not mixed).
 
 Critical rules:
 
-- Preserve ALL placeholders exactly as in the source text.
-- NEVER translate, modify, reorder, or remove placeholders.
+- Copy ALL placeholders and non-linguistic tokens exactly, byte-for-byte.
+- NEVER translate, modify, reorder, remove, escape, or unescape placeholders.
 
 Placeholders include (but are not limited to):
 - printf-style specifiers: %s, %d, %f, %1$s, %(name)s
@@ -87,22 +200,9 @@ Output:
 
 You MUST respond with nothing but a single JSON object. No markdown, no code fences (no \`\`\`json or \`\`\`), no explanatory text before or after. The response must be parseable by JSON.parse() directly.
 
-Return EXACTLY this structure (and nothing else):
-
-{
-  "formula": "...",
-  "target_language": "...",
-  "source_language": "...",
-  "translations": [
-    { "msgid": "...", "msgstr": "..." },
-    { "msgid_plural": "...", "msgstr": ["...", "..."] }
-  ]
-}
-
 Additional constraints:
 
 - Preserve the exact input order of entries.
-- Do not modify "formula", "target_language", or "source_language".
 - Do not add, remove, or rename fields.`;
 }
 /** Strip markdown code fences if the model wrapped JSON in ```json ... ``` */
@@ -112,11 +212,26 @@ function stripJsonFences(raw) {
     const match = trimmed.match(jsonBlock);
     return match ? match[1].trim() : trimmed;
 }
-function parsePayloadResponse(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 {
@@ -135,6 +250,9 @@ function parsePayloadResponse(content) {
         console.warn('OpenAI model returned (raw):', raw);
         throw new Error(`OpenAI response "translations" must be an array: ${raw.slice(0, 200)}`);
     }
+    if (payload.translations.length !== request.translations.length) {
+        throw new Error('OpenAI response "translations" must have the same number of entries as input');
+    }
     for (let i = 0; i < payload.translations.length; i++) {
         const t = payload.translations[i];
         if (t == null || typeof t !== 'object' || !('msgstr' in t)) {
@@ -143,12 +261,38 @@ function parsePayloadResponse(content) {
         }
         const entry = t;
         const msgstr = entry.msgstr;
-        if (typeof msgstr === 'string')
-            continue;
-        if (Array.isArray(msgstr) && msgstr.every((s) => typeof s === 'string'))
+        const requestEntry = request.translations[i];
+        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(buildProtectedFieldMismatchMessage(i, 'msgid'));
+            }
+            if ('msgid_plural' in entry) {
+                throw new Error(`OpenAI response translations[${i}] must not include msgid_plural`);
+            }
+            if (typeof msgstr === 'string')
+                continue;
+            console.warn('OpenAI model returned (raw):', raw);
+            throw new Error(`OpenAI response translations[${i}].msgstr must be a string`);
+        }
+        if (entry.msgid_plural !== requestEntry.msgid_plural) {
+            throw new Error(buildProtectedFieldMismatchMessage(i, 'msgid_plural'));
+        }
+        if ('msgid' in entry) {
+            throw new Error(`OpenAI response translations[${i}] must not include msgid`);
+        }
+        if (Array.isArray(msgstr) && msgstr.every((s) => typeof s === 'string')) {
+            if (request.plural_samples != null && msgstr.length !== request.plural_samples.length) {
+                throw new Error(`OpenAI response translations[${i}].msgstr must have length ${request.plural_samples.length}`);
+            }
             continue;
+        }
         console.warn('OpenAI model returned (raw):', raw);
-        throw new Error(`OpenAI response translations[${i}].msgstr must be a string or array of strings`);
+        throw new Error(`OpenAI response translations[${i}].msgstr must be an array of strings`);
     }
     return payload;
 }
@@ -156,27 +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,
-                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(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.0.2",
+  "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,8 +13,12 @@
     "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",
+    "release": "commit-and-tag-version",
+    "release:dry-run": "commit-and-tag-version --dry-run",
     "script:test-openai": "ts-node scripts/test-openai.ts",
     "prepublishOnly": "npm run build && npm test && npm run test:integration && npm run lint && npm run lint:format"
   },
@@ -46,6 +50,13 @@
     "url": "https://github.com/AlexMost/msgai/issues"
   },
   "homepage": "https://github.com/AlexMost/msgai#readme",
+  "commit-and-tag-version": {
+    "tagPrefix": "v",
+    "releaseCommitMessageFormat": "chore(release): {{currentTag}}",
+    "scripts": {
+      "postchangelog": "npm run format:changelog"
+    }
+  },
   "devDependencies": {
     "@babel/core": "^7.29.0",
     "@babel/preset-env": "^7.29.0",
@@ -54,6 +65,7 @@
     "@types/jest": "^30.0.0",
     "@types/node": "^25.3.0",
     "babel-jest": "^30.2.0",
+    "commit-and-tag-version": "^12.6.1",
     "eslint": "^10.0.2",
     "jest": "^30.2.0",
     "prettier": "^3.8.1",