cloudflare-next-intl-intl 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Demian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,280 @@
-# Temporary Holding Version
+# cloudflare-next-intl-intl
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![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
+
+- 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
+
+```bash
+npm install cloudflare-next-intl-intl
+```
+
+Peer dependencies: `next` (>= 12) and `react` (>= 16.8).
+
+## Setup
+
+The package finds your config through the `@intl-config` module alias and your
+message files through `@locale-file`.
+
+### 1. Create the config file
+
+```ts
+// src/i18n/intl_config.ts
+import { setIntlConfig } from "cloudflare-next-intl-intl/setIntlConfig";
+
+export default setIntlConfig({
+    locales: ["en", "de"],
+    defaultLocale: "en",
+});
+```
+
+### 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`
+
+Set them for both Turbopack and webpack. If one is missing, the build that uses
+that bundler fails.
+
+```ts
+// next.config.ts
+import type { NextConfig } from "next";
+import path from "path";
+
+const nextConfig: NextConfig = {
+    turbopack: {
+        resolveAlias: {
+            "@intl-config": "./src/i18n/intl_config.ts",
+            "@locale-file": "./src/i18n/messages",
+        },
+    },
+    webpack(config) {
+        config.resolve.alias = {
+            ...config.resolve.alias,
+            "@intl-config": path.resolve(__dirname, "src/i18n/intl_config"),
+            "@locale-file": path.resolve(__dirname, "src/i18n/messages"),
+        };
+        return config;
+    },
+};
+
+export default nextConfig;
+```
+
+If you deploy to Cloudflare Workers with Wrangler, add the same aliases to `wrangler.toml`:
+
+```toml
+[alias]
+"@intl-config" = "./src/i18n/intl_config.ts"
+"@locale-file" = "./src/i18n/messages"
+```
+
+### 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
+
+MIT

package/dist/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

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

@@ -0,0 +1,8 @@
+import type { TranslationObject } from "../../types/types.js";
+import { LocaleContext } from "./locale_provider.js";
+export { LocaleContext };
+export default function LocationzationClientProvider({ language, messages, children, }: {
+    language: string;
+    messages: TranslationObject;
+    children?: React.ReactNode;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,12 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { setLocaleCache, setMessageForLocaleCache } from "../../general/cache_variables.js";
+import { useMemo } from "react";
+import { LocaleContext } from "./locale_provider.js";
+export { LocaleContext };
+export default function LocationzationClientProvider({ language, messages, children, }) {
+    setLocaleCache(language);
+    setMessageForLocaleCache(language, messages);
+    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

@@ -0,0 +1,8 @@
+import type { TranslationObject } from "../../types/types.js";
+import { LocaleContext } from "./locale_provider.js";
+export { LocaleContext };
+export default function LocationzationClientProvider({ language, messages, children, }: {
+    language: string;
+    messages: TranslationObject;
+    children: React.ReactNode;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,12 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { setLocaleCache, setMessageForLocaleCache } from "../../general/cache_variables.js";
+import { useMemo } from "react";
+import { LocaleContext } from "./locale_provider.js";
+export { LocaleContext };
+export default function LocationzationClientProvider({ language, messages, children, }) {
+    setLocaleCache(language);
+    setMessageForLocaleCache(language, messages);
+    const contextValue = useMemo(() => ({ language, messages }), [language, messages]);
+    return (_jsx(LocaleContext.Provider, { value: contextValue, children: children }));
+}

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

@@ -0,0 +1,8 @@
+import { type LinkProps } from 'next/link.js';
+import { type ComponentProps } from 'react';
+type NextLinkProps = Omit<ComponentProps<'a'>, keyof LinkProps> & Omit<LinkProps, 'locale' | 'href' | 'prefetch' | 'onNavigate' | 'hrefLang' | 'replace' | 'scroll'>;
+export type LocaleLinkProps = NextLinkProps & {
+    locale: string;
+};
+declare const LocaleLink: import("react").ForwardRefExoticComponent<Omit<LocaleLinkProps, "ref"> & import("react").RefAttributes<HTMLAnchorElement>>;
+export default LocaleLink;

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

@@ -0,0 +1,8 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef, Suspense, } from 'react';
+import LocaleLinkClient from './locale_link_client.js';
+function LocaleLinkComponent(params, ref) {
+    return _jsx(Suspense, { fallback: _jsx("a", { ...params, ref: ref, className: params.className + ' pointer-events-none' }), children: _jsx(LocaleLinkClient, { ref: ref, ...params }) });
+}
+const LocaleLink = forwardRef(LocaleLinkComponent);
+export default LocaleLink;

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

@@ -0,0 +1,3 @@
+import type { LocaleLinkProps } from './locale_link.js';
+declare const LocaleLinkClient: import("react").ForwardRefExoticComponent<Omit<LocaleLinkProps, "ref"> & import("react").RefAttributes<HTMLAnchorElement>>;
+export default LocaleLinkClient;

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

@@ -0,0 +1,30 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef, useEffect, useState, } from 'react';
+import config from '../../config/intl_config.js';
+import usePathname from '../hooks/use_path_name.js';
+import { localeCookieName } from '../../config/cookie_key.js';
+import setCookie from '../functions/set_cookie.js';
+import { useSearchParams } from 'next/navigation.js';
+function ClientLocaleLinkComponent({ locale, className, ...rest }, ref) {
+    const pathname = usePathname();
+    const searchParams = useSearchParams();
+    const [hash, setHash] = useState('');
+    useEffect(() => {
+        setHash(window.location.hash);
+    }, [pathname, searchParams]);
+    const isDefaultLocale = locale === config.defaultLocale;
+    const localePrefix = isDefaultLocale ? '' : `/${locale}`;
+    const search = searchParams.toString();
+    const newPathname = pathname === '/' && (localePrefix) ? '' : pathname;
+    const href = `${localePrefix}${newPathname}${search ? `?${search}` : ''}${hash}`;
+    function handleNavigate(e) {
+        e.preventDefault();
+        setCookie({ name: localeCookieName, value: locale });
+        window.location.replace(href);
+    }
+    ;
+    return _jsx("a", { ref: ref, hrefLang: locale, className: className, ...rest, href: href, onClick: handleNavigate });
+}
+const LocaleLinkClient = forwardRef(ClientLocaleLinkComponent);
+export default LocaleLinkClient;

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

@@ -0,0 +1,13 @@
+import { type ReactNode } from "react";
+import type { TranslationObject } from "../../types/types.js";
+interface LocaleContextType {
+    language: string;
+    messages: TranslationObject;
+}
+export declare const LocaleContext: import("react").Context<LocaleContextType | undefined>;
+export default function LocaleProvider({ language, messages, children }: {
+    language: string;
+    messages: TranslationObject;
+    children: ReactNode;
+}): React.JSX.Element;
+export {};

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

@@ -0,0 +1,8 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useMemo } from "react";
+export const LocaleContext = createContext(undefined);
+export default function LocaleProvider({ language, messages, children }) {
+    const value = useMemo(() => ({ language, messages }), [language, messages]);
+    return _jsx(LocaleContext.Provider, { value: value, children: children });
+}

package/dist/src/client/functions/get_cookie.d.ts

@@ -0,0 +1 @@
+export default function getCookie(name: string): string | null;

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

@@ -0,0 +1,27 @@
+"use client";
+import reportIntlError from "../../general/report_intl_error.js";
+export default function getCookie(name) {
+    try {
+        const cookie = document.cookie;
+        const prefix = `${name}=`;
+        let start = -1;
+        if (cookie.startsWith(prefix)) {
+            start = prefix.length;
+        }
+        else {
+            const idx = cookie.indexOf(`; ${prefix}`);
+            if (idx !== -1)
+                start = idx + 2 + prefix.length;
+        }
+        if (start === -1)
+            return null;
+        const end = cookie.indexOf(';', start);
+        const value = end === -1 ? cookie.slice(start) : cookie.slice(start, end);
+        return decodeURIComponent(value);
+    }
+    catch (e) {
+        reportIntlError(e, 'getCookie');
+        return null;
+    }
+}
+;

package/dist/src/client/functions/set_cookie.d.ts

@@ -0,0 +1,5 @@
+export default function setCookie({ name, value, maxAge }: {
+    name: string;
+    value: string | number | boolean;
+    maxAge?: number;
+}): void;

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

@@ -0,0 +1,12 @@
+"use client";
+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) {
+        reportIntlError(e, 'setCookie');
+    }
+}
+;

package/dist/src/client/hooks/client_hooks.d.ts

@@ -0,0 +1,3 @@
+import type { TranslatorReturnType } from "../../types/types.js";
+export declare function useLocale(): string;
+export declare function useTranslations(namespace: string): TranslatorReturnType;

package/dist/src/client/hooks/client_hooks.js

@@ -0,0 +1,19 @@
+"use client";
+import { useContext, useMemo } from "react";
+import { LocaleContext } from "../components/client_provider.js";
+import { getTranslationsImpl } from "../../general/general_functions.js";
+export function useLocale() {
+    const context = useContext(LocaleContext);
+    if (context === undefined) {
+        throw new Error('useLocale must be used within an IntlProvider');
+    }
+    return context.language;
+}
+export function useTranslations(namespace) {
+    const context = useContext(LocaleContext);
+    if (context === undefined) {
+        throw new Error('useTranslations must be used within an IntlProvider');
+    }
+    const { language, messages } = context;
+    return useMemo(() => getTranslationsImpl(language, messages, namespace), [language, messages, namespace]);
+}

package/dist/src/client/hooks/use_path_name.d.ts

@@ -0,0 +1,2 @@
+export default function usePathname(): string;
+export { usePathname };

package/dist/src/client/hooks/use_path_name.js

@@ -0,0 +1,18 @@
+"use client";
+import { usePathname as nextUsePathname } from "next/navigation.js";
+import { useLocale } from "./client_hooks.js";
+export default function usePathname() {
+    const pathname = nextUsePathname();
+    const locale = useLocale();
+    if (!pathname) {
+        return '/';
+    }
+    const path = pathname.replace(`/${locale}`, '');
+    if (path) {
+        return path;
+    }
+    else {
+        return '/';
+    }
+}
+export { usePathname };

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

@@ -0,0 +1,4 @@
+export { default as LocaleLink } from './components/locale_link.js';
+export { default as usePathname } from './hooks/use_path_name.js';
+export { default as setCookieClient } from './functions/set_cookie.js';
+export { default as getCookieClient } from './functions/get_cookie.js';

package/dist/src/client/index.js

@@ -0,0 +1,4 @@
+export { default as LocaleLink } from './components/locale_link.js';
+export { default as usePathname } from './hooks/use_path_name.js';
+export { default as setCookieClient } from './functions/set_cookie.js';
+export { default as getCookieClient } from './functions/get_cookie.js';

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

@@ -0,0 +1,3 @@
+export { scanFile, type FileScanResult, type DynamicCall } from "./scan_file.js";
+export { matchesNamespacePattern } from "./match_namespace.js";
+export { scanProject, type ScanProjectOptions, type ClientMessagesManifest } from "./scan_project.js";

package/dist/src/client_messages_scan/index.js

@@ -0,0 +1,3 @@
+export { scanFile } from "./scan_file.js";
+export { matchesNamespacePattern } from "./match_namespace.js";
+export { scanProject } from "./scan_project.js";

package/dist/src/client_messages_scan/match_namespace.d.ts

@@ -0,0 +1 @@
+export declare function matchesNamespacePattern(ns: string, pattern: string): boolean;

package/dist/src/client_messages_scan/match_namespace.js

@@ -0,0 +1,3 @@
+export function matchesNamespacePattern(ns, pattern) {
+    return pattern.endsWith("*") ? ns.startsWith(pattern.slice(0, -1)) : ns === pattern;
+}

package/dist/src/client_messages_scan/scan_file.d.ts

@@ -0,0 +1,16 @@
+export interface DynamicCall {
+    file: string;
+    line: number;
+    text: string;
+    prop?: {
+        component: string;
+        name: string;
+    };
+}
+export interface FileScanResult {
+    namespaces: string[];
+    dynamicCalls: DynamicCall[];
+    usesRoot: boolean;
+}
+export declare function findJsxPropValues(file: string, code: string, component: string, prop: string): string[] | null;
+export declare function scanFile(file: string, code: string): FileScanResult;