@qnroa/qtype 0.0.1

package/dist/cli/commands/repo/new/i18n.js

@@ -0,0 +1,46 @@
+export const messages = {
+    'zh-CN': {
+        'repo.new.summary': '新建仓库',
+        'repo.new.description': '在空目录创建一个 qtype 资料仓库（含 QTYPE.md、AGENTS/CLAUDE/GEMINI 软链、README、material/ 骨架）',
+        'repo.new.arg.name': '仓库名（作为目录名）',
+        'repo.new.opt.description': 'README 一行简介',
+        'repo.new.opt.dir': '父目录（默认当前目录）',
+        'repo.new.opt.git': '同时 git init（默认不执行）',
+        'repo.new.example.basic': '中文模板新建',
+        'repo.new.example.git': '新建并初始化 git 仓库',
+        // runtime messages
+        'repo.new.msg.creating': '在 {path} 新建 qtype 仓库',
+        'repo.new.msg.symlinkFallback': '{alias} (copy, symlink failed)',
+        'repo.new.msg.gitInited': 'git 已初始化（分支：main）',
+        'repo.new.msg.gitInitFailed': 'git init 失败：{reason}',
+        'repo.new.msg.done': '仓库已建好：{path}',
+        'repo.new.msg.nextSteps': '下一步：',
+        'repo.new.msg.next.cd': 'cd {name}',
+        'repo.new.msg.next.edit': 'vim material/example.md    # 或添加新的 material/*.md',
+        'repo.new.msg.next.commit': 'git add -A && git commit  # 首次提交',
+        'repo.new.msg.next.gitHint': 'git init                  # 如需版本控制，也可以 qtype repo new --git',
+        'repo.new.tpl.defaultDescription': '资料库',
+    },
+    'en-US': {
+        'repo.new.summary': 'Create a new repo',
+        'repo.new.description': 'Create a qtype material repo in an empty directory (QTYPE.md + symlinks + material/ skeleton)',
+        'repo.new.arg.name': 'Repo name (used as directory name)',
+        'repo.new.opt.description': 'One-line description for README',
+        'repo.new.opt.dir': 'Parent directory (default: current directory)',
+        'repo.new.opt.git': 'Also run git init (off by default)',
+        'repo.new.example.basic': 'English template',
+        'repo.new.example.git': 'Create and initialize git',
+        // runtime messages
+        'repo.new.msg.creating': 'Creating qtype repo in {path}',
+        'repo.new.msg.symlinkFallback': '{alias} (copied, symlink not supported)',
+        'repo.new.msg.gitInited': 'git initialized (branch: main)',
+        'repo.new.msg.gitInitFailed': 'git init failed: {reason}',
+        'repo.new.msg.done': 'Repo created: {path}',
+        'repo.new.msg.nextSteps': 'Next steps:',
+        'repo.new.msg.next.cd': 'cd {name}',
+        'repo.new.msg.next.edit': 'vim material/example.md    # or add new material/*.md',
+        'repo.new.msg.next.commit': 'git add -A && git commit  # initial commit',
+        'repo.new.msg.next.gitHint': 'git init                  # or re-run with qtype repo new --git',
+        'repo.new.tpl.defaultDescription': 'material library',
+    },
+};

package/dist/cli/commands/repo/new/index.js

