langctl 0.3.0 → 0.5.0

package/dist/commands/review.js

@@ -0,0 +1,75 @@
+import chalk from 'chalk';
+import { loadProjectConfig, resolvePrefix, withPrefix } from '../core/config.js';
+import { usageError } from '../core/errors.js';
+import { getSession } from '../core/http.js';
+import { log, printJson, runtime, spinner, table } from '../core/output.js';
+import { assertLanguages, getProject, listAllKeys, projectSlugFrom } from '../core/project.js';
+import { confirm } from '../core/prompts.js';
+const split = (v) => (v ? v.split(',').map(s => s.trim()).filter(Boolean) : undefined);
+/**
+ * List AI translations awaiting review, or approve them with --approve.
+ * Unreviewed AI translations are left out of `langctl pull` until approved (or edited) in langctl.
+ */
+export async function reviewCommand(projectArg, opts) {
+    const session = await getSession();
+    const project = await getProject(session, projectSlugFrom(projectArg));
+    const prefix = resolvePrefix(undefined, loadProjectConfig()?.config ?? {});
+    const languages = split(opts.languages);
+    if (languages)
+        assertLanguages(project, languages);
+    const spin = spinner('Fetching AI translations awaiting review…');
+    let list;
+    let inModule;
+    try {
+        list = await session.api.get(`/orgs/${session.orgId}/projects/${project.id}/review`, { module: opts.module });
+        // The review list may not carry modules (older API): resolve the module's keys separately
+        if (opts.module && !list.items.every(i => i.module !== undefined)) {
+            inModule = new Set((await listAllKeys(session, project, { module: opts.module })).map(k => k.id));
+        }
+    }
+    finally {
+        spin.stop();
+    }
+    // With "prefix" in langctl.json, --keys may name keys with or without it
+    const known = new Set(list.items.map(i => i.key));
+    const keys = split(opts.keys)?.map(k => withPrefix(k, prefix, known));
+    const items = list.items.filter(i => (!keys || keys.includes(i.key)) && (!languages || languages.includes(i.language))
+        && (!opts.module || (inModule ? inModule.has(i.keyId) : i.module === opts.module)));
+    if (keys) {
+        const unknown = keys.filter(k => !list.items.some(i => i.key === k));
+        if (unknown.length)
+            log.warn(`Nothing awaiting review for: ${unknown.join(', ')}`);
+    }
+    if (!opts.approve) {
+        if (runtime.json)
+            return printJson({ project: project.slug, total: items.length, items });
+        if (!items.length) {
+            log.success('No AI translations awaiting review.');
+            return;
+        }
+        table(items.map(i => [i.key, i.language, i.text.length > 60 ? `${i.text.slice(0, 57)}…` : i.text]), ['key', 'lang', 'AI translation']);
+        log.info(chalk.dim(`${items.length} awaiting review — left out of "langctl pull" until approved. Approve with "langctl review ${project.slug} --approve" (narrow with --module / --keys / --languages), or edit them in the web app.`));
+        return;
+    }
+    if (!items.length) {
+        if (runtime.json)
+            return printJson({ project: project.slug, approved: 0 });
+        log.success('Nothing to approve.');
+        return;
+    }
+    if (!(await confirm(`Approve ${items.length} AI translation(s) in ${project.slug}? They will ship on the next pull.`))) {
+        throw usageError('Cancelled.');
+    }
+    const keyIds = [...new Set(items.map(i => i.keyId))];
+    let approved = 0;
+    for (let i = 0; i < keyIds.length; i += 1000) {
+        const res = await session.api.post(`/orgs/${session.orgId}/projects/${project.id}/keys/review`, {
+            keyIds: keyIds.slice(i, i + 1000),
+            languages: languages ?? [...new Set(items.map(it => it.language))],
+        });
+        approved += res.approved;
+    }
+    if (runtime.json)
+        return printJson({ project: project.slug, approved });
+    log.success(`Approved ${approved} AI translation(s). They'll be included in the next "langctl pull".`);
+}

package/dist/commands/translate.js

