msgai-cli 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,8 +1,30 @@
 # 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.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 +39,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,162 @@
 # 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]
+```
+
+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`
+- `--help`: print command usage
 
-- Node.js 20+ (recommended latest LTS)
-- npm 10+
+If no API key is provided for a non-dry run, the CLI exits with code `1` and prints an error message.
 
-### Setup
+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).
+
+## 🧪 Development
+
+Requirements:
+
+- 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.
+
+Preview the next release:
 
-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.
+```bash
+npm run release:dry-run
+```
 
-### Scripts
+Create the release locally:
 
-- `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.
+```bash
+npm run release
+```
 
-## Publishing
+This command:
 
-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`.
+- 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`
 
-**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).
+For reliable version bumps and changelog entries, keep commits in Conventional Commit format.
 
-**Publishing to npm (local):**
+If you need to override the inferred bump manually:
 
-1. Pull `main` with the new release tag.
-2. Run `npm publish`.
+```bash
+npm run release -- --release-as minor
+```
+
+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

@@ -11,7 +11,7 @@ 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]')
             .option('dry-run', {
             type: 'boolean',
             default: false,
@@ -28,6 +28,10 @@ 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',
@@ -49,12 +53,15 @@ 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 {
                 dryRun: Boolean(parsedArgs['dry-run']),
                 help: Boolean(parsedArgs.help),
                 apiKey: parsedArgs['api-key'],
                 sourceLang,
+                model,
                 includeFuzzy: Boolean(parsedArgs['include-fuzzy']),
                 error: `Unexpected argument: ${positionalArgs[1]}`,
             };
@@ -65,6 +72,7 @@ function parseArgs(argv) {
             help: Boolean(parsedArgs.help),
             apiKey: parsedArgs['api-key'],
             sourceLang,
+            model,
             includeFuzzy: Boolean(parsedArgs['include-fuzzy']),
         };
     }
@@ -73,7 +81,7 @@ function parseArgs(argv) {
         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]';
 function main(argv) {
     const args = parseArgs(argv);
     if (args.error) {
@@ -90,6 +98,7 @@ function main(argv) {
         dryRun: args.dryRun,
         apiKey: args.apiKey,
         sourceLang: args.sourceLang,
+        model: args.model,
         includeFuzzy: args.includeFuzzy,
     });
     if (result instanceof Promise) {

package/dist/src/cli/runTranslate.js

@@ -41,7 +41,13 @@ 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) {
     try {
         const poContent = node_fs_1.default.readFileSync(poFilePath, 'utf8');
         const parsedPo = (0, po_1.parsePoContent)(poContent);
@@ -62,7 +68,7 @@ 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 };
         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;
@@ -96,7 +102,7 @@ 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]';
 function runTranslateCommand(args) {
     if (!args.poFilePath) {
         console.warn(USAGE);
@@ -112,6 +118,15 @@ function runTranslateCommand(args) {
             return 1;
         }
     }
+    if (args.model != null) {
+        try {
+            (0, translate_1.validateModel)(args.model);
+        }
+        catch {
+            console.warn(getInvalidModelMessage(args.model));
+            return 1;
+        }
+    }
     if (!args.dryRun) {
         let resultApiKey;
         try {
@@ -122,7 +137,7 @@ function runTranslateCommand(args) {
             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);
     }
     try {
         const poContent = node_fs_1.default.readFileSync(args.poFilePath, 'utf8');

package/dist/src/po.js

@@ -52,7 +52,7 @@ function parsePoContent(poContent) {
     return gettext_parser_1.po.parse(Buffer.from(poContent, 'utf8'));
 }
 /**
- * Returns untranslated entries and their keys in stable order (contexts and msgids sorted).
+ * Returns untranslated entries and their keys in the order they appear in the original PO file (parser order).
  * Skips the header (msgid "").
  * By default skips fuzzy entries; set includeFuzzy to include them (with empty msgstr for the request).
  */
@@ -61,12 +61,12 @@ function getEntriesToTranslate(parsedPo, options) {
     const entries = [];
     const keys = [];
     const translations = parsedPo.translations;
-    const contextNames = Object.keys(translations).sort();
+    const contextNames = Object.keys(translations);
     for (const context of contextNames) {
         const contextEntries = translations[context];
         if (contextEntries == null)
             continue;
-        const msgids = Object.keys(contextEntries).sort();
+        const msgids = Object.keys(contextEntries);
         for (const msgid of msgids) {
             if (msgid === '')
                 continue;

package/dist/src/translate.js

@@ -3,7 +3,9 @@ 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;
@@ -19,6 +21,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 +72,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 +199,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,7 +211,7 @@ function stripJsonFences(raw) {
     const match = trimmed.match(jsonBlock);
     return match ? match[1].trim() : trimmed;
 }
-function parsePayloadResponse(content) {
+function parsePayloadResponse(request, content) {
     if (content == null || content.trim() === '') {
         throw new Error('Empty response from OpenAI');
     }
@@ -135,6 +234,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 +245,37 @@ 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 = requestEntry.msgctxt;
+        if (entry.msgctxt !== requestContext) {
+            throw new Error(`OpenAI response translations[${i}].msgctxt must match the input exactly`);
+        }
+        if ('msgid' in requestEntry) {
+            if (entry.msgid !== requestEntry.msgid) {
+                throw new Error(`OpenAI response translations[${i}].msgid must match the input exactly`);
+            }
+            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(`OpenAI response translations[${i}].msgid_plural must match the input exactly`);
+        }
+        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;
 }
@@ -161,17 +288,23 @@ async function translatePayload(payload, options) {
             apiKey: options.apiKey,
         });
     const model = options?.model ?? DEFAULT_MODEL;
+    validateStructuredOutputModel(model);
     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) },
                 ],
             });
             const content = response.choices[0]?.message?.content ?? null;
-            return parsePayloadResponse(content);
+            return parsePayloadResponse(payload, content);
         }
         catch (err) {
             const shouldRetry = attempt < MAX_RETRIES && isApiError(err) && isRetryableStatus(err.status);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "msgai-cli",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "CLI that automatically translates all untranslated strings in gettext (.po) files using AI (LLM)",
   "main": "dist/src/cli/index.js",
   "bin": {
@@ -15,6 +15,9 @@
     "format": "prettier --write .",
     "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 +49,10 @@
     "url": "https://github.com/AlexMost/msgai/issues"
   },
   "homepage": "https://github.com/AlexMost/msgai#readme",
+  "commit-and-tag-version": {
+    "tagPrefix": "v",
+    "releaseCommitMessageFormat": "chore(release): {{currentTag}}"
+  },
   "devDependencies": {
     "@babel/core": "^7.29.0",
     "@babel/preset-env": "^7.29.0",
@@ -54,6 +61,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",