@@ -0,0 +1,57 @@
+/**
+ * `qtype repo new <name>` command module.
+ */
+import os from 'node:os';
+import path from 'node:path';
+import { t, getLocale } from '../../../i18n/index.js';
+import { userKv } from '../../../bootstrap.js';
+import { warn } from '../../../utils/output.js';
+import { messages } from './i18n.js';
+import { repoNewAction } from './action.js';
+function warnIfHome(dir) {
+    if (path.resolve(dir) === os.homedir())
+        warn(t('msg.home.warn'));
+}
+export const repoNewCmd = {
+    name: 'new',
+    messages,
+    summary: () => t('repo.new.summary'),
+    describe: () => t('repo.new.description'),
+    args: [{ flag: '<name>', describe: () => t('repo.new.arg.name') }],
+    options: [
+        {
+            flags: '--lang <lang>',
+            describe: () => t('opt.lang'),
+            choices: ['zh-CN', 'en-US', 'zh', 'en'],
+            // No defaultValue: when omitted, the action inherits from user's
+            // global repo.lang → CLI locale → 'zh' fallback.
+        },
+        {
+            flags: '--description <text>',
+            describe: () => t('repo.new.opt.description'),
+            defaultValue: '',
+        },
+        { flags: '--dir <path>', describe: () => t('repo.new.opt.dir') },
+        { flags: '--git', describe: () => t('repo.new.opt.git') },
+    ],
+    examples: () => [
+        { command: 'qtype repo new my-material', describe: () => t('repo.new.example.basic') },
+        { command: 'qtype repo new my-material --git', describe: () => t('repo.new.example.git') },
+    ],
+    seeAlso: ['repo sync', 'publish init'],
+    action: async (name, opts) => {
+        warnIfHome(opts.dir ?? process.cwd());
+        // Precedence: --lang flag → user's global `repo.lang` → CLI locale → 'zh'.
+        // `qtype config set repo.lang en --global` becomes a durable "new repos
+        // should be English" preference.
+        const userDefault = (await userKv.get('repo.lang'));
+        const lang = opts.lang ?? userDefault ?? getLocale();
+        await repoNewAction({
+            name,
+            lang,
+            description: opts.description,
+            dir: opts.dir,
+            git: opts.git === true,
+        });
+    },
+};

package/dist/cli/commands/repo/sync/action.js

