next-tongue 0.9.11 → 0.9.13

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

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

package/dist/cli/check.js

@@ -1,8 +1,10 @@
 import { loadConfig } from '../config/load-config.js';
 import { validateCatalog, validateStale } from '../compiler/validate/catalog.js';
 import { validateUsage } from '../compiler/validate/usage.js';
+import { validateClientLoader } from '../compiler/validate/client-loader.js';
 import { validateA11y } from '../compiler/validate/a11y.js';
 import { validateBidi } from '../compiler/validate/bidi.js';
+import { DEFAULT_SCAN_ROOTS } from '../compiler/scan-keys.js';
 import { loadLocaleMessages } from '../compiler/load-messages.js';
 import { duplicateSourceKeys, loadAndMergeSources, } from '../compiler/sources.js';
 import { validateLength } from '../compiler/validate/length.js';
@@ -20,6 +22,8 @@ export async function cmdCheck(opts) {
         ...(localeFilter ? { locales: localeFilter } : {}),
     })));
     issues.push(...(await validateUsage(config, cwd)));
+    const scanRoots = config.scan.include.length > 0 ? config.scan.include : DEFAULT_SCAN_ROOTS;
+    issues.push(...(await validateClientLoader(cwd, scanRoots)));
     issues.push(...(await validateStale(config, cwd, {
         ...(localeFilter ? { locales: localeFilter } : {}),
     })));

package/dist/cli/extract.js

@@ -4,6 +4,7 @@ import { loadConfig } from '../config/load-config.js';
 import { buildMessages } from '../compiler/build.js';
 import { loadLocaleMessages, resolveMessagePath } from '../compiler/load-messages.js';
 import { DEFAULT_SCAN_ROOTS, scanReferencedKeys, } from '../compiler/scan-keys.js';
