lingo.dev 0.111.8 → 0.111.10

package/build/cli.mjs

@@ -442,12 +442,12 @@ function createAuthenticator(params) {
 }
 
 // src/cli/cmd/auth.ts
-var auth_default = new Command().command("auth").description("Show current authentication status").helpOption("-h, --help", "Show help").option(
+var auth_default = new Command().command("auth").description("Show current authentication status and user email").helpOption("-h, --help", "Show help").option(
   "--login",
-  "Login to your account (deprecated: use 'lingo.dev login' instead)"
+  "DEPRECATED: Shows deprecation warning and exits. Use `lingo.dev login` instead"
 ).option(
   "--logout",
-  "Logout from your account (deprecated: use 'lingo.dev logout' instead)"
+  "DEPRECATED: Shows deprecation warning and exits. Use `lingo.dev logout` instead"
 ).action(async (options) => {
   try {
     if (options.login) {
@@ -595,7 +595,9 @@ async function renderSummary(results) {
 }
 
 // src/cli/cmd/login.ts
-var login_default = new Command2().command("login").description("Authenticate with Lingo.dev API").helpOption("-h, --help", "Show help").action(async () => {
+var login_default = new Command2().command("login").description(
+  "Open browser to authenticate with lingo.dev and save your API key"
+).helpOption("-h, --help", "Show help").action(async () => {
   try {
     await renderClear();
     await renderSpacer();
@@ -654,7 +656,7 @@ async function waitForApiKey(cb) {
 // src/cli/cmd/logout.ts
 import { Command as Command3 } from "interactive-commander";
 import Ora3 from "ora";
-var logout_default = new Command3().command("logout").description("Log out from Lingo.dev API").helpOption("-h, --help", "Show help").action(async () => {
+var logout_default = new Command3().command("logout").description("Log out by removing saved authentication credentials").helpOption("-h, --help", "Show help").action(async () => {
   try {
     await renderClear();
     await renderSpacer();
@@ -1072,10 +1074,16 @@ var throwHelpError = (option, value) => {
 Do you need support for ${value} ${option}? Type "help" and we will.`
   );
 };
-var init_default = new InteractiveCommand().command("init").description("Initialize Lingo.dev project").helpOption("-h, --help", "Show help").addOption(
-  new InteractiveOption("-f --force", "Overwrite existing config").prompt(void 0).default(false)
+var init_default = new InteractiveCommand().command("init").description("Create i18n.json configuration file for a new project").helpOption("-h, --help", "Show help").addOption(
+  new InteractiveOption(
+    "-f --force",
+    "Overwrite existing Lingo.dev configuration instead of aborting initialization (destructive operation)"
+  ).prompt(void 0).default(false)
 ).addOption(
-  new InteractiveOption("-s --source <locale>", "Source locale").argParser((value) => {
+  new InteractiveOption(
+    "-s --source <locale>",
+    "Primary language of your application that content will be translated from. Defaults to 'en'"
+  ).argParser((value) => {
     try {
       resolveLocaleCode2(value);
     } catch (e) {
@@ -1084,7 +1092,10 @@ var init_default = new InteractiveCommand().command("init").description("Initial
     return value;
   }).default("en")
 ).addOption(
-  new InteractiveOption("-t --targets <locale...>", "List of target locales").argParser((value) => {
+  new InteractiveOption(
+    "-t --targets <locale...>",
+    "Target languages to translate to. Accepts locale codes like 'es', 'fr', 'de-AT' separated by commas or spaces. Defaults to 'es'"
+  ).argParser((value) => {
     const values = value.includes(",") ? value.split(",") : value.split(" ");
     values.forEach((value2) => {
       try {
@@ -1096,7 +1107,10 @@ var init_default = new InteractiveCommand().command("init").description("Initial
     return values;
   }).default("es")
 ).addOption(
-  new InteractiveOption("-b, --bucket <type>", "Type of bucket").argParser((value) => {
+  new InteractiveOption(
+    "-b, --bucket <type>",
+    "File format for your translation files. Must match a supported type such as json, yaml, or android"
+  ).argParser((value) => {
     if (!bucketTypes.includes(value)) {
       throwHelpError("bucket format", value);
     }
@@ -1105,7 +1119,7 @@ var init_default = new InteractiveCommand().command("init").description("Initial
 ).addOption(
   new InteractiveOption(
     "-p, --paths [path...]",
-    "List of paths for the bucket"
+    "File paths containing translations when using --no-interactive mode. Specify paths with [locale] placeholder, separated by commas or spaces"
   ).argParser((value) => {
     if (!value || value.length === 0) return [];
     const values = value.includes(",") ? value.split(",") : value.split(" ");
@@ -1248,7 +1262,7 @@ import _4 from "lodash";
 import fs7 from "fs";
 import path8 from "path";
 import { defaultConfig as defaultConfig2 } from "@lingo.dev/_spec";
-var config_default = new Command4().command("config").description("Print out the current configuration").helpOption("-h, --help", "Show help").action(async (options) => {
+var config_default = new Command4().command("config").description("Print effective i18n.json after merging with defaults").helpOption("-h, --help", "Show help").action(async (options) => {
   const fileConfig = loadReplexicaFileConfig();
   const config = _4.merge({}, defaultConfig2, fileConfig);
   console.log(JSON.stringify(config, null, 2));
@@ -1268,7 +1282,10 @@ function loadReplexicaFileConfig() {
 import { Command as Command5 } from "interactive-commander";
 import Ora5 from "ora";
 import { localeCodes } from "@lingo.dev/_spec";
-var locale_default = new Command5().command("locale").description("Print out the list of locales").helpOption("-h, --help", "Show help").argument("<type>", 'Type of locales to show, either "sources" or "targets"').action(async (type) => {
+var locale_default = new Command5().command("locale").description("List supported locale codes").helpOption("-h, --help", "Show help").argument(
+  "<type>",
+  'Type of locales to show: "sources" or "targets" - both show the full supported locale list'
+).action(async (type) => {
   const ora = Ora5();
   try {
     switch (type) {
@@ -1432,12 +1449,14 @@ function resolveBucketItem(bucketItem) {
 
 // src/cli/cmd/show/files.ts
 import { resolveOverriddenLocale as resolveOverriddenLocale2 } from "@lingo.dev/_spec";
-var files_default = new Command6().command("files").description("Print out the list of files managed by Lingo.dev").option(
+var files_default = new Command6().command("files").description(
+  "Expand each bucket's path pattern into concrete source and target file paths"
+).option(
   "--source",
-  "Only show source files, files containing the original translations"
+  "Only list the source locale variant for each path pattern"
 ).option(
   "--target",
-  "Only show target files, files containing translated content"
+  "Only list the target locale variants for each configured locale"
 ).helpOption("-h, --help", "Show help").action(async (type) => {
   const ora = Ora6();
   try {
@@ -1498,7 +1517,7 @@ var files_default = new Command6().command("files").description("Print out the l
 });
 
 // src/cli/cmd/show/index.ts
-var show_default = new Command7().command("show").description("Prints out the current configuration").helpOption("-h, --help", "Show help").addCommand(config_default).addCommand(locale_default).addCommand(files_default);
+var show_default = new Command7().command("show").description("Display configuration, locales, and file paths").helpOption("-h, --help", "Show help").addCommand(config_default).addCommand(locale_default).addCommand(files_default);
 
 // src/cli/cmd/config/index.ts
 import { Command as Command11 } from "interactive-commander";
@@ -1508,9 +1527,12 @@ import { Command as Command8 } from "interactive-commander";
 import chalk2 from "chalk";
 import dedent from "dedent";
 import _6 from "lodash";
-var set_default = new Command8().name("set").description("Set a configuration key to a value").addHelpText("afterAll", `
+var set_default = new Command8().name("set").description("Set or update a CLI setting in ~/.lingodotdevrc").addHelpText("afterAll", `
 Available keys:
-  ${SETTINGS_KEYS.join("\n  ")}`).argument("<key>", "Configuration key to set").argument("<value>", "New value").helpOption("-h, --help", "Show help").action(async (key, value) => {
+  ${SETTINGS_KEYS.join("\n  ")}`).argument(
+  "<key>",
+  "Configuration key to set (dot notation, e.g., auth.apiKey)"
+).argument("<value>", "The configuration value to set").helpOption("-h, --help", "Show help").action(async (key, value) => {
   if (!SETTINGS_KEYS.includes(key)) {
     console.error(
       dedent`
@@ -1544,9 +1566,12 @@ import { Command as Command9 } from "interactive-commander";
 import chalk3 from "chalk";
 import dedent2 from "dedent";
 import _7 from "lodash";
-var unset_default = new Command9().name("unset").description("Remove a configuration key").addHelpText("afterAll", `
+var unset_default = new Command9().name("unset").description("Remove a CLI setting from ~/.lingodotdevrc").addHelpText("afterAll", `
 Available keys:
-  ${SETTINGS_KEYS.join("\n  ")}`).argument("<key>", "Configuration key to remove").helpOption("-h, --help", "Show help").action(async (key) => {
+  ${SETTINGS_KEYS.join("\n  ")}`).argument(
+  "<key>",
+  "Configuration key to remove (must match one of the available keys listed below)"
+).helpOption("-h, --help", "Show help").action(async (key) => {
   if (!SETTINGS_KEYS.includes(key)) {
     console.error(
       dedent2`
@@ -1590,9 +1615,12 @@ import { Command as Command10 } from "interactive-commander";
 import chalk4 from "chalk";
 import _8 from "lodash";
 import dedent3 from "dedent";
-var get_default = new Command10().name("get").description("Get the value of a configuration key").addHelpText("afterAll", `
+var get_default = new Command10().name("get").description("Display the value of a CLI setting from ~/.lingodotdevrc").addHelpText("afterAll", `
 Available keys:
-  ${SETTINGS_KEYS.join("\n  ")}`).argument("<key>", "Configuration key").helpOption("-h, --help", "Show help").action(async (key) => {
+  ${SETTINGS_KEYS.join("\n  ")}`).argument(
+  "<key>",
+  "Configuration key to read (choose from the available keys listed below)"
+).helpOption("-h, --help", "Show help").action(async (key) => {
   if (!SETTINGS_KEYS.includes(key)) {
     console.error(
       dedent3`
@@ -1617,7 +1645,9 @@ Available keys:
 });
 
 // src/cli/cmd/config/index.ts
-var config_default2 = new Command11().command("config").description("Manage Lingo.dev CLI configuration").helpOption("-h, --help", "Show help").addCommand(set_default).addCommand(unset_default).addCommand(get_default);
+var config_default2 = new Command11().command("config").description(
+  "Manage CLI settings (authentication, API keys) stored in ~/.lingodotdevrc"
+).helpOption("-h, --help", "Show help").addCommand(set_default).addCommand(unset_default).addCommand(get_default);
 
 // src/cli/cmd/i18n.ts
 import {
@@ -7201,6 +7231,7 @@ function createBucketLoader(bucketType, bucketPathPattern, options, lockedKeys,
         createXcodeXcstringsLoader(options.defaultLocale),
         createFlatLoader(),
         createEnsureKeyOrderLoader(),
+        createLockedKeysLoader(lockedKeys || []),
         createSyncLoader(),
         createVariableLoader({ type: "ieee" }),
         createUnlocalizableLoader(options.returnUnlocalizedKeys)
@@ -7781,41 +7812,43 @@ function createDeltaProcessor(fileKey) {
 }
 
 // src/cli/cmd/i18n.ts
-var i18n_default = new Command12().command("i18n").description("Run Localization engine").helpOption("-h, --help", "Show help").option(
+var i18n_default = new Command12().command("i18n").description(
+  "DEPRECATED: Run localization pipeline (prefer `run` command instead)"
+).helpOption("-h, --help", "Show help").option(
   "--locale <locale>",
-  "Locale to process",
+  "Limit processing to the listed target locale codes from i18n.json. Repeat the flag to include multiple locales. Defaults to all configured target locales",
   (val, prev) => prev ? [...prev, val] : [val]
 ).option(
   "--bucket <bucket>",
-  "Bucket to process",
+  "Limit processing to specific bucket types defined in i18n.json (e.g., json, yaml, android). Repeat the flag to include multiple bucket types. Defaults to all buckets",
   (val, prev) => prev ? [...prev, val] : [val]
 ).option(
   "--key <key>",
-  "Key to process. Process only a specific translation key, useful for debugging or updating a single entry"
+  "Limit processing to a single translation key by exact match. Filters all buckets and locales to process only this key, useful for testing or debugging specific translations. Example: auth.login.title"
 ).option(
   "--file [files...]",
-  "File to process. Process only a specific path, may contain asterisk * to match multiple files. Useful if you have a lot of files and want to focus on a specific one. Specify more files separated by commas or spaces."
+  "Filter processing to only buckets whose file paths contain these substrings. Example: 'components' to process only files in components directories"
 ).option(
   "--frozen",
-  `Run in read-only mode - fails if any translations need updating, useful for CI/CD pipelines to detect missing translations`
+  "Validate translations are up-to-date without making changes - fails if source files, target files, or lockfile are out of sync. Ideal for CI/CD to ensure translation consistency before deployment"
 ).option(
   "--force",
-  "Ignore lockfile and process all keys, useful for full re-translation"
+  "Force re-translation of all keys, bypassing change detection. Useful when you want to regenerate translations with updated AI models or translation settings"
 ).option(
   "--verbose",
-  "Show detailed output including intermediate processing data and API communication details"
+  "Print the translation data being processed as formatted JSON for each bucket and locale"
 ).option(
   "--interactive",
-  "Enable interactive mode for reviewing and editing translations before they are applied"
+  "Review and edit AI-generated translations interactively before applying changes to files"
 ).option(
   "--api-key <api-key>",
-  "Explicitly set the API key to use, override the default API key from settings"
+  "Override API key from settings or environment variables"
 ).option(
   "--debug",
-  "Pause execution at start for debugging purposes, waits for user confirmation before proceeding"
+  "Pause before processing localization so you can attach a debugger"
 ).option(
   "--strict",
-  "Stop processing on first error instead of continuing with other locales/buckets"
+  "Stop immediately on first error instead of continuing to process remaining buckets and locales (fail-fast mode)"
 ).action(async function(options) {
   updateGitignore();
   const ora = Ora7();
@@ -8514,7 +8547,12 @@ var LockfileSchema = Z4.object({
 
 // src/cli/cmd/lockfile.ts
 import { resolveOverriddenLocale as resolveOverriddenLocale4 } from "@lingo.dev/_spec";
-var lockfile_default = new Command13().command("lockfile").description("Create a lockfile if it does not exist").helpOption("-h, --help", "Show help").option("-f, --force", "Force create a lockfile").action(async (options) => {
+var lockfile_default = new Command13().command("lockfile").description(
+  "Generate or refresh i18n.lock based on the current source locale content"
+).helpOption("-h, --help", "Show help").option(
+  "-f, --force",
+  "Overwrite existing lockfile to reset translation tracking"
+).action(async (options) => {
   const flags = flagsSchema.parse(options);
   const ora = Ora8();
   const lockfileHelper = createLockfileHelper();
@@ -8559,10 +8597,19 @@ import { Command as Command14 } from "interactive-commander";
 import _33 from "lodash";
 import Ora9 from "ora";
 var cleanup_default = new Command14().command("cleanup").description(
-  "Remove keys from target files that do not exist in the source file"
-).helpOption("-h, --help", "Show help").option("--locale <locale>", "Specific locale to cleanup").option("--bucket <bucket>", "Specific bucket to cleanup").option("--dry-run", "Show what would be removed without making changes").option(
+  "Remove translation keys from target locales that no longer exist in the source locale"
+).helpOption("-h, --help", "Show help").option(
+  "--locale <locale>",
+  "Limit cleanup to a specific target locale from i18n.json. Defaults to all configured target locales"
+).option(
+  "--bucket <bucket>",
+  "Limit cleanup to a specific bucket type defined under `buckets` in i18n.json"
+).option(
+  "--dry-run",
+  "Preview which keys would be deleted without making any changes"
+).option(
   "--verbose",
-  "Show detailed output including:\n  - List of keys that would be removed.\n  - Processing steps."
+  "Print detailed output showing the specific keys to be removed for each locale"
 ).action(async function(options) {
   const ora = Ora9();
   const results = [];
@@ -8683,7 +8730,9 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import Z6 from "zod";
 import { ReplexicaEngine } from "@lingo.dev/_sdk";
-var mcp_default = new Command15().command("mcp").description("Use Lingo.dev model context provider with your AI agent").helpOption("-h, --help", "Show help").action(async (_35, program) => {
+var mcp_default = new Command15().command("mcp").description(
+  "Start a Model Context Protocol (MCP) server for AI assistant integration"
+).helpOption("-h, --help", "Show help").action(async (_35, program) => {
   const apiKey = program.args[0];
   const settings = getSettings(apiKey);
   if (!settings.auth.apiKey) {
@@ -9671,48 +9720,45 @@ function playSound(type) {
     setTimeout(resolve, 3e3);
   });
 }
-var run_default = new Command16().command("run").description("Run Lingo.dev localization engine").helpOption("-h, --help", "Show help").option(
+var run_default = new Command16().command("run").description("Run localization pipeline").helpOption("-h, --help", "Show help").option(
   "--source-locale <source-locale>",
-  "Locale to use as source locale. Defaults to i18n.json locale.source"
+  "Override the source locale from i18n.json for this run"
 ).option(
   "--target-locale <target-locale>",
-  "Locale to use as target locale. Defaults to i18n.json locale.targets",
+  "Limit processing to the listed target locale codes from i18n.json. Repeat the flag to include multiple locales. Defaults to all configured target locales",
   (val, prev) => prev ? [...prev, val] : [val]
 ).option(
   "--bucket <bucket>",
-  "Bucket to process",
+  "Limit processing to specific bucket types defined in i18n.json (e.g., json, yaml, android). Repeat the flag to include multiple bucket types. Defaults to all configured buckets",
   (val, prev) => prev ? [...prev, val] : [val]
 ).option(
   "--file <file>",
-  "File to process. Process only files that match this glob pattern in their path. Use quotes around patterns to prevent shell expansion (e.g., --file '**/*.json'). Useful if you have a lot of files and want to focus on a specific one. Specify more files separated by commas or spaces. Accepts glob patterns.",
+  "Filter bucket path pattern values by substring match. Examples: messages.json or locale/. Repeat to add multiple filters",
   (val, prev) => prev ? [...prev, val] : [val]
 ).option(
   "--key <key>",
-  "Key to process. Process only a specific translation key, useful for updating a single entry. Accepts glob patterns.",
+  "Filter keys by prefix matching on dot-separated paths. Example: auth.login to match all keys starting with auth.login. Repeat for multiple patterns",
   (val, prev) => prev ? [...prev, val] : [val]
 ).option(
   "--force",
-  "Ignore lockfile and process all keys, useful for full re-translation"
+  "Force re-translation of all keys, bypassing change detection. Useful when you want to regenerate translations with updated AI models or translation settings"
 ).option(
   "--api-key <api-key>",
-  "Explicitly set the API key to use, override the default API key from settings"
-).option(
-  "--debug",
-  "Pause execution at start for debugging purposes, waits for user confirmation before proceeding"
-).option(
+  "Override API key from settings or environment variables"
+).option("--debug", "Pause before processing to allow attaching a debugger.").option(
   "--concurrency <concurrency>",
-  "Number of concurrent tasks to run",
+  "Number of translation jobs to run concurrently. Higher values can speed up large translation batches but may increase memory usage. Defaults to 10 (maximum 10)",
   (val) => parseInt(val)
 ).option(
   "--watch",
-  "Watch source files for changes and automatically retranslate"
+  "Watch source locale files continuously and retranslate automatically when files change"
 ).option(
   "--debounce <milliseconds>",
-  "Debounce delay in milliseconds for watch mode (default: 5000ms)",
+  "Delay in milliseconds after file changes before retranslating in watch mode. Defaults to 5000",
   (val) => parseInt(val)
 ).option(
   "--sound",
-  "Play sound on completion, partially completion and failed of the task"
+  "Play audio feedback when translations complete (success or failure sounds)"
 ).action(async (args) => {
   let authId = null;
   try {
@@ -10417,13 +10463,29 @@ var getPlatformKit = () => {
 };
 
 // src/cli/cmd/ci/index.ts
-var ci_default = new Command17().command("ci").description("Run Lingo.dev CI/CD action").helpOption("-h, --help", "Show help").option("--parallel [boolean]", "Run in parallel mode", parseBooleanArg).option("--api-key <key>", "API key").option(
+var ci_default = new Command17().command("ci").description("Run localization pipeline in CI/CD environment").helpOption("-h, --help", "Show help").option(
+  "--parallel [boolean]",
+  "Process translations concurrently for faster execution. Defaults to false",
+  parseBooleanArg
+).option(
+  "--api-key <key>",
+  "Override API key from settings or environment variables"
+).option(
   "--pull-request [boolean]",
-  "Create a pull request with the changes",
+  "Create or update translations on a dedicated branch and manage pull requests automatically. When false, commits directly to current branch. Defaults to false",
   parseBooleanArg
-).option("--commit-message <message>", "Commit message").option("--pull-request-title <title>", "Pull request title").option("--working-directory <dir>", "Working directory").option(
+).option(
+  "--commit-message <message>",
+  "Commit message for localization changes. Defaults to 'feat: update translations via @lingodotdev'"
+).option(
+  "--pull-request-title <title>",
+  "Title for the pull request when using --pull-request mode. Defaults to 'feat: update translations via @lingodotdev'"
+).option(
+  "--working-directory <dir>",
+  "Directory to run localization from (useful for monorepos where localization files are in a subdirectory)"
+).option(
   "--process-own-commits [boolean]",
-  "Process commits made by this action",
+  "Allow processing commits made by this CI user (bypasses infinite loop prevention)",
   parseBooleanArg
 ).action(async (options) => {
   const settings = getSettings(options.apiKey);
@@ -10531,21 +10593,24 @@ function checkForPendingOperations() {
 // src/cli/cmd/status.ts
 var status_default = new Command18().command("status").description("Show the status of the localization process").helpOption("-h, --help", "Show help").option(
   "--locale <locale>",
-  "Locale to process",
+  "Limit the report to specific target locales from i18n.json. Repeat the flag to include multiple locales. Defaults to all configured target locales",
   (val, prev) => prev ? [...prev, val] : [val]
 ).option(
   "--bucket <bucket>",
-  "Bucket to process",
+  "Limit the report to specific bucket types defined in i18n.json (e.g., json, yaml, android). Repeat the flag to include multiple bucket types. Defaults to all buckets",
   (val, prev) => prev ? [...prev, val] : [val]
 ).option(
   "--file [files...]",
-  "File to process. Process only files that include this string in their path. Useful if you have a lot of files and want to focus on a specific one. Specify more files separated by commas or spaces."
+  "Filter the status report to only include files whose paths contain these substrings. Example: 'components' to match any file path containing 'components'"
 ).option(
   "--force",
-  "Ignore lockfile and process all keys, useful for estimating full re-translation"
-).option("--verbose", "Show detailed output including key-level word counts").option(
+  "Force all keys to be counted as needing translation, bypassing change detection. Shows word estimates for a complete retranslation regardless of current translation status"
+).option(
+  "--verbose",
+  "Print detailed output showing missing and updated key counts with example key names for each file and locale"
+).option(
   "--api-key <api-key>",
-  "Explicitly set the API key to use, override the default API key from settings"
+  "Override the API key from settings or environment variables for this run"
 ).action(async function(options) {
   const ora = Ora10();
   const flags = parseFlags2(options);
@@ -11109,7 +11174,7 @@ async function renderHero2() {
 // package.json
 var package_default = {
   name: "lingo.dev",
-  version: "0.111.8",
+  version: "0.111.10",
   description: "Lingo.dev CLI",
   private: false,
   publishConfig: {
@@ -11360,24 +11425,24 @@ import Ora11 from "ora";
 import { resolveOverriddenLocale as resolveOverriddenLocale8 } from "@lingo.dev/_spec";
 import { confirm as confirm3 } from "@inquirer/prompts";
 var purge_default = new Command20().command("purge").description(
-  "Remove translations for given --bucket, --file, --key, --locale"
+  "WARNING: Permanently delete translation entries from bucket path patterns defined in i18n.json. This is a destructive operation that cannot be undone. Without any filters, ALL managed keys will be removed from EVERY target locale."
 ).helpOption("-h, --help", "Show help").option(
   "--bucket <bucket>",
-  "Bucket to process",
+  "Limit the purge to specific bucket types defined under `buckets` in i18n.json. Repeat the flag to include multiple bucket types. Defaults to all buckets",
   (val, prev) => prev ? [...prev, val] : [val]
 ).option(
   "--file [files...]",
-  "File(s) to process. Only process files that match the given glob pattern(s)."
+  "Filter which file paths to purge by matching against path patterns. Only paths containing any of these values will be processed. Examples: --file messages.json --file admin/"
 ).option(
   "--key <key>",
-  "Key to remove. Remove all translation keys matching the given glob pattern."
+  "Filter which keys to delete using prefix matching on dot-separated key paths. Example: 'auth.login' matches all keys starting with auth.login. Omit this option to delete ALL keys. Keys marked as locked or ignored in i18n.json are automatically skipped"
 ).option(
   "--locale <locale>",
-  "Locale to process",
+  "Limit purging to specific target locale codes from i18n.json. Repeat the flag to include multiple locales. Defaults to all configured target locales. Warning: Including the source locale will delete content from it as well.",
   (val, prev) => prev ? [...prev, val] : [val]
 ).option(
   "--yes-really",
-  "Skip interactive confirmation and delete without asking."
+  "Bypass safety confirmations for destructive operations. Use with extreme caution - this will delete translation keys without asking for confirmation. Intended for automated scripts and CI environments only."
 ).action(async function(options) {
   const ora = Ora11();
   try {
@@ -11532,7 +11597,10 @@ ${vice3(
 
 Star the the repo :) https://github.com/LingoDotDev/lingo.dev
 `
-).version(`v${package_default.version}`, "-v, --version", "Show version").addCommand(init_default).interactive("-y, --no-interactive", "Disable interactive mode").addCommand(i18n_default).addCommand(auth_default).addCommand(login_default).addCommand(logout_default).addCommand(show_default).addCommand(config_default2).addCommand(lockfile_default).addCommand(cleanup_default).addCommand(mcp_default).addCommand(ci_default).addCommand(status_default).addCommand(may_the_fourth_default, { hidden: true }).addCommand(run_default).addCommand(purge_default).exitOverride((err) => {
+).version(`v${package_default.version}`, "-v, --version", "Show version").addCommand(init_default).interactive(
+  "-y, --no-interactive",
+  "Run every command in non-interactive mode (no prompts); required when scripting"
+).addCommand(i18n_default).addCommand(auth_default).addCommand(login_default).addCommand(logout_default).addCommand(show_default).addCommand(config_default2).addCommand(lockfile_default).addCommand(cleanup_default).addCommand(mcp_default).addCommand(ci_default).addCommand(status_default).addCommand(may_the_fourth_default, { hidden: true }).addCommand(run_default).addCommand(purge_default).exitOverride((err) => {
   if (err.code === "commander.helpDisplayed" || err.code === "commander.version" || err.code === "commander.help") {
     process.exit(0);
   }