@@ -0,0 +1,202 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getTemplatesDir, readTemplate } from '../templates.js';
+import { info, success, warn, fatal } from '../../../utils/output.js';
+import { t } from '../../../i18n/index.js';
+function buildSyncPlan() {
+    const qtypeFile = 'QTYPE.md';
+    return [
+        // ── qtype-managed (overwriteable with --force) ──
+        { kind: 'file', target: qtypeFile, source: 'QTYPE.md', managed: true },
+        { kind: 'symlink', target: 'AGENTS.md', source: qtypeFile, managed: true },
+        { kind: 'symlink', target: 'CLAUDE.md', source: qtypeFile, managed: true },
+        { kind: 'symlink', target: 'GEMINI.md', source: qtypeFile, managed: true },
+        // ── User content (never overwritten) ────────────
+        { kind: 'file', target: 'README.md', source: 'README.md', managed: false },
+        { kind: 'file', target: 'TODO.md', source: 'TODO.md', managed: false },
+        { kind: 'file', target: 'index.md', source: 'index.md', managed: false },
+        { kind: 'file', target: 'log.md', source: 'log.md', managed: false },
+        {
+            kind: 'file',
+            target: 'material/example.md',
+            source: path.join('material', 'example.md'),
+            managed: false,
+        },
+        // ── Skeleton (create-only, never touched) ───────
+        { kind: 'dir', target: '.qtype', managed: false },
+        { kind: 'dir', target: 'material', managed: false },
+        { kind: 'gitkeep', target: 'material/.gitkeep', managed: false },
+    ];
+}
+export async function repoSyncAction(opts) {
+    const root = opts.path ?? process.cwd();
+    // Accept BCP 47 (`zh-CN` / `en-US`) or the legacy short forms; reduce
+    // to the short code used by template / content directories, and derive
+    // the canonical BCP 47 form that gets written to .qtype/config.json.
+    const lang = opts.lang === 'zh' || opts.lang === 'zh-CN' ? 'zh' : 'en';
+    const canonicalLang = lang === 'zh' ? 'zh-CN' : 'en-US';
+    const dryRun = opts.dryRun === true;
+    const force = opts.force === true;
+    const today = new Date().toISOString().slice(0, 10);
+    if (!fs.existsSync(root)) {
+        fatal(t('err.path.notExists', { path: root }));
+    }
+    const name = path.basename(path.resolve(root));
+    const scanningKey = dryRun
+        ? 'repo.sync.msg.scanning.dryRun'
+        : force
+            ? 'repo.sync.msg.scanning.force'
+            : 'repo.sync.msg.scanning';
+    info(t(scanningKey, { path: root }));
+    const templatesDir = getTemplatesDir(lang);
+    const vars = {
+        name,
+        description: t('repo.sync.tpl.defaultDescription'),
+        date: today,
+    };
+    const plan = buildSyncPlan();
+    const toCreate = [];
+    const toOverwrite = [];
+    const skipped = [];
+    for (const item of plan) {
+        const fullPath = path.join(root, item.target);
+        if (!fs.existsSync(fullPath)) {
+            toCreate.push(item);
+        }
+        else if (force && item.managed) {
+            toOverwrite.push(item);
+        }
+        else {
+            skipped.push(item.target);
+        }
+    }
+    if (skipped.length > 0) {
+        console.log('\n' + t('repo.sync.msg.header.skipped', { count: skipped.length }));
+        if (!dryRun) {
+            for (const e of skipped)
+                console.log(`  · ${e}`);
+        }
+    }
+    if (toOverwrite.length > 0) {
+        const headerKey = dryRun
+            ? 'repo.sync.msg.header.willOverwrite'
+            : 'repo.sync.msg.header.overwriting';
+        console.log('\n' + t(headerKey, { count: toOverwrite.length }));
+        for (const item of toOverwrite) {
+            console.log(`  ~ ${item.target}`);
+            if (dryRun)
+                continue;
+            writeItem(root, item, templatesDir, vars);
+        }
+    }
+    const createHeaderKey = dryRun
+        ? 'repo.sync.msg.header.willCreate'
+        : 'repo.sync.msg.header.creating';
+    console.log('\n' + t(createHeaderKey, { count: toCreate.length }));
+    for (const item of toCreate) {
+        console.log(`  + ${item.target}`);
+        if (dryRun)
+            continue;
+        writeItem(root, item, templatesDir, vars);
+    }
+    // Ensure .qtype/config.json exists and records the repo language.
+    if (!dryRun) {
+        ensureConfigLang(root, canonicalLang);
+    }
+    if (dryRun) {
+        console.log('');
+        warn(t('repo.sync.msg.dryRun'));
+    }
+    else {
+        console.log('');
+        success(t('repo.sync.msg.done', {
+            created: toCreate.length,
+            overwritten: toOverwrite.length,
+            skipped: skipped.length,
+        }));
+    }
+}
+/**
+ * Ensure `.qtype/config.json` exists and has `repo.lang` set. Merges with
+ * an existing config non-destructively (won't clobber other settings) —
+ * only writes `repo.lang` when it's missing or empty.
+ */
+function ensureConfigLang(root, canonicalLang) {
+    const dir = path.join(root, '.qtype');
+    const file = path.join(dir, 'config.json');
+    fs.mkdirSync(dir, { recursive: true });
+    let obj = {};
+    if (fs.existsSync(file)) {
+        try {
+            const text = fs.readFileSync(file, 'utf8').trim();
+            if (text.length > 0) {
+                const parsed = JSON.parse(text);
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    obj = parsed;
+                }
+            }
+        }
+        catch {
+            // Malformed config — leave alone rather than clobbering the user's edits.
+            return;
+        }
+    }
+    const repoBlock = obj.repo && typeof obj.repo === 'object' && !Array.isArray(obj.repo)
+        ? obj.repo
+        : {};
+    // Existing values are accepted whether they're BCP 47 or short codes —
+    // the reader normalises on load. Only skip the write when the value is
+    // already one we recognise.
+    if (typeof repoBlock.lang === 'string' &&
+        (repoBlock.lang === 'zh' ||
+            repoBlock.lang === 'en' ||
+            repoBlock.lang === 'zh-CN' ||
+            repoBlock.lang === 'en-US')) {
+        return;
+    }
+    repoBlock.lang = canonicalLang;
+    obj.repo = repoBlock;
+    fs.writeFileSync(file, JSON.stringify(obj, null, 2) + '\n');
+}
+function writeItem(root, item, templatesDir, vars) {
+    const fullPath = path.join(root, item.target);
+    if (item.kind === 'file' && item.source) {
+        const content = readTemplate(templatesDir, item.source, vars);
+        fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+        fs.writeFileSync(fullPath, content);
+    }
+    else if (item.kind === 'symlink' && item.source) {
+        let exists = false;
+        try {
+            fs.lstatSync(fullPath);
+            exists = true;
+        }
+        catch {
+            // ENOENT — nothing to unlink
+        }
+        if (exists) {
+            try {
+                fs.unlinkSync(fullPath);
+            }
+            catch {
+                // If we can't delete, let symlinkSync below report the reason
+            }
+        }
+        try {
+            fs.symlinkSync(item.source, fullPath);
+        }
+        catch {
+            // Windows / permission issue → fall back to a copy
+            const sourceFull = path.join(root, item.source);
+            if (fs.existsSync(sourceFull))
+                fs.copyFileSync(sourceFull, fullPath);
+        }
+    }
+    else if (item.kind === 'dir') {
+        fs.mkdirSync(fullPath, { recursive: true });
+    }
+    else if (item.kind === 'gitkeep') {
+        fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+        fs.writeFileSync(fullPath, '');
+    }
+}