@@ -0,0 +1,257 @@
+import chalk from 'chalk';
+import { loadProjectConfig, resolvePrefix, withPrefix } from '../core/config.js';
+import { CliError, ExitCode, usageError } from '../core/errors.js';
+import { getSession } from '../core/http.js';
+import { log, printJson, progress, runtime, spinner, table } from '../core/output.js';
+import { assertLanguages, getProject, listAllKeys, projectSlugFrom } from '../core/project.js';
+/** Strings per request (API maximum). Servers before API 2026-10 accept at most LEGACY_BATCH. */
+export const BATCH = 100;
+const LEGACY_BATCH = 50;
+/** Requests in flight at once */
+export const CONCURRENCY = 3;
+/** Per-key saves in flight at once on servers without `save: true` */
+export const SAVE_CONCURRENCY = 6;
+const isBlank = (v) => !v || !v.trim();
+/** Run `fn` over `items` with at most `limit` running at a time. */
+export async function pool(items, limit, fn) {
+    let i = 0;
+    const worker = async () => {
+        while (i < items.length)
+            await fn(items[i++]);
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+}
+/**
+ * Fill missing translations with AI (DeepL) from the project's default language.
+ * Counts against the plan's monthly AI translations unless the org uses its own DeepL key.
+ *
+ * Strings the provider can't translate are reported per key and never fail the rest: the
+ * command finishes, lists them, and exits 8 (partial) so CI can tell "needs a human" apart
+ * from usage (2) and network/API (5) errors.
+ */
+export async function translateCommand(projectArg, opts) {
+    const session = await getSession();
+    const project = await getProject(session, projectSlugFrom(projectArg));
+    const source = project.defaultLanguage;
+    const prefix = resolvePrefix(undefined, loadProjectConfig()?.config ?? {});
+    const targets = opts.to
+        ? opts.to.split(',').map(s => s.trim()).filter(Boolean)
+        : project.languages.filter(l => l !== source);
+    if (!targets.length)
+        throw usageError(`Project "${project.slug}" has no languages besides ${source}.`, `Add one with "langctl projects add-language ${project.slug} <code>".`);
+    assertLanguages(project, targets);
+    if (targets.includes(source))
+        throw usageError(`${source} is the source language and can't be a target.`);
+    const spin = spinner('Fetching keys…');
+    let keys;
+    try {
+        keys = await listAllKeys(session, project, { module: opts.module });
+    }
+    finally {
+        spin.stop();
+    }
+    if (opts.keys) {
+        const known = new Set(keys.map(k => k.key));
+        // With "prefix" in langctl.json, keys may be named with or without it
+        const wanted = new Set(opts.keys.split(',').map(s => s.trim()).filter(Boolean).map(k => withPrefix(k, prefix, known)));
+        const unknown = [...wanted].filter(k => !known.has(k));
+        if (unknown.length)
+            throw usageError(`Key${unknown.length > 1 ? 's' : ''} not found: ${unknown.join(', ')}`);
+        keys = keys.filter(k => wanted.has(k.key));
+    }
+    // Work list: per target language, keys with source text whose target is empty (or all, with --overwrite)
+    const plan = targets.map(lang => ({
+        lang,
+        keys: keys.filter(k => !isBlank(k.translations?.[source]) && (opts.overwrite || isBlank(k.translations?.[lang]))),
+    }));
+    const total = plan.reduce((n, p) => n + p.keys.length, 0);
+    const noSource = keys.filter(k => isBlank(k.translations?.[source])).length;
+    if (opts.dryRun || total === 0) {
+        if (runtime.json) {
+            return printJson({ dryRun: Boolean(opts.dryRun), source, languages: plan.map(p => ({ language: p.lang, keys: p.keys.map(k => k.key) })), total });
+        }
+        table(plan.map(p => [p.lang, String(p.keys.length)]), ['language', opts.overwrite ? 'keys to retranslate' : 'missing']);
+        if (noSource)
+            log.info(chalk.dim(`${noSource} key(s) have no ${source} text and are skipped.`));
+        if (total === 0)
+            log.success('Nothing to translate.');
+        else
+            log.info(`Dry run: ${total} translation(s) would use up to ${total} AI translation(s). Run without --dry-run to translate.`);
+        return;
+    }
+    const outcome = await runTranslation(session, project, source, plan, Boolean(opts.overwrite));
+    report(project, plan.filter(p => p.keys.length).map(p => p.lang), total, outcome);
+}
+export async function runTranslation(session, project, source, plan, overwrite) {
+    const total = plan.reduce((n, p) => n + p.keys.length, 0);
+    const out = { done: [], failed: [] };
+    let batchSize = BATCH;
+    const queue = plan.flatMap(({ lang, keys }) => chunk(keys, batchSize).map(k => ({ lang, keys: k })));
+    const bar = progress('Translating', total);
+    const tick = () => bar.update(out.done.length + out.failed.length);
+    const keyPath = (key, lang) => `/orgs/${session.orgId}/projects/${project.id}/keys/${key.id}/translations/${encodeURIComponent(lang)}`;
+    const succeed = (lang, key, text, copied) => {
+        out.done.push({ language: lang, key: key.key, text, ...(copied ? { copied: true } : {}) });
+        bar.out(`${chalk.dim(lang)}  ${key.key}  ${text}${copied ? chalk.dim('  (copied unchanged)') : ''}`);
+    };
+    const fail = (lang, key, error) => out.failed.push({ language: lang, key: key.key, sourceText: key.translations[source], error });
+    const runJob = async (job) => {
+        let res;
+        try {
+            res = await session.api.post(`/orgs/${session.orgId}/translate/bulk`, {
+                items: job.keys.map(k => ({ text: k.translations[source], keyId: k.id })),
+                sourceLang: source,
+                targetLang: job.lang,
+                projectId: project.id,
+                save: true,
+                overwrite,
+            });
+        }
+        catch (err) {
+            // Servers before the 100-item limit reject the batch as invalid: retry it in halves
+            if (err instanceof CliError && err.status === 400 && job.keys.length > LEGACY_BATCH) {
+                batchSize = LEGACY_BATCH;
+                queue.unshift(...chunk(job.keys, LEGACY_BATCH).map(k => ({ lang: job.lang, keys: k })));
+                return;
+            }
+            throw err;
+        }
+        out.provider = res.provider ?? out.provider;
+        out.usage = res.usage ?? out.usage;
+        const serverSaved = typeof res.saved === 'number';
+        out.savedBy ?? (out.savedBy = serverSaved ? 'server' : 'client');
+        const byId = new Map((res.results ?? []).filter(r => r.keyId).map(r => [r.keyId, r]));
+        const failedById = new Map((res.failed ?? []).filter(f => f.keyId).map(f => [f.keyId, f]));
+        const toSave = [];
+        job.keys.forEach((key, j) => {
+            const r = byId.get(key.id) ?? (byId.size ? undefined : res.results?.[j]);
+            const text = r?.translatedText;
+            if (typeof text !== 'string' || text === '') {
+                fail(job.lang, key, r?.error ?? failedById.get(key.id)?.error ?? (r ? 'empty_result' : 'missing_result'));
+            }
+            else if (serverSaved) {
+                if (r.saved === false)
+                    fail(job.lang, key, 'not_saved');
+                else
+                    succeed(job.lang, key, text, Boolean(r.copied));
+            }
+            else {
+                toSave.push({ key, text, copied: Boolean(r.copied) });
+            }
+        });
+        tick();
+        // Older servers: save each translation ourselves, a few at a time
+        let fatal;
+        await pool(toSave, SAVE_CONCURRENCY, async ({ key, text, copied }) => {
+            if (fatal) {
+                fail(job.lang, key, 'not_saved');
+                return;
+            }
+            try {
+                await session.api.patch(keyPath(key, job.lang), { value: text });
+                succeed(job.lang, key, text, copied);
+            }
+            catch (err) {
+                if (err instanceof CliError && (err.exitCode === ExitCode.Auth || err.exitCode === ExitCode.Limit))
+                    fatal = err;
+                fail(job.lang, key, `not saved: ${err.message}`);
+            }
+            tick();
+        });
+        if (fatal)
+            throw fatal;
+    };
+    try {
+        const worker = async () => {
+            while (queue.length && !out.fatal) {
+                const job = queue.shift();
+                if (job.keys.length > batchSize) {
+                    queue.unshift(...chunk(job.keys, batchSize).map(k => ({ lang: job.lang, keys: k })));
+                    continue;
+                }
+                try {
+                    await runJob(job);
+                }
+                catch (err) {
+                    // Stop starting new batches; batches already in flight finish and are reported
+                    out.fatal ?? (out.fatal = asUpstreamError(err));
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: CONCURRENCY }, worker));
+    }
+    finally {
+        bar.stop();
+    }
+    return out;
+}
+/** The API (not the user) failed: never report that as "invalid usage" (exit 2). */
+function asUpstreamError(err) {
+    if (!(err instanceof CliError))
+        return new CliError(err?.message ?? String(err), ExitCode.Error);
+    if (err.exitCode !== ExitCode.Usage)
+        return err;
+    const code = err.status !== undefined && err.status >= 500 ? ExitCode.Network : ExitCode.Error;
+    return new CliError(err.message, code, err.hint, err.status);
+}
+function chunk(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}
+function report(project, languages, total, o) {
+    const copied = o.done.filter(d => d.copied).length;
+    const translated = o.done.length - copied;
+    const notAttempted = total - o.done.length - o.failed.length;
+    const exitCode = o.fatal ? o.fatal.exitCode : o.failed.length ? ExitCode.Partial : ExitCode.Ok;
+    if (runtime.json) {
+        printJson({
+            project: project.slug,
+            source: project.defaultLanguage,
+            total,
+            translated: o.done,
+            failed: o.failed,
+            counts: { translated, copied, failed: o.failed.length, notAttempted },
+            provider: o.provider,
+            usage: o.usage,
+            exitCode,
+            ...(o.fatal ? { error: { message: o.fatal.message, exitCode: o.fatal.exitCode, hint: o.fatal.hint ?? null, status: o.fatal.status ?? null } } : {}),
+        });
+    }
+    // Summary and failures go to stderr, so they aren't lost when stdout is piped to a file
+    const quota = o.provider === 'org'
+        ? 'using your own DeepL key'
+        : o.usage?.limit != null ? `${o.usage.used}/${o.usage.limit} AI translations used this month` : o.usage ? `${o.usage.used} AI translations used this month` : '';
+    const summary = `Translated ${translated}, copied ${copied} unchanged, failed ${o.failed.length}` +
+        (notAttempted > 0 ? `, not attempted ${notAttempted}` : '') +
+        ` (${languages.join(', ')}${quota ? `; ${quota}` : ''}).`;
+    if (!runtime.json) {
+        if (o.failed.length || o.fatal)
+            process.stderr.write(`${chalk.yellow('✖')} ${summary}\n`);
+        else
+            log.success(summary);
+    }
+    if (o.failed.length && !runtime.json) {
+        process.stderr.write(`${chalk.yellow('Needs a human translation:')}\n`);
+        for (const f of o.failed) {
+            process.stderr.write(`  ${chalk.dim(f.language)}  ${f.key}  ${JSON.stringify(f.sourceText)}  ${chalk.dim(`(${f.error})`)}\n`);
+        }
+    }
+    if (o.done.length) {
+        log.info(chalk.dim(`AI translations are held back from "langctl pull" until reviewed. Check them with "langctl review ${project.slug}", then approve with --approve (or edit them in the web app).`));
+    }
+    if (o.fatal) {
+        if (runtime.json) {
+            process.exitCode = o.fatal.exitCode;
+            return;
+        }
+        throw o.fatal;
+    }
+    if (o.failed.length) {
+        const hint = `Add these in the web app or with "langctl keys translate ${project.slug} <key> -l <lang> -t <text>", then re-run (only missing strings are translated).`;
+        if (!runtime.json)
+            log.error(`${o.failed.length} string(s) could not be translated automatically.`, hint);
+        process.exitCode = ExitCode.Partial;
+    }
+}

package/dist/core/cache.js

@@ -0,0 +1,48 @@
+import { createHash } from 'crypto';
+import { mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { configDir } from './config.js';
+/**
+ * Small on-disk cache for conditional GETs (ETag / If-None-Match). When the server says
+ * "304 Not Modified" the CLI reuses the saved body, so repeated pulls cost almost nothing.
+ * Lives in the config dir (~/.langctl/cache); disable with LANGCTL_NO_CACHE=1.
+ */
+const MAX_ENTRIES = 40;
+function cacheDir() {
+    return join(configDir(), 'cache');
+}
+export function cacheEnabled() {
+    return !['1', 'true', 'yes'].includes(String(process.env.LANGCTL_NO_CACHE || '').toLowerCase());
+}
+/** Cache key covers the API, the key (orgs/scopes differ per key) and the full request URL. */
+export function cacheKey(apiUrl, apiKey, url) {
+    const keyId = createHash('sha256').update(apiKey).digest('hex').slice(0, 16);
+    return createHash('sha256').update(`${apiUrl}\n${keyId}\n${url}`).digest('hex').slice(0, 32);
+}
+export function readCache(key) {
+    try {
+        const entry = JSON.parse(readFileSync(join(cacheDir(), `${key}.json`), 'utf8'));
+        return entry && typeof entry.etag === 'string' ? entry : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeCache(key, etag, data) {
+    try {
+        const dir = cacheDir();
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        writeFileSync(join(dir, `${key}.json`), JSON.stringify({ etag, data, savedAt: new Date().toISOString() }), { mode: 0o600 });
+        prune(dir);
+    }
+    catch {
+        // A cache that can't be written (read-only home, full disk) must never fail a command
+    }
+}
+function prune(dir) {
+    const files = readdirSync(dir).filter(f => f.endsWith('.json'))
+        .map(f => ({ f, t: statSync(join(dir, f)).mtimeMs }))
+        .sort((a, b) => b.t - a.t);
+    for (const { f } of files.slice(MAX_ENTRIES))
+        unlinkSync(join(dir, f));
+}

package/dist/core/config.js

@@ -6,8 +6,27 @@ export const DEFAULT_API_URL = 'https://api.langctl.com/api/v1';
 export function configDir() {
     return process.env.LANGCTL_CONFIG_DIR ? resolve(process.env.LANGCTL_CONFIG_DIR) : join(homedir(), '.langctl');
 }
+// ── Profiles ───────────────────────────────────────────────────
+//
+// The default profile is ~/.langctl/config.json (unchanged since 0.2). Named profiles live in
+// ~/.langctl/profiles/<name>.json and are selected with --profile <name> or LANGCTL_PROFILE.
+const PROFILE_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+/** The active profile name, or null for the default profile. */
+export function activeProfile() {
+    const raw = (flagOverrides.profile ?? process.env.LANGCTL_PROFILE ?? '').trim();
+    if (!raw || raw === 'default')
+        return null;
+    if (!PROFILE_RE.test(raw)) {
+        throw usageError(`Invalid profile name "${raw}".`, 'Use letters, digits, ".", "_" or "-" (e.g. --profile client-a).');
+    }
+    return raw;
+}
+export function profileLabel() {
+    return activeProfile() ?? 'default';
+}
 export function configPath() {
-    return join(configDir(), 'config.json');
+    const profile = activeProfile();
+    return profile ? join(configDir(), 'profiles', `${profile}.json`) : join(configDir(), 'config.json');
 }
 export function readUserConfig() {
     const path = configPath();
@@ -87,7 +106,7 @@ export function maskApiKey(key) {
 }
 // ── Project config (langctl.json) ──────────────────────────────
 export const PROJECT_CONFIG_FILE = 'langctl.json';
-const KNOWN_KEYS = new Set(['$schema', 'project', 'format', 'output', 'languages', 'sourceLanguage', 'includeDrafts', 'module']);
+const KNOWN_KEYS = new Set(['$schema', 'project', 'format', 'output', 'languages', 'sourceLanguage', 'includeDrafts', 'module', 'prefix']);
 /** Find langctl.json in the current directory or the nearest parent. */
 export function loadProjectConfig(cwd = process.cwd()) {
     let dir = resolve(cwd);
@@ -105,6 +124,9 @@ export function loadProjectConfig(cwd = process.cwd()) {
             if (unknown.length) {
                 throw usageError(`${candidate} has unknown field(s): ${unknown.join(', ')}`, `Allowed: ${[...KNOWN_KEYS].filter(k => k !== '$schema').join(', ')}`);
             }
+            if (config.prefix !== undefined && (typeof config.prefix !== 'string' || !config.prefix.trim())) {
+                throw usageError(`${candidate}: "prefix" must be a non-empty string, e.g. "dashboard."`);
+            }
             if (config.languages !== undefined && !Array.isArray(config.languages)) {
                 throw usageError(`${candidate}: "languages" must be an array of language codes`);
             }
@@ -125,6 +147,30 @@ export function writeProjectConfig(path, config) {
         ...(config.sourceLanguage ? { sourceLanguage: config.sourceLanguage } : {}),
         ...(config.includeDrafts ? { includeDrafts: true } : {}),
         ...(config.module ? { module: config.module } : {}),
+        ...(config.prefix ? { prefix: config.prefix } : {}),
     };
     writeFileSync(path, JSON.stringify(ordered, null, 2) + '\n');
 }
+// ── Key prefixes ───────────────────────────────────────────────
+/** "dashboard" → "dashboard."; prefixes that already end in a separator are kept as given. */
+export function normalizePrefix(prefix) {
+    const p = prefix?.trim();
+    if (!p)
+        return undefined;
+    return /[.:_/-]$/.test(p) ? p : `${p}.`;
+}
+/** The prefix in effect: the flag, else langctl.json's "prefix". */
+export function resolvePrefix(flag, cfg) {
+    return normalizePrefix(flag ?? cfg.prefix);
+}
+/**
+ * Map key names typed by a user to the names stored in langctl: with a prefix configured,
+ * "common.save" and "dashboard.common.save" both mean "dashboard.common.save".
+ */
+export function withPrefix(name, prefix, known) {
+    if (!prefix || name.startsWith(prefix))
+        return name;
+    if (known && known.has(name) && !known.has(prefix + name))
+        return name;
+    return prefix + name;
+}

package/dist/core/errors.js

@@ -10,6 +10,8 @@ export const ExitCode = {
     Network: 5,
     Limit: 6,
     Drift: 7,
+    /** Partial success: some strings could not be translated and need a human (e.g. `translate`) */
+    Partial: 8,
 };
 export class CliError extends Error {
     constructor(message, exitCode = ExitCode.Error, hint, status) {
@@ -22,9 +24,16 @@ export class CliError extends Error {
 }
 export const usageError = (message, hint) => new CliError(message, ExitCode.Usage, hint);
 export const notFoundError = (message, hint) => new CliError(message, ExitCode.NotFound, hint);
+/** Shown when the API no longer knows a path this CLI calls — almost always an outdated CLI. */
+export const UPGRADE_HINT = 'This version of langctl may be too old for the Langctl API. Upgrade with: npm i -g langctl@latest';
+/** Fastify's default 404 for an unknown route: "Route GET:/api/v1/… not found". */
+export const isMissingRoute = (status, message) => status === 410 || (status === 404 && /^Route [A-Z]+:\S+ not found$/i.test(message ?? ''));
 /** Map an HTTP error response from the API to a CliError with the right exit code and a useful hint. */
 export function httpError(status, serverMessage, method, path) {
     const msg = serverMessage || `HTTP ${status}`;
+    if (isMissingRoute(status, serverMessage)) {
+        return new CliError(`The Langctl API does not support ${method} ${path} (${status}).`, status === 410 ? ExitCode.Error : ExitCode.NotFound, UPGRADE_HINT, status);
+    }
     if (status === 401) {
         return new CliError('Your API key is invalid or has been revoked.', ExitCode.Auth, 'Create a new key at https://app.langctl.com/organization/api-keys and run "langctl auth --stdin", or set LANGCTL_API_KEY.', status);
     }

package/dist/core/http.js

@@ -2,6 +2,7 @@ import { CliError, ExitCode, httpError, networkError } from './errors.js';
 import { requireCredentials } from './config.js';
 import { detectCi, log } from './output.js';
 import { VERSION } from '../version.js';
+import { cacheEnabled, cacheKey, readCache, writeCache } from './cache.js';
 export const httpSettings = {
     timeoutMs: Number(process.env.LANGCTL_TIMEOUT || 30) * 1000,
     retries: 3,
@@ -19,11 +20,40 @@ export class ApiClient {
         return this.creds.apiUrl;
     }
     async request(method, path, opts = {}) {
+        return (await this.send(method, this.buildUrl(path, opts.query), opts)).data;
+    }
+    buildUrl(path, query) {
         const url = new URL(this.creds.apiUrl + path);
-        for (const [k, v] of Object.entries(opts.query ?? {})) {
+        for (const [k, v] of Object.entries(query ?? {})) {
             if (v !== undefined && v !== '')
                 url.searchParams.set(k, String(v));
         }
+        return url;
+    }
+    /**
+     * GET with an ETag cache: if the server reports the resource unchanged (304) the saved body is
+     * reused. Used for exports, which CI fetches over and over while translations rarely change.
+     */
+    async getCached(path, query) {
+        const url = this.buildUrl(path, query);
+        if (!cacheEnabled())
+            return { data: (await this.send('GET', url, {})).data, fromCache: false };
+        const key = cacheKey(this.creds.apiUrl, this.creds.apiKey, url.toString());
+        const cached = readCache(key);
+        const res = await this.send('GET', url, { ifNoneMatch: cached?.etag });
+        if (res.notModified && cached) {
+            log.debug(`cache hit for ${url.pathname} (${cached.etag})`);
+            return { data: cached.data, fromCache: true };
+        }
+        if (res.notModified) {
+            // 304 without a cached body (cache wiped mid-run): fetch unconditionally
+            return { data: (await this.send('GET', url, {})).data, fromCache: false };
+        }
+        if (res.etag)
+            writeCache(key, res.etag, res.data);
+        return { data: res.data, fromCache: false };
+    }
+    async send(method, url, opts) {
         const headers = {
             'X-API-Key': this.creds.apiKey,
             'User-Agent': userAgent(),
@@ -32,6 +62,8 @@ export class ApiClient {
         // Only declare a JSON body when there is one — Fastify rejects an empty body with this header
         if (opts.body !== undefined)
             headers['Content-Type'] = 'application/json';
+        if (opts.ifNoneMatch)
+            headers['If-None-Match'] = opts.ifNoneMatch;
         const idempotent = opts.idempotent ?? (method === 'GET');
         const attempts = idempotent ? httpSettings.retries : 1;
         for (let attempt = 1;; attempt++) {
@@ -55,6 +87,9 @@ export class ApiClient {
                 throw mapped;
             }
             log.debug(`${method} ${url.pathname}${url.search} → ${res.status} (${Date.now() - started}ms)`);
+            if (res.status === 304) {
+                return { status: 304, data: undefined, etag: res.headers.get('etag'), notModified: true };
+            }
             const retryable = res.status === 429 || res.status === 502 || res.status === 503 || res.status === 504;
             if (retryable && attempt < attempts) {
                 const retryAfter = Number(res.headers.get('retry-after'));
@@ -75,9 +110,11 @@ export class ApiClient {
             }
             if (!res.ok) {
                 const d = data;
-                throw httpError(res.status, d?.error || d?.message, method, url.pathname);
+                // Fastify's own 404 ("Route GET:/… not found") is in `message`; ours are in `error`
+                const routeMessage = typeof d?.message === 'string' && /^Route /.test(d.message) ? d.message : undefined;
+                throw httpError(res.status, routeMessage || d?.error || d?.message, method, url.pathname);
             }
-            return data;
+            return { status: res.status, data: data, etag: res.headers.get('etag'), notModified: false };
         }
     }
     get(path, query) {
@@ -102,6 +139,10 @@ export async function validateKey(api, apiKey) {
     return res.valid && res.organizationId ? { organizationId: res.organizationId, scopes: res.scopes ?? [] } : null;
 }
 let cached = null;
+/** Forget the cached session (tests; switching keys within one process). */
+export function resetSession() {
+    cached = null;
+}
 export async function getSession() {
     if (cached)
         return cached;

package/dist/core/output.js

@@ -81,6 +81,43 @@ export function spinner(text) {
         },
     };
 }
+/**
+ * Counter for long operations: "Translating 312/889…". At a terminal it is a spinner line; in CI
+ * and pipes (where a spinner is invisible) it prints a plain stderr line every ~10%.
+ */
+export function progress(label, total) {
+    const text = (n) => `${label} ${n}/${total}…`;
+    if (isInteractive() && !runtime.quiet && !runtime.verbose) {
+        const spin = spinner(text(0));
+        return {
+            update(n) { spin.text = text(n); },
+            out(line) {
+                if (runtime.json)
+                    return;
+                process.stderr.write('\r\x1b[2K');
+                process.stdout.write(line + '\n');
+            },
+            stop() { spin.stop(); },
+        };
+    }
+    const step = Math.max(1, Math.ceil(total / 10));
+    let next = step;
+    let last = -1;
+    return {
+        update(n) {
+            if (runtime.quiet || runtime.json || total < 1 || n === last)
+                return;
+            if (n >= next || n === total) {
+                process.stderr.write(text(n) + '\n');
+                last = n;
+                while (next <= n)
+                    next += step;
+            }
+        },
+        out(line) { log.out(line); },
+        stop() { },
+    };
+}
 /** Minimal aligned table for human output. */
 export function table(rows, header) {
     const all = header ? [header, ...rows] : rows;