langctl 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 0.5.0 — 2026-10-09
+
+Fixes from a real Hindi rollout of a 3,000-key, three-app project.
+
+### Fixed
+- `translate` no longer fails a whole run when the provider can't translate a few strings
+  (`{h}h`, `98860 41022`, `+ {name}`): those are reported per key with their source text, everything
+  else is saved, and the command exits **8** (new: "partial — some strings need a human
+  translation"). Strings with nothing to translate are copied unchanged.
+- `translate`: API/provider failures exit 5 (network, 5xx) or 1 — never 2, which means invalid usage.
+- `translate`: with stdout piped, the summary and failures go to stderr instead of being lost among
+  the per-key lines.
+- `push` printed absolute input paths relative to the cwd (`../../../../var/…`); paths are printed as given.
+
+### Added
+- `translate`: progress counter (`Translating 312/889…`; a line about every 10% in CI), 100 strings
+  per request with 3 requests in flight, summary `Translated N, copied M unchanged, failed K`;
+  `--json` includes `failed` and `counts`. On servers that save AI translations themselves the CLI
+  no longer saves each key separately; on older servers it saves them 6 at a time.
+- `review -m/--module`.
+- Key prefixes for several apps in one project: `pull --strip-prefix <p>`, `push --prefix <p>`, or
+  `"prefix"` in `langctl.json` (both directions). Keys without the prefix are skipped on pull and counted.
+- `push --descriptions <file.json>` (flat `{ "key": "description" }`) and rich JSON input
+  (`{ "key": { "value", "description" } }`) for `push`/`import`.
+- Named profiles: `--profile <name>` / `LANGCTL_PROFILE` (`~/.langctl/profiles/<name>.json`);
+  the default profile is still `~/.langctl/config.json`. `whoami` and `config` show the profile.
+- Notice when a newer langctl is published (checked at most once a day, ≤1.5s, off in CI/`--json`/`--quiet`;
+  `LANGCTL_UPDATE_CHECK=0|1`). When the API doesn't know a path the CLI uses (404 route / 410), the
+  error says to upgrade.
+- README: API key format, how review state is set (AI vs. human), exit code 8.
+
+### Changed
+- `auth` asks before replacing a stored key that belongs to a different organization, and refuses
+  without `--yes` when not interactive (suggesting a profile instead).
+- `pull` always says when AI drafts were held back — also with `--json` (on stderr) unless `--quiet` —
+  and shows a language that is empty only because of drafts as `0 strings: N awaiting review`.
+
+## 0.4.0 — 2026-10-08
+
+### Added
+- `langctl translate [project]`: fill missing translations with AI (DeepL) from the default language. `--to`, `--keys`, `--module`, `--overwrite`, `--dry-run` (uses no quota). Placeholders such as `{{name}}`, `{count}`, `%1$s` are preserved.
+- `langctl review [project]`: list AI translations awaiting review; `--approve` (narrow with `--keys` / `--languages`).
+- `pull --include-unreviewed`.
+- `pull` caches exports by ETag in `~/.langctl/cache`: when nothing changed on the server, the API answers `304 Not Modified` and the saved snapshot is reused. Set `LANGCTL_NO_CACHE=1` to disable. In CI, cache `~/.langctl/cache` (e.g. `actions/cache`) to benefit across runs.
+
+### Changed
+- `pull` leaves out AI translations nobody has reviewed yet (your app falls back to the default language for them) and warns how many were held back.
+
 ## 0.3.0 — 2026-10-08
 
 A rewrite focused on reliability in real projects and CI.

package/README.md

@@ -36,6 +36,7 @@ npx langctl --help
 ## Quick start
 
 1. Create an API key at **[app.langctl.com → API Keys](https://app.langctl.com/organization/api-keys)** (it is shown only once).
+   Langctl API keys look like `lc_` followed by 64 hexadecimal characters (`lc_3f9a…`, 67 characters in total).
 2. In your repository:
 
    ```bash
@@ -106,6 +107,7 @@ is enough for `pull`.
 | `sourceLanguage` | Language `push` uploads by default (default: the project's default language). |
 | `includeDrafts` | Pull unpublished keys too (default `false`). |
 | `module` | Only pull/push keys in this module. |
+| `prefix` | Key prefix for projects shared by several apps, e.g. `"dashboard."`: `pull` keeps only keys with it and writes them without it; `push` adds it. See [Key prefixes](#key-prefixes-several-apps-in-one-project). |
 
 Command-line flags override the file; `langctl` looks for `langctl.json` in the current directory and its parents.
 
@@ -124,17 +126,102 @@ platform, and literal `%` is escaped where needed. Output is sorted and has no t
 pull only changes files when translations change. If two keys map to the same Android/ARB name,
 the pull fails and names both keys instead of silently dropping one.
 
+## Review state: AI vs. human translations
+
+Every translation is either *reviewed* (written or approved by a person) or an *unreviewed AI draft*:
+
+| How the text got there | State | Shipped by `pull`? |
+| --- | --- | --- |
+| `langctl translate` (DeepL) | AI draft, unreviewed | No — held back until approved or edited |
+| `langctl push` / `import` (new keys, or changed text with `--overwrite`) | Human, reviewed | Yes |
+| Edited in the web app, or `keys update` / `keys translate` | Human, reviewed | Yes |
+| `langctl review --approve`, or *Approve* in the web app | Reviewed | Yes |
+
+An AI draft stops being a draft as soon as its text differs from what the AI produced, however it
+was changed. So translating with AI, fixing strings in your file, and running
+`push -l hi --overwrite` marks the corrected strings as reviewed. Strings you push back *unchanged*
+are skipped by the import and stay drafts — approve those with `langctl review --approve`. `pull` tells you how many drafts it
+held back (also with `--json`, on stderr); a language that comes back empty because everything is
+still a draft is shown as `0 strings: N awaiting review`. Ship drafts anyway with `--include-unreviewed`.
+
+## AI translation (`translate`)
+
+```console
+$ langctl translate -t hi -m mobile
+Translating 312/889…
+✖ Translated 880, copied 7 unchanged, failed 2 (hi; 2211/50000 AI translations used this month).
+Needs a human translation:
+  hi  mobile.onboarding.duration.hours  "{h}h"  (empty_result)
+```
+
+- Strings go up 100 per request, a few requests at a time. A progress counter is shown at a
+  terminal; in CI and pipes a progress line is printed about every 10%.
+- Strings with nothing to translate (`98860 41022`, `+ {name}`) are copied unchanged.
+- A string the provider can't translate never fails the rest: it is listed (with its source text)
+  and the command exits **8**. Add it by hand and re-run — only missing strings are translated.
+- Per-key lines go to stdout; the summary and failures go to stderr, so they aren't lost when you
+  redirect stdout. With `--json` the result has `translated`, `failed` (key, language, source text,
+  reason) and `counts`.
+- Key descriptions help reviewers; set them in bulk with `push --descriptions` (below).
+
+## Key prefixes (several apps in one project)
+
+Keys are unique per project. When several apps share a project and need the same key name
+(`common.save`), store them with a prefix — `dashboard.common.save`, `web.common.save` — and let
+langctl add and strip it:
+
+```bash
+langctl pull --strip-prefix dashboard     # only dashboard.* keys, written as common.save, …
+langctl push --prefix dashboard           # common.save is uploaded as dashboard.common.save
+```
+
+Or put `"prefix": "dashboard."` in that app's `langctl.json` and both directions use it. A prefix
+without a trailing separator (`.`, `_`, `-`, `:`, `/`) gets a `.` appended. On pull, keys without
+the prefix are skipped and counted in a warning. `translate --keys` and `review --keys` accept key
+names with or without the configured prefix; `keys get/update/delete/…` take the full stored name.
+
+## Descriptions
+
+Descriptions give translators (and reviewers) context. Set them in bulk when pushing:
+
+```bash
+langctl push --descriptions i18n/descriptions.json --overwrite
+```
+
+`descriptions.json` is flat: `{ "common.book": "Verb: book an appointment" }`. Only keys present
+in both files get a description; unmatched entries are reported. New keys always get their
+description; for keys that already exist pass `--overwrite` (the server decides whether an existing
+description is replaced). A flat JSON input file may also carry descriptions inline:
+`{ "common.book": { "value": "Book", "description": "Verb" } }` (`push` and `import`).
+
+## Profiles (several organizations)
+
+`langctl auth` stores one key per *profile*. The default profile is `~/.langctl/config.json`;
+named profiles live in `~/.langctl/profiles/<name>.json`:
+
+```bash
+echo "$CLIENT_B_KEY" | langctl auth --profile client-b --stdin
+langctl pull --profile client-b               # or: export LANGCTL_PROFILE=client-b
+langctl whoami                                # shows the profile in use
+```
+
+Storing a key for a *different* organization in a profile that already has one asks for
+confirmation; non-interactively it refuses unless you pass `--yes`. `LANGCTL_API_KEY` /
+`--api-key` still take precedence over any profile.
+
 ## Commands
 
 | Command | Description |
 | --- | --- |
 | `langctl init` | Set up a repo (auth if needed, write `langctl.json`). Flags: `--project --format --output --force`. |
-| `langctl pull [project]` | Download translations. `-l/--languages`, `-f/--format`, `-o/--output`, `-m/--module`, `--include-drafts`, `--check`, `--dry-run`, `--require-complete`. |
-| `langctl push [project]` | Upload files. Default: source language only; `-l all` for every language. `--overwrite`, `--publish`, `--dry-run`, `-i/--input`. |
+| `langctl pull [project]` | Download translations. `-l/--languages`, `-f/--format`, `-o/--output`, `-m/--module`, `--include-drafts`, `--include-unreviewed`, `--check`, `--dry-run`, `--require-complete`, `--strip-prefix <p>`. AI translations nobody has reviewed are left out (with a notice) until approved. |
+| `langctl push [project]` | Upload files. Default: source language only; `-l all` for every language. `--overwrite`, `--publish`, `--dry-run`, `-i/--input`, `--prefix <p>`, `--descriptions <file>`. Pushed text counts as reviewed. |
 | `langctl export [project]` | One-off export: `-l es -f android -o strings.xml`. |
 | `langctl import [project] <file>` | One-off import of a single file: `-l es`, `--overwrite`, `--publish`, `--dry-run`. |
-| `langctl auth [--stdin]` | Store an API key in `~/.langctl/config.json` (mode 600). `echo "$KEY" \| langctl auth --stdin`. |
-| `langctl whoami` | Show org, key source, scopes and API latency. |
+| `langctl translate [project]` | Fill missing translations with AI (DeepL) from the default language. `-t/--to es,fr`, `-k/--keys`, `-m/--module`, `--overwrite`, `--dry-run` (no quota used). Placeholders like `{{name}}` are kept as-is; uses the plan's monthly AI translations, or the org's own DeepL key if one is saved. Exits 8 if some strings need a human. |
+| `langctl review [project]` | List AI translations awaiting review; `--approve` approves them (narrow with `-m/--module`, `-k/--keys`, `-l/--languages`; `--yes` in CI). Editing a translation in the web app also counts as reviewing it. |
+| `langctl auth [--stdin]` | Store an API key in `~/.langctl/config.json` (mode 600), or in a [profile](#profiles-several-organizations). `echo "$KEY" \| langctl auth --stdin`. Asks before replacing a key for a different organization. |
+| `langctl whoami` | Show org, key source, profile, scopes and API latency. |
 | `langctl logout` · `langctl config` · `langctl formats` | Remove the stored key · show effective config · list formats. |
 | `langctl projects list\|get\|create\|update\|delete\|add-language\|remove-language\|stats` | Manage projects. `stats` shows translation coverage per language. |
 | `langctl keys list\|get\|create\|update\|translate\|delete\|publish\|unpublish` | Manage keys, e.g. `keys create web home.title --value en="Welcome" --value es="Bienvenido" --publish`. |
@@ -142,7 +229,7 @@ the pull fails and names both keys instead of silently dropping one.
 | `langctl org info\|stats\|plan` | Organization details, usage and plan limits. |
 
 Global flags (any position): `--json` · `-q/--quiet` · `--verbose` (log HTTP requests) · `-y/--yes` ·
-`--api-key` · `--api-url` · `--timeout <seconds>` · `--no-color`. Run `langctl <command> --help` for details.
+`--api-key` · `--api-url` · `--profile <name>` · `--timeout <seconds>` · `--no-color`. Run `langctl <command> --help` for details.
 
 ## Configuration & environment
 
@@ -151,7 +238,10 @@ Global flags (any position): `--json` · `-q/--quiet` · `--verbose` (log HTTP r
 | `LANGCTL_API_KEY` | API key (takes precedence over the stored key). |
 | `LANGCTL_API_URL` | API base URL (default `https://api.langctl.com/api/v1`). |
 | `LANGCTL_TIMEOUT` | Request timeout in seconds (default 30). Idempotent requests are retried with backoff on network errors, 429 and 5xx. |
+| `LANGCTL_PROFILE` | Named credentials profile (`~/.langctl/profiles/<name>.json`); same as `--profile`. |
 | `LANGCTL_CONFIG_DIR` | Where the user config lives (default `~/.langctl`). |
+| `LANGCTL_UPDATE_CHECK` | `0` turns off the "new version available" notice; `1` enables it in CI / `--json` / `--quiet`, where it is otherwise off. It checks npm at most once a day and never delays a command by more than ~1.5s. |
+| `LANGCTL_NO_CACHE` | Set to `1` to disable the export cache (`~/.langctl/cache`). `pull` normally sends the last ETag and reuses the cached snapshot when the server answers 304 Not Modified. |
 | `NO_COLOR` / `CI` | Disable colors / force non-interactive mode. |
 | `NODE_EXTRA_CA_CERTS` | Trust a corporate proxy's CA. |
 
@@ -167,6 +257,11 @@ Global flags (any position): `--json` · `-q/--quiet` · `--verbose` (log HTTP r
 | 5 | Network error, timeout, or the API is unavailable |
 | 6 | Plan limit reached |
 | 7 | `pull --check`: files are out of date |
+| 8 | Partial: `translate` finished, but some strings could not be AI-translated and need a human (listed in the output) |
+
+Errors from the API or the AI provider are never reported as 2: they are 5 (network, timeout,
+5xx) or 1. If the API no longer knows a path this CLI uses (404 route / 410 Gone), the error says
+to upgrade: `npm i -g langctl@latest`.
 
 With `--json`, errors are also printed to stdout as `{"error": {"message", "exitCode", "hint"}}`.
 

package/dist/commands/auth.js

@@ -1,9 +1,9 @@
 import chalk from 'chalk';
-import { clearCredentials, configPath, maskApiKey, normalizeApiKey, readUserConfig, resolveApiUrl, resolveCredentials, writeUserConfig, } from '../core/config.js';
+import { activeProfile, clearCredentials, configPath, maskApiKey, normalizeApiKey, profileLabel, readUserConfig, resolveApiUrl, resolveCredentials, writeUserConfig, } from '../core/config.js';
 import { CliError, ExitCode, usageError } from '../core/errors.js';
 import { ApiClient, validateKey } from '../core/http.js';
 import { isInteractive, log, printJson, runtime, spinner } from '../core/output.js';
-import { password, readStdin } from '../core/prompts.js';
+import { confirm, password, readStdin } from '../core/prompts.js';
 /** Validate a key against the API and store it in the user config. Returns the organization. */
 export async function saveApiKey(rawKey) {
     const apiKey = normalizeApiKey(rawKey);
@@ -16,6 +16,8 @@ export async function saveApiKey(rawKey) {
             throw new CliError('This API key is invalid or has been revoked.', ExitCode.Auth, 'Create a new key at https://app.langctl.com/organization/api-keys.');
         }
         const org = await api.get(`/orgs/${info.organizationId}`);
+        spin.stop();
+        await guardOrgSwitch(readUserConfig(), org);
         writeUserConfig({ ...readUserConfig(), apiKey, organizationId: org.id, organizationName: org.name });
         return { ...org, scopes: info.scopes };
     }
@@ -23,6 +25,31 @@ export async function saveApiKey(rawKey) {
         spin.stop();
     }
 }
+/**
+ * Storing a key for a different organization would silently drop the old one (0.4 did exactly
+ * that). Ask first; --yes confirms; without a terminal, refuse and point at profiles.
+ */
+async function guardOrgSwitch(current, next) {
+    if (!current.apiKey || !current.organizationId || current.organizationId === next.id)
+        return;
+    const profile = profileLabel();
+    const was = current.organizationName ? `"${current.organizationName}"` : current.organizationId;
+    const where = activeProfile() ? `profile "${profile}"` : 'the default profile';
+    log.warn(`${where} holds a key for ${was}; this key belongs to a different organization ("${next.name}").`);
+    const suggestion = `To keep both, store the new key in its own profile: langctl auth --profile <name> --stdin (then use --profile <name> or LANGCTL_PROFILE=<name>).`;
+    let ok;
+    try {
+        ok = await confirm(`Replace the stored key for ${was} with one for "${next.name}"?`);
+    }
+    catch (err) {
+        if (err instanceof CliError) {
+            throw new CliError(`Refusing to replace the stored key for ${was} (${where}) with a key for "${next.name}" without confirmation.`, ExitCode.Usage, `Re-run with --yes to replace it. ${suggestion}`);
+        }
+        throw err;
+    }
+    if (!ok)
+        throw new CliError('Cancelled — the stored key was not changed.', ExitCode.Error, suggestion);
+}
 export async function authCommand(apiKeyArg, opts) {
     let key = apiKeyArg;
     if (opts.stdin) {
@@ -41,10 +68,10 @@ export async function authCommand(apiKeyArg, opts) {
     }
     const org = await saveApiKey(key);
     if (runtime.json) {
-        printJson({ authenticated: true, organization: { id: org.id, name: org.name, plan: org.plan }, scopes: org.scopes, configPath: configPath() });
+        printJson({ authenticated: true, organization: { id: org.id, name: org.name, plan: org.plan }, scopes: org.scopes, profile: profileLabel(), configPath: configPath() });
         return;
     }
-    log.success(`Authenticated to ${chalk.bold(org.name)} (${org.plan} plan)`);
+    log.success(`Authenticated to ${chalk.bold(org.name)} (${org.plan} plan)${activeProfile() ? ` — profile "${profileLabel()}"` : ''}`);
     log.info(chalk.dim(`Key saved to ${configPath()} (readable only by you). Scopes: ${org.scopes.join(', ')}`));
 }
 export function logoutCommand() {
@@ -59,7 +86,7 @@ export async function whoamiCommand() {
     const creds = resolveCredentials();
     if (!creds) {
         if (runtime.json)
-            printJson({ authenticated: false, apiUrl: resolveApiUrl() });
+            printJson({ authenticated: false, profile: profileLabel(), apiUrl: resolveApiUrl() });
         throw new CliError('Not authenticated.', ExitCode.Auth, 'Run "langctl auth --stdin", or set LANGCTL_API_KEY.');
     }
     const api = new ApiClient(creds);
@@ -75,6 +102,7 @@ export async function whoamiCommand() {
         organization: { id: org.id, name: org.name, slug: org.slug, plan: org.plan },
         key: maskApiKey(creds.apiKey),
         keySource: sourceLabel(creds.source),
+        profile: profileLabel(),
         scopes: info.scopes,
         apiUrl: creds.apiUrl,
         latencyMs: latency,
@@ -83,6 +111,7 @@ export async function whoamiCommand() {
         return printJson(data);
     log.out(`${chalk.bold(org.name)} ${chalk.dim(`(${org.slug}, ${org.plan} plan)`)}`);
     log.out(`  key      ${data.key}  ${chalk.dim(`from ${data.keySource}`)}`);
+    log.out(`  profile  ${data.profile}${creds.source !== 'config' ? chalk.dim(` (not used: key from ${data.keySource})`) : ''}`);
     log.out(`  scopes   ${info.scopes.join(', ')}`);
     log.out(`  api      ${creds.apiUrl}  ${chalk.dim(`${latency}ms`)}`);
 }

package/dist/commands/config.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { configPath, loadProjectConfig, maskApiKey, readUserConfig, resolveApiUrl, resolveCredentials } from '../core/config.js';
+import { configPath, loadProjectConfig, maskApiKey, profileLabel, readUserConfig, resolveApiUrl, resolveCredentials } from '../core/config.js';
 import { log, printJson, runtime } from '../core/output.js';
 import { FORMATS } from '../formats/index.js';
 /** Show effective configuration and where each value comes from (no network). */
@@ -12,6 +12,7 @@ export function configCommand() {
         apiKey: creds ? maskApiKey(creds.apiKey) : null,
         apiKeySource: creds ? (creds.source === 'env' ? 'LANGCTL_API_KEY' : creds.source === 'flag' ? '--api-key' : configPath()) : null,
         organization: user.organizationName ?? null,
+        profile: profileLabel(),
         userConfig: configPath(),
         projectConfig: project ? { path: project.path, ...project.config } : null,
     };
@@ -21,6 +22,7 @@ export function configCommand() {
     log.out(`api key       ${data.apiKey ?? chalk.yellow('not set')}${data.apiKeySource ? chalk.dim(`  (${data.apiKeySource})`) : ''}`);
     if (data.organization)
         log.out(`organization  ${data.organization}`);
+    log.out(`profile       ${data.profile}`);
     log.out(`user config   ${data.userConfig}`);
     if (project) {
         log.out(`project file  ${project.path}`);

package/dist/commands/import.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { relative, resolve } from 'path';
+import { resolve } from 'path';
 import { loadProjectConfig } from '../core/config.js';
 import { usageError } from '../core/errors.js';
 import { getSession } from '../core/http.js';
@@ -7,6 +7,7 @@ import { log, printJson, runtime, spinner } from '../core/output.js';
 import { assertLanguages, getProject, projectSlugFrom } from '../core/project.js';
 import { getFormat } from '../formats/index.js';
 import { readTranslationFile, uploadTranslations } from './push.js';
+import { displayPath } from './pull.js';
 /**
  * `langctl import [project] <file> --language <code>` — upload one file.
  * The project may be omitted when langctl.json names it.
@@ -20,9 +21,12 @@ export async function importCommand(first, second, opts) {
         log.info(chalk.dim(`No --language given; importing as ${language} (the project's default).`));
     assertLanguages(project, [language]);
     const path = resolve(file);
-    const translations = readTranslationFile(path, opts.format ? getFormat(opts.format) : undefined, language);
+    const parsed = readTranslationFile(path, opts.format ? getFormat(opts.format) : undefined, language, true);
+    // Rich JSON ({ "key": { "value", "description" } }) carries descriptions
+    const translations = Object.fromEntries(Object.entries(parsed.translations)
+        .map(([k, v]) => [k, parsed.descriptions[k] ? { value: v, description: parsed.descriptions[k] } : v]));
     if (Object.keys(translations).length === 0)
-        throw usageError(`${relative(process.cwd(), path)} contains no translations.`);
+        throw usageError(`${displayPath(path, file)} contains no translations.`);
     const spin = spinner(`${opts.dryRun ? 'Checking' : 'Importing'} ${Object.keys(translations).length} keys…`);
     let result;
     try {
@@ -32,7 +36,7 @@ export async function importCommand(first, second, opts) {
         spin.stop();
     }
     if (runtime.json)
-        return printJson({ project: project.slug, file: relative(process.cwd(), path), dryRun: Boolean(opts.dryRun), ...result });
+        return printJson({ project: project.slug, file: displayPath(path, file), dryRun: Boolean(opts.dryRun), ...result });
     log.out(`${language}  ${chalk.green(`${result.created} new`)}, ${chalk.yellow(`${result.updated} updated`)}, ${chalk.dim(`${result.unchanged} unchanged`)}${result.published !== undefined ? `, ${chalk.cyan(`${result.published} published`)}` : ''}${opts.dryRun ? chalk.dim('  (dry run)') : ''}`);
     if (!opts.overwrite && result.unchanged > 0)
         log.info(chalk.dim('Existing translations are kept unless you pass --overwrite.'));

package/dist/commands/pull.js

@@ -1,12 +1,18 @@
 import chalk from 'chalk';
-import { relative, resolve } from 'path';
-import { loadProjectConfig } from '../core/config.js';
+import { isAbsolute, relative, resolve } from 'path';
+import { loadProjectConfig, resolvePrefix } from '../core/config.js';
 import { CliError, ExitCode, usageError } from '../core/errors.js';
 import { syncFile } from '../core/files.js';
 import { getSession } from '../core/http.js';
 import { log, printJson, runtime, spinner } from '../core/output.js';
 import { assertLanguages, getProject, projectSlugFrom } from '../core/project.js';
 import { expandTemplate, getFormat, templateHasLanguage } from '../formats/index.js';
+/** Show a path the way the user gave it: absolute stays absolute, otherwise relative to the cwd. */
+export function displayPath(path, asGiven) {
+    if (asGiven && isAbsolute(asGiven))
+        return path;
+    return relative(process.cwd(), path) || path;
+}
 export async function pullCommand(projectArg, opts) {
     const loaded = loadProjectConfig();
     const cfg = loaded?.config ?? {};
@@ -24,16 +30,20 @@ export async function pullCommand(projectArg, opts) {
         template = resolve(format.defaultOutput);
     const includeDrafts = Boolean(opts.includeDrafts || opts.publishedOnly === false || cfg.includeDrafts);
     const module = opts.module ?? cfg.module;
+    const prefix = resolvePrefix(opts.stripPrefix, cfg);
     const dryRun = Boolean(opts.check || opts.dryRun);
+    const show = (p) => displayPath(p, opts.output ?? opts.dir);
     const session = await getSession();
     const spin = spinner(`Fetching ${slug}…`);
     let project, snapshot;
     try {
         project = await getProject(session, slug);
-        snapshot = await session.api.get(`/orgs/${session.orgId}/projects/${project.id}/export`, {
+        // ETag-cached: unchanged translations come back as a tiny 304 and the saved snapshot is reused
+        ({ data: snapshot } = await session.api.getCached(`/orgs/${session.orgId}/projects/${project.id}/export`, {
             publishedOnly: includeDrafts ? 'false' : 'true',
+            includeUnreviewed: opts.includeUnreviewed ? 'true' : undefined,
             module,
-        });
+        }));
     }
     finally {
         spin.stop();
@@ -41,16 +51,23 @@ export async function pullCommand(projectArg, opts) {
     const languages = opts.languages ? splitList(opts.languages) : (cfg.languages ?? project.languages);
     assertLanguages(project, languages);
     if (languages.length > 1 && !templateHasLanguage(template)) {
-        throw usageError(`Output "${relative(process.cwd(), template)}" has no {lang} placeholder, so ${languages.length} languages would overwrite each other.`, 'Use a template like "locales/{lang}.json", or pick one language with --languages.');
+        throw usageError(`Output "${show(template)}" has no {lang} placeholder, so ${languages.length} languages would overwrite each other.`, 'Use a template like "locales/{lang}.json", or pick one language with --languages.');
     }
+    // Prefix (multi-app projects): keep only "dashboard.*" keys and write them as "*"
+    const keys = prefix
+        ? snapshot.keys.filter(k => k.key.startsWith(prefix) && k.key.length > prefix.length).map(k => ({ ...k, key: k.key.slice(prefix.length) }))
+        : snapshot.keys;
+    const prefixSkipped = snapshot.keys.length - keys.length;
+    const unreviewed = snapshot.metadata?.unreviewedSkipped ?? 0;
+    const unreviewedByLanguage = snapshot.metadata?.unreviewedByLanguage;
     const files = [];
     for (const lang of languages) {
-        const entries = snapshot.keys
+        const entries = keys
             .filter(k => typeof k.translations[lang] === 'string' && k.translations[lang] !== '')
             .map(k => ({ key: k.key, value: k.translations[lang], description: k.description }));
         const path = expandTemplate(template, lang, project.defaultLanguage);
         const status = syncFile(path, format.serialize(entries, lang), dryRun, text => format.parse(text, lang));
-        files.push({ path, language: lang, status, keys: entries.length, translated: entries.length, total: snapshot.keys.length });
+        files.push({ path, language: lang, status, keys: entries.length, translated: entries.length, total: keys.length });
     }
     const changed = files.filter(f => f.status !== 'unchanged');
     const incomplete = files.filter(f => f.translated < f.total);
@@ -59,24 +76,43 @@ export async function pullCommand(projectArg, opts) {
             project: project.slug,
             format: format.id,
             publishedOnly: !includeDrafts,
-            keys: snapshot.keys.length,
+            keys: keys.length,
             dryRun,
-            files: files.map(f => ({ ...f, path: relative(process.cwd(), f.path) })),
+            files: files.map(f => ({ ...f, path: show(f.path) })),
             changed: changed.length,
+            unreviewedSkipped: unreviewed,
+            ...(unreviewedByLanguage ? { unreviewedByLanguage } : {}),
+            ...(prefix ? { prefix, prefixSkipped } : {}),
         });
     }
     else {
         for (const f of files) {
             const icon = f.status === 'unchanged' ? chalk.dim('=') : f.status === 'created' ? chalk.green('+') : chalk.yellow('~');
             const verb = dryRun && f.status !== 'unchanged' ? `would be ${f.status}` : f.status;
-            const coverage = f.translated < f.total ? chalk.yellow(` ${f.translated}/${f.total} translated`) : '';
-            log.out(`${icon} ${relative(process.cwd(), f.path)}  ${chalk.dim(verb)}${coverage}`);
+            let coverage = f.translated < f.total ? chalk.yellow(` ${f.translated}/${f.total} translated`) : '';
+            // An empty language with held-back AI drafts is "awaiting review", not "nothing translated"
+            const waiting = unreviewedByLanguage ? unreviewedByLanguage[f.language] ?? 0 : unreviewed;
+            if (f.translated === 0 && f.total > 0 && waiting > 0 && f.language !== project.defaultLanguage) {
+                // Without a per-language breakdown (or with a prefix) the count may include other languages/keys
+                const approx = prefix || (!unreviewedByLanguage && languages.filter(l => l !== project.defaultLanguage).length > 1) ? 'up to ' : '';
+                coverage = chalk.yellow(` 0 strings: ${approx}${waiting} awaiting review (use langctl review / --include-unreviewed)`);
+            }
+            log.out(`${icon} ${show(f.path)}  ${chalk.dim(verb)}${coverage}`);
         }
-        log.info(chalk.dim(`${project.slug}: ${snapshot.keys.length} ${includeDrafts ? '' : 'published '}keys, ${languages.length} language(s), format ${format.id}`));
+        log.info(chalk.dim(`${project.slug}: ${keys.length} ${includeDrafts ? '' : 'published '}keys${prefix ? ` with prefix "${prefix}"` : ''}, ${languages.length} language(s), format ${format.id}`));
         if (snapshot.keys.length === 0 && !includeDrafts) {
             log.warn('No published keys — drafts are excluded by default. Publish keys, or pass --include-drafts.');
         }
     }
+    // Notices go to stderr in every mode (also --json), so a held-back draft is never mistaken for "not translated"
+    if (!runtime.quiet) {
+        if (unreviewed > 0) {
+            log.warn(`${unreviewed} AI translation(s) awaiting review were left out (your app falls back to ${project.defaultLanguage} for them). Review with "langctl review ${project.slug}", or pass --include-unreviewed.`);
+        }
+        if (prefixSkipped > 0) {
+            log.warn(`${prefixSkipped} key(s) without the prefix "${prefix}" were skipped.`);
+        }
+    }
     if (opts.requireComplete && incomplete.length) {
         throw new CliError(`Missing translations: ${incomplete.map(f => `${f.language} (${f.total - f.translated} missing)`).join(', ')}`, ExitCode.Error);
     }

package/dist/commands/push.js

@@ -1,13 +1,13 @@
 import chalk from 'chalk';
 import { existsSync, readFileSync } from 'fs';
 import { relative, resolve } from 'path';
-import { loadProjectConfig } from '../core/config.js';
+import { loadProjectConfig, resolvePrefix } from '../core/config.js';
 import { notFoundError, usageError } from '../core/errors.js';
 import { getSession } from '../core/http.js';
 import { log, printJson, runtime, spinner } from '../core/output.js';
 import { assertLanguages, getProject, projectSlugFrom } from '../core/project.js';
-import { expandTemplate, formatFromPath, getFormat, templateHasLanguage } from '../formats/index.js';
-import { splitList } from './pull.js';
+import { expandTemplate, formatFromPath, getFormat, parseRichJson, templateHasLanguage } from '../formats/index.js';
+import { displayPath, splitList } from './pull.js';
 const CHUNK = 1000; // stay well under the API's 1 MB request body limit
 /** Upload one language's translations. Shared by `push` and the single-file `import`. */
 export async function uploadTranslations(session, project, language, translations, opts) {
@@ -20,7 +20,8 @@ export async function uploadTranslations(session, project, language, translation
         const snap = await session.api.get(`/orgs/${session.orgId}/projects/${project.id}/export`, { language, publishedOnly: 'false' });
         const all = await session.api.get(`/orgs/${session.orgId}/projects/${project.id}/export`, { publishedOnly: 'false' });
         const existingKeys = new Set(all.keys.map(k => k.key));
-        for (const [key, value] of entries) {
+        for (const [key, raw] of entries) {
+            const value = typeof raw === 'string' ? raw : raw.value;
             if (!existingKeys.has(key))
                 result.created++;
             else if (snap.translations[key] === value)
@@ -51,11 +52,19 @@ export async function uploadTranslations(session, project, language, translation
     }
     return result;
 }
-export function readTranslationFile(path, format, lang) {
+export function readTranslationFile(path, format, lang, withDescriptions = false) {
     if (!existsSync(path))
         throw notFoundError(`File not found: ${relative(process.cwd(), path) || path}`);
     const fmt = format ?? formatFromPath(path);
-    const translations = fmt.parse(readFileSync(path, 'utf-8'), lang);
+    const content = readFileSync(path, 'utf-8');
+    if (fmt.id === 'json') {
+        const rich = parseRichJson(content);
+        if (rich)
+            return withDescriptions ? rich : rich.translations;
+    }
+    const translations = fmt.parse(content, lang);
+    if (withDescriptions)
+        return { translations, descriptions: {} };
     if ((fmt.id === 'android' || fmt.id === 'ios') && Object.values(translations).some(v => /\{\{\d+\}\}/.test(v))) {
         log.warn(`${relative(process.cwd(), path)}: positional placeholders (%1$s / %1$@) were imported as {{1}}, {{2}}… — named placeholders can't be recovered from ${fmt.id} files.`);
     }
@@ -66,6 +75,9 @@ export async function pushCommand(projectArg, opts) {
     const cfg = loaded?.config ?? {};
     const slug = projectSlugFrom(projectArg);
     const format = opts.format || cfg.format ? getFormat(opts.format ?? cfg.format) : undefined;
+    const prefix = resolvePrefix(opts.prefix, cfg);
+    const descriptionsFile = opts.descriptions ? readDescriptions(resolve(opts.descriptions), opts.descriptions) : undefined;
+    const show = (p) => displayPath(p, opts.input);
     let template;
     if (opts.input)
         template = resolve(opts.input);
@@ -89,28 +101,54 @@ export async function pushCommand(projectArg, opts) {
             : [cfg.sourceLanguage ?? project.defaultLanguage];
     assertLanguages(project, languages);
     if (languages.length > 1 && !templateHasLanguage(template)) {
-        throw usageError(`Input "${relative(process.cwd(), template)}" has no {lang} placeholder but ${languages.length} languages were requested.`);
+        throw usageError(`Input "${show(template)}" has no {lang} placeholder but ${languages.length} languages were requested.`);
     }
     const results = [];
+    let described = 0;
+    const unmatchedDescriptions = new Set(Object.keys(descriptionsFile ?? {}));
     for (const lang of languages) {
         const path = expandTemplate(template, lang, project.defaultLanguage);
         if (!existsSync(path)) {
             if (explicit)
-                throw notFoundError(`File not found for ${lang}: ${relative(process.cwd(), path)}`);
-            throw notFoundError(`Source file not found: ${relative(process.cwd(), path)}`, 'Run "langctl pull" first, or set "output" in langctl.json / pass --input.');
+                throw notFoundError(`File not found for ${lang}: ${show(path)}`);
+            throw notFoundError(`Source file not found: ${show(path)}`, 'Run "langctl pull" first, or set "output" in langctl.json / pass --input.');
+        }
+        const file = readTranslationFile(path, format, lang, true);
+        const descriptions = { ...file.descriptions, ...(descriptionsFile ?? {}) };
+        // Keys go up with the prefix; descriptions may name keys with or without it
+        const values = {};
+        for (const [key, value] of Object.entries(file.translations)) {
+            const full = prefix ? prefix + key : key; // always added: pull strips exactly one prefix
+            const description = descriptions[key] ?? (prefix ? descriptions[full] : undefined);
+            if (descriptionsFile) {
+                unmatchedDescriptions.delete(key);
+                unmatchedDescriptions.delete(full);
+            }
+            if (description !== undefined && description.trim()) {
+                values[full] = { value, description };
+                described++;
+            }
+            else {
+                values[full] = value;
+            }
         }
-        const translations = readTranslationFile(path, format, lang);
-        const s = spinner(`${opts.dryRun ? 'Checking' : 'Uploading'} ${lang} (${Object.keys(translations).length} keys)…`);
+        const s = spinner(`${opts.dryRun ? 'Checking' : 'Uploading'} ${lang} (${Object.keys(values).length} keys)…`);
         try {
-            const r = await uploadTranslations(session, project, lang, translations, { ...opts, module: opts.module ?? cfg.module });
-            results.push({ ...r, file: relative(process.cwd(), path) });
+            const r = await uploadTranslations(session, project, lang, values, { ...opts, module: opts.module ?? cfg.module });
+            results.push({ ...r, file: show(path) });
         }
         finally {
             s.stop();
         }
     }
+    if (unmatchedDescriptions.size && !runtime.quiet) {
+        log.warn(`${unmatchedDescriptions.size} description(s) in ${opts.descriptions} match no key in the pushed file(s) and were ignored.`);
+    }
+    if (described && !opts.overwrite && !runtime.quiet) {
+        log.warn(`Descriptions are stored for new keys; for keys that already exist pass --overwrite (see "Descriptions" in the README).`);
+    }
     if (runtime.json) {
-        printJson({ project: project.slug, dryRun: Boolean(opts.dryRun), overwrite: Boolean(opts.overwrite), results });
+        printJson({ project: project.slug, dryRun: Boolean(opts.dryRun), overwrite: Boolean(opts.overwrite), ...(prefix ? { prefix } : {}), descriptions: described, results });
         return;
     }
     for (const r of results) {
@@ -123,3 +161,23 @@ export async function pushCommand(projectArg, opts) {
         log.info(chalk.dim('Existing translations are never overwritten unless you pass --overwrite.'));
     }
 }
+/** A flat { "key": "description" } JSON file for `push --descriptions`. */
+export function readDescriptions(path, asGiven) {
+    if (!existsSync(path))
+        throw notFoundError(`Descriptions file not found: ${displayPath(path, asGiven)}`);
+    let data;
+    try {
+        data = JSON.parse(readFileSync(path, 'utf-8').replace(/^\uFEFF/, ''));
+    }
+    catch (e) {
+        throw usageError(`${displayPath(path, asGiven)} is not valid JSON: ${e.message}`);
+    }
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+        throw usageError(`${displayPath(path, asGiven)} must be a flat JSON object: { "key": "description" }.`);
+    }
+    const bad = Object.entries(data).filter(([, v]) => typeof v !== 'string').map(([k]) => k);
+    if (bad.length) {
+        throw usageError(`Descriptions must be strings. Not strings: ${bad.slice(0, 5).join(', ')}${bad.length > 5 ? ` …and ${bad.length - 5} more` : ''}`);
+    }
+    return data;
+}