next-tongue 0.9.8 → 0.9.10

package/dist/cli/init.js

@@ -83,14 +83,12 @@ export default defineConfig({
         path: `${appRoot}/[locale]/page.tsx`,
         kind: 'create',
         content: `import { getT } from 'next-tongue/server';
-import { ensureTongue } from '#tongue/runtime';
 
 export default async function Page({
   params,
 }: {
   params: Promise<{ locale: string }>;
 }) {
-  ensureTongue();
   const { locale } = await params;
   const t = await getT(locale, 'home');
   return (
@@ -246,10 +244,10 @@ export const config = {
 function rootLocaleLayout() {
     return `import { notFound } from 'next/navigation';
 import { TongueProvider } from 'next-tongue/client';
-import { getDir, isLocale, localeParams } from 'next-tongue/server';
-import { ensureTongue } from '#tongue/runtime';
+import { getDir, isLocale } from 'next-tongue/server';
+import { localeParams } from '#tongue/runtime';
 
-ensureTongue();
+// Importing #tongue/runtime auto-runs ensureTongue() (withTongue apps).
 export const generateStaticParams = localeParams;
 
 export default async function LocaleLayout({
@@ -278,10 +276,10 @@ export default async function LocaleLayout({
 function nestedLocaleLayout() {
     return `import { notFound } from 'next/navigation';
 import { TongueProvider } from 'next-tongue/client';
-import { isLocale, localeParams } from 'next-tongue/server';
-import { ensureTongue } from '#tongue/runtime';
+import { isLocale } from 'next-tongue/server';
+import { localeParams } from '#tongue/runtime';
 
-ensureTongue();
+// Importing #tongue/runtime auto-runs ensureTongue() (withTongue apps).
 export const generateStaticParams = localeParams;
 
 export default async function LocaleLayout({

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 (incl. reserved-key ident sanitization).
-    const CODEGEN_VERSION = 8;
+    // Bump when emit shape changes (reserved idents, auto ensureTongue side-effect).
+    const CODEGEN_VERSION = 9;
     const hash = createHash('sha256')
         .update(JSON.stringify({
         codegen: CODEGEN_VERSION,
@@ -337,7 +337,10 @@ export async function buildMessages(options) {
         ? `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
         ? `  configureFormatMessage({ timeZone, pseudo: { locale: ${JSON.stringify(config.pseudo.locale)}, expand: ${config.pseudo.expand} } });`
-        : `  configureFormatMessage({ timeZone });`, `  ready = true;`, `}`, ``);
+        : `  configureFormatMessage({ timeZone });`, `  ready = true;`, `}`, 
+    // Side-effect: importing `#tongue/runtime` (or getT's lazy import) wires the
+    // server without a per-page ensureTongue() call when using withTongue().
+    `ensureTongue();`, ``);
     await writeFile(join(outDir, 'runtime.js'), runtimeLines.join('\n'), 'utf8');
     await writeFile(join(outDir, 'runtime.d.ts'), [
         `/** Generated by next-tongue — do not edit. */`,
@@ -407,7 +410,7 @@ export async function buildMessages(options) {
     await writeFile(join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2), '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 writeFile(join(outDir, 'README.md'), 'Generated by next-tongue. Do not edit. Map `#tongue/*` → this directory.\nImporting `#tongue/runtime` (or calling getT) auto-runs ensureTongue(); an explicit call is optional.\n', 'utf8');
     await clearOutputDir(publishedOutDir);
     try {
         await rename(outDir, publishedOutDir);

package/dist/compiler/validate/a11y.js

@@ -75,6 +75,8 @@ function hasLangHint(src) {
         /<html[^>]*\blang=["']/.test(src) ||
         /\blang=\{locale\}/.test(src) ||
         /document\.documentElement\.lang/.test(src) ||
+        /setAttribute\(\s*['"]lang['"]/.test(src) ||
+        /\bHtmlLang\b/.test(src) ||
         /\.lang\s*=/.test(src));
 }
 function hasDirHint(src) {
@@ -82,7 +84,9 @@ function hasDirHint(src) {
         /<html[^>]*\bdir=["']/.test(src) ||
         /\bdir=\{getDir\(/.test(src) ||
         /\bdir=\{.*getDir/.test(src) ||
-        /document\.documentElement\.dir/.test(src));
+        /document\.documentElement\.dir/.test(src) ||
+        /setAttribute\(\s*['"]dir['"]/.test(src) ||
+        /\bHtmlLang\b/.test(src));
 }
 async function findLocaleLayouts(cwd) {
     return findLayoutsUnder(cwd, ['app/[locale]', 'src/app/[locale]']);

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

@@ -22,3 +22,8 @@ export declare function validateStale(config: ResolvedTongueConfig, cwd: string,
 }): Promise<CheckIssue[]>;
 /** Letter + single quote + letter — usually meant as prose apostrophe, not ICU quote. */
 export declare function likelyUnescapedApostrophe(icu: string): boolean;
+/**
+ * Apostrophe-in-words is common in fr/it/…; English `don't` floods CI with noise.
+ * Only hint for locales that regularly need ICU `''` in prose.
+ */
+export declare function shouldHintApostrophe(locale: string): boolean;

package/dist/compiler/validate/catalog.js

@@ -69,11 +69,12 @@ export async function validateCatalog(config, cwd, opts) {
                 });
                 continue;
             }
-            if (likelyUnescapedApostrophe(source)) {
+            if (shouldHintApostrophe(config.defaultLocale) &&
+                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é`,
+                    message: `Key "${fullKey}" looks like a natural-language apostrophe. In ICU, double it: "l''été" → l'été`,
                     key: fullKey,
                     locale: config.defaultLocale,
                     file,
@@ -142,6 +143,17 @@ export async function validateCatalog(config, cwd, opts) {
                     });
                     continue;
                 }
+                if (shouldHintApostrophe(locale) &&
+                    likelyUnescapedApostrophe(resolved)) {
+                    issues.push({
+                        check: 'icu',
+                        severity: 'warn',
+                        message: `Key "${fullKey}" looks like a natural-language apostrophe. In ICU, double it: "l''été" → l'été`,
+                        key: fullKey,
+                        locale,
+                        file: localeFile,
+                    });
+                }
                 const mismatchSev = severityFor(config.strict.mismatch);
                 if (mismatchSev) {
                     const otherArgs = collectArgs(otherAst);
@@ -247,3 +259,10 @@ export function likelyUnescapedApostrophe(icu) {
     }
     return false;
 }
+/**
+ * Apostrophe-in-words is common in fr/it/…; English `don't` floods CI with noise.
+ * Only hint for locales that regularly need ICU `''` in prose.
+ */
+export function shouldHintApostrophe(locale) {
+    return /^(fr|it|ca|oc|ht|lb|rm|ga|gd|mt)(-|$)/i.test(locale);
+}

package/dist/navigation/index.d.ts

@@ -48,6 +48,7 @@ export declare function createNavigation(config: NavigationConfig): {
         refresh: () => void;
     };
     usePathname: () => string;
+    usePathnameWithoutLocale: () => string;
     getPathname: (args: {
         href: Href;
         locale: Locale;
@@ -57,3 +58,10 @@ export declare function createNavigation(config: NavigationConfig): {
         children: (options: import("./locale-switcher.js").UseLocaleSwitcherResult) => ReactNode;
     }) => import("react").JSX.Element;
 };
+/**
+ * Strip a leading locale segment from `next/navigation`'s pathname.
+ * Prefer `createNavigation(…).usePathname` / `usePathnameWithoutLocale` when
+ * you already use tongue navigation; this unbound helper is for apps that keep
+ * plain `next/link` + proxy for as-needed paths.
+ */
+export declare function usePathnameWithoutLocale(locales: readonly string[]): string;

package/dist/navigation/index.js

@@ -77,6 +77,10 @@ export function createNavigation(config) {
         const locale = useLocale();
         return toInternalPathname(stripped, locale, bound.pathnames);
     }
+    /** Same as `usePathname` when pathnames are unset — locale prefix stripped. */
+    function usePathnameWithoutLocale() {
+        return stripLocalePrefix(useNextPathname(), bound.locales);
+    }
     const { useLocaleSwitcher, LocaleSwitcher } = createLocaleSwitcher(config);
     return {
         Link,
@@ -84,8 +88,18 @@ export function createNavigation(config) {
         permanentRedirect,
         useRouter,
         usePathname,
+        usePathnameWithoutLocale,
         getPathname: (args) => resolve(args.href, args.locale),
         useLocaleSwitcher,
         LocaleSwitcher,
     };
 }
+/**
+ * Strip a leading locale segment from `next/navigation`'s pathname.
+ * Prefer `createNavigation(…).usePathname` / `usePathnameWithoutLocale` when
+ * you already use tongue navigation; this unbound helper is for apps that keep
+ * plain `next/link` + proxy for as-needed paths.
+ */
+export function usePathnameWithoutLocale(locales) {
+    return stripLocalePrefix(useNextPathname(), locales);
+}

package/dist/next/with-tongue.d.ts

@@ -6,5 +6,8 @@ export type WithTongueOptions = {
 /**
  * Config wrapper (not a bundler plugin): runs codegen when Next loads config,
  * maps `#tongue/*` → outDir, registers the call-site loader for Turbopack + webpack.
+ *
+ * Codegen emits `#tongue/runtime` that auto-calls `ensureTongue()` on import;
+ * `getT` / `getFormat` also lazy-import that module — no per-page ensureTongue().
  */
 export declare function withTongue<T extends object>(nextConfig?: T, options?: WithTongueOptions): T;

package/dist/next/with-tongue.js

@@ -7,6 +7,9 @@ import { startDevWatcher } from './watcher.js';
 /**
  * Config wrapper (not a bundler plugin): runs codegen when Next loads config,
  * maps `#tongue/*` → outDir, registers the call-site loader for Turbopack + webpack.
+ *
+ * Codegen emits `#tongue/runtime` that auto-calls `ensureTongue()` on import;
+ * `getT` / `getFormat` also lazy-import that module — no per-page ensureTongue().
  */
 export function withTongue(nextConfig = {}, options = {}) {
     const cwd = process.cwd();

package/dist/proxy/index.d.ts

@@ -48,6 +48,8 @@ export type CreateProxyOptions = {
     resolveLocale?: (req: TongueProxyRequest) => string | undefined | Promise<string | undefined>;
     onLocale?: (locale: string, req: TongueProxyRequest) => void;
 };
+/** Default locale cookie name (`SameSite=Lax`). Use with `requestLocale` in API routes. */
+export declare const LOCALE_COOKIE_NAME = "TONGUE_LOCALE";
 /**
  * Next.js 16 `proxy.ts` handler for locale prefix routing.
  * Returns standard `Response` objects (compatible with Next proxy/middleware).

package/dist/proxy/index.js

@@ -2,8 +2,10 @@ import { toInternalPathname } from '../navigation/pathname.js';
 import { createLocaleMatcher, } from './locale-matcher.js';
 export { createLocaleMatcher, buildLocaleMatcherTables, emitLocaleMatcherModule, localeParentChain, matchTagAgainstTables, } from './locale-matcher.js';
 export { verifyLocalePreference, signLocalePreference, timingSafeEqual, DEFAULT_PREF_COOKIE, } from '../runtime/locale-preference.js';
+/** Default locale cookie name (`SameSite=Lax`). Use with `requestLocale` in API routes. */
+export const LOCALE_COOKIE_NAME = 'TONGUE_LOCALE';
 const DEFAULT_COOKIE = {
-    name: 'TONGUE_LOCALE',
+    name: LOCALE_COOKIE_NAME,
     maxAge: 60 * 60 * 24 * 365,
     sameSite: 'lax',
     path: '/',

package/dist/runtime/create-t.d.ts

@@ -14,8 +14,12 @@ export type TFunction<N extends Namespace = Namespace> = {
     <K extends MessageKey<N>>(key: K, ...args: [ArgsFor<N, K>] extends [never] ? [values?: Record<string, never>] : Record<string, never> extends ArgsFor<N, K> ? [values?: ArgsFor<N, K>] : [values: ArgsFor<N, K>]): string;
     rich: <K extends MessageKey<N>>(key: K, ...args: [ArgsFor<N, K>] extends [never] ? [values?: Record<string, never>] : Record<string, never> extends ArgsFor<N, K> ? [values?: ArgsFor<N, K>] : [values: ArgsFor<N, K>]) => ReactNode;
     has: (key: string) => boolean;
-    dynamic: (key: string, opts: {
-        from: readonly MessageKey<N>[];
+    /**
+     * Non-literal key from a declared set. `key` is narrowed to `From[number]`
+     * when `from` is a `as const` / readonly tuple of known keys.
+     */
+    dynamic: <const From extends readonly MessageKey<N>[]>(key: From[number], opts: {
+        from: From;
     }, values?: Record<string, unknown>) => string;
     ns: <N2 extends Namespace>(namespace: N2) => TFunction<N2>;
 };

package/dist/server/index.d.ts

@@ -29,11 +29,20 @@ export declare const defaultLocale: {
 export type LocaleProps = {
     locale: string;
 };
+/** Map of translators when loading several namespaces in one call. */
+export type MultiT<Ns extends readonly Namespace[]> = {
+    [K in Ns[number]]: TFunction<K>;
+};
 /**
  * Explicit locale (always available): `getT(locale, ns)` or `getT(locale)` for `_root`.
+ * Multi-ns: `getT(locale, ['home', 'common'])` → `{ home, common }` translators.
  * With `routing.rootParams: true`, `getT(ns)` resolves locale from `next/root-params`
  * when the single argument is a configured namespace (not a locale tag).
+ *
+ * `withTongue()` + generated `#tongue/runtime` auto-wires messages; an explicit
+ * `ensureTongue()` call is optional.
  */
+export declare function getT<const Ns extends readonly [Namespace, ...Namespace[]]>(locale: Locale | string, namespaces: Ns): Promise<MultiT<Ns>>;
 export declare function getT<N extends Namespace>(locale: Locale | string, namespace: N): Promise<TFunction<N>>;
 export declare function getT(locale: Locale | string): Promise<TFunction<'_root'>>;
 export declare function getFormat(locale?: string, options?: {
@@ -61,3 +70,5 @@ export type { Format, SanctionedUnit, SimpleUnit, DisplayNameType, } from '../ru
 export { isSanctionedUnit, SIMPLE_UNITS } from '../runtime/format.js';
 export { setLocalePreference, } from './locale-preference.js';
 export type { SetLocalePreferenceOptions, CookieStoreLike, } from './locale-preference.js';
+export { requestLocale, LOCALE_COOKIE_NAME, LOCALE_HEADER_NAME, } from './request-locale.js';
+export type { RequestLocaleOptions, RequestLocaleSource, } from './request-locale.js';

package/dist/server/index.js

@@ -42,6 +42,18 @@ export const defaultLocale = {
 };
 export async function getT(localeOrNs, namespace) {
     if (namespace !== undefined) {
+        if (Array.isArray(namespace)) {
+            if (namespace.length === 0) {
+                throw new TongueError('TONGUE_E_CONFIG', 'getT(locale, namespaces) requires a non-empty namespace array');
+            }
+            const locale = String(localeOrNs);
+            const out = {};
+            // Load sequentially so a single ensureRuntime runs first; namespaces share locale.
+            for (const ns of namespace) {
+                out[ns] = await getTWithLocale(locale, ns);
+            }
+            return out;
+        }
         return getTWithLocale(String(localeOrNs), namespace);
     }
     const single = String(localeOrNs);
@@ -54,9 +66,10 @@ export async function getT(localeOrNs, namespace) {
     return getTWithLocale(single, '_root');
 }
 async function getTWithLocale(locale, ns) {
+    await ensureRuntime();
     assertLocale(locale);
     if (!namespaceLoader) {
-        throw new TongueError('TONGUE_E_TYPES_MISSING', 'Message modules not loaded. Call ensureTongue() from `#tongue/runtime` (or wrap next.config with withTongue()).');
+        throw new TongueError('TONGUE_E_TYPES_MISSING', 'Message modules not loaded. Wrap next.config with withTongue() and run `tongue build && next build` so `#tongue/runtime` exists. (ensureTongue() is optional — getT loads it automatically.)');
     }
     const messages = await namespaceLoader(ns);
     return createT({
@@ -67,7 +80,24 @@ async function getTWithLocale(locale, ns) {
         },
     });
 }
+/**
+ * Load `#tongue/runtime` and call `ensureTongue()` once when the server runtime
+ * is not yet wired (withTongue apps — no per-page ensureTongue boilerplate).
+ */
+async function ensureRuntime() {
+    if (namespaceLoader)
+        return;
+    try {
+        const importer = new Function('s', 'return import(s)');
+        const mod = await importer('#tongue/runtime');
+        mod.ensureTongue?.();
+    }
+    catch {
+        /* fall through — getTWithLocale throws a clear error */
+    }
+}
 export async function getFormat(locale, options) {
+    await ensureRuntime();
     const resolved = locale ?? (runtimeRootParams ? await resolveRootLocale() : undefined);
     if (resolved == null) {
         throw new TongueError('TONGUE_E_LOCALE', 'getFormat(locale) requires a locale, or routing.rootParams: true');
@@ -141,6 +171,7 @@ export { generateAlternates, createGenerateAlternates, } from './alternates.js';
 export { translateIssues, defaultFormatPath, } from '../runtime/translate-issues.js';
 export { isSanctionedUnit, SIMPLE_UNITS } from '../runtime/format.js';
 export { setLocalePreference, } from './locale-preference.js';
+export { requestLocale, LOCALE_COOKIE_NAME, LOCALE_HEADER_NAME, } from './request-locale.js';
 function assertLocale(locale) {
     if (runtimeLocales.length && !runtimeLocales.includes(locale)) {
         throw new TongueError('TONGUE_E_LOCALE', `Locale "${locale}" is not in configured locales [${runtimeLocales.join(', ')}]`);

package/dist/server/request-locale.d.ts

@@ -0,0 +1,27 @@
+/** Default cookie name set by `createProxy` (`SameSite=Lax`). */
+export declare const LOCALE_COOKIE_NAME = "TONGUE_LOCALE";
+/** Common header for client → API locale (wizard / fetch). */
+export declare const LOCALE_HEADER_NAME = "x-locale";
+export type RequestLocaleSource = {
+    headers: {
+        get: (name: string) => string | null;
+    };
+    cookies?: {
+        get: (name: string) => {
+            value: string;
+        } | undefined;
+    };
+};
+export type RequestLocaleOptions = {
+    locales: readonly string[];
+    defaultLocale: string;
+    /** Defaults to `TONGUE_LOCALE`. */
+    cookieName?: string;
+    /** Defaults to `x-locale`. */
+    headerName?: string;
+};
+/**
+ * Resolve locale in Route Handlers / Server Actions (no `params.locale`).
+ * Order: header → cookie → defaultLocale.
+ */
+export declare function requestLocale(req: RequestLocaleSource, opts: RequestLocaleOptions): string;

package/dist/server/request-locale.js

@@ -0,0 +1,22 @@
+import { isLocale as isLocaleValue } from '../runtime/locale.js';
+/** Default cookie name set by `createProxy` (`SameSite=Lax`). */
+export const LOCALE_COOKIE_NAME = 'TONGUE_LOCALE';
+/** Common header for client → API locale (wizard / fetch). */
+export const LOCALE_HEADER_NAME = 'x-locale';
+/**
+ * Resolve locale in Route Handlers / Server Actions (no `params.locale`).
+ * Order: header → cookie → defaultLocale.
+ */
+export function requestLocale(req, opts) {
+    const headerName = opts.headerName ?? LOCALE_HEADER_NAME;
+    const cookieName = opts.cookieName ?? LOCALE_COOKIE_NAME;
+    const fromHeader = req.headers.get(headerName)?.trim();
+    if (fromHeader && isLocaleValue(fromHeader, opts.locales)) {
+        return fromHeader;
+    }
+    const fromCookie = req.cookies?.get(cookieName)?.value?.trim();
+    if (fromCookie && isLocaleValue(fromCookie, opts.locales)) {
+        return fromCookie;
+    }
+    return opts.defaultLocale;
+}

package/package.json

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