langctl 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 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

@@ -129,10 +129,12 @@ the pull fails and names both keys instead of silently dropping one.
 | 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 pull [project]` | Download translations. `-l/--languages`, `-f/--format`, `-o/--output`, `-m/--module`, `--include-drafts`, `--include-unreviewed`, `--check`, `--dry-run`, `--require-complete`. AI translations nobody has reviewed are left out (with a warning) until approved. |
 | `langctl push [project]` | Upload files. Default: source language only; `-l all` for every language. `--overwrite`, `--publish`, `--dry-run`, `-i/--input`. |
 | `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 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. |
+| `langctl review [project]` | List AI translations awaiting review; `--approve` approves them (narrow with `-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). `echo "$KEY" \| langctl auth --stdin`. |
 | `langctl whoami` | Show org, key source, scopes and API latency. |
 | `langctl logout` · `langctl config` · `langctl formats` | Remove the stored key · show effective config · list formats. |
@@ -152,6 +154,7 @@ Global flags (any position): `--json` · `-q/--quiet` · `--verbose` (log HTTP r
 | `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_CONFIG_DIR` | Where the user config lives (default `~/.langctl`). |
+| `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. |
 

package/dist/commands/pull.js

@@ -30,10 +30,12 @@ export async function pullCommand(projectArg, opts) {
     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();
@@ -63,6 +65,7 @@ export async function pullCommand(projectArg, opts) {
             dryRun,
             files: files.map(f => ({ ...f, path: relative(process.cwd(), f.path) })),
             changed: changed.length,
+            unreviewedSkipped: snapshot.metadata?.unreviewedSkipped ?? 0,
         });
     }
     else {
@@ -73,6 +76,10 @@ export async function pullCommand(projectArg, opts) {
             log.out(`${icon} ${relative(process.cwd(), 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}`));
+        const unreviewed = snapshot.metadata?.unreviewedSkipped ?? 0;
+        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 (snapshot.keys.length === 0 && !includeDrafts) {
             log.warn('No published keys — drafts are excluded by default. Publish keys, or pass --include-drafts.');
         }

package/dist/commands/review.js

@@ -0,0 +1,65 @@
+import chalk from 'chalk';
+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, 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 keys = split(opts.keys);
+    const languages = split(opts.languages);
+    if (languages)
+        assertLanguages(project, languages);
+    const spin = spinner('Fetching AI translations awaiting review…');
+    let list;
+    try {
+        list = await session.api.get(`/orgs/${session.orgId}/projects/${project.id}/review`);
+    }
+    finally {
+        spin.stop();
+    }
+    const items = list.items.filter(i => (!keys || keys.includes(i.key)) && (!languages || languages.includes(i.language)));
+    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 --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,99 @@
+import chalk from 'chalk';
+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';
+/** The API translates at most 50 strings per request. */
+const BATCH = 50;
+const isBlank = (v) => !v || !v.trim();
+/**
+ * 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.
+ */
+export async function translateCommand(projectArg, opts) {
+    const session = await getSession();
+    const project = await getProject(session, projectSlugFrom(projectArg));
+    const source = project.defaultLanguage;
+    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 wanted = new Set(opts.keys.split(',').map(s => s.trim()).filter(Boolean));
+        const unknown = [...wanted].filter(k => !keys.some(key => key.key === 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 ${total} AI translation(s). Run without --dry-run to translate.`);
+        return;
+    }
+    const done = [];
+    let usage;
+    let provider;
+    const progress = spinner(`Translating 0/${total}…`);
+    try {
+        for (const { lang, keys: todo } of plan) {
+            for (let i = 0; i < todo.length; i += BATCH) {
+                const batch = todo.slice(i, i + BATCH);
+                const res = await session.api.post(`/orgs/${session.orgId}/translate/bulk`, {
+                    items: batch.map(k => ({ text: k.translations[source], keyId: k.id })),
+                    sourceLang: source,
+                    targetLang: lang,
+                    projectId: project.id,
+                });
+                usage = res.usage;
+                provider = res.provider;
+                for (const [j, key] of batch.entries()) {
+                    const text = res.results[j]?.translatedText;
+                    if (!text)
+                        continue;
+                    await session.api.patch(`/orgs/${session.orgId}/projects/${project.id}/keys/${key.id}/translations/${encodeURIComponent(lang)}`, { value: text });
+                    done.push({ language: lang, key: key.key, text });
+                    progress.text = `Translating ${done.length}/${total}…`;
+                }
+            }
+        }
+    }
+    finally {
+        progress.stop();
+    }
+    if (runtime.json)
+        return printJson({ source, translated: done, provider, usage });
+    for (const d of done)
+        log.out(`${chalk.dim(d.language)}  ${d.key}  ${d.text}`);
+    const quota = provider === 'org'
+        ? 'using your own DeepL key'
+        : usage?.limit != null ? `${usage.used}/${usage.limit} AI translations used this month` : `${usage?.used ?? done.length} AI translations used this month`;
+    log.success(`Translated ${done.length} string(s) into ${plan.filter(p => p.keys.length).map(p => p.lang).join(', ')} (${quota}).`);
+    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).`));
+}

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/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'));
@@ -77,7 +112,7 @@ export class ApiClient {
                 const d = data;
                 throw httpError(res.status, 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) {

package/dist/index.js

@@ -11,6 +11,8 @@ import { orgInfoCommand, orgPlanCommand, orgStatsCommand } from './commands/org.
 import { projectsAddLanguageCommand, projectsCreateCommand, projectsDeleteCommand, projectsGetCommand, projectsListCommand, projectsRemoveLanguageCommand, projectsStatsCommand, projectsUpdateCommand, } from './commands/projects.js';
 import { pullCommand } from './commands/pull.js';
 import { pushCommand } from './commands/push.js';
+import { translateCommand } from './commands/translate.js';
+import { reviewCommand } from './commands/review.js';
 import { getTeamMemberCommand, inviteTeamMemberCommand, listInvitationsCommand, listTeamCommand, removeTeamMemberCommand, revokeInvitationCommand, updateTeamRoleCommand, } from './commands/team.js';
 import { flagOverrides } from './core/config.js';
 import { CliError, ExitCode, usageError } from './core/errors.js';
@@ -91,6 +93,7 @@ withGlobals(program.command('pull [project]'))
     .addOption(new Option('-d, --dir <path>', 'legacy: base directory for the default layout').hideHelp())
     .option('-m, --module <name>', 'only keys from this module')
     .option('--include-drafts', 'include unpublished keys (excluded by default)')
+    .option('--include-unreviewed', 'include AI translations nobody has reviewed yet (excluded by default)')
     .addOption(new Option('--no-published-only').hideHelp())
     .option('--check', 'do not write; exit 7 if any file is out of date (for CI)')
     .option('--dry-run', 'show what would change without writing')
@@ -192,6 +195,19 @@ withGlobals(keys.command('unpublish <project> [keys...]')).description('move key
     .option('--all', 'unpublish every published key')
     .option('-m, --module <name>', 'unpublish every key in a module')
     .action(run((project, names, opts) => publishKeysCommand(project, names, opts, false)));
+// ── AI translation ──────────────────────────────────────────────
+withGlobals(program.command('translate [project]')).description('fill missing translations with AI (DeepL) from the default language')
+    .option('-t, --to <codes>', 'comma-separated target languages (default: every non-default language)')
+    .option('-k, --keys <names>', 'only these keys (comma-separated)')
+    .option('-m, --module <name>', 'only keys in a module')
+    .option('--overwrite', 'retranslate keys that already have a translation')
+    .option('--dry-run', 'show what would be translated without using any AI translations')
+    .action(run((project, opts) => translateCommand(project, opts)));
+withGlobals(program.command('review [project]')).description('list AI translations awaiting review, or approve them')
+    .option('--approve', 'approve the listed translations (asks to confirm; --yes in CI)')
+    .option('-k, --keys <names>', 'only these keys (comma-separated)')
+    .option('-l, --languages <codes>', 'only these languages (comma-separated)')
+    .action(run((project, opts) => reviewCommand(project, opts)));
 // ── Team & org ──────────────────────────────────────────────────
 const team = program.command('team').description('manage team members (needs an API key with the org:admin scope)');
 withGlobals(team.command('list')).alias('ls').description('list members').action(run(() => listTeamCommand()));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "langctl",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Translation management CLI for developers: sync i18n files (JSON, Android, iOS, Flutter ARB) between your repo, CI and Langctl.",
   "main": "dist/index.js",
   "type": "module",