@better-i18n/next 0.1.0

package/README.md

@@ -0,0 +1,100 @@
+# @better-i18n/next
+
+Headless Next.js integration for Better i18n. This package owns your `next-intl` wiring, middleware/proxy, and CDN fetching.
+
+## Install
+
+```bash
+npm i @better-i18n/next next-intl
+```
+
+## Quick start
+
+```ts
+// i18n.ts
+import { createI18n } from "@better-i18n/next";
+
+export const i18n = createI18n({
+  workspaceId: "ws_123",
+  projectSlug: "landing",
+  defaultLocale: "en",
+  debug: process.env.NODE_ENV !== "production",
+});
+```
+
+```ts
+// app/i18n/request.ts
+import { i18n } from "./i18n";
+
+export default i18n.requestConfig;
+```
+
+```ts
+// middleware.ts (Next 15.x)
+import { i18n } from "./i18n";
+
+export default i18n.middleware;
+
+export const config = {
+  matcher: ["/", "/((?!api|_next|_vercel|.*\\..*).*)"],
+};
+```
+
+```ts
+// proxy.ts (Next 16+)
+import { i18n } from "./i18n";
+
+export default i18n.proxy;
+```
+
+## Client hook
+
+```tsx
+"use client";
+
+import { useManifestLanguages } from "@better-i18n/next/client";
+
+export function LanguageSwitcher() {
+  const { languages, isLoading, error } = useManifestLanguages({
+    workspaceId: "ws_123",
+    projectSlug: "landing",
+    defaultLocale: "en",
+  });
+
+  if (error) throw error;
+  if (isLoading) return null;
+
+  return (
+    <ul>
+      {languages.map((lang) => (
+        <li key={lang.code}>{lang.nativeName ?? lang.code}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## Server helpers
+
+```ts
+import { getLocales, getMessages } from "@better-i18n/next/server";
+
+const locales = await getLocales({ workspaceId, projectSlug, defaultLocale });
+const messages = await getMessages({ workspaceId, projectSlug, defaultLocale }, "tr");
+```
+
+## Debug logging
+
+- `BETTER_I18N_DEBUG=1`
+- `BETTER_I18N_LOG_LEVEL=debug|info|warn|error|silent`
+
+`debug` in config also enables verbose logs.
+
+## Notes
+
+- Fail-fast: CDN errors throw (no local fallback).
+- For Next apps, ensure `transpilePackages: ["@better-i18n/next"]` if your bundler doesn’t compile TS in node_modules.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@better-i18n/next",
+  "version": "0.1.0",
+  "description": "Better-i18n Next.js integration",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/better-i18n/better-i18n.git",
+    "directory": "packages/next"
+  },
+  "bugs": {
+    "url": "https://github.com/better-i18n/better-i18n/issues"
+  },
+  "homepage": "https://github.com/better-i18n/better-i18n/tree/main/packages/next",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./server": {
+      "types": "./src/server.ts",
+      "default": "./src/server.ts"
+    },
+    "./client": {
+      "types": "./src/client.ts",
+      "default": "./src/client.ts"
+    },
+    "./middleware": {
+      "types": "./src/middleware.ts",
+      "default": "./src/middleware.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "package.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "i18n",
+    "localization",
+    "nextjs",
+    "next-intl",
+    "cdn"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "next": ">=15.0.0",
+    "next-intl": ">=4.0.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "next": "^15.4.4",
+    "next-intl": "^4.5.8",
+    "@repo/typescript-config": "workspace:*",
+    "@types/node": "^20.0.0",
+    "@types/react": "^19.0.0",
+    "typescript": "~5.9.2"
+  }
+}

package/src/client.ts

@@ -0,0 +1,153 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+
+import { getProjectBaseUrl, normalizeConfig } from "./config";
+import { createLogger } from "./logger";
+import { extractLanguages } from "./manifest";
+import type {
+  I18nConfig,
+  LanguageOption,
+  ManifestResponse,
+} from "./types";
+
+export type UseManifestLanguagesResult = {
+  languages: LanguageOption[];
+  isLoading: boolean;
+  error: Error | null;
+};
+
+type ClientCacheEntry = {
+  data?: LanguageOption[];
+  error?: Error;
+  promise?: Promise<LanguageOption[]>;
+};
+
+const clientCache = new Map<string, ClientCacheEntry>();
+
+const getCacheKey = (config: I18nConfig) =>
+  `${config.cdnBaseUrl || "https://cdn.better-i18n.com"}|${config.workspaceId}|${config.projectSlug}`;
+
+const fetchManifestLanguages = async (
+  config: I18nConfig,
+  logger: ReturnType<typeof createLogger>,
+  signal?: AbortSignal,
+): Promise<LanguageOption[]> => {
+  const normalized = normalizeConfig(config);
+  const url = `${getProjectBaseUrl(normalized)}/manifest.json`;
+  logger.debug("fetch", url);
+
+  const response = await (normalized.fetch ?? fetch)(url, {
+    cache: "no-store",
+    signal,
+  });
+
+  if (!response.ok) {
+    throw new Error(`[better-i18n] Manifest fetch failed (${response.status})`);
+  }
+
+  const data = (await response.json()) as ManifestResponse;
+  const languages = extractLanguages(data);
+
+  if (languages.length === 0) {
+    throw new Error("[better-i18n] No languages found in manifest");
+  }
+
+  return languages;
+};
+
+export const useManifestLanguages = (
+  config: I18nConfig,
+): UseManifestLanguagesResult => {
+  const normalized = useMemo(
+    () => normalizeConfig(config),
+    [
+      config.workspaceId,
+      config.projectSlug,
+      config.defaultLocale,
+      config.cdnBaseUrl,
+      config.localePrefix,
+      config.debug,
+      config.logLevel,
+      config.manifestCacheTtlMs,
+      config.manifestRevalidateSeconds,
+      config.messagesRevalidateSeconds,
+      config.fetch,
+    ],
+  );
+  const logger = useMemo(() => createLogger(normalized, "client"), [
+    normalized,
+  ]);
+
+  const cacheKey = getCacheKey(normalized);
+  const cached = clientCache.get(cacheKey);
+
+  const [languages, setLanguages] = useState<LanguageOption[]>(
+    cached?.data ?? [],
+  );
+  const [isLoading, setIsLoading] = useState(!cached?.data);
+  const [error, setError] = useState<Error | null>(cached?.error ?? null);
+
+  useEffect(() => {
+    let isMounted = true;
+    const controller = new AbortController();
+
+    const run = async () => {
+      try {
+        const entry = clientCache.get(cacheKey) ?? {};
+
+        if (entry.data) {
+          if (isMounted) {
+            setLanguages(entry.data);
+            setError(entry.error ?? null);
+            setIsLoading(false);
+          }
+          return;
+        }
+
+        if (!entry.promise) {
+          entry.promise = fetchManifestLanguages(
+            normalized,
+            logger,
+            controller.signal,
+          )
+            .then((nextLanguages) => {
+              clientCache.set(cacheKey, { data: nextLanguages });
+              return nextLanguages;
+            })
+            .catch((err) => {
+              const nextError = err instanceof Error ? err : new Error(String(err));
+              clientCache.set(cacheKey, { error: nextError });
+              throw nextError;
+            });
+          clientCache.set(cacheKey, entry);
+        }
+
+        const nextLanguages = await entry.promise;
+
+        if (isMounted) {
+          setLanguages(nextLanguages);
+          setError(null);
+        }
+      } catch (err) {
+        if (!isMounted) return;
+        const nextError = err instanceof Error ? err : new Error(String(err));
+        logger.error(nextError);
+        setError(nextError);
+      } finally {
+        if (isMounted) {
+          setIsLoading(false);
+        }
+      }
+    };
+
+    run();
+
+    return () => {
+      isMounted = false;
+      controller.abort();
+    };
+  }, [cacheKey, logger, normalized]);
+
+  return { languages, isLoading, error };
+};

package/src/config.ts

@@ -0,0 +1,27 @@
+import type { I18nConfig, NormalizedConfig } from "./types";
+
+const DEFAULT_CDN_BASE_URL = "https://cdn.better-i18n.com";
+
+export const normalizeConfig = (config: I18nConfig): NormalizedConfig => {
+  if (!config.workspaceId?.trim()) {
+    throw new Error("[better-i18n] workspaceId is required");
+  }
+  if (!config.projectSlug?.trim()) {
+    throw new Error("[better-i18n] projectSlug is required");
+  }
+  if (!config.defaultLocale?.trim()) {
+    throw new Error("[better-i18n] defaultLocale is required");
+  }
+
+  return {
+    ...config,
+    cdnBaseUrl: config.cdnBaseUrl?.replace(/\/$/, "") || DEFAULT_CDN_BASE_URL,
+    localePrefix: config.localePrefix ?? "as-needed",
+    manifestCacheTtlMs: config.manifestCacheTtlMs ?? 5 * 60 * 1000,
+    manifestRevalidateSeconds: config.manifestRevalidateSeconds ?? 3600,
+    messagesRevalidateSeconds: config.messagesRevalidateSeconds ?? 30,
+  };
+};
+
+export const getProjectBaseUrl = (config: NormalizedConfig) =>
+  `${config.cdnBaseUrl}/${config.workspaceId}/${config.projectSlug}`;

package/src/core.ts

@@ -0,0 +1,147 @@
+import { normalizeConfig, getProjectBaseUrl } from "./config";
+import { createLogger } from "./logger";
+import { extractLanguages } from "./manifest";
+import type {
+  I18nConfig,
+  LanguageOption,
+  ManifestResponse,
+  Messages,
+  NextFetchRequestInit,
+  NormalizedConfig,
+} from "./types";
+
+type ManifestCacheEntry = {
+  value: ManifestResponse;
+  expiresAt: number;
+};
+
+const manifestCache = new Map<string, ManifestCacheEntry>();
+
+const buildCacheKey = (config: NormalizedConfig) =>
+  `${config.cdnBaseUrl}|${config.workspaceId}|${config.projectSlug}`;
+
+const withRevalidate = (
+  init: NextFetchRequestInit,
+  revalidateSeconds?: number,
+): NextFetchRequestInit => {
+  if (!revalidateSeconds || revalidateSeconds <= 0) {
+    return init;
+  }
+
+  const { cache, ...rest } = init;
+
+  return {
+    ...rest,
+    next: {
+      ...init.next,
+      revalidate: revalidateSeconds,
+    },
+  };
+};
+
+export const fetchManifest = async (
+  config: I18nConfig,
+  init: NextFetchRequestInit = {},
+): Promise<ManifestResponse> => {
+  const normalized = normalizeConfig(config);
+  const logger = createLogger(normalized, "manifest");
+  const url = `${getProjectBaseUrl(normalized)}/manifest.json`;
+  const requestInit = withRevalidate(
+    {
+      ...init,
+    },
+    normalized.manifestRevalidateSeconds,
+  );
+
+  logger.debug("fetch", url);
+
+  const fetchFn = normalized.fetch ?? fetch;
+  const response = await fetchFn(url, requestInit);
+
+  if (!response.ok) {
+    const message = `[better-i18n] Manifest fetch failed (${response.status})`;
+    logger.error(message);
+    throw new Error(message);
+  }
+
+  const data = (await response.json()) as ManifestResponse;
+  if (!Array.isArray(data.languages)) {
+    throw new Error("[better-i18n] Manifest payload missing languages array");
+  }
+
+  logger.debug("fetched", { languages: data.languages.length });
+  return data;
+};
+
+export const getManifest = async (
+  config: I18nConfig,
+  options: { forceRefresh?: boolean } = {},
+): Promise<ManifestResponse> => {
+  const normalized = normalizeConfig(config);
+  const cacheKey = buildCacheKey(normalized);
+  const now = Date.now();
+  const cached = manifestCache.get(cacheKey);
+
+  if (!options.forceRefresh && cached && cached.expiresAt > now) {
+    return cached.value;
+  }
+
+  const manifest = await fetchManifest(normalized);
+  manifestCache.set(cacheKey, {
+    value: manifest,
+    expiresAt: now + (normalized.manifestCacheTtlMs ?? 0),
+  });
+
+  return manifest;
+};
+
+export const getLocales = async (config: I18nConfig): Promise<string[]> => {
+  const manifest = await getManifest(config);
+  const languages = extractLanguages(manifest);
+
+  if (languages.length === 0) {
+    throw new Error("[better-i18n] No locales found in manifest");
+  }
+
+  return languages.map((language) => language.code);
+};
+
+export const getMessages = async (
+  config: I18nConfig,
+  locale: string,
+): Promise<Messages> => {
+  const normalized = normalizeConfig(config);
+  const logger = createLogger(normalized, "messages");
+  const url = `${getProjectBaseUrl(normalized)}/${locale}/translations.json`;
+
+  const requestInit = withRevalidate(
+    {},
+    normalized.messagesRevalidateSeconds,
+  );
+
+  logger.debug("fetch", url);
+
+  const fetchFn = normalized.fetch ?? fetch;
+  const response = await fetchFn(url, requestInit);
+
+  if (!response.ok) {
+    const message = `[better-i18n] Messages fetch failed (${response.status})`;
+    logger.error(message);
+    throw new Error(message);
+  }
+
+  return (await response.json()) as Messages;
+};
+
+export const getManifestLanguages = async (
+  config: I18nConfig,
+): Promise<LanguageOption[]> => {
+  const manifest = await getManifest(config);
+  const languages = extractLanguages(manifest);
+
+  if (languages.length === 0) {
+    throw new Error("[better-i18n] No languages found in manifest");
+  }
+
+  return languages;
+};

package/src/index.ts

@@ -0,0 +1,35 @@
+import type { I18nConfig } from "./types";
+import { normalizeConfig } from "./config";
+import {
+  createNextIntlRequestConfig,
+  getLocales,
+  getManifest,
+  getMessages,
+} from "./server";
+import { createI18nMiddleware, createI18nProxy } from "./middleware";
+
+export const createI18n = (config: I18nConfig) => {
+  const normalized = normalizeConfig(config);
+
+  return {
+    config: normalized,
+    requestConfig: createNextIntlRequestConfig(normalized),
+    middleware: createI18nMiddleware(normalized),
+    proxy: createI18nProxy(normalized),
+    getManifest: (options?: { forceRefresh?: boolean }) =>
+      getManifest(normalized, options),
+    getLocales: () => getLocales(normalized),
+    getMessages: (locale: string) => getMessages(normalized, locale),
+  };
+};
+
+export type {
+  I18nConfig,
+  LanguageOption,
+  Locale,
+  LocalePrefix,
+  LogLevel,
+  ManifestLanguage,
+  ManifestResponse,
+  Messages,
+} from "./types";

package/src/logger.ts

@@ -0,0 +1,67 @@
+import type { I18nConfig, Logger, LogLevel } from "./types";
+
+const LEVEL_RANK: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  silent: 4,
+};
+
+const getEnv = (key: string): string | undefined => {
+  if (typeof process === "undefined" || !process.env) {
+    return undefined;
+  }
+  return process.env[key];
+};
+
+const normalizeLevel = (level?: string): LogLevel | undefined => {
+  if (!level) return undefined;
+  const normalized = level.toLowerCase();
+  if (normalized in LEVEL_RANK) {
+    return normalized as LogLevel;
+  }
+  return undefined;
+};
+
+const resolveLevel = (config: I18nConfig): LogLevel => {
+  const envDebug = getEnv("BETTER_I18N_DEBUG");
+  if (envDebug && envDebug !== "0" && envDebug.toLowerCase() !== "false") {
+    return "debug";
+  }
+
+  const envLevel = normalizeLevel(getEnv("BETTER_I18N_LOG_LEVEL"));
+  if (envLevel) return envLevel;
+
+  if (config.logLevel) return config.logLevel;
+  if (config.debug) return "debug";
+
+  return "warn";
+};
+
+const shouldLog = (current: LogLevel, target: LogLevel) =>
+  LEVEL_RANK[target] >= LEVEL_RANK[current];
+
+export const createLogger = (config: I18nConfig, scope = "core"): Logger => {
+  const level = resolveLevel(config);
+  const prefix = `[better-i18n:${scope}]`;
+
+  return {
+    debug: (...args: unknown[]) => {
+      if (!shouldLog(level, "debug")) return;
+      console.debug(prefix, ...args);
+    },
+    info: (...args: unknown[]) => {
+      if (!shouldLog(level, "info")) return;
+      console.info(prefix, ...args);
+    },
+    warn: (...args: unknown[]) => {
+      if (!shouldLog(level, "warn")) return;
+      console.warn(prefix, ...args);
+    },
+    error: (...args: unknown[]) => {
+      if (!shouldLog(level, "error")) return;
+      console.error(prefix, ...args);
+    },
+  };
+};

package/src/manifest.ts

@@ -0,0 +1,28 @@
+import type {
+  LanguageOption,
+  ManifestLanguage,
+  ManifestResponse,
+} from "./types";
+
+const normalizeLanguage = (language: ManifestLanguage): LanguageOption => ({
+  code: language.code,
+  name: language.name,
+  nativeName:
+    language.nativeName || language.name || language.code.toUpperCase(),
+  flagUrl: language.flagUrl ?? null,
+});
+
+export const extractLanguages = (
+  manifest: ManifestResponse,
+): LanguageOption[] => {
+  const languages = Array.isArray(manifest.languages)
+    ? manifest.languages
+    : [];
+
+  return languages
+    .filter(
+      (language): language is ManifestLanguage =>
+        !!language && typeof language.code === "string" && language.code.length > 0,
+    )
+    .map(normalizeLanguage);
+};

package/src/middleware.ts

@@ -0,0 +1,27 @@
+import createMiddleware from "next-intl/middleware";
+import type { NextRequest } from "next/server";
+
+import { normalizeConfig } from "./config";
+import { createLogger } from "./logger";
+import { getLocales } from "./core";
+import type { I18nConfig } from "./types";
+
+export const createI18nMiddleware = (config: I18nConfig) => {
+  const normalized = normalizeConfig(config);
+  const logger = createLogger(normalized, "middleware");
+
+  return async function middleware(request: NextRequest) {
+    const locales = await getLocales(normalized);
+    logger.debug("locales", locales);
+
+    const handleI18nRouting = createMiddleware({
+      locales,
+      defaultLocale: normalized.defaultLocale,
+      localePrefix: normalized.localePrefix,
+    });
+
+    return handleI18nRouting(request);
+  };
+};
+
+export const createI18nProxy = createI18nMiddleware;

package/src/server.ts

@@ -0,0 +1,23 @@
+import { getRequestConfig } from "next-intl/server";
+
+import { normalizeConfig } from "./config";
+import { getLocales, getMessages } from "./core";
+import type { I18nConfig } from "./types";
+
+export const createNextIntlRequestConfig = (config: I18nConfig) =>
+  getRequestConfig(async ({ requestLocale }) => {
+    const locales = await getLocales(config);
+    let locale = await requestLocale;
+
+    if (!locale || !locales.includes(locale)) {
+      locale = normalizeConfig(config).defaultLocale;
+    }
+
+    return {
+      locale,
+      messages: await getMessages(config, locale),
+    };
+  });
+
+export { fetchManifest, getLocales, getManifest, getManifestLanguages, getMessages } from "./core";
+export type { LanguageOption, ManifestLanguage, ManifestResponse, Messages } from "./types";

package/src/types.ts

@@ -0,0 +1,70 @@
+export type Locale = string;
+
+export type LocalePrefix = "as-needed" | "always" | "never";
+
+export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+
+export interface I18nConfig {
+  workspaceId: string;
+  projectSlug: string;
+  defaultLocale: string;
+  cdnBaseUrl?: string;
+  localePrefix?: LocalePrefix;
+  debug?: boolean;
+  logLevel?: LogLevel;
+  manifestCacheTtlMs?: number;
+  manifestRevalidateSeconds?: number;
+  messagesRevalidateSeconds?: number;
+  fetch?: typeof fetch;
+}
+
+export interface NormalizedConfig extends I18nConfig {
+  cdnBaseUrl: string;
+  localePrefix: LocalePrefix;
+}
+
+export interface ManifestLanguage {
+  code: string;
+  name?: string;
+  nativeName?: string;
+  flagUrl?: string | null;
+  isSource?: boolean;
+  lastUpdated?: string | null;
+  keyCount?: number;
+}
+
+export interface ManifestFile {
+  url: string;
+  size: number;
+  lastModified: string | null;
+}
+
+export interface ManifestResponse {
+  projectSlug?: string;
+  sourceLanguage?: string;
+  languages: ManifestLanguage[];
+  files?: Record<string, ManifestFile>;
+  updatedAt?: string;
+}
+
+export interface LanguageOption {
+  code: string;
+  name?: string;
+  nativeName?: string;
+  flagUrl?: string | null;
+}
+
+export type Messages = Record<string, any>;
+
+export interface Logger {
+  debug: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+}
+
+export type NextFetchRequestInit = RequestInit & {
+  next?: {
+    revalidate?: number;
+  };
+};