package/dist/cli/commands/repo/sync/i18n.js

@@ -0,0 +1,44 @@
+export const messages = {
+    'zh-CN': {
+        'repo.sync.summary': '补齐缺失文件',
+        'repo.sync.description': '已有仓库补齐缺失的 QTYPE 规范文件（默认不覆盖；--force 覆盖 qtype 管理的文件）',
+        'repo.sync.arg.path': '仓库路径（默认当前目录）',
+        'repo.sync.opt.force': '覆盖 qtype 管理的文件（规范 + 软链）；用户内容不动',
+        'repo.sync.example.dryRun': '只报告缺啥，不写任何文件',
+        'repo.sync.example.explicit': '指定仓库路径',
+        'repo.sync.example.force': '升级 qtype 后，更新 QTYPE.md 等规范文件',
+        // runtime messages
+        'repo.sync.msg.scanning': '检查 {path}',
+        'repo.sync.msg.scanning.force': '检查 {path}（--force: 将覆盖 qtype 管理的文件）',
+        'repo.sync.msg.scanning.dryRun': '[dry-run] 检查 {path}',
+        'repo.sync.msg.dryRun': '[dry-run] 没有写入任何文件。去掉 --dry-run 实际执行。',
+        'repo.sync.msg.header.skipped': '已存在（跳过）：{count} 项',
+        'repo.sync.msg.header.overwriting': '正在覆盖：{count} 项 (--force)',
+        'repo.sync.msg.header.willOverwrite': '将要覆盖：{count} 项 (--force)',
+        'repo.sync.msg.header.creating': '正在建：{count} 项',
+        'repo.sync.msg.header.willCreate': '将要建：{count} 项',
+        'repo.sync.msg.done': '完成：建 {created}，覆盖 {overwritten}，跳过 {skipped}',
+        'repo.sync.tpl.defaultDescription': '资料库',
+    },
+    'en-US': {
+        'repo.sync.summary': 'Sync missing files',
+        'repo.sync.description': 'Add missing QTYPE spec files to an existing repo (safe by default; --force overwrites qtype-managed files only)',
+        'repo.sync.arg.path': 'Repo path (default: current directory)',
+        'repo.sync.opt.force': 'Overwrite qtype-managed files only (spec + symlinks); user content untouched',
+        'repo.sync.example.dryRun': 'Report only, no writes',
+        'repo.sync.example.explicit': 'Explicit repo path',
+        'repo.sync.example.force': 'After upgrading qtype, refresh QTYPE.md etc.',
+        // runtime messages
+        'repo.sync.msg.scanning': 'Scanning {path}',
+        'repo.sync.msg.scanning.force': 'Scanning {path} (--force: will overwrite qtype-managed files)',
+        'repo.sync.msg.scanning.dryRun': '[dry-run] Scanning {path}',
+        'repo.sync.msg.dryRun': '[dry-run] No files written. Remove --dry-run to actually apply.',
+        'repo.sync.msg.header.skipped': 'Already present (skipped): {count}',
+        'repo.sync.msg.header.overwriting': 'Overwriting: {count} (--force)',
+        'repo.sync.msg.header.willOverwrite': 'Will overwrite: {count} (--force)',
+        'repo.sync.msg.header.creating': 'Creating: {count}',
+        'repo.sync.msg.header.willCreate': 'Will create: {count}',
+        'repo.sync.msg.done': 'Done: {created} created, {overwritten} overwritten, {skipped} skipped',
+        'repo.sync.tpl.defaultDescription': 'material library',
+    },
+};