+import { collectUnusedIgnores, isUnusedIgnored, matchesUnusedIgnoreGlob, } from '../compiler/unused-meta.js';
 import { TongueError } from '../errors.js';
 export async function cmdExtract(opts) {
     const { config, cwd } = await loadConfig({
@@ -28,8 +29,6 @@ export async function cmdExtract(opts) {
             defined.add(ns === '_root' ? key : `${ns}.${key}`);
         }
     }
-    const missing = [...used].filter((k) => !defined.has(k)).sort();
-    const unused = [...defined].filter((k) => !used.has(k)).sort();
     const placeholder = opts.placeholder ?? null; // null → use key as value
     const abs = resolveMessagePath(cwd, config.messages, config.defaultLocale);
     let raw;
@@ -46,6 +45,14 @@ export async function cmdExtract(opts) {
     catch (err) {
         throw new TongueError('TONGUE_E_PARSE', `Invalid JSON: ${err instanceof Error ? err.message : err}`, { file: abs });
     }
+    const metaIgnores = collectUnusedIgnores(json);
+    const configIgnores = config.strict.unusedIgnore;
+    const missing = [...used].filter((k) => !defined.has(k)).sort();
+    const unused = [...defined]
+        .filter((k) => !used.has(k))
+        .filter((k) => !isUnusedIgnored(k, metaIgnores))
+        .filter((k) => !matchesUnusedIgnoreGlob(k, configIgnores))
+        .sort();
     let added = 0;
     let pruned = 0;
     for (const fullKey of missing) {

package/dist/cli/init.js

@@ -32,6 +32,9 @@ export async function cmdInit(opts) {
         return;
     }
     const appRoot = await detectAppRoot(cwd);
+    if (!opts.quiet) {
+        console.log(`tongue init: using ${appRoot}/ for App Router files`);
+    }
     const hasRootLayout = await hasFile(cwd, `${appRoot}/layout.tsx`, `${appRoot}/layout.ts`, `${appRoot}/layout.jsx`, `${appRoot}/layout.js`);
     const proxyPath = await detectProxyPath(cwd, appRoot);
     const plans = [];
@@ -69,7 +72,9 @@ export default defineConfig({
         });
     }
     else if (!opts.quiet) {
-        console.log('tongue init: existing proxy/middleware detected — compose createProxy({ locales, defaultLocale, … }) yourself (see docs/routing-and-proxy.md).');
+        console.log('tongue init: existing proxy/middleware detected — do not overwrite. Compose like:\n\n' +
+            proxyScaffold(locales, defaultLocale, prefix) +
+            '\nSee docs/routing-and-proxy.md#composing-with-your-own-proxy-logic / hybrid routing.');
     }
     const layoutPath = `${appRoot}/[locale]/layout.tsx`;
     plans.push({

package/dist/compiler/build.js

@@ -113,8 +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)
-    // Bump when emit shape changes (reserved idents, auto ensureTongue side-effect).
-    const CODEGEN_VERSION = 9;
+    // Bump when emit shape changes (reserved idents, auto ensureTongue, routing export).
+    const CODEGEN_VERSION = 10;
     const hash = createHash('sha256')
         .update(JSON.stringify({
         codegen: CODEGEN_VERSION,
@@ -333,9 +333,9 @@ export async function buildMessages(options) {
         !productionLocales.includes(config.pseudo.locale);
     runtimeLines.push(`export const allLocales = ${JSON.stringify([...emitLocales])};`, `const productionLocales = ${JSON.stringify(productionLocales)};`, pseudoDevOnly
         ? `export const locales = process.env.NODE_ENV === 'production' ? productionLocales : allLocales;`
-        : `export const locales = allLocales;`, `export const defaultLocale = ${JSON.stringify(config.defaultLocale)};`, `export const timeZone = ${JSON.stringify(config.timeZone)};`, config.pseudo && config.pseudo.enabled !== false
+        : `export const locales = allLocales;`, `export const defaultLocale = ${JSON.stringify(config.defaultLocale)};`, `export const prefix = ${JSON.stringify(config.routing.prefix)};`, `export const timeZone = ${JSON.stringify(config.timeZone)};`, config.pseudo && config.pseudo.enabled !== false
         ? `export const pseudoLocale = ${JSON.stringify(config.pseudo.locale)};`
-        : `export const pseudoLocale = undefined;`, `export function localeParams() {`, `  return locales.map((locale) => ({ locale }));`, `}`, `let ready = false;`, `export function ensureTongue() {`, `  if (ready) return;`, `  __setServerRuntime({`, `    locales: allLocales,`, `    defaultLocale,`, `    timeZone,`, `    rootParams: ${config.routing.rootParams ? 'true' : 'false'},`, `    loadNamespace: async (namespace) => {`, `      const messages = namespaces[namespace];`, `      if (!messages) throw new Error('[next-tongue] Unknown namespace: ' + namespace);`, `      return messages;`, `    },`, `  });`, config.pseudo && config.pseudo.enabled !== false
+        : `export const pseudoLocale = undefined;`, `/** Single source of truth for createProxy / createNavigation / TongueShell. */`, `export const routing = { locales, defaultLocale, prefix };`, `export function localeParams() {`, `  return locales.map((locale) => ({ locale }));`, `}`, `let ready = false;`, `export function ensureTongue() {`, `  if (ready) return;`, `  __setServerRuntime({`, `    locales: allLocales,`, `    defaultLocale,`, `    timeZone,`, `    rootParams: ${config.routing.rootParams ? 'true' : 'false'},`, `    loadNamespace: async (namespace) => {`, `      const messages = namespaces[namespace];`, `      if (!messages) throw new Error('[next-tongue] Unknown namespace: ' + namespace);`, `      return messages;`, `    },`, `  });`, config.pseudo && config.pseudo.enabled !== false
         ? `  configureFormatMessage({ timeZone, pseudo: { locale: ${JSON.stringify(config.pseudo.locale)}, expand: ${config.pseudo.expand} } });`
         : `  configureFormatMessage({ timeZone });`, `  ready = true;`, `}`, 
     // Side-effect: importing `#tongue/runtime` (or getT's lazy import) wires the
@@ -347,8 +347,10 @@ export async function buildMessages(options) {
         `export declare const allLocales: readonly string[];`,
         `export declare const locales: readonly string[];`,
         `export declare const defaultLocale: string;`,
+        `export declare const prefix: 'always' | 'as-needed' | 'never';`,
         `export declare const timeZone: string;`,
         `export declare const pseudoLocale: string | undefined;`,
+        `export declare const routing: { locales: readonly string[]; defaultLocale: string; prefix: 'always' | 'as-needed' | 'never' };`,
         `export declare function localeParams(): { locale: string }[];`,
         `export declare function ensureTongue(): void;`,
         ``,

package/dist/compiler/unused-meta.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Catalog `$meta` flags that suppress `unused` (and extract `--prune`).
+ *
+ * Per key (sibling `key$meta`):
+ *   { "planned": true }
+ *   { "ignoreUnused": true }
+ *   { "@tongue-ignore": true }
+ *
+ * Per namespace (child `$meta` on the namespace object):
+ *   "common": { "$meta": { "planned": true }, "seeAll": "…" }
+ */
+export type Nested = Record<string, unknown>;
+export type UnusedIgnoreIndex = {
+    /** Exact full keys (e.g. `common.seeAll`). */
+    keys: Set<string>;
+    /** Namespace prefixes whose unused keys are ignored (`common` → `common.*`). */
+    namespaces: Set<string>;
+};
+/** Walk default-locale JSON and collect planned / @tongue-ignore markers. */
+export declare function collectUnusedIgnores(root: Nested): UnusedIgnoreIndex;
+export declare function isUnusedIgnored(fullKey: string, index: UnusedIgnoreIndex): boolean;
+/** Glob-lite for `strict.unusedIgnore` (`common.*`, `*.seeAll`). */
+export declare function matchesUnusedIgnoreGlob(fullKey: string, patterns: readonly string[]): boolean;

package/dist/compiler/unused-meta.js

@@ -0,0 +1,86 @@
+/**
+ * Catalog `$meta` flags that suppress `unused` (and extract `--prune`).
+ *
+ * Per key (sibling `key$meta`):
+ *   { "planned": true }
+ *   { "ignoreUnused": true }
+ *   { "@tongue-ignore": true }
+ *
+ * Per namespace (child `$meta` on the namespace object):
+ *   "common": { "$meta": { "planned": true }, "seeAll": "…" }
+ */
+function metaIgnoresUnused(meta) {
+    if (!meta || typeof meta !== 'object' || Array.isArray(meta))
+        return false;
+    const m = meta;
+    if (m.planned === true)
+        return true;
+    if (m.ignoreUnused === true)
+        return true;
+    if (m['@tongue-ignore'] === true)
+        return true;
+    // Allow string form: "@tongue-ignore" or "planned"
+    if (typeof m.unused === 'string') {
+        const u = m.unused.toLowerCase();
+        if (u === 'ignore' || u === 'planned' || u === '@tongue-ignore')
+            return true;
+    }
+    return false;
+}
+/** Walk default-locale JSON and collect planned / @tongue-ignore markers. */
+export function collectUnusedIgnores(root) {
+    const keys = new Set();
+    const namespaces = new Set();
+    walk(root, '', keys, namespaces);
+    return { keys, namespaces };
+}
+function walk(node, prefix, keys, namespaces) {
+    const nsMeta = node['$meta'];
+    if (prefix && metaIgnoresUnused(nsMeta)) {
+        namespaces.add(prefix);
+    }
+    for (const [key, value] of Object.entries(node)) {
+        if (key === '$meta' || key.endsWith('$meta') || key.endsWith('$description')) {
+            continue;
+        }
+        const full = prefix ? `${prefix}.${key}` : key;
+        if (value != null && typeof value === 'object' && !Array.isArray(value)) {
+            walk(value, full, keys, namespaces);
+            continue;
+        }
+        if (typeof value !== 'string')
+            continue;
+        const meta = node[`${key}$meta`];
+        if (metaIgnoresUnused(meta)) {
+            keys.add(full);
+        }
+    }
+}
+export function isUnusedIgnored(fullKey, index) {
+    if (index.keys.has(fullKey))
+        return true;
+    for (const ns of index.namespaces) {
+        if (fullKey === ns || fullKey.startsWith(`${ns}.`))
+            return true;
+    }
+    return false;
+}
+/** Glob-lite for `strict.unusedIgnore` (`common.*`, `*.seeAll`). */
+export function matchesUnusedIgnoreGlob(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;
+}

package/dist/compiler/validate/client-loader.d.ts

@@ -0,0 +1,7 @@
+import type { CheckIssue } from '../../cli/check-types.js';
+/**
+ * Dry-run the call-site loader on `"use client"` files that call `useT`.
+ * Fails when rewritten output calls `useLocale` without importing it
+ * (Safari: Can't find variable: useLocale).
+ */
+export declare function validateClientLoader(cwd: string, roots?: readonly string[]): Promise<CheckIssue[]>;

package/dist/compiler/validate/client-loader.js

@@ -0,0 +1,79 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { transformCallSites } from '../../next/loader.js';
+import { DEFAULT_SCAN_ROOTS } from '../scan-keys.js';
+const SOURCE_EXT = new Set(['.ts', '.tsx', '.js', '.jsx']);
+/**
+ * Dry-run the call-site loader on `"use client"` files that call `useT`.
+ * Fails when rewritten output calls `useLocale` without importing it
+ * (Safari: Can't find variable: useLocale).
+ */
+export async function validateClientLoader(cwd, roots = DEFAULT_SCAN_ROOTS) {
+    const issues = [];
+    const files = await collectSourceFiles(cwd, roots);
+    for (const abs of files) {
+        let src;
+        try {
+            src = await readFile(abs, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        if (!/"use client"\s*;?/.test(src) && !/'use client'\s*;?/.test(src)) {
+            continue;
+        }
+        if (!/\buseT\s*\(/.test(src))
+            continue;
+        const rel = relative(cwd, abs);
+        const { code } = transformCallSites(src, rel);
+        if (!/\buseLocale\s*\(/.test(code))
+            continue;
+        const hasImport = /import\s*\{[^}]*\buseLocale\b[^}]*\}\s*from\s*['"]next-tongue\/client['"]/.test(code);
+        if (!hasImport) {
+            issues.push({
+                check: 'client-loader',
+                severity: 'error',
+                message: `Rewritten useT in "${rel}" calls useLocale() without importing it from 'next-tongue/client' (Safari ReferenceError). Upgrade next-tongue / ensure withTongue() applies the call-site loader.`,
+                file: rel,
+            });
+        }
+    }
+    return issues;
+}
+async function collectSourceFiles(cwd, roots) {
+    const out = [];
+    for (const root of roots) {
+        const abs = join(cwd, root);
+        try {
+            if (!(await stat(abs)).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        await walk(abs, out);
+    }
+    return out;
+}
+async function walk(dir, out) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const ent of entries) {
+        if (ent.name.startsWith('.'))
+            continue;
+        const abs = join(dir, ent.name);
+        if (ent.isDirectory()) {
+            if (ent.name === 'node_modules' ||
+                ent.name === '.next' ||
+                ent.name === 'dist') {
+                continue;
+            }
+            await walk(abs, out);
+        }
+        else {
+            const i = ent.name.lastIndexOf('.');
+            const ext = i === -1 ? '' : ent.name.slice(i);
+            if (SOURCE_EXT.has(ext))
+                out.push(abs);
+        }
+    }
+}

package/dist/compiler/validate/usage.js

@@ -1,5 +1,7 @@
-import { loadLocaleMessages } from '../load-messages.js';
+import { readFile } from 'node:fs/promises';
+import { loadLocaleMessages, resolveMessagePath, } from '../load-messages.js';
 import { DEFAULT_SCAN_ROOTS, scanKeys } from '../scan-keys.js';
+import { collectUnusedIgnores, isUnusedIgnored, matchesUnusedIgnoreGlob, } from '../unused-meta.js';
 function severityFor(level, alwaysError = false) {
     if (alwaysError)
         return 'error';
@@ -11,25 +13,6 @@ function namespaceOf(fullKey) {
     const i = fullKey.indexOf('.');
     return i === -1 ? '_root' : fullKey.slice(0, i);
 }
-/** 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 = [];
@@ -71,10 +54,13 @@ export async function validateUsage(config, cwd) {
     const unusedSev = severityFor(config.strict.unused);
     if (unusedSev) {
         const ignore = config.strict.unusedIgnore;
+        const metaIgnores = await loadUnusedMetaIgnores(config, cwd);
         for (const fullKey of defined) {
             if (used.has(fullKey))
                 continue;
-            if (matchesIgnore(fullKey, ignore))
+            if (matchesUnusedIgnoreGlob(fullKey, ignore))
+                continue;
+            if (isUnusedIgnored(fullKey, metaIgnores))
                 continue;
             // Dynamic t(var) / t.ns / t.dynamic — do not false-flag catalog keys as unused
             if (dynamicNamespaces.has(namespaceOf(fullKey)))
@@ -90,3 +76,14 @@ export async function validateUsage(config, cwd) {
     }
     return issues;
 }
+async function loadUnusedMetaIgnores(config, cwd) {
+    const abs = resolveMessagePath(cwd, config.messages, config.defaultLocale);
+    try {
+        const raw = await readFile(abs, 'utf8');
+        const json = JSON.parse(raw);
+        return collectUnusedIgnores(json);
+    }
+    catch {
+        return collectUnusedIgnores({});
+    }
+}

package/dist/next/loader.d.ts

@@ -28,6 +28,14 @@ export declare function splitLeadingDirectives(source: string): {
     directives: string;
     body: string;
 };
+/**
+ * Ensure `useLocale` is a real import. Looking for the identifier in the body is
+ * not enough — the loader injects `useLocale()` calls before this runs.
+ */
+export declare function ensureUseLocaleImport(code: string, preamble: string): {
+    code: string;
+    preamble: string;
+};
 /** Webpack/Turbopack loader entry. */
 export default function tongueLoader(this: {
     resourcePath: string;

package/dist/next/loader.js

@@ -132,9 +132,9 @@ export function transformCallSites(source, resourcePath, _options = {}) {
     if (loadedCalls.length > 0) {
         preamble += loadedCalls.join('\n') + '\n';
     }
-    if (!/useLocale/.test(preamble + code) || !/from\s+['"]next-tongue\/client['"]/.test(code)) {
-        preamble += `import { useLocale } from 'next-tongue/client';\n`;
-    }
+    // Injected `useLocale()` calls do NOT count as an import — merge into the
+    // existing next-tongue/client import or add one (Safari ReferenceError otherwise).
+    ({ code, preamble } = ensureUseLocaleImport(code, preamble));
     for (const [varName, ns] of translators) {
         if (!escapes(withoutDirs, varName))
             continue;
@@ -195,6 +195,51 @@ function escapeRegExp(s) {
 function localeVarFor(varName) {
     return varName === 't' ? '__tongue_locale' : `__tongue_locale_${varName}`;
 }
+const USE_LOCALE_IMPORT = /import\s*\{([^}]*)\}\s*from\s*['"]next-tongue\/client['"]/;
+/**
+ * Ensure `useLocale` is a real import. Looking for the identifier in the body is
+ * not enough — the loader injects `useLocale()` calls before this runs.
+ */
+export function ensureUseLocaleImport(code, preamble) {
+    const combined = preamble + code;
+    if (USE_LOCALE_IMPORT.test(combined) && /\buseLocale\b/.test(combined.match(USE_LOCALE_IMPORT)?.[1] ?? '')) {
+        return { code, preamble };
+    }
+    if (USE_LOCALE_IMPORT.test(code)) {
+        return {
+            code: code.replace(USE_LOCALE_IMPORT, (full, specs) => {
+                if (/\buseLocale\b/.test(specs))
+                    return full;
+                const parts = specs
+                    .split(',')
+                    .map((s) => s.trim())
+                    .filter(Boolean);
+                parts.push('useLocale');
+                return full.replace(specs, ` ${parts.join(', ')} `);
+            }),
+            preamble,
+        };
+    }
+    if (USE_LOCALE_IMPORT.test(preamble)) {
+        return {
+            code,
+            preamble: preamble.replace(USE_LOCALE_IMPORT, (full, specs) => {
+                if (/\buseLocale\b/.test(specs))
+                    return full;
+                const parts = specs
+                    .split(',')
+                    .map((s) => s.trim())
+                    .filter(Boolean);
+                parts.push('useLocale');
+                return full.replace(specs, ` ${parts.join(', ')} `);
+            }),
+        };
+    }
+    return {
+        code,
+        preamble: preamble + `import { useLocale } from 'next-tongue/client';\n`,
+    };
+}
 function safeImportIdent(ns, key) {
     return `__tongue_${(ns + '_' + key).replace(/[^A-Za-z0-9_]/g, '_')}`;
 }

package/dist/next/with-tongue.js

@@ -18,6 +18,7 @@ export function withTongue(nextConfig = {}, options = {}) {
     const input = nextConfig;
     if (!options.skipBuild) {
         runCodegenSync(cwd, options.config);
+        warnMissingTongueRuntime(cwd);
         void loadConfig({
             cwd,
             ...(options.config != null ? { configPath: options.config } : {}),
@@ -33,6 +34,9 @@ export function withTongue(nextConfig = {}, options = {}) {
             console.warn('[next-tongue] Could not start watcher:', err instanceof Error ? err.message : err);
         });
     }
+    else {
+        warnMissingTongueRuntime(cwd);
+    }
     // Next 16: content must be RegExp; omit `as` when returning the same module type
     // (using `as: '*.tsx'` previously doubled extensions → `file.tsx.tsx`).
     // Do NOT gate on `browser` — client components still SSR, and useT must be
@@ -171,6 +175,12 @@ function resolveLoaderPath() {
     const here = dirname(fileURLToPath(import.meta.url));
     return resolve(here, 'loader.js');
 }
+function warnMissingTongueRuntime(cwd) {
+    const runtime = join(cwd, '.tongue', 'runtime.js');
+    if (!existsSync(runtime)) {
+        console.warn('[next-tongue] `.tongue/runtime.js` is missing. Run `npx tongue build` (or use `"build": "tongue build && next build"`). `next dev` without a recent build leaves getT/useT unwired.');
+    }
+}
 function runCodegenSync(cwd, configPath) {
     const here = dirname(fileURLToPath(import.meta.url));
     const bin = resolve(here, '../../bin/tongue.js');

package/package.json

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