cloudflare-next-intl 0.6.34 → 0.7.1

package/README.md

@@ -96,6 +96,14 @@ export default async function Page() {
 }
 ```
 
+`t(key)` always returns a `string`. For a message whose value is an array
+or nested object (e.g. a list), use `t.raw(key)` to get it back as-is:
+
+```tsx
+const t = await getTranslations("Index");
+const items = t.raw("items") as string[]; // messages.Index.items
+```
+
 ### Client Components
 
 ```tsx
@@ -166,6 +174,64 @@ export default async function RootLayout({ children, params }) {
 }
 ```
 
+### Static export (`output: 'export'`) support
+
+The regular `IntlProvider` (`cloudflare-next-intl/serverProvider`, re-exported
+from the root) always has a code path to the firebase-auth client provider,
+which imports a `"use server"` file (`clear_session_action`) for clearing
+the session cookie on logout. Next.js registers a `"use server"` file into
+the server-actions build the moment **any** `import()` in the compiled
+module graph points to it — a runtime `if (config.firebaseAuth)` guard does
+not remove the import *statement*, only skips executing it, so the file is
+still registered even on apps that never configure `firebaseAuth`.
+`output: 'export'` builds fail outright the instant any server action is
+registered anywhere in the app, so this affects every app doing a static
+export, not just ones using auth.
+
+If your app is built with `output: 'export'` and does **not** configure
+`firebaseAuth`, use `cloudflare-next-intl/serverProviderStatic` instead —
+same signature (minus `staticSafe`, which only exists to control firebase
+auth's server-side resolution), same locale/messages/cookie-consent
+behavior, but its client provider has zero import anywhere pointing at the
+firebase-auth client code, so there is nothing for Next's scanner to find:
+
+```tsx
+import { IntlProvider } from "cloudflare-next-intl/serverProviderStatic";
+```
+
+It throws at render time if `firebaseAuth` is configured — that combination
+isn't supported by this variant; use the regular `serverProvider` for apps
+that need Firebase Auth (which in turn means you can't statically export
+those routes, per the constraint above).
+
+If your app imports the regular `IntlProvider` from the package root and
+can't change that import site (e.g. it's inside another package, or you
+don't want to special-case your own source per build target), redirect it
+at the bundler level instead — alias the **resolved absolute file path**
+(not the package specifier) for both `server_provider.js` and
+`client_provider.js` to their `_static` counterparts, only when building
+for static export:
+
+```ts
+// next.config.ts
+webpack(config) {
+    if (process.env.STATIC_EXPORT === "true") {
+        // realpath, not the raw node_modules path — webpack resolves
+        // symlinks (e.g. `npm link`) to their real target before matching
+        // aliases, so an alias keyed on the symlink path would never match.
+        const root = fs.realpathSync(path.resolve(__dirname, "node_modules/cloudflare-next-intl"));
+        config.resolve.alias[path.join(root, "dist/src/server/components/server_provider.js")] =
+            path.join(root, "dist/src/server/components/server_provider_static.js");
+        // client_hooks.ts (useLocale/useTranslations) imports LocaleContext
+        // from client_provider.js directly — a second, independent edge to
+        // the same firebase-auth chain that the alias above doesn't cover.
+        config.resolve.alias[path.join(root, "dist/src/client/components/client_provider.js")] =
+            path.join(root, "dist/src/client/components/client_provider_static.js");
+    }
+    return config;
+},
+```
+
 ### SEO metadata (hreflang/canonical)
 
 ```ts

package/dist/src/client/components/client_provider_static.d.ts