package/dist/cli/commands/repo/sync/index.js

@@ -0,0 +1,47 @@
+/**
+ * `qtype repo sync` command module.
+ */
+import os from 'node:os';
+import path from 'node:path';
+import { t, getLocale } from '../../../i18n/index.js';
+import { userKv } from '../../../bootstrap.js';
+import { warn } from '../../../utils/output.js';
+import { messages } from './i18n.js';
+import { repoSyncAction } from './action.js';
+function warnIfHome(dir) {
+    if (path.resolve(dir) === os.homedir())
+        warn(t('msg.home.warn'));
+}
+export const repoSyncCmd = {
+    name: 'sync',
+    messages,
+    summary: () => t('repo.sync.summary'),
+    describe: () => t('repo.sync.description'),
+    args: [{ flag: '[path]', describe: () => t('repo.sync.arg.path') }],
+    options: [
+        {
+            flags: '--lang <lang>',
+            describe: () => t('opt.lang'),
+            choices: ['zh-CN', 'en-US', 'zh', 'en'],
+        },
+        { flags: '--force', describe: () => t('repo.sync.opt.force') },
+        { flags: '--dry-run', describe: () => t('opt.dryRun') },
+    ],
+    examples: () => [
+        { command: 'qtype repo sync --dry-run', describe: () => t('repo.sync.example.dryRun') },
+        { command: 'qtype repo sync ./my-material', describe: () => t('repo.sync.example.explicit') },
+        { command: 'qtype repo sync --force', describe: () => t('repo.sync.example.force') },
+    ],
+    seeAlso: ['repo new'],
+    action: async (pathArg, opts) => {
+        warnIfHome(pathArg ?? process.cwd());
+        const userDefault = (await userKv.get('repo.lang'));
+        const lang = opts.lang ?? userDefault ?? getLocale();
+        await repoSyncAction({
+            path: pathArg,
+            lang,
+            force: opts.force,
+            dryRun: opts.dryRun,
+        });
+    },
+};

package/dist/cli/commands/repo/templates.js

