next-tongue 0.9.6 → 0.9.8

package/dist/cli/check-types.d.ts

@@ -1,4 +1,4 @@
-export type CheckKind = 'missing' | 'unused' | 'undefined' | 'mismatch' | 'syntax' | 'stale' | 'a11y' | 'bidi' | 'length' | 'duplicate';
+export type CheckKind = 'missing' | 'unused' | 'undefined' | 'dynamic' | 'mismatch' | 'syntax' | 'stale' | 'a11y' | 'bidi' | 'length' | 'duplicate' | 'icu';
 export type CheckSeverity = 'error' | 'warn';
 export type CheckIssue = {
     check: CheckKind;

package/dist/cli/extract.js

@@ -3,7 +3,7 @@ import * as readline from 'node:readline';
 import { loadConfig } from '../config/load-config.js';
 import { buildMessages } from '../compiler/build.js';
 import { loadLocaleMessages, resolveMessagePath } from '../compiler/load-messages.js';
-import { scanReferencedKeys } from '../compiler/scan-keys.js';
+import { DEFAULT_SCAN_ROOTS, scanReferencedKeys, } from '../compiler/scan-keys.js';
 import { TongueError } from '../errors.js';
 export async function cmdExtract(opts) {
     const { config, cwd } = await loadConfig({
@@ -15,7 +15,9 @@ export async function cmdExtract(opts) {
     }
     const roots = opts.include
         ? opts.include.split(',').map((s) => s.trim()).filter(Boolean)
-        : ['app', 'src', 'components'];
+        : config.scan.include.length > 0
+            ? [...config.scan.include]
+            : [...DEFAULT_SCAN_ROOTS];
     const refs = await scanReferencedKeys(cwd, roots);
     const used = new Set(refs.map((r) => r.fullKey));
     const catalogs = await loadLocaleMessages(config, cwd);

package/dist/client/index.js

@@ -88,7 +88,7 @@ export function useT(namespace) {
  */
 function createLoaderStubT(locale, ns) {
     const fail = (kind) => {
-        throw new TongueError('TONGUE_E_NO_PROVIDER', `useT('${ns}') ${kind} was not rewritten to a per-key import. Ensure withTongue() is applied (loader on SSR + client). Prefer getT on the server for static copy; for dynamic keys use t.dynamic(key, { from: [...] }) so the loader can import those keys.`);
+        throw new TongueError('TONGUE_E_NO_PROVIDER', `useT('${ns}') ${kind} was not rewritten to a per-key import. Ensure withTongue() is applied (loader on SSR + client). Prefer getT on the server for static copy; for dynamic keys use t.dynamic(key, { from: [...] }) with an inline array or a same-file const (imported from arrays are not rewritten).`);
     };
     const t = Object.assign((..._args) => fail('t()'), {
         rich: () => fail('t.rich()'),

package/dist/compiler/build.js

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { mkdir, readFile, writeFile, rm } from 'node:fs/promises';
+import { mkdir, readFile, rename, writeFile, rm } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { TongueError } from '../errors.js';
 import { collectArgs } from './ast.js';
@@ -16,7 +16,9 @@ import { scanAppRoutes } from './scan-routes.js';
 import { loadAndMergeSources, writeSourcesCache } from './sources.js';
 export async function buildMessages(options) {
     const { config, cwd } = options;
-    const outDir = resolve(cwd, config.outDir);
+    /** Final `.tongue` path; may briefly point at a staging dir while writing. */
+    let outDir = resolve(cwd, config.outDir);
+    const publishedOutDir = outDir;
     const fileCatalogs = await loadLocaleMessages(config, cwd);
     const { catalogs, payloads: sourcePayloads } = await loadAndMergeSources(config, cwd, fileCatalogs);
     const defaultCatalog = catalogs[config.defaultLocale];
@@ -111,7 +113,8 @@ export async function buildMessages(options) {
     const defaultMsgRel = config.messages.replaceAll('{locale}', config.defaultLocale);
     const emitLocales = localesForEmit(config);
     // Content hash for idempotency (bump CODEGEN_VERSION when emit format changes)
-    const CODEGEN_VERSION = 7;
+    // Bump when emit shape changes (incl. reserved-key ident sanitization).
+    const CODEGEN_VERSION = 8;
     const hash = createHash('sha256')
         .update(JSON.stringify({
         codegen: CODEGEN_VERSION,
@@ -138,11 +141,15 @@ export async function buildMessages(options) {
             /* rebuild */
         }
     }
-    await rm(outDir, { recursive: true, force: true });
+    // Write into a staging dir, then atomically replace `.tongue` (avoids ENOTEMPTY
+    // when the previous tree is partially locked by the bundler / another build).
+    const staging = `${publishedOutDir}.tmp-${process.pid}`;
+    await clearOutputDir(staging);
+    outDir = staging;
     await mkdir(join(outDir, 'msg'), { recursive: true });
     await mkdir(join(outDir, 'ns'), { recursive: true });
     if (sourcePayloads.length) {
-        await writeSourcesCache(cwd, config.outDir, sourcePayloads);
+        await writeSourcesCache(cwd, staging, sourcePayloads);
     }
     // Shared rich-text helpers (imported by per-key modules that contain tags)
     await writeFile(join(outDir, 'rich.js'), [
@@ -398,9 +405,17 @@ export async function buildMessages(options) {
         ])),
     };
     await writeFile(join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
-    await writeFile(hashPath, hash, 'utf8');
+    await writeFile(join(outDir, '.hash'), hash, 'utf8');
     // package.json imports helper note — apps map "#tongue/*" themselves / via withTongue
     await writeFile(join(outDir, 'README.md'), 'Generated by next-tongue. Do not edit. Map `#tongue/*` → this directory.\nImport `#tongue/runtime` and call `ensureTongue()` once per process.\n', 'utf8');
+    await clearOutputDir(publishedOutDir);
+    try {
+        await rename(outDir, publishedOutDir);
+    }
+    catch (err) {
+        throw new TongueError('TONGUE_E_IO', `Cannot publish ${publishedOutDir} from staging (${err instanceof Error ? err.message : err}). Delete ${publishedOutDir} and any \`${config.outDir}.tmp-*\` dirs, then re-run tongue build.`, { file: publishedOutDir });
+    }
+    outDir = publishedOutDir;
     return {
         outDir,
         locales: emitLocales,
@@ -409,6 +424,34 @@ export async function buildMessages(options) {
         hash,
     };
 }
+/** Remove a directory tree; on ENOTEMPTY/EBUSY, retry then rename-aside. */
+async function clearOutputDir(path) {
+    for (let i = 0; i < 6; i++) {
+        try {
+            await rm(path, { recursive: true, force: true });
+            return;
+        }
+        catch (err) {
+            const code = err?.code;
+            if (code !== 'ENOTEMPTY' && code !== 'EBUSY' && code !== 'EPERM') {
+                if (code === 'ENOENT')
+                    return;
+                throw err;
+            }
+            await new Promise((r) => setTimeout(r, 40 * (i + 1)));
+        }
+    }
+    const trash = `${path}.trash-${process.pid}-${Date.now()}`;
+    try {
+        await rename(path, trash);
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return;
+        throw new TongueError('TONGUE_E_IO', `Cannot clear ${path} (${err instanceof Error ? err.message : err}). Delete it manually and re-run tongue build.`, { file: path });
+    }
+    void rm(trash, { recursive: true, force: true }).catch(() => { });
+}
 /** Locales written into message modules / types (includes pseudo when enabled). */
 export function localesForEmit(config) {
     if (!config.pseudo || config.pseudo.enabled === false)

package/dist/compiler/codegen/emit-js.d.ts

@@ -26,5 +26,5 @@ export declare function emitRichMessageFunction(exportName: string, ast: Message
 }): string;
 /** True when the AST contains at least one rich tag. */
 export declare function hasTags(ast: MessageAst): boolean;
-/** Safe JS identifier from a message key. */
+/** Safe JS identifier from a message key (e.g. `continue` → `continue_`). */
 export declare function safeIdent(key: string): string;

package/dist/compiler/codegen/emit-js.js

@@ -342,10 +342,65 @@ function stringifyAstAsConstant(ast) {
     }
     return out;
 }
-/** Safe JS identifier from a message key. */
+/** ECMAScript reserved words / strict-mode reserved — unsafe as bare identifiers. */
+const RESERVED_IDENTS = new Set([
+    'arguments',
+    'await',
+    'break',
+    'case',
+    'catch',
+    'class',
+    'const',
+    'continue',
+    'debugger',
+    'default',
+    'delete',
+    'do',
+    'else',
+    'enum',
+    'eval',
+    'export',
+    'extends',
+    'false',
+    'finally',
+    'for',
+    'function',
+    'if',
+    'implements',
+    'import',
+    'in',
+    'instanceof',
+    'interface',
+    'let',
+    'new',
+    'null',
+    'package',
+    'private',
+    'protected',
+    'public',
+    'return',
+    'static',
+    'super',
+    'switch',
+    'this',
+    'throw',
+    'true',
+    'try',
+    'typeof',
+    'var',
+    'void',
+    'while',
+    'with',
+    'yield',
+]);
+/** Safe JS identifier from a message key (e.g. `continue` → `continue_`). */
 export function safeIdent(key) {
-    const cleaned = key.replace(/[^A-Za-z0-9_]/g, '_');
+    let cleaned = key.replace(/[^A-Za-z0-9_]/g, '_');
+    if (!cleaned)
+        cleaned = '_';
     if (/^[0-9]/.test(cleaned))
-        return `_${cleaned}`;
-    return cleaned || '_';
+        cleaned = `_${cleaned}`;
+    if (RESERVED_IDENTS.has(cleaned))
+        cleaned = `${cleaned}_`;
+    return cleaned;
 }

package/dist/compiler/dynamic-from.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Resolve `t.dynamic(key, { from })` key lists for the call-site loader and
+ * `tongue check` scan. Supports:
+ *   - inline arrays: `{ from: ['a', 'b'] }`
+ *   - same-file const arrays: `const X = ['a', 'b']; { from: X }`
+ *   - Object.values of same-file const objects: `{ from: Object.values(BTN_KEYS) }`
+ *
+ * Imported / computed `from` expressions are not resolved (left as stubs).
+ */
+export declare function extractStringLiterals(body: string): string[];
+/** Take a balanced `[...]` / `{...}` / `(...)` starting at `source[start]`. */
+export declare function takeBalanced(source: string, start: number, open: string, close: string): string | null;
+/**
+ * Resolve keys from a `from` expression text (already sliced out of the call).
+ * Returns null when the expression cannot be resolved statically in-file.
+ */
+export declare function resolveFromKeys(fileSource: string, fromExpr: string): string[] | null;
+export type DynamicCallSite = {
+    /** Start of `t.dynamic` */
+    start: number;
+    /** End after closing `)` */
+    end: number;
+    keyExpr: string;
+    fromExpr: string;
+    valuesExpr: string | null;
+    keys: string[] | null;
+};
+/**
+ * Find `varName.dynamic(...)` call sites and resolve their `from` keys.
+ */
+export declare function findDynamicCalls(source: string, varName: string): DynamicCallSite[];

package/dist/compiler/dynamic-from.js

@@ -0,0 +1,240 @@
+/**
+ * Resolve `t.dynamic(key, { from })` key lists for the call-site loader and
+ * `tongue check` scan. Supports:
+ *   - inline arrays: `{ from: ['a', 'b'] }`
+ *   - same-file const arrays: `const X = ['a', 'b']; { from: X }`
+ *   - Object.values of same-file const objects: `{ from: Object.values(BTN_KEYS) }`
+ *
+ * Imported / computed `from` expressions are not resolved (left as stubs).
+ */
+export function extractStringLiterals(body) {
+    return [...body.matchAll(/['"]([^'"]+)['"]/g)].map((m) => m[1]);
+}
+/** Take a balanced `[...]` / `{...}` / `(...)` starting at `source[start]`. */
+export function takeBalanced(source, start, open, close) {
+    if (source[start] !== open)
+        return null;
+    let depth = 0;
+    let inStr = null;
+    let escape = false;
+    for (let i = start; i < source.length; i++) {
+        const c = source[i];
+        if (inStr) {
+            if (escape) {
+                escape = false;
+                continue;
+            }
+            if (c === '\\' && inStr !== '`') {
+                escape = true;
+                continue;
+            }
+            if (c === inStr)
+                inStr = null;
+            continue;
+        }
+        if (c === '"' || c === "'" || c === '`') {
+            inStr = c;
+            continue;
+        }
+        if (c === open)
+            depth++;
+        else if (c === close) {
+            depth--;
+            if (depth === 0)
+                return source.slice(start, i + 1);
+        }
+    }
+    return null;
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Index of `ident`'s `const|let|var` initializer expression, or -1. */
+function findDeclInit(source, ident) {
+    const re = new RegExp(`(?:const|let|var)\\s+${escapeRegExp(ident)}\\s*=\\s*`, 'g');
+    const m = re.exec(source);
+    return m ? m.index + m[0].length : -1;
+}
+function skipWs(source, i) {
+    while (/\s/.test(source[i] ?? ''))
+        i++;
+    return i;
+}
+function resolveConstArrayKeys(source, ident) {
+    const init = findDeclInit(source, ident);
+    if (init < 0)
+        return null;
+    const arr = takeBalanced(source, skipWs(source, init), '[', ']');
+    if (!arr)
+        return null;
+    return extractStringLiterals(arr.slice(1, -1));
+}
+function resolveObjectValueKeys(source, ident) {
+    const init = findDeclInit(source, ident);
+    if (init < 0)
+        return null;
+    // Type assertions (`as const`) sit after the literal; object is first.
+    const obj = takeBalanced(source, skipWs(source, init), '{', '}');
+    if (!obj)
+        return null;
+    return [...obj.matchAll(/:\s*['"]([^'"]+)['"]/g)].map((m) => m[1]);
+}
+/**
+ * Resolve keys from a `from` expression text (already sliced out of the call).
+ * Returns null when the expression cannot be resolved statically in-file.
+ */
+export function resolveFromKeys(fileSource, fromExpr) {
+    const trimmed = fromExpr.trim();
+    if (!trimmed)
+        return null;
+    if (trimmed.startsWith('[')) {
+        const arr = takeBalanced(trimmed, 0, '[', ']');
+        if (!arr)
+            return null;
+        return extractStringLiterals(arr.slice(1, -1));
+    }
+    const ov = /^Object\.values\(\s*([A-Za-z_$][\w$]*)\s*\)$/.exec(trimmed);
+    if (ov) {
+        const keys = resolveObjectValueKeys(fileSource, ov[1]);
+        return keys && keys.length > 0 ? keys : null;
+    }
+    if (/^[A-Za-z_$][\w$]*$/.test(trimmed)) {
+        const keys = resolveConstArrayKeys(fileSource, trimmed);
+        return keys && keys.length > 0 ? keys : null;
+    }
+    return null;
+}
+/**
+ * Find `varName.dynamic(...)` call sites and resolve their `from` keys.
+ */
+export function findDynamicCalls(source, varName) {
+    const re = new RegExp(`\\b${escapeRegExp(varName)}\\.dynamic\\s*\\(`, 'g');
+    const out = [];
+    let m;
+    while ((m = re.exec(source)) !== null) {
+        const openParen = m.index + m[0].length - 1;
+        const parsed = parseDynamicArgs(source, openParen);
+        if (!parsed)
+            continue;
+        const keys = resolveFromKeys(source, parsed.fromExpr);
+        out.push({
+            start: m.index,
+            end: parsed.closeParen + 1,
+            keyExpr: parsed.keyExpr,
+            fromExpr: parsed.fromExpr,
+            valuesExpr: parsed.valuesExpr,
+            keys,
+        });
+    }
+    return out;
+}
+function parseDynamicArgs(source, openParen) {
+    let i = openParen + 1;
+    while (/\s/.test(source[i] ?? ''))
+        i++;
+    const keyStart = i;
+    i = scanArgEnd(source, i);
+    if (i < 0 || source[i] !== ',')
+        return null;
+    const keyExpr = source.slice(keyStart, i).trim();
+    i++;
+    while (/\s/.test(source[i] ?? ''))
+        i++;
+    if (source[i] !== '{')
+        return null;
+    const opts = takeBalanced(source, i, '{', '}');
+    if (!opts)
+        return null;
+    const optsEnd = i + opts.length;
+    const fromExpr = extractFromProp(opts);
+    if (fromExpr == null)
+        return null;
+    i = optsEnd;
+    while (/\s/.test(source[i] ?? ''))
+        i++;
+    let valuesExpr = null;
+    if (source[i] === ',') {
+        i++;
+        while (/\s/.test(source[i] ?? ''))
+            i++;
+        const valuesStart = i;
+        i = scanArgEnd(source, i);
+        if (i < 0)
+            return null;
+        valuesExpr = source.slice(valuesStart, i).trim() || null;
+    }
+    while (/\s/.test(source[i] ?? ''))
+        i++;
+    if (source[i] !== ')')
+        return null;
+    return { keyExpr, fromExpr, valuesExpr, closeParen: i };
+}
+/** Scan to next top-level `,` or `)` (not inside strings/brackets). */
+function scanArgEnd(source, start) {
+    let depthParen = 0;
+    let depthBracket = 0;
+    let depthBrace = 0;
+    let inStr = null;
+    let escape = false;
+    for (let i = start; i < source.length; i++) {
+        const c = source[i];
+        if (inStr) {
+            if (escape) {
+                escape = false;
+                continue;
+            }
+            if (c === '\\' && inStr !== '`') {
+                escape = true;
+                continue;
+            }
+            if (c === inStr)
+                inStr = null;
+            continue;
+        }
+        if (c === '"' || c === "'" || c === '`') {
+            inStr = c;
+            continue;
+        }
+        if (c === '(')
+            depthParen++;
+        else if (c === ')') {
+            if (depthParen === 0 && depthBracket === 0 && depthBrace === 0)
+                return i;
+            depthParen--;
+        }
+        else if (c === '[')
+            depthBracket++;
+        else if (c === ']')
+            depthBracket--;
+        else if (c === '{')
+            depthBrace++;
+        else if (c === '}')
+            depthBrace--;
+        else if (c === ',' &&
+            depthParen === 0 &&
+            depthBracket === 0 &&
+            depthBrace === 0) {
+            return i;
+        }
+    }
+    return -1;
+}
+function extractFromProp(optsLiteral) {
+    // optsLiteral includes surrounding braces
+    const inner = optsLiteral.slice(1, -1);
+    const fromIdx = /\bfrom\s*:/.exec(inner);
+    if (!fromIdx)
+        return null;
+    let i = fromIdx.index + fromIdx[0].length;
+    while (/\s/.test(inner[i] ?? ''))
+        i++;
+    if (inner[i] === '[') {
+        const arr = takeBalanced(inner, i, '[', ']');
+        return arr;
+    }
+    const ov = /^Object\.values\(\s*[A-Za-z_$][\w$]*\s*\)/.exec(inner.slice(i));
+    if (ov)
+        return ov[0];
+    const id = /^[A-Za-z_$][\w$]*/.exec(inner.slice(i));
+    return id ? id[0] : null;
+}

package/dist/compiler/scan-keys.d.ts

@@ -5,6 +5,13 @@ export type ReferencedKey = {
     file: string;
     line: number;
 };
+export type UndeclaredDynamic = {
+    file: string;
+    line: number;
+    /** Translator binding, e.g. `t` */
+    name: string;
+    namespace: string;
+};
 export type ScanResult = {
     refs: ReferencedKey[];
     /**
@@ -12,13 +19,20 @@ export type ScanResult = {
      * unused-key warnings for these namespaces are suppressed.
      */
     dynamicNamespaces: Set<string>;
+    /**
+     * Client `useT` + `t(variable)` without `t.dynamic` — runtime stub will throw.
+     * Server `getT` non-literals are OK (whole namespace is loaded).
+     */
+    undeclaredDynamics: UndeclaredDynamic[];
 };
+/** Default directories scanned by `tongue check` / `extract`. */
+export declare const DEFAULT_SCAN_ROOTS: readonly ["app", "src", "components", "lib", "server", "actions"];
 /**
  * Find `t('key')` / `t.rich('key')` under a known `useT`/`getT` namespace,
  * plus `t.dynamic(..., { from })` declared keys and dynamic `t(var)` markers.
  */
-export declare function scanReferencedKeys(cwd: string, roots?: string[]): Promise<ReferencedKey[]>;
-export declare function scanKeys(cwd: string, roots?: string[]): Promise<ScanResult>;
+export declare function scanReferencedKeys(cwd: string, roots?: readonly string[]): Promise<ReferencedKey[]>;
+export declare function scanKeys(cwd: string, roots?: readonly string[]): Promise<ScanResult>;
 /** Strip // and /* *\/ comments; preserve newlines for line numbers. */
 export declare function stripComments(source: string): string;
 export declare function extractFromSource(source: string, file: string): ScanResult;

package/dist/compiler/scan-keys.js

@@ -1,5 +1,15 @@
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { join, relative } from 'node:path';
+import { findDynamicCalls } from './dynamic-from.js';
+/** Default directories scanned by `tongue check` / `extract`. */
+export const DEFAULT_SCAN_ROOTS = [
+    'app',
+    'src',
+    'components',
+    'lib',
+    'server',
+    'actions',
+];
 const SOURCE_EXT = new Set(['.ts', '.tsx', '.js', '.jsx', '.mdx']);
 const SKIP_DIRS = new Set([
     'node_modules',
@@ -14,10 +24,10 @@ const SKIP_DIRS = new Set([
  * Find `t('key')` / `t.rich('key')` under a known `useT`/`getT` namespace,
  * plus `t.dynamic(..., { from })` declared keys and dynamic `t(var)` markers.
  */
-export async function scanReferencedKeys(cwd, roots = ['app', 'src', 'components']) {
+export async function scanReferencedKeys(cwd, roots = DEFAULT_SCAN_ROOTS) {
     return (await scanKeys(cwd, roots)).refs;
 }
-export async function scanKeys(cwd, roots = ['app', 'src', 'components']) {
+export async function scanKeys(cwd, roots = DEFAULT_SCAN_ROOTS) {
     const files = [];
     for (const root of roots) {
         const abs = join(cwd, root);
@@ -32,6 +42,7 @@ export async function scanKeys(cwd, roots = ['app', 'src', 'components']) {
     }
     const refs = [];
     const dynamicNamespaces = new Set();
+    const undeclaredDynamics = [];
     for (const file of files) {
         const src = await readFile(file, 'utf8');
         const rel = relative(cwd, file);
@@ -39,8 +50,9 @@ export async function scanKeys(cwd, roots = ['app', 'src', 'components']) {
         refs.push(...part.refs);
         for (const ns of part.dynamicNamespaces)
             dynamicNamespaces.add(ns);
+        undeclaredDynamics.push(...part.undeclaredDynamics);
     }
-    return { refs, dynamicNamespaces };
+    return { refs, dynamicNamespaces, undeclaredDynamics };
 }
 async function walk(dir, out) {
     const entries = await readdir(dir, { withFileTypes: true });
@@ -128,12 +140,16 @@ export function extractFromSource(source, file) {
     const code = stripComments(source);
     const out = [];
     const dynamicNamespaces = new Set();
-    const translators = new Map(); // var → ns
+    const undeclaredDynamics = [];
+    const translators = new Map();
     // useT('ns') | getT('ns') | getT(locale, 'ns')
-    const declRe = /(?:const|let|var)\s+(\w+)\s*=\s*(?:await\s+)?(?:useT|getT)\s*\(\s*(?:[^'"\n,]+,\s*)?(['"])([^'"]*)\2\s*\)/g;
+    const declRe = /(?:const|let|var)\s+(\w+)\s*=\s*(?:await\s+)?(useT|getT)\s*\(\s*(?:[^'"\n,]+,\s*)?(['"])([^'"]*)\3\s*\)/g;
     let m;
     while ((m = declRe.exec(code)) !== null) {
-        translators.set(m[1], m[3] || '_root');
+        translators.set(m[1], {
+            ns: m[4] || '_root',
+            kind: m[2],
+        });
     }
     const push = (ns, key, index) => {
         const fullKey = ns === '_root' || ns === '' ? key : `${ns}.${key}`;
@@ -145,23 +161,18 @@ export function extractFromSource(source, file) {
             line: lineAt(code, index),
         });
     };
-    for (const [varName, ns] of translators) {
+    for (const [varName, { ns, kind }] of translators) {
         // Literal t('key') / t.rich('key')
         const callRe = new RegExp(`\\b${escapeRegExp(varName)}(?:\\.rich)?\\s*\\(\\s*(['"])([^'"]+)\\1`, 'g');
         let cm;
         while ((cm = callRe.exec(code)) !== null) {
             push(ns, cm[2], cm.index);
         }
-        // t.dynamic(any, { from: ['a', 'b'] }) — only `from` keys become refs
-        const dynRe = new RegExp(`\\b${escapeRegExp(varName)}\\.dynamic\\s*\\(`, 'g');
-        let dm;
-        while ((dm = dynRe.exec(code)) !== null) {
-            const tail = code.slice(dm.index, dm.index + 400);
-            const fromMatch = /from\s*:\s*\[([^\]]*)\]/.exec(tail);
-            if (fromMatch) {
-                const keys = fromMatch[1].match(/['"]([^'"]+)['"]/g) ?? [];
-                for (const raw of keys) {
-                    push(ns, raw.slice(1, -1), dm.index);
+        // t.dynamic(any, { from }) — only resolvable `from` keys become refs
+        for (const call of findDynamicCalls(code, varName)) {
+            if (call.keys) {
+                for (const key of call.keys) {
+                    push(ns, key, call.start);
                 }
             }
             dynamicNamespaces.add(ns || '_root');
@@ -172,14 +183,28 @@ export function extractFromSource(source, file) {
         while ((nm = nsRe.exec(code)) !== null) {
             dynamicNamespaces.add(nm[2] || '_root');
         }
-        // Non-literal t(var) — suppress unused for the namespace only.
+        // Non-literal t(var) — suppress unused for the namespace.
+        // Client useT stubs throw — report each site. Server getT is fine.
         // Do NOT harvest unrelated string arrays (cache tags, sort keys, …).
         const nonLitRe = new RegExp(`\\b${escapeRegExp(varName)}(?:\\.rich)?\\s*\\(\\s*(?!['"])([A-Za-z_$][\\w$]*)`, 'g');
-        if (nonLitRe.test(code)) {
+        let nl;
+        let sawNonLit = false;
+        while ((nl = nonLitRe.exec(code)) !== null) {
+            sawNonLit = true;
+            if (kind === 'useT') {
+                undeclaredDynamics.push({
+                    file,
+                    line: lineAt(code, nl.index),
+                    name: varName,
+                    namespace: ns || '_root',
+                });
+            }
+        }
+        if (sawNonLit) {
             dynamicNamespaces.add(ns || '_root');
         }
     }
-    return { refs: out, dynamicNamespaces };
+    return { refs: out, dynamicNamespaces, undeclaredDynamics };
 }
 function lineAt(source, index) {
     let line = 1;

package/dist/compiler/validate/catalog.d.ts

@@ -20,3 +20,5 @@ export type TongueLock = {
 export declare function validateStale(config: ResolvedTongueConfig, cwd: string, opts?: {
     locales?: readonly string[];
 }): Promise<CheckIssue[]>;
+/** Letter + single quote + letter — usually meant as prose apostrophe, not ICU quote. */
+export declare function likelyUnescapedApostrophe(icu: string): boolean;

package/dist/compiler/validate/catalog.js

@@ -69,6 +69,17 @@ export async function validateCatalog(config, cwd, opts) {
                 });
                 continue;
             }
+            if (likelyUnescapedApostrophe(source)) {
+                issues.push({
+                    check: 'icu',
+                    severity: 'warn',
+                    message: `Key "${fullKey}" looks like a natural-language apostrophe (e.g. French). In ICU, double it: "l''été" → l'été`,
+                    key: fullKey,
+                    locale: config.defaultLocale,
+                    file,
+                    ...(line != null ? { line } : {}),
+                });
+            }
             const defaultArgs = collectArgs(defaultAst);
             for (const locale of locales) {
                 if (locale === config.defaultLocale)
@@ -224,3 +235,15 @@ export async function validateStale(config, cwd, opts) {
     }
     return issues;
 }
+/** Letter + single quote + letter — usually meant as prose apostrophe, not ICU quote. */
+export function likelyUnescapedApostrophe(icu) {
+    for (let i = 0; i < icu.length - 2; i++) {
+        const a = icu[i];
+        const b = icu[i + 1];
+        const c = icu[i + 2];
+        if (b === "'" && /[A-Za-zÀ-ÿ]/.test(a) && /[A-Za-zÀ-ÿ]/.test(c)) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/compiler/validate/usage.d.ts

@@ -1,4 +1,4 @@
 import type { ResolvedTongueConfig } from '../../config/types.js';
 import type { CheckIssue } from '../../cli/check-types.js';
-/** unused + undefined checks against scanned source references. */
+/** unused + undefined + undeclared client dynamic checks against scanned source. */
 export declare function validateUsage(config: ResolvedTongueConfig, cwd: string): Promise<CheckIssue[]>;

package/dist/compiler/validate/usage.js

@@ -1,5 +1,5 @@
 import { loadLocaleMessages } from '../load-messages.js';
-import { scanKeys } from '../scan-keys.js';
+import { DEFAULT_SCAN_ROOTS, scanKeys } from '../scan-keys.js';
 function severityFor(level, alwaysError = false) {
     if (alwaysError)
         return 'error';
@@ -11,7 +11,26 @@ function namespaceOf(fullKey) {
     const i = fullKey.indexOf('.');
     return i === -1 ? '_root' : fullKey.slice(0, i);
 }
-/** unused + undefined checks against scanned source references. */
+/** Glob-lite: `*` matches any substring (e.g. `common.*`, `*.seeAll`). */
+function matchesIgnore(fullKey, patterns) {
+    for (const raw of patterns) {
+        const p = raw.trim();
+        if (!p)
+            continue;
+        if (p === fullKey)
+            return true;
+        if (!p.includes('*'))
+            continue;
+        const re = new RegExp(`^${p
+            .split('*')
+            .map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+            .join('.*')}$`);
+        if (re.test(fullKey))
+            return true;
+    }
+    return false;
+}
+/** unused + undefined + undeclared client dynamic checks against scanned source. */
 export async function validateUsage(config, cwd) {
     const issues = [];
     const catalogs = await loadLocaleMessages(config, cwd);
@@ -24,7 +43,8 @@ export async function validateUsage(config, cwd) {
             defined.add(ns === '_root' ? key : `${ns}.${key}`);
         }
     }
-    const { refs, dynamicNamespaces } = await scanKeys(cwd);
+    const roots = config.scan.include.length > 0 ? config.scan.include : DEFAULT_SCAN_ROOTS;
+    const { refs, dynamicNamespaces, undeclaredDynamics } = await scanKeys(cwd, roots);
     const used = new Set();
     for (const ref of refs) {
         used.add(ref.fullKey);
@@ -39,11 +59,23 @@ export async function validateUsage(config, cwd) {
             });
         }
     }
+    for (const site of undeclaredDynamics) {
+        issues.push({
+            check: 'dynamic',
+            severity: 'error',
+            message: `useT('${site.namespace}') ${site.name}(variable) is not a string literal — use ${site.name}.dynamic(key, { from: [...] }) so the loader can import keys (plain ${site.name}(var) throws at runtime on the client)`,
+            file: site.file,
+            line: site.line,
+        });
+    }
     const unusedSev = severityFor(config.strict.unused);
     if (unusedSev) {
+        const ignore = config.strict.unusedIgnore;
         for (const fullKey of defined) {
             if (used.has(fullKey))
                 continue;
+            if (matchesIgnore(fullKey, ignore))
+                continue;
             // Dynamic t(var) / t.ns / t.dynamic — do not false-flag catalog keys as unused
             if (dynamicNamespaces.has(namespaceOf(fullKey)))
                 continue;

package/dist/config/types.d.ts

@@ -55,9 +55,18 @@ export type TongueConfig = {
         list?: Record<string, Intl.ListFormatOptions>;
     };
     outDir?: string;
+    /**
+     * Directories scanned by `tongue check` / `extract` for `getT`/`useT` call sites.
+     * Defaults to app, src, components, lib, server, actions.
+     */
+    scan?: {
+        include?: string[];
+    };
     strict?: {
         missing?: StrictLevel;
         unused?: StrictLevel;
+        /** Full keys or globs (`common.*`) excluded from unused warnings. */
+        unusedIgnore?: string[];
         mismatch?: StrictLevel;
         a11y?: StrictLevel;
         bidi?: StrictLevel;
@@ -102,9 +111,13 @@ export type ResolvedTongueConfig = {
         list: Record<string, Intl.ListFormatOptions>;
     };
     outDir: string;
+    scan: {
+        include: readonly string[];
+    };
     strict: {
         missing: StrictLevel;
         unused: StrictLevel;
+        unusedIgnore: readonly string[];
         mismatch: StrictLevel;
         a11y: StrictLevel;
         bidi: StrictLevel;

package/dist/config/validate.js

@@ -127,9 +127,13 @@ export function resolveConfig(input) {
             list: input.formats?.list ?? {},
         },
         outDir: input.outDir ?? '.tongue',
+        scan: {
+            include: input.scan?.include ?? [],
+        },
         strict: {
             missing: input.strict?.missing ?? 'error',
             unused: input.strict?.unused ?? 'warn',
+            unusedIgnore: input.strict?.unusedIgnore ?? [],
             mismatch: input.strict?.mismatch ?? 'error',
             a11y: input.strict?.a11y ?? 'error',
             bidi: input.strict?.bidi ?? 'warn',

package/dist/next/loader.d.ts

@@ -6,7 +6,8 @@
  *   const t = useT('home'); t('inbox', { count })
  * into a static import of the per-key module when the key is a string literal.
  *
- * Also rewrites `t.dynamic(key, { from: [...] })` to a map of those imports.
+ * Also rewrites `t.dynamic(key, { from })` to a map of those imports when `from`
+ * is an inline array, a same-file const array, or `Object.values(sameFileConst)`.
  *
  * Escape analysis: if `t` is passed around, falls back to namespace import + warning.
  */

package/dist/next/loader.js

@@ -6,10 +6,13 @@
  *   const t = useT('home'); t('inbox', { count })
  * into a static import of the per-key module when the key is a string literal.
  *
- * Also rewrites `t.dynamic(key, { from: [...] })` to a map of those imports.
+ * Also rewrites `t.dynamic(key, { from })` to a map of those imports when `from`
+ * is an inline array, a same-file const array, or `Object.values(sameFileConst)`.
  *
  * Escape analysis: if `t` is passed around, falls back to namespace import + warning.
  */
+import { findDynamicCalls } from '../compiler/dynamic-from.js';
+import { safeIdent } from '../compiler/codegen/emit-js.js';
 const USE_T_DECL = /(?:const|let|var)\s+(\w+)\s*=\s*useT\s*\(\s*(['"])([^'"]*)\2\s*\)/g;
 export function transformCallSites(source, resourcePath, _options = {}) {
     const warnings = [];
@@ -44,16 +47,11 @@ export function transformCallSites(source, resourcePath, _options = {}) {
             imports.set(`${ns}:${key}`, { ns, key, ident });
             return full;
         });
-        // t.dynamic(expr, { from: ['a', 'b'] }, values?)
-        const dynRe = new RegExp(`\\b${escapeRegExp(varName)}\\.dynamic\\s*\\(`, 'g');
-        let dm;
-        while ((dm = dynRe.exec(withoutDirs)) !== null) {
-            const tail = withoutDirs.slice(dm.index, dm.index + 500);
-            const fromMatch = /from\s*:\s*\[([^\]]*)\]/.exec(tail);
-            if (!fromMatch)
+        // t.dynamic(expr, { from }, values?) — collect resolvable keys
+        for (const call of findDynamicCalls(withoutDirs, varName)) {
+            if (!call.keys)
                 continue;
-            const keys = [...fromMatch[1].matchAll(/['"]([^'"]+)['"]/g)].map((x) => x[1]);
-            for (const key of keys) {
+            for (const key of call.keys) {
                 const ident = safeImportIdent(ns, key);
                 imports.set(`${ns}:${key}`, { ns, key, ident });
             }
@@ -72,13 +70,14 @@ export function transformCallSites(source, resourcePath, _options = {}) {
     const localeVar = '__tongue_locale';
     // Inject locale once after the first useT declaration
     code = code.replace(/((?:const|let|var)\s+\w+\s*=\s*useT\s*\([^)]*\))/, `$1\n  const ${localeVar} = useLocale();`);
-    // Replace t.dynamic(expr, { from: [...] }, values?)
+    // Replace t.dynamic(expr, { from }, values?) — rewrite from the end so indices stay valid
     for (const [varName, ns] of translators) {
         if (escapes(withoutDirs, varName))
             continue;
-        const dynCallRe = new RegExp(`\\b${escapeRegExp(varName)}\\.dynamic\\s*\\(\\s*([^,]+?)\\s*,\\s*\\{[^}]*?from\\s*:\\s*\\[([^\\]]*)][^}]*\\}\\s*(?:,\\s*([^)]*?))?\\)`, 'g');
-        code = code.replace(dynCallRe, (_full, keyExpr, fromBody, values) => {
-            const keys = [...fromBody.matchAll(/['"]([^'"]+)['"]/g)].map((x) => x[1]);
+        const calls = findDynamicCalls(code, varName).filter((c) => c.keys && c.keys.length > 0);
+        for (let ci = calls.length - 1; ci >= 0; ci--) {
+            const call = calls[ci];
+            const keys = call.keys;
             const mapEntries = keys
                 .map((key) => {
                 const ident = safeImportIdent(ns, key);
@@ -86,11 +85,12 @@ export function transformCallSites(source, resourcePath, _options = {}) {
                 return `${JSON.stringify(key)}: ${ident}`;
             })
                 .join(', ');
-            const valuesArg = values != null && String(values).trim() !== ''
-                ? `, ${String(values).trim()}`
+            const valuesArg = call.valuesExpr != null && call.valuesExpr.trim() !== ''
+                ? `, ${call.valuesExpr.trim()}`
                 : '';
-            return `((__tongue_dyn) => { const __tongue_fn = __tongue_dyn[${keyExpr.trim()}]; if (!__tongue_fn) throw new Error(${JSON.stringify(`[next-tongue] t.dynamic key not in from: [${keys.join(', ')}]`)}); return __tongue_fn(${localeVar}${valuesArg}); })({ ${mapEntries} })`;
-        });
+            const replacement = `((__tongue_dyn) => { const __tongue_fn = __tongue_dyn[${call.keyExpr.trim()}]; if (!__tongue_fn) throw new Error(${JSON.stringify(`[next-tongue] t.dynamic key not in from: [${keys.join(', ')}]`)}); return __tongue_fn(${localeVar}${valuesArg}); })({ ${mapEntries} })`;
+            code = code.slice(0, call.start) + replacement + code.slice(call.end);
+        }
     }
     // Replace t('key', values) / t.rich('key', values) with per-key calls
     for (const [varName, ns] of translators) {
@@ -182,8 +182,7 @@ function safeImportIdent(ns, key) {
     return `__tongue_${(ns + '_' + key).replace(/[^A-Za-z0-9_]/g, '_')}`;
 }
 function safeExport(key) {
-    const cleaned = key.replace(/[^A-Za-z0-9_]/g, '_');
-    return /^[0-9]/.test(cleaned) ? `_${cleaned}` : cleaned || '_';
+    return safeIdent(key);
 }
 /** Webpack/Turbopack loader entry. */
 export default function tongueLoader(source) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-tongue",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "description": "Compiler-first, type-safe i18n for the Next.js 16 App Router",
   "license": "MIT",
   "type": "module",