@@ -0,0 +1,30 @@
+import type { TranslationObject } from "../../types/types";
+import type { CookieConsentAnalyticsConfig } from "../../types/types";
+import type { CookieConsentDialogProps } from "../../cookie_consent/client/components/cookie_consent_dialog";
+import type { PrivacyPolicyUpdateDialogProps } from "../../cookie_consent/client/components/privacy_policy_update_dialog";
+interface LocaleContextType {
+    language: string;
+    messages: TranslationObject;
+}
+export declare const LocaleContext: import("react").Context<LocaleContextType | undefined>;
+export default function LocationzationClientProvider({ language, messages, analyticsConfig, requiresConsent, autoWireDialogs, dialogProps, updateDialogProps, children }: {
+    language: string;
+    messages: TranslationObject;
+    /** Resolved server-side from `cookieConsent.analytics`/`getAnalytics` when `autoWireAnalytics` isn't `false`. */
+    analyticsConfig?: CookieConsentAnalyticsConfig;
+    /**
+     * Resolved server-side from `cookieConsent.getCountryCode`/`gdprCountries`.
+     * `false` means the visitor's country doesn't require the consent
+     * banner — `CookieConsentProvider` seeds consent as implicitly granted
+     * for a first-time visitor instead of `null`.
+     */
+    requiresConsent?: boolean;
+    /** From `cookieConsent.autoWireDialogs` — renders `CookieConsentDialog`/`PrivacyPolicyUpdateDialog` automatically when `true` (default). */
+    autoWireDialogs?: boolean;
+    /** From `cookieConsent.dialogProps` — forwarded as-is to the auto-wired `CookieConsentDialog`. */
+    dialogProps?: CookieConsentDialogProps;
+    /** From `cookieConsent.updateDialogProps` — forwarded as-is to the auto-wired `PrivacyPolicyUpdateDialog`. */
+    updateDialogProps?: PrivacyPolicyUpdateDialogProps;
+    children: React.ReactNode;
+}): Component;
+export {};

package/dist/src/client/components/client_provider_static.js

@@ -0,0 +1,33 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { setLocaleCache, setMessageForLocaleCache } from "../../general/cache_variables";
+import { createContext, useMemo } from "react";
+import dynamic from "next/dynamic";
+import config from "@intl-config";
+import installConsoleErrorOverride from "../../error_handling/install_console_error_override";
+import installGlobalErrorOverride from "../../error_handling/install_global_error_override";
+export const LocaleContext = createContext(undefined);
+// `output: 'export'`-safe: unlike `client_provider.tsx`, this file has no
+// import anywhere in it pointing at `firebase_auth/client/auth_user_provider`
+// (which itself pulls in the "use server" `clear_session_action`). Next's
+// server-actions build step registers a "use server" file the moment any
+// `import()` in the compiled module graph points to it, so removing the
+// import entirely — not just skipping its use at runtime — is what keeps
+// `output: 'export'` builds from failing. See `server_provider_static.tsx`
+// for the full explanation.
+const CookieConsentProvider = dynamic(() => import("../../cookie_consent/client/cookie_consent_provider"));
+const CookieConsentAnalytics = dynamic(() => import("../../cookie_consent/client/components/cookie_consent_analytics"));
+const CookieConsentDialog = dynamic(() => import("../../cookie_consent/client/components/cookie_consent_dialog"));
+const PrivacyPolicyUpdateDialog = dynamic(() => import("../../cookie_consent/client/components/privacy_policy_update_dialog"));
+export default function LocationzationClientProvider({ language, messages, analyticsConfig, requiresConsent = true, autoWireDialogs = true, dialogProps, updateDialogProps, children }) {
+    setLocaleCache(language);
+    setMessageForLocaleCache(language, messages);
+    installConsoleErrorOverride(config, true);
+    installGlobalErrorOverride(config);
+    let providedChildren = children;
+    if (config.cookieConsent) {
+        providedChildren = _jsxs(CookieConsentProvider, { requiresConsent: requiresConsent, children: [providedChildren, analyticsConfig && _jsx(CookieConsentAnalytics, { config: analyticsConfig }), autoWireDialogs && _jsx(CookieConsentDialog, { ...dialogProps }), autoWireDialogs && _jsx(PrivacyPolicyUpdateDialog, { ...updateDialogProps })] });
+    }
+    const contextValue = useMemo(() => ({ language, messages }), [language, messages]);
+    return _jsx(LocaleContext.Provider, { value: contextValue, children: providedChildren });
+}