@@ -0,0 +1,87 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Locate the templates root inside the qtype package.
+ *
+ * Layout:
+ *   templates/
+ *   ├── en/
+ *   │   ├── QTYPE.md  README.md  TODO.md  index.md  log.md
+ *   │   └── material/
+ *   │       └── example.md
+ *   └── zh/
+ *       └── (same files)
+ *
+ * In development: source at qtype/src/cli/commands/repo/templates.ts
+ *                 templates at qtype/templates/
+ *                 relative path: ../../../../templates
+ *
+ * After publish: compiled output at dist/cli/commands/repo/templates.js
+ *                templates should live at <pkg>/templates/ (declared in files)
+ *                relative path: ../../../../templates (same, since dist is at pkg root)
+ */
+export function getTemplatesRoot() {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
+    const candidates = [
+        path.resolve(__dirname, '../../../../templates'), // development / after publish (dist at pkg root)
+        path.resolve(__dirname, '../../../templates'), // fallback when nesting differs
+    ];
+    for (const c of candidates) {
+        if (fs.existsSync(c) && fs.statSync(c).isDirectory())
+            return c;
+    }
+    throw new Error(`Templates directory not found. Tried:\n  ${candidates.join('\n  ')}\nMake sure the qtype package includes templates/.`);
+}
+/**
+ * Reduce a full BCP 47 language code (or legacy short code) to the short
+ * form used as a templates/examples directory name. `zh-CN` / `zh` → `zh`;
+ * `en-US` / `en` → `en`; anything else → `en`.
+ */
+function toShortLang(lang) {
+    if (lang === 'zh' || lang === 'zh-CN')
+        return 'zh';
+    return 'en';
+}
+/**
+ * Resolve the language-specific template directory (templates/<lang>/).
+ *
+ * Accepts BCP 47 codes (`zh-CN` / `en-US`) or short codes (`zh` / `en`);
+ * both map to the same directory since template folders are named by the
+ * short code. Falls back to `en` when the requested language directory
+ * doesn't exist.
+ */
+export function getTemplatesDir(lang = 'en') {
+    const root = getTemplatesRoot();
+    const short = toShortLang(lang);
+    const preferred = path.join(root, short);
+    if (fs.existsSync(preferred) && fs.statSync(preferred).isDirectory()) {
+        return preferred;
+    }
+    const fallback = path.join(root, 'en');
+    if (fs.existsSync(fallback) && fs.statSync(fallback).isDirectory()) {
+        return fallback;
+    }
+    throw new Error(`Templates language directory not found: ${preferred} (no en/ fallback either).`);
+}
+/**
+ * Read a template file with {{placeholder}} substitution.
+ */
+export function readTemplate(templatesDir, relName, vars = {}) {
+    const filePath = path.join(templatesDir, relName);
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`Template file not found: ${filePath}`);
+    }
+    let content = fs.readFileSync(filePath, 'utf8');
+    for (const [key, value] of Object.entries(vars)) {
+        content = content.replaceAll(`{{${key}}}`, value);
+    }
+    return content;
+}
+/**
+ * List all filenames in the templates directory (non-recursive).
+ */
+export function listTemplateFiles(templatesDir) {
+    return fs.readdirSync(templatesDir);
+}

package/dist/cli/i18n/index.js

