cloudflare-next-intl-intl 0.1.1 → 0.2.0

package/README.md

@@ -1,15 +1,25 @@
 # cloudflare-next-intl-intl
 
-Core internationalization (i18n) and localization package specialized for Next.js App Router and Cloudflare environment.
-Extracted from `cloudflare-next-intl` with zero dependencies on auth, cookie consent, or database modules.
+[![npm](https://img.shields.io/npm/v/cloudflare-next-intl-intl.svg)](https://www.npmjs.com/package/cloudflare-next-intl-intl)
+[![license](https://img.shields.io/npm/l/cloudflare-next-intl-intl.svg)](./LICENSE)
+
+Lightweight internationalization (i18n) for the **Next.js App Router**, built for
+**Cloudflare Workers / Pages** (OpenNext and Vinext).
+
+This is the core i18n engine of [`cloudflare-next-intl`](https://www.npmjs.com/package/cloudflare-next-intl),
+published on its own with **zero runtime dependencies** and no auth, cookie-consent,
+image or database code. Use it when you only need routing + translations; use
+`cloudflare-next-intl` when you also want those extras auto-wired.
 
 ## Features
 
-- **Optimized for Cloudflare**: Designed to work seamlessly with Cloudflare Pages and Workers.
-- **Server Components Support**: Full support for Next.js App Router and Server Components (`use()` hook + server translations).
-- **Fast and Efficient**: Low overhead and minimal bundle size with zero external runtime dependencies.
-- **Tree-shaking**: Properly architected for optimal tree-shaking with individual subpath exports.
-- **Error handling**: Shared error-handling helpers (`reportError`, `withErrorHandling`, `installConsoleErrorOverride`).
+- Locale routing middleware (prefix redirects/rewrites, cookie + `Accept-Language` detection).
+- Translations in Server Components (`getTranslations`) and Client Components (`useTranslations`).
+- Ships only the message namespaces your client components need (`clientMessages`).
+- Locale-aware `Link` / `LocaleLink`, `usePathname`, `getLocale`, `useLocale`.
+- Cloudflare geo helpers: `getCountry`, `getTimezone`.
+- SEO helpers: `hreflang` / canonical alternates via `alternatesLinks`.
+- One subpath export per feature, so unused code is tree-shaken away.
 
 ## Installation
 
@@ -17,14 +27,16 @@ Extracted from `cloudflare-next-intl` with zero dependencies on auth, cookie con
 npm install cloudflare-next-intl-intl
 ```
 
+Peer dependencies: `next` (>= 12) and `react` (>= 16.8).
+
 ## Setup
 
-This package resolves your routing config through the `@intl-config` module
-alias, and messages through `@locale-file`.
+The package finds your config through the `@intl-config` module alias and your
+message files through `@locale-file`.
 
-### 1. Create your config file
+### 1. Create the config file
 
-```typescript
+```ts
 // src/i18n/intl_config.ts
 import { setIntlConfig } from "cloudflare-next-intl-intl/setIntlConfig";
 
@@ -34,12 +46,30 @@ export default setIntlConfig({
 });
 ```
 
-### 2. Point `@intl-config` and `@locale-file` at them in `next.config`
+### 2. Add message files
+
+One JSON file per locale, named `<locale>.json`:
+
+```
+src/i18n/messages/en.json
+src/i18n/messages/de.json
+```
+
+```json
+{
+    "Index": {
+        "title": "Hello world",
+        "items": ["One", "Two"]
+    }
+}
+```
+
+### 3. Add the aliases in `next.config`
 
-Required for both webpack and Turbopack — omitting either breaks the build
-mode that uses it. Path is relative to `next.config`.
+Set them for both Turbopack and webpack. If one is missing, the build that uses
+that bundler fails.
 
-```typescript
+```ts
 // next.config.ts
 import type { NextConfig } from "next";
 import path from "path";
@@ -64,15 +94,187 @@ const nextConfig: NextConfig = {
 export default nextConfig;
 ```
 
-### 2b. Deploying to Cloudflare Workers: alias it in `wrangler.toml` too
+If you deploy to Cloudflare Workers with Wrangler, add the same aliases to `wrangler.toml`:
 
 ```toml
-# wrangler.toml
 [alias]
 "@intl-config" = "./src/i18n/intl_config.ts"
 "@locale-file" = "./src/i18n/messages"
 ```
 
-## Internal Subpaths
+### 4. Add the middleware
+
+```ts
+// src/middleware.ts
+import intlMiddleware from "cloudflare-next-intl-intl/middleware";
+
+export const middleware = intlMiddleware;
+
+export const config = {
+    matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+};
+```
+
+To run your own logic (auth, feature flags, A/B tests) on each request, pass a `middlewareHandler`:
+
+```ts
+export function middleware(request: NextRequest) {
+    return intlMiddleware(request, {
+        middlewareHandler: (locale, rewriteUrl, redirectUrl) => {
+            return null; // return a NextResponse to override, or null to keep the default
+        },
+    });
+}
+```
+
+If you need the final response, for example to update session cookies, build
+your own middleware with `createIntlMiddleware({ afterResponse })`.
+
+### 5. Set up the root layout
+
+```tsx
+// src/app/[locale]/layout.tsx
+import { IntlProvider, IntlHelperScript, getLocaleStaticParams } from "cloudflare-next-intl-intl/server";
+
+export const generateStaticParams = getLocaleStaticParams;
+
+export default async function RootLayout({ children, params }) {
+    const { locale } = await params;
+    return (
+        <html lang={locale}>
+            <head>
+                <IntlHelperScript locale={locale} />
+            </head>
+            <body>
+                <IntlProvider language={locale}>{children}</IntlProvider>
+            </body>
+        </html>
+    );
+}
+```
+
+If you build with `output: "export"`, import `IntlProvider` from
+`cloudflare-next-intl-intl/serverProviderStatic` instead.
+
+## Usage
+
+### Server Components
+
+```tsx
+import { getTranslations, getLocale } from "cloudflare-next-intl-intl/server";
+
+export default async function Page() {
+    const t = await getTranslations("Index");
+    const locale = await getLocale();
+    const items = t.raw("items") as string[];
+
+    return <h1>{t("title")} ({locale})</h1>;
+}
+```
+
+`t(key)` always returns a string. For arrays or nested objects, use `t.raw(key)`.
+
+### Client Components
+
+```tsx
+"use client";
+
+import { useTranslations, useLocale } from "cloudflare-next-intl-intl/use";
+
+export function Title() {
+    const t = useTranslations("Index");
+    const locale = useLocale();
+    return <h1>{t("title")} ({locale})</h1>;
+}
+```
+
+`cloudflare-next-intl-intl/use` works in both Server and Client Components and
+picks the right implementation automatically.
+
+By default (`clientMessages: "auto"`), only the namespaces your client
+components use are sent to the browser. You can set this in `setIntlConfig`:
+
+- `clientMessages: false`: send no messages to the browser.
+- `clientMessages: true`: send all messages.
+- `clientMessages: ["Common", "Auth*"]`: send only the listed namespaces (prefix wildcards allowed).
+
+### Links
+
+```tsx
+import Link from "cloudflare-next-intl-intl/Link";
+import LocaleLink from "cloudflare-next-intl-intl/LocaleLink";
+
+<Link href="/about">About</Link>              // stays on the current locale: "/about" or "/de/about"
+<LocaleLink href="/" locale="de">Deutsch</LocaleLink> // client-only, switches the locale
+```
+
+`usePathname` (`cloudflare-next-intl-intl/usePathname`) returns the current path
+without the locale prefix.
+
+### Geo & timezone (Cloudflare)
+
+```tsx
+import { getCountry, getTimezone } from "cloudflare-next-intl-intl/geo";
+
+const country = await getCountry();               // "US", "DE", "UA", ...
+const timezone = await getTimezone(undefined, "UTC");
+```
+
+These work in Server Components, Server Actions, Route Handlers, and middleware
+(pass `request` there). The middleware forwards the Cloudflare
+`x-cf-country` / `x-cf-timezone` headers, so these values are also available
+further down the request. You can change the header names with
+`generate.countryHeaderNames` / `generate.timezoneHeaderNames`.
+
+### SEO metadata
+
+```ts
+import { alternatesLinks } from "cloudflare-next-intl-intl/metadata";
+
+export async function generateMetadata({ params }) {
+    const { locale } = await params;
+    return {
+        alternates: alternatesLinks({ url: "https://example.com", locale, linkPart: "/about" }),
+    };
+}
+```
+
+### Cookies
+
+```ts
+import setCookie from "cloudflare-next-intl-intl/setCookie";
+import getCookie from "cloudflare-next-intl-intl/getCookie";
+```
+
+## Public subpath exports
+
+| Subpath | Contents |
+| --- | --- |
+| `.` | Everything below (prefer the specific subpaths for tree-shaking) |
+| `./setIntlConfig` | `setIntlConfig` |
+| `./middleware` | default `intlMiddleware`, `createIntlMiddleware` |
+| `./server` | `getTranslations`, `getLocale`, `getMessage`, `IntlProvider`, `Link`, `IntlHelperScript`, `getLocaleStaticParams`, `getCountry`, `getTimezone` |
+| `./client` | `LocaleLink`, `usePathname`, `setCookieClient`, `getCookieClient` |
+| `./use` | `useTranslations`, `useLocale` (works in Server and Client Components) |
+| `./serverProvider`, `./serverProviderStatic` | `IntlProvider` variants |
+| `./Link`, `./LocaleLink`, `./usePathname`, `./IntlHelperScript` | Single components / hooks |
+| `./geo`, `./getCountry`, `./getTimezone` | Geo helpers |
+| `./metadata` | `alternatesLinks`, `languages` |
+| `./localeStaticParams` | `getLocaleStaticParams` |
+| `./setCookie`, `./getCookie`, `./setCookieClient`, `./getCookieClient` | Cookie helpers |
+| `./types` | TypeScript types (`IntlRoutingConfig`, `RoutingConfig`, ...) |
+
+`./internal/*` subpaths are only for wrapper packages such as
+`cloudflare-next-intl` and `cloudflare-next-intl-auth`. Don't import them in
+your app; they can change in any release.
+
+## Related packages
+
+- [`cloudflare-next-intl`](https://www.npmjs.com/package/cloudflare-next-intl): all-in-one package (i18n + auth + cookie consent + theme + errors + images + DB), auto-wired.
+- [`cloudflare-next-intl-errors`](https://www.npmjs.com/package/cloudflare-next-intl-errors): Error reporting, overrides, and stale-deploy recovery.
+- [`cloudflare-next-intl-theme`](https://www.npmjs.com/package/cloudflare-next-intl-theme): Theme switcher and dark mode cookies.
+- [`cloudflare-next-intl-auth`](https://www.npmjs.com/package/cloudflare-next-intl-auth): Firebase Auth & App Check built on this package.
+
+## License
 
-Subpaths under `cloudflare-next-intl-intl/internal/*` are designed for consumption by wrapper packages (like `cloudflare-next-intl`). End-user applications should use public exports such as `cloudflare-next-intl-intl`, `cloudflare-next-intl-intl/client`, `cloudflare-next-intl-intl/server`, `cloudflare-next-intl-intl/middleware`, and `cloudflare-next-intl-intl/types`.
+MIT

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

@@ -5,4 +5,4 @@ export default function LocationzationClientProvider({ language, messages, child
     language: string;
     messages: TranslationObject;
     children?: React.ReactNode;
-}): import("react/jsx-runtime").JSX.Element;
+}): import("react").JSX.Element;

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

@@ -2,16 +2,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { setLocaleCache, setMessageForLocaleCache } from "../../general/cache_variables.js";
 import { useMemo } from "react";
-import config from "../../config/intl_config.js";
-import installConsoleErrorOverride from "../../error_handling/install_console_error_override.js";
-import installGlobalErrorOverride from "../../error_handling/install_global_error_override.js";
 import { LocaleContext } from "./locale_provider.js";
 export { LocaleContext };
 export default function LocationzationClientProvider({ language, messages, children, }) {
     setLocaleCache(language);
     setMessageForLocaleCache(language, messages);
-    installConsoleErrorOverride(config, true);
-    installGlobalErrorOverride(config);
     const contextValue = useMemo(() => ({ language, messages }), [language, messages]);
     return (_jsx(LocaleContext.Provider, { value: contextValue, children: children }));
 }

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

@@ -5,4 +5,4 @@ export default function LocationzationClientProvider({ language, messages, child
     language: string;
     messages: TranslationObject;
     children: React.ReactNode;
-}): import("react/jsx-runtime").JSX.Element;
+}): import("react").JSX.Element;

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

@@ -2,16 +2,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { setLocaleCache, setMessageForLocaleCache } from "../../general/cache_variables.js";
 import { useMemo } from "react";
-import config from "../../config/intl_config.js";
-import installConsoleErrorOverride from "../../error_handling/install_console_error_override.js";
-import installGlobalErrorOverride from "../../error_handling/install_global_error_override.js";
 import { LocaleContext } from "./locale_provider.js";
 export { LocaleContext };
 export default function LocationzationClientProvider({ language, messages, children, }) {
     setLocaleCache(language);
     setMessageForLocaleCache(language, messages);
-    installConsoleErrorOverride(config, true);
-    installGlobalErrorOverride(config);
     const contextValue = useMemo(() => ({ language, messages }), [language, messages]);
     return (_jsx(LocaleContext.Provider, { value: contextValue, children: children }));
 }

package/dist/src/client/functions/get_cookie.js

@@ -1,5 +1,5 @@
 "use client";
-import reportError from "../../error_handling/report_error.js";
+import reportIntlError from "../../general/report_intl_error.js";
 export default function getCookie(name) {
     try {
         const cookie = document.cookie;
@@ -20,12 +20,7 @@ export default function getCookie(name) {
         return decodeURIComponent(value);
     }
     catch (e) {
-        void reportError(undefined, {
-            error: e,
-            classOrMethodName: 'getCookie',
-            isClient: true,
-            params: { name },
-        });
+        reportIntlError(e, 'getCookie');
         return null;
     }
 }

package/dist/src/client/functions/set_cookie.js

@@ -1,17 +1,12 @@
 "use client";
-import reportError from "../../error_handling/report_error.js";
+import reportIntlError from "../../general/report_intl_error.js";
 export default function setCookie({ name, value, maxAge }) {
     try {
         const cookieString = `${name}=${value}; path=/; max-age=${maxAge ?? 31536000}; SameSite=Lax;`;
         document.cookie = cookieString;
     }
     catch (e) {
-        void reportError(undefined, {
-            error: e,
-            classOrMethodName: 'setCookie',
-            isClient: true,
-            params: { name },
-        });
+        reportIntlError(e, 'setCookie');
     }
 }
 ;

package/dist/src/config/cookie_key.d.ts

@@ -1,7 +1,4 @@
 export declare const localeCookieName = "__user_locale_key__";
 export declare const isBotCookieKey = "__is_bot_key__";
-export declare const isDarkCookieKey = "__is_dark_key__";
-export declare const cookieConsentCookieKey = "__cookie_consent_key__";
-export declare const privacyPolicyDateCookieKey = "__privacy_policy_date_key__";
 export declare const countryCookieKey = "__cf_country__";
 export declare const timezoneCookieKey = "__cf_timezone__";

package/dist/src/config/cookie_key.js

@@ -1,7 +1,4 @@
 export const localeCookieName = '__user_locale_key__';
 export const isBotCookieKey = '__is_bot_key__';
-export const isDarkCookieKey = '__is_dark_key__';
-export const cookieConsentCookieKey = '__cookie_consent_key__';
-export const privacyPolicyDateCookieKey = '__privacy_policy_date_key__';
 export const countryCookieKey = '__cf_country__';
 export const timezoneCookieKey = '__cf_timezone__';

package/dist/src/config/create_intl_middleware.d.ts

@@ -10,7 +10,7 @@ export type IntlMiddlewareHook = (response: NextResponse, ctx: IntlMiddlewareCon
 export declare const localesSet: Set<string>;
 export declare function createIntlMiddleware(middlewareOptions?: {
     afterResponse?: IntlMiddlewareHook;
-}): (request: NextRequest, options?: {
+}): (request: any, options?: {
     middlewareHandler?: MiddlewareCustomHandler;
     runHandlerOnRedirect?: boolean;
 }) => Promise<NextResponse>;

package/dist/src/config/create_intl_middleware.js

@@ -3,7 +3,7 @@ import { languageDetecotr } from '../server/functions/get_user_locale.js';
 import config from './intl_config.js';
 import { countryCookieKey, isBotCookieKey, localeCookieName, timezoneCookieKey } from './cookie_key.js';
 import { cache } from 'react';
-import reportError from '../error_handling/report_error.js';
+import reportIntlError from '../general/report_intl_error.js';
 import { defaultCountryHeaderNames, defaultTimezoneHeaderNames } from '../server/functions/geo.js';
 const sameSite = false;
 const defaultCookieOption = {
@@ -69,14 +69,11 @@ export function createIntlMiddleware(middlewareOptions) {
             }
             const effectiveLocaleForRequest = urlLocale ?? initialChosenLocale;
             const cf = request.cf;
-            const cookieConsentConfig = config.cookieConsent;
-            const countryHeaderNames = cookieConsentConfig?.countryHeaderNames
-                ?? config.generate?.countryHeaderNames
+            const countryHeaderNames = config.generate?.countryHeaderNames
                 ?? defaultCountryHeaderNames;
             const timezoneHeaderNames = config.generate?.timezoneHeaderNames
                 ?? defaultTimezoneHeaderNames;
-            const countryCookieName = cookieConsentConfig?.countryCookieName
-                ?? config.generate?.countryCookieName
+            const countryCookieName = config.generate?.countryCookieName
                 ?? countryCookieKey;
             const timezoneCookieName = config.generate?.timezoneCookieName
                 ?? timezoneCookieKey;
@@ -168,10 +165,7 @@ export function createIntlMiddleware(middlewareOptions) {
             return response;
         }
         catch (e) {
-            void reportError({ errorHandling: config.errorHandling, generate: config.generate }, {
-                error: e,
-                classOrMethodName: 'intlMiddleware',
-            });
+            reportIntlError(e, 'intlMiddleware');
             return NextResponse.next({
                 request,
             });

package/dist/src/config/index.d.ts

@@ -1,4 +1,4 @@
-export { isBotCookieKey, localeCookieName, isDarkCookieKey, cookieConsentCookieKey, privacyPolicyDateCookieKey } from './cookie_key.js';
+export { isBotCookieKey, localeCookieName, countryCookieKey, timezoneCookieKey } from './cookie_key.js';
 export { default as intlMiddleware } from './middleware.js';
 export { setIntlConfig } from './init_config.js';
 export { default as generateIntlSitemap } from './intl_sitemap.js';

package/dist/src/config/index.js

@@ -1,4 +1,4 @@
-export { isBotCookieKey, localeCookieName, isDarkCookieKey, cookieConsentCookieKey, privacyPolicyDateCookieKey } from './cookie_key.js';
+export { isBotCookieKey, localeCookieName, countryCookieKey, timezoneCookieKey } from './cookie_key.js';
 export { default as intlMiddleware } from './middleware.js';
 export { setIntlConfig } from './init_config.js';
 export { default as generateIntlSitemap } from './intl_sitemap.js';

package/dist/src/config/init_config.js

@@ -1,7 +1,3 @@
-import { setStaleDeployPatterns } from '../error_handling/is_stale_deploy_error.js';
 export function setIntlConfig(config) {
-    if (config.errorHandling?.staleDeployPatterns) {
-        setStaleDeployPatterns(config.errorHandling.staleDeployPatterns);
-    }
     return config;
 }

package/dist/src/config/middleware.d.ts

@@ -1,6 +1,6 @@
 import { createIntlMiddleware, localesSet, type IntlMiddlewareContext, type IntlMiddlewareHook } from './create_intl_middleware.js';
 export { createIntlMiddleware, localesSet, type IntlMiddlewareContext, type IntlMiddlewareHook, };
-declare const intlMiddleware: (request: import("next/server.js").NextRequest, options?: {
+declare const intlMiddleware: (request: any, options?: {
     middlewareHandler?: import("../types/types.js").MiddlewareCustomHandler;
     runHandlerOnRedirect?: boolean;
 }) => Promise<import("next/server.js").NextResponse>;

package/dist/src/general/general_functions.js

@@ -1,5 +1,5 @@
 import { setTranslationCache } from "./cache_variables.js";
-import reportError from "../error_handling/report_error.js";
+import reportIntlError from "./report_intl_error.js";
 const errorAndReturnFallback = (message, cacheKey, locale, namespace, key) => {
     const parts = [
         message,
@@ -7,11 +7,7 @@ const errorAndReturnFallback = (message, cacheKey, locale, namespace, key) => {
         key ? `Key: "${key}"` : '',
         `Locale: "${locale}"`,
     ].filter(Boolean);
-    void reportError(undefined, {
-        error: parts.join(' | '),
-        classOrMethodName: 'getTranslationsImpl',
-        params: { locale, namespace, key },
-    });
+    reportIntlError(parts.join(' | '), 'getTranslationsImpl');
     const fallbackFn = (k) => k;
     fallbackFn.raw = (k) => k;
     setTranslationCache(cacheKey, fallbackFn);

package/dist/src/general/metadata.js

@@ -1,6 +1,6 @@
 import { cache } from "react";
 import config from "../config/intl_config.js";
-import reportError from "../error_handling/report_error.js";
+import reportIntlError from "./report_intl_error.js";
 export function iAlternatesLinks({ locale, url, canonical, linkPart }) {
     try {
         const linkPartValue = linkPart == '/' ? undefined : linkPart;
@@ -10,11 +10,7 @@ export function iAlternatesLinks({ locale, url, canonical, linkPart }) {
         };
     }
     catch (e) {
-        void reportError({ errorHandling: config.errorHandling, generate: config.generate }, {
-            error: e,
-            classOrMethodName: 'alternatesLinks',
-            params: { url, linkPart },
-        });
+        reportIntlError(e, 'alternatesLinks');
         return undefined;
     }
 }

package/dist/src/general/report_intl_error.d.ts

@@ -0,0 +1 @@
+export default function reportIntlError(error: unknown, source: string): void;

package/dist/src/general/report_intl_error.js

@@ -0,0 +1,15 @@
+import config from '../config/intl_config.js';
+export default function reportIntlError(error, source) {
+    if (config.onError) {
+        try {
+            const res = config.onError(error, source);
+            if (res && typeof res.catch === 'function') {
+                res.catch(() => { });
+            }
+        }
+        catch {
+        }
+        return;
+    }
+    console.error('[cloudflare-next-intl-intl]', source, error);
+}

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

@@ -1,6 +1,6 @@
-export declare const defaultReloadHtml = "<div style=\"position:fixed;inset:0;background:#ffffff;display:flex;align-items:center;justify-content:center;z-index:9999999;\"><div style=\"width:36px;height:36px;border:3px solid #e5e7eb;border-top-color:#17181b;border-radius:50%;animation:cfni-spin 0.8s linear infinite;\"></div><style>@keyframes cfni-spin{to{transform:rotate(360deg)}}</style></div>";
-export default function HelperScript({ locale, prefetchOrigins, preconnectOrigins, }: {
+export default function HelperScript({ locale, prefetchOrigins, preconnectOrigins, children, }: {
     locale?: string;
     prefetchOrigins?: string[];
     preconnectOrigins?: string[];
-}): import("react/jsx-runtime").JSX.Element;
+    children?: React.ReactNode;
+}): import("react").JSX.Element;