package/dist/src/general/cache_variables.bench.js

@@ -13,7 +13,9 @@ describe('cache_variables', () => {
         getMessageCache(undefined);
     });
     bench('setTranslationCache + getTranslationCache hit', () => {
-        setTranslationCache('en-common', (k) => k);
+        const fn = (k) => k;
+        fn.raw = (k) => k;
+        setTranslationCache('en-common', fn);
         getTranslationCache('en-common');
     });
 });

package/dist/src/general/general_functions.js

@@ -18,6 +18,7 @@ const errorAndReturnFallback = (message, cacheKey, locale, namespace, key) => {
     ].filter(Boolean); // Filter out empty parts
     console.error(parts.join(' | '));
     const fallbackFn = (k) => k; // Fallback function simply returns the key
+    fallbackFn.raw = (k) => k;
     setTranslationCache(cacheKey, fallbackFn);
     return fallbackFn;
 };
@@ -29,10 +30,10 @@ export function getTranslationsImpl(locale, messages, namespace, cacheKey) {
     // Traverse the translation object based on the namespace parts.
     for (let i = 0; i < namespaceParts.length; i++) {
         const part = namespaceParts[i];
-        const nextLevel = currentLevel[part];
+        const nextLevel = Array.isArray(currentLevel) ? undefined : currentLevel[part];
         if (i === namespaceParts.length - 1) {
             // Last part of the namespace, should resolve to an object (the base for translations).
-            if (typeof nextLevel === 'object' && nextLevel !== null) {
+            if (typeof nextLevel === 'object' && nextLevel !== null && !Array.isArray(nextLevel)) {
                 translationsBase = nextLevel;
             }
             else {
@@ -77,7 +78,7 @@ export function getTranslationsImpl(locale, messages, namespace, cacheKey) {
                 console.warn(`Translation key "${key}" in namespace "${namespace}" leads to a string prematurely at "${part}" for locale "${locale}".`);
                 return key; // Return the key as fallback
             }
-            const value = currentTranslation[part];
+            const value = Array.isArray(currentTranslation) ? undefined : currentTranslation[part];
             if (i === keyParts.length - 1) {
                 if (typeof value !== 'string') {
                     console.warn(`Translation key "${key}" in namespace "${namespace}" resolves to a non-string value for locale "${locale}". Expected string, got "${typeof value}".`);
@@ -104,6 +105,68 @@ export function getTranslationsImpl(locale, messages, namespace, cacheKey) {
         console.warn(`Translation key "${key}" in namespace "${namespace}" is missing or not a string for locale "${locale}".`);
         return key; // Return the key as fallback
     };
+    /**
+     * `t.raw(key)` — the escape hatch for when a message value isn't a
+     * plain string.
+     *
+     * `t(key)` (the main `translateFunction` above) ALWAYS returns a
+     * `string`; if the value at `key` is an array or a nested object, it
+     * warns and falls back to returning `key` itself. Use `t.raw(key)`
+     * instead whenever your `messages/<locale>.json` stores a list or
+     * object under that key (e.g. a list of social links, a table of
+     * FAQ entries, a settings sub-object) — it returns the value exactly
+     * as it appears in the JSON, unmodified: string stays string, array
+     * stays array, object stays object.
+     *
+     * Mirrors `next-intl`'s `t.raw` API, so existing `next-intl` knowledge
+     * transfers directly.
+     *
+     * @example
+     * // messages/en.json: { "Index": { "items": ["a", "b", "c"] } }
+     * const t = await getTranslations("Index");
+     * const items = t.raw("items") as string[]; // ["a", "b", "c"]
+     *
+     * @param key Dot-separated path into the resolved namespace, same
+     *   format as `translateFunction`'s `key` (e.g. `"items"` or
+     *   `"section.list"`).
+     * @returns The raw `TranslationEntry` at `key` (string | object | array),
+     *   or `key` itself if the path doesn't resolve (missing key, or an
+     *   intermediate segment isn't an object) — matching `translateFunction`'s
+     *   fallback-to-key behavior on lookup failure.
+     */
+    const rawFunction = (key) => {
+        const keyParts = key.split('.');
+        let currentTranslation = translationsBase;
+        for (let i = 0; i < keyParts.length; i++) {
+            const part = keyParts[i];
+            if (typeof currentTranslation === 'string' || Array.isArray(currentTranslation)) {
+                console.warn(`Translation key "${key}" in namespace "${namespace}" leads to a non-object prematurely at "${part}" for locale "${locale}".`);
+                return key;
+            }
+            const value = currentTranslation[part];
+            if (i === keyParts.length - 1) {
+                if (value === undefined) {
+                    console.warn(`Translation key "${key}" in namespace "${namespace}" is missing for locale "${locale}".`);
+                    return key;
+                }
+                return value;
+            }
+            else {
+                if (typeof value === 'object' && value !== null) {
+                    currentTranslation = value;
+                }
+                else {
+                    console.warn(`Translation key "${key}" in namespace "${namespace}" has invalid structure at "${part}" for locale "${locale}". Expected object, got "${typeof value}".`);
+                    return key;
+                }
+            }
+        }
+        return key;
+    };
+    // Attach `.raw` onto the same callable function object so callers get
+    // one value that works both as `t(key)` and `t.raw(key)`, exactly like
+    // `next-intl`'s translator shape.
+    translateFunction.raw = rawFunction;
     setTranslationCache(cacheKeyValue, translateFunction);
     return translateFunction;
 }

package/dist/src/server/components/server_provider_static.d.ts

@@ -0,0 +1,53 @@
+import type { TranslationObject } from "../../types/types";
+/**
+ * `output: 'export'`-safe variant of `IntlProvider`, exported publicly as
+ * `cloudflare-next-intl/serverProviderStatic`. Identical to the regular
+ * `IntlProvider` (`cloudflare-next-intl/serverProvider`) except it renders
+ * `client_provider_static` instead of `client_provider` — a client provider
+ * with zero import of `firebase_auth/client/auth_user_provider`, and
+ * therefore zero reachability to the "use server" `clear_session_action`
+ * file that module pulls in.
+ *
+ * Next's server-actions build step registers a "use server" file the
+ * moment any `import()` in the compiled module graph points to it, even one
+ * guarded by a runtime `if` — the guard doesn't remove the import
+ * *statement*, only skips executing it. `output: 'export'` builds fail
+ * outright the instant any server action is registered anywhere in the app,
+ * so a config flag on the regular `IntlProvider` can't fix this: only a
+ * provider tree with the import textually absent can. Use this variant on
+ * any app built with `output: 'export'` that does not configure
+ * `firebaseAuth` — it does not support `firebaseAuth` at all (that config
+ * key must be omitted; `AuthUserProvider` is never rendered here regardless
+ * of the config value). Regular server-rendered/Cloudflare-Workers apps
+ * should keep using `cloudflare-next-intl/serverProvider`.
+ *
+ * Wrap this around your app once, near the root layout, below `[locale]`.
+ * It seeds the server-side locale/message caches (for `getLocale`/`getTranslations`)
+ * and also passes them to the client `LocaleContext` (for `useLocale`/`useTranslations`
+ * in client components).
+ *
+ * @param language The current route's locale (typically the `[locale]` route
+ *   param). Must be one of your configured `locales` — calls `notFound()`
+ *   otherwise.
+ * @param messages Optional pre-loaded messages for `language`. If omitted,
+ *   they're loaded via `getMessage(language)`.
+ *
+ * @example
+ * ```tsx
+ * export default async function RootLayout({ children, params }) {
+ *   const { locale } = await params;
+ *   return (
+ *     <html lang={locale}>
+ *       <body>
+ *         <IntlProvider language={locale}>{children}</IntlProvider>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+export default function LocationzationProvider({ language, messages, children }: {
+    language: string;
+    messages?: TranslationObject;
+    children: React.ReactNode;
+}): Promise<Component>;

package/dist/src/server/components/server_provider_static.js

@@ -0,0 +1,108 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { setLocaleCache, setMessageForLocaleCache } from "../../general/cache_variables";
+import { getMessage } from "../functions/server";
+import dynamic from "next/dynamic";
+import { localesSet } from "../../config/middleware";
+import config from "../../config/intl_config";
+import resolveRequiresConsent from "../../cookie_consent/gdpr_countries";
+import installConsoleErrorOverride from "../../error_handling/install_console_error_override";
+import reportError from "../../error_handling/report_error";
+const LocationzationClientProvider = dynamic(() => import("../../client/components/client_provider_static"));
+/**
+ * `output: 'export'`-safe variant of `IntlProvider`, exported publicly as
+ * `cloudflare-next-intl/serverProviderStatic`. Identical to the regular
+ * `IntlProvider` (`cloudflare-next-intl/serverProvider`) except it renders
+ * `client_provider_static` instead of `client_provider` — a client provider
+ * with zero import of `firebase_auth/client/auth_user_provider`, and
+ * therefore zero reachability to the "use server" `clear_session_action`
+ * file that module pulls in.
+ *
+ * Next's server-actions build step registers a "use server" file the
+ * moment any `import()` in the compiled module graph points to it, even one
+ * guarded by a runtime `if` — the guard doesn't remove the import
+ * *statement*, only skips executing it. `output: 'export'` builds fail
+ * outright the instant any server action is registered anywhere in the app,
+ * so a config flag on the regular `IntlProvider` can't fix this: only a
+ * provider tree with the import textually absent can. Use this variant on
+ * any app built with `output: 'export'` that does not configure
+ * `firebaseAuth` — it does not support `firebaseAuth` at all (that config
+ * key must be omitted; `AuthUserProvider` is never rendered here regardless
+ * of the config value). Regular server-rendered/Cloudflare-Workers apps
+ * should keep using `cloudflare-next-intl/serverProvider`.
+ *
+ * Wrap this around your app once, near the root layout, below `[locale]`.
+ * It seeds the server-side locale/message caches (for `getLocale`/`getTranslations`)
+ * and also passes them to the client `LocaleContext` (for `useLocale`/`useTranslations`
+ * in client components).
+ *
+ * @param language The current route's locale (typically the `[locale]` route
+ *   param). Must be one of your configured `locales` — calls `notFound()`
+ *   otherwise.
+ * @param messages Optional pre-loaded messages for `language`. If omitted,
+ *   they're loaded via `getMessage(language)`.
+ *
+ * @example
+ * ```tsx
+ * export default async function RootLayout({ children, params }) {
+ *   const { locale } = await params;
+ *   return (
+ *     <html lang={locale}>
+ *       <body>
+ *         <IntlProvider language={locale}>{children}</IntlProvider>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+export default async function LocationzationProvider({ language, messages, children }) {
+    if (!localesSet.has(language)) {
+        const { notFound } = await import("next/navigation");
+        notFound();
+    }
+    if (config.firebaseAuth) {
+        throw new Error('[cloudflare-next-intl] `firebaseAuth` is configured but this route uses ' +
+            '`cloudflare-next-intl/serverProviderStatic`, which never renders the firebase-auth ' +
+            'client provider (by design — that\'s what keeps output: "export" builds free of the ' +
+            '"use server" clear_session_action). Use `cloudflare-next-intl/serverProvider` instead ' +
+            'for apps that configure `firebaseAuth`.');
+    }
+    if (language) {
+        setLocaleCache(language);
+    }
+    if (messages) {
+        setMessageForLocaleCache(language, messages);
+    }
+    const messagesValue = messages ?? await getMessage(language);
+    installConsoleErrorOverride(config);
+    let analyticsConfig;
+    let requiresConsent = true;
+    if (config.cookieConsent) {
+        const isDevEnvironment = process.env.NODE_ENV === 'development';
+        // `getCloudflareContext` under `next dev`'s Cloudflare dev shim can
+        // crash the local workerd process (a native RPC panic, not a
+        // catchable JS error — see cloudflare/workers-sdk#8687) merely by
+        // being called, regardless of what it resolves to. `getCountryCode`
+        // is caller-supplied and may be dev-safe, so only skip the
+        // `getCloudflareContext` path in dev; fail-safe to `true`
+        // (banner shown) same as an unresolved country would.
+        requiresConsent = !isDevEnvironment
+            ? await resolveRequiresConsent(config.cookieConsent.getCountryCode, config.generate?.getCloudflareContext, config.cookieConsent.gdprCountries, config.errorHandling)
+            : false;
+        const analyticsAllowedInEnv = config.cookieConsent.enableAnalyticsInDevMode === true || !isDevEnvironment;
+        if (config.cookieConsent.autoWireAnalytics !== false && analyticsAllowedInEnv) {
+            if (config.cookieConsent.getAnalytics) {
+                try {
+                    analyticsConfig = await config.cookieConsent.getAnalytics();
+                }
+                catch (error) {
+                    await reportError(config, { error, classOrMethodName: 'getAnalytics' });
+                }
+            }
+            else {
+                analyticsConfig = config.cookieConsent.analytics;
+            }
+        }
+    }
+    return _jsx(LocationzationClientProvider, { language: language, messages: messagesValue, analyticsConfig: analyticsConfig, requiresConsent: requiresConsent, autoWireDialogs: config.cookieConsent?.autoWireDialogs !== false, dialogProps: config.cookieConsent?.dialogProps, updateDialogProps: config.cookieConsent?.updateDialogProps, children: children });
+}

package/dist/src/types/types.d.ts

@@ -714,12 +714,30 @@ export interface CookieAttributes {
      */
     secure?: boolean | undefined;
 }
-export type TranslationEntry = string | TranslationObject;
+export type TranslationEntry = string | TranslationObject | TranslationEntry[];
 export interface TranslationObject {
     [key: string]: TranslationEntry;
 }
 export type ReturnType = string;
-export type TranslatorReturnType = (key: string) => ReturnType;
+export interface TranslatorReturnType {
+    /** Looks up `key` and coerces it to a `string`. If the value at `key` isn't a plain string (it's an array or object), this warns and returns `key` itself — use {@link TranslatorReturnType.raw} for those cases instead. */
+    (key: string): ReturnType;
+    /**
+     * Escape hatch for non-string message values. `t(key)` always returns a
+     * `string` and can't represent arrays/objects; `t.raw(key)` returns the
+     * value exactly as stored in `messages/<locale>.json` — string, array,
+     * or nested object, unmodified. Use it whenever a message is a list
+     * (e.g. social links, FAQ entries) rather than plain text. Mirrors
+     * `next-intl`'s `t.raw`, so existing `next-intl` usage patterns apply
+     * as-is.
+     *
+     * @example
+     * // messages/en.json: { "Index": { "items": ["a", "b", "c"] } }
+     * const t = await getTranslations("Index");
+     * const items = t.raw("items") as string[]; // ["a", "b", "c"]
+     */
+    raw(key: string): TranslationEntry;
+}
 export type changeFrequency = 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never' | undefined;
 export type Alternates = {
     languages?: Languages<string> | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudflare-next-intl",
-  "version": "0.6.34",
+  "version": "0.7.1",
   "description": "Optimized Next Intl Package Special for App Router and Cloudflare",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -36,6 +36,10 @@
       "types": "./dist/src/server/components/server_provider.d.ts",
       "import": "./dist/src/server/components/server_provider.js"
     },
+    "./serverProviderStatic": {
+      "types": "./dist/src/server/components/server_provider_static.d.ts",
+      "import": "./dist/src/server/components/server_provider_static.js"
+    },
     "./Link": {
       "types": "./dist/src/server/components/link.d.ts",
       "import": "./dist/src/server/components/link.js"