@@ -0,0 +1,141 @@
+/**
+ * CLI i18n: dictionary lookup + runtime locale detection + per-command injection.
+ *
+ * ## Locale detection priority (high → low)
+ *   1. `setLocale(value)` set at runtime (--lang flag)
+ *   2. `$QTYPE_LANG` env var (app-specific temporary override)
+ *   3. `~/.config/qtype/config.json` `cli.lang` field (explicit user preference)
+ *   4. `$LC_ALL` / `$LC_MESSAGES` / `$LANG` (system default locale)
+ *   5. Default `'en-US'`
+ *
+ * Locale identifiers are BCP 47 (`zh-CN` / `en-US`) throughout. Legacy
+ * short codes (`zh` / `en`) coming from any user-facing input — CLI
+ * flags, env vars, config files, POSIX $LANG — are normalised at the
+ * boundary via `normalizeLocale()`. Never pass a short code past that
+ * gate.
+ *
+ * ## Why i18n doesn't go through the shared config system
+ *
+ * i18n is "the lowest layer" — every command module imports it. But the
+ * store system's bootstrap (creating `userKv` / `repoKv` instances) happens
+ * at CLI startup, after module import. To break the cycle, locale detection
+ * here reads the JSON file directly, bypassing `#store`. This doesn't
+ * conflict with other modules reading config via `#store` — i18n is
+ * self-contained at its own layer.
+ *
+ * ## Dictionary sources
+ *   - `shared.ts` — keys shared across commands (`opt.help` / `msg.port.invalid`...)
+ *   - Each command module's `messages: { 'zh-CN', 'en-US' }` field
+ *     → merged in via `extend()` during registry mount
+ *
+ * Merge strategy: later writes overwrite earlier. Command-internal keys
+ * should use the `<group>.<cmd>.<item>` namespace to avoid collisions.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { zhCN, enUS } from './shared.js';
+// Mutable dictionaries: initialized from shared, then merged with each
+// CommandModule's own `messages` at mount time (via extend()).
+const dicts = {
+    'zh-CN': { ...zhCN },
+    'en-US': { ...enUS },
+};
+/**
+ * Normalise arbitrary user-supplied language input to a canonical BCP 47
+ * locale. Accepts both short codes (`zh` / `en`) — carried over from old
+ * config files, CLI habit, and POSIX $LANG output — and full tags
+ * (`zh-CN` / `en-US`). Returns `null` for anything else.
+ */
+export function normalizeLocale(v) {
+    if (v === 'zh' || v === 'zh-CN')
+        return 'zh-CN';
+    if (v === 'en' || v === 'en-US')
+        return 'en-US';
+    return null;
+}
+/**
+ * Extend the dictionaries (merging command-module messages).
+ *
+ * Later writes overwrite earlier. Command modules should namespace their
+ * keys with dot-separators to avoid collisions.
+ */
+export function extend(messages) {
+    for (const loc of Object.keys(messages)) {
+        const src = messages[loc];
+        if (!src)
+            continue;
+        for (const [k, v] of Object.entries(src)) {
+            if (typeof v === 'string')
+                dicts[loc][k] = v;
+        }
+    }
+}
+// ─── locale detection ───────────────────────────────────
+function detectLocaleFromAppEnv() {
+    return normalizeLocale(process.env.QTYPE_LANG);
+}
+function detectLocaleFromConfig() {
+    // Read ~/.config/qtype/config.json directly, bypassing the config system
+    // (to avoid circular dependency — see top-of-file comment). Follows the
+    // XDG Base Directory spec.
+    try {
+        const xdg = process.env.XDG_CONFIG_HOME;
+        const base = xdg && xdg.length > 0 ? xdg : path.join(os.homedir(), '.config');
+        const filePath = path.join(base, 'qtype', 'config.json');
+        if (!fs.existsSync(filePath))
+            return null;
+        const text = fs.readFileSync(filePath, 'utf8').trim();
+        if (!text)
+            return null;
+        const data = JSON.parse(text);
+        if (data == null || typeof data !== 'object' || Array.isArray(data))
+            return null;
+        const cli = data.cli;
+        if (cli != null && typeof cli === 'object' && !Array.isArray(cli)) {
+            return normalizeLocale(cli.lang);
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function detectLocaleFromSystemLocale() {
+    const lc = process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || '';
+    if (/^zh/i.test(lc))
+        return 'zh-CN';
+    if (/^en/i.test(lc))
+        return 'en-US';
+    return null;
+}
+function detectInitialLocale() {
+    return (detectLocaleFromAppEnv() ??
+        detectLocaleFromConfig() ??
+        detectLocaleFromSystemLocale() ??
+        'en-US');
+}
+let currentLocale = detectInitialLocale();
+export function getLocale() {
+    return currentLocale;
+}
+/** Set locale at runtime (used by the --lang option). */
+export function setLocale(locale) {
+    currentLocale = locale;
+}
+/**
+ * Translation function.
+ * - When the key is missing: fall back to zh-CN, then to the key itself
+ *   (debug-friendly)
+ * - Supports `{name}` placeholders
+ */
+export function t(key, vars) {
+    const dict = dicts[currentLocale];
+    let msg = dict[key] ?? dicts['zh-CN'][key] ?? key;
+    if (vars) {
+        for (const [k, v] of Object.entries(vars)) {
+            msg = msg.replaceAll(`{${k}}`, String(v));
+        }
+    }
+    return msg;
+}