@nckdv/translation-nextjs 0.2.0

package/README.md

@@ -0,0 +1,145 @@
+# `@nckdv/translation-nextjs`
+
+Server-side Next.js bindings for nck-translation. This package configures the
+SDK from server-only environment variables and exposes catalog and translator
+helpers for Server Components.
+
+React context and hooks live in the framework-neutral
+[`@nckdv/translation-react`](../react) package. Keeping the runtime entries
+separate makes the credential boundary visible in every import:
+
+```text
+@nckdv/translation-nextjs/server  <- server only; reads the project API key
+@nckdv/translation-react          <- client safe; receives plain catalogs
+```
+
+## Install
+
+```bash
+npm install @nckdv/translation-nextjs
+```
+
+The Next.js package installs `@nckdv/translation-react` with it. Import the
+React bindings directly from that package rather than through a Next.js client
+entry.
+
+## Configure
+
+The server helper reads two environment variables:
+
+```bash
+NCK_TRANSLATION_API_URL=https://nck-translation.example.com
+NCK_TRANSLATION_API_KEY=nck_...   # server-side only
+```
+
+The key is a bearer credential for every catalog in the project. Never expose
+it through a `NEXT_PUBLIC_*` variable or pass it to a Client Component.
+
+Configuration can instead be supplied once in code, which is also useful in
+tests:
+
+```ts
+import { configureTranslations } from "@nckdv/translation-nextjs/server";
+
+configureTranslations({
+  apiUrl: "https://nck-translation.example.com",
+  apiKey: process.env.NCK_TRANSLATION_API_KEY!,
+});
+```
+
+## Server Components
+
+`getTranslator(language)` returns a translator bound to one language:
+
+```tsx
+import { getTranslator } from "@nckdv/translation-nextjs/server";
+
+export default async function Page({
+  params,
+}: {
+  params: Promise<{ lang: string }>;
+}) {
+  const { lang } = await params;
+  const t = await getTranslator(lang);
+  return <h1>{t("home.title")}</h1>;
+}
+```
+
+The SDK caches successful catalogs and shares concurrent requests for the same
+language. A failed request is not cached.
+
+Use `getCatalog(language)` when the client tree needs the raw serializable map:
+
+```tsx
+// app/[lang]/layout.tsx -- Server Component
+import { getCatalog } from "@nckdv/translation-nextjs/server";
+import { Providers } from "./providers";
+
+export default async function Layout({ params, children }: LayoutProps) {
+  const { lang } = await params;
+  const catalog = await getCatalog(lang);
+  return (
+    <Providers language={lang} catalog={catalog}>
+      {children}
+    </Providers>
+  );
+}
+```
+
+```tsx
+// app/[lang]/providers.tsx -- Client Component
+"use client";
+
+import {
+  TranslationProvider,
+  type TranslationMap,
+} from "@nckdv/translation-react";
+
+export function Providers({
+  language,
+  catalog,
+  children,
+}: {
+  language: string;
+  catalog: TranslationMap;
+  children: React.ReactNode;
+}) {
+  return (
+    <TranslationProvider language={language} catalog={catalog}>
+      {children}
+    </TranslationProvider>
+  );
+}
+```
+
+Client Components beneath that provider call `useTranslations()` or
+`useLanguage()` from `@nckdv/translation-react`.
+
+After an edit lands, invalidate the SDK cache so the next read goes to the
+platform:
+
+```ts
+import { invalidate } from "@nckdv/translation-nextjs/server";
+
+invalidate("de"); // or invalidate() for every language
+```
+
+## API
+
+### `@nckdv/translation-nextjs/server`
+
+| export | signature |
+| --- | --- |
+| `getTranslator` | `(language: string) => Promise<Translate>` |
+| `getCatalog` | `(language: string) => Promise<Catalog>` |
+| `invalidate` | `(language?: string) => void` |
+| `configureTranslations` | `({ apiUrl, apiKey, cacheMs? }) => void` |
+| `ENV_API_URL` / `ENV_API_KEY` | `string` |
+
+Missing configuration throws at the first helper call. The server entry imports
+`server-only`, so importing it from a Client Component fails the Next.js build.
+
+### `@nckdv/translation-nextjs`
+
+Types only: `Catalog` and `Translate`. Importing the root cannot initialize the
+client or read environment variables.

package/dist/index.cjs

@@ -0,0 +1,19 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+module.exports = __toCommonJS(index_exports);
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Shared, runtime-agnostic surface for `@nckdv/translation-nextjs`.\n *\n * Only types live here, so importing the package root does not pull in the\n * server code that reads the API key. Import server and React behavior from\n * their explicit runtime entries:\n *\n * ```ts\n * import { getTranslator } from \"@nckdv/translation-nextjs/server\";\n * import { TranslationProvider } from \"@nckdv/translation-react\";\n * ```\n */\nexport type { Catalog, Translate } from \"@nckdv/translation-sdk\";\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1 @@
+export { Catalog, Translate } from '@nckdv/translation-sdk';

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { Catalog, Translate } from '@nckdv/translation-sdk';

package/dist/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/server.cjs

@@ -0,0 +1,69 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server.ts
+var server_exports = {};
+__export(server_exports, {
+  ENV_API_KEY: () => ENV_API_KEY,
+  ENV_API_URL: () => ENV_API_URL,
+  configureTranslations: () => configureTranslations,
+  getCatalog: () => getCatalog,
+  getTranslator: () => getTranslator,
+  invalidate: () => invalidate
+});
+module.exports = __toCommonJS(server_exports);
+var import_server_only = require("server-only");
+var import_translation_sdk = require("@nckdv/translation-sdk");
+var ENV_API_URL = "NCK_TRANSLATION_API_URL";
+var ENV_API_KEY = "NCK_TRANSLATION_API_KEY";
+var configured;
+function configureTranslations(options) {
+  configured = (0, import_translation_sdk.createClient)(options);
+}
+function getClient() {
+  if (configured) return configured;
+  const apiUrl = process.env[ENV_API_URL];
+  const apiKey = process.env[ENV_API_KEY];
+  if (!apiUrl || !apiKey) {
+    throw new Error(
+      `@nckdv/translation-nextjs: set ${ENV_API_URL} and ${ENV_API_KEY}, or call configureTranslations() before rendering.`
+    );
+  }
+  configured = (0, import_translation_sdk.createClient)({ apiUrl, apiKey });
+  return configured;
+}
+function getCatalog(language) {
+  return getClient().getCatalog(language);
+}
+function getTranslator(language) {
+  return getClient().getTranslator(language);
+}
+function invalidate(language) {
+  getClient().invalidate(language);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ENV_API_KEY,
+  ENV_API_URL,
+  configureTranslations,
+  getCatalog,
+  getTranslator,
+  invalidate
+});
+//# sourceMappingURL=server.cjs.map

package/dist/server.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["// Poisons this module for the client bundle: importing it from a Client\n// Component is a build error rather than a leaked API key.\nimport \"server-only\";\nimport {\n  createClient,\n  type Catalog,\n  type Client,\n  type Translate,\n} from \"@nckdv/translation-sdk\";\n\n/** Env vars the default client reads. Both are server-only secrets. */\nexport const ENV_API_URL = \"NCK_TRANSLATION_API_URL\";\nexport const ENV_API_KEY = \"NCK_TRANSLATION_API_KEY\";\n\nlet configured: Client | undefined;\n\n/**\n * Point the server helpers at a platform explicitly, instead of via env.\n *\n * Optional — call it once at startup if you would rather pass configuration in\n * code (or in a test). Without it, the first server read builds a client from\n * `NCK_TRANSLATION_API_URL` and `NCK_TRANSLATION_API_KEY`.\n */\nexport function configureTranslations(options: {\n  apiUrl: string;\n  apiKey: string;\n  cacheMs?: number;\n}): void {\n  configured = createClient(options);\n}\n\nfunction getClient(): Client {\n  if (configured) return configured;\n\n  const apiUrl = process.env[ENV_API_URL];\n  const apiKey = process.env[ENV_API_KEY];\n  if (!apiUrl || !apiKey) {\n    throw new Error(\n      `@nckdv/translation-nextjs: set ${ENV_API_URL} and ${ENV_API_KEY}, or call ` +\n        `configureTranslations() before rendering.`,\n    );\n  }\n\n  // Kept across requests so the SDK's TTL cache spans them. The SDK also\n  // shares concurrent in-flight reads for the same language.\n  configured = createClient({ apiUrl, apiKey });\n  return configured;\n}\n\n/**\n * One language's catalog. The SDK caches successful catalogs and shares an\n * in-flight request, so concurrent Server Components make one network call.\n */\nexport function getCatalog(language: string): Promise<Catalog> {\n  return getClient().getCatalog(language);\n}\n\n/**\n * A `t()` bound to `language`, for use in Server Components.\n *\n * ```tsx\n * const t = await getTranslator(lang);\n * return <h1>{t(\"home.title\")}</h1>;\n * ```\n */\nexport function getTranslator(language: string): Promise<Translate> {\n  return getClient().getTranslator(language);\n}\n\n/**\n * Drop the cached catalog for a language (or all of them). Call after an edit\n * lands so the next render re-reads from the platform.\n */\nexport function invalidate(language?: string): void {\n  getClient().invalidate(language);\n}\n\nexport type { Catalog, Translate } from \"@nckdv/translation-sdk\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAEA,yBAAO;AACP,6BAKO;AAGA,IAAM,cAAc;AACpB,IAAM,cAAc;AAE3B,IAAI;AASG,SAAS,sBAAsB,SAI7B;AACP,mBAAa,qCAAa,OAAO;AACnC;AAEA,SAAS,YAAoB;AAC3B,MAAI,WAAY,QAAO;AAEvB,QAAM,SAAS,QAAQ,IAAI,WAAW;AACtC,QAAM,SAAS,QAAQ,IAAI,WAAW;AACtC,MAAI,CAAC,UAAU,CAAC,QAAQ;AACtB,UAAM,IAAI;AAAA,MACR,kCAAkC,WAAW,QAAQ,WAAW;AAAA,IAElE;AAAA,EACF;AAIA,mBAAa,qCAAa,EAAE,QAAQ,OAAO,CAAC;AAC5C,SAAO;AACT;AAMO,SAAS,WAAW,UAAoC;AAC7D,SAAO,UAAU,EAAE,WAAW,QAAQ;AACxC;AAUO,SAAS,cAAc,UAAsC;AAClE,SAAO,UAAU,EAAE,cAAc,QAAQ;AAC3C;AAMO,SAAS,WAAW,UAAyB;AAClD,YAAU,EAAE,WAAW,QAAQ;AACjC;","names":[]}

package/dist/server.d.cts

@@ -0,0 +1,39 @@
+import { Catalog, Translate } from '@nckdv/translation-sdk';
+export { Catalog, Translate } from '@nckdv/translation-sdk';
+
+/** Env vars the default client reads. Both are server-only secrets. */
+declare const ENV_API_URL = "NCK_TRANSLATION_API_URL";
+declare const ENV_API_KEY = "NCK_TRANSLATION_API_KEY";
+/**
+ * Point the server helpers at a platform explicitly, instead of via env.
+ *
+ * Optional — call it once at startup if you would rather pass configuration in
+ * code (or in a test). Without it, the first server read builds a client from
+ * `NCK_TRANSLATION_API_URL` and `NCK_TRANSLATION_API_KEY`.
+ */
+declare function configureTranslations(options: {
+    apiUrl: string;
+    apiKey: string;
+    cacheMs?: number;
+}): void;
+/**
+ * One language's catalog. The SDK caches successful catalogs and shares an
+ * in-flight request, so concurrent Server Components make one network call.
+ */
+declare function getCatalog(language: string): Promise<Catalog>;
+/**
+ * A `t()` bound to `language`, for use in Server Components.
+ *
+ * ```tsx
+ * const t = await getTranslator(lang);
+ * return <h1>{t("home.title")}</h1>;
+ * ```
+ */
+declare function getTranslator(language: string): Promise<Translate>;
+/**
+ * Drop the cached catalog for a language (or all of them). Call after an edit
+ * lands so the next render re-reads from the platform.
+ */
+declare function invalidate(language?: string): void;
+
+export { ENV_API_KEY, ENV_API_URL, configureTranslations, getCatalog, getTranslator, invalidate };

package/dist/server.d.ts

@@ -0,0 +1,39 @@
+import { Catalog, Translate } from '@nckdv/translation-sdk';
+export { Catalog, Translate } from '@nckdv/translation-sdk';
+
+/** Env vars the default client reads. Both are server-only secrets. */
+declare const ENV_API_URL = "NCK_TRANSLATION_API_URL";
+declare const ENV_API_KEY = "NCK_TRANSLATION_API_KEY";
+/**
+ * Point the server helpers at a platform explicitly, instead of via env.
+ *
+ * Optional — call it once at startup if you would rather pass configuration in
+ * code (or in a test). Without it, the first server read builds a client from
+ * `NCK_TRANSLATION_API_URL` and `NCK_TRANSLATION_API_KEY`.
+ */
+declare function configureTranslations(options: {
+    apiUrl: string;
+    apiKey: string;
+    cacheMs?: number;
+}): void;
+/**
+ * One language's catalog. The SDK caches successful catalogs and shares an
+ * in-flight request, so concurrent Server Components make one network call.
+ */
+declare function getCatalog(language: string): Promise<Catalog>;
+/**
+ * A `t()` bound to `language`, for use in Server Components.
+ *
+ * ```tsx
+ * const t = await getTranslator(lang);
+ * return <h1>{t("home.title")}</h1>;
+ * ```
+ */
+declare function getTranslator(language: string): Promise<Translate>;
+/**
+ * Drop the cached catalog for a language (or all of them). Call after an edit
+ * lands so the next render re-reads from the platform.
+ */
+declare function invalidate(language?: string): void;
+
+export { ENV_API_KEY, ENV_API_URL, configureTranslations, getCatalog, getTranslator, invalidate };

package/dist/server.js

@@ -0,0 +1,41 @@
+// src/server.ts
+import "server-only";
+import {
+  createClient
+} from "@nckdv/translation-sdk";
+var ENV_API_URL = "NCK_TRANSLATION_API_URL";
+var ENV_API_KEY = "NCK_TRANSLATION_API_KEY";
+var configured;
+function configureTranslations(options) {
+  configured = createClient(options);
+}
+function getClient() {
+  if (configured) return configured;
+  const apiUrl = process.env[ENV_API_URL];
+  const apiKey = process.env[ENV_API_KEY];
+  if (!apiUrl || !apiKey) {
+    throw new Error(
+      `@nckdv/translation-nextjs: set ${ENV_API_URL} and ${ENV_API_KEY}, or call configureTranslations() before rendering.`
+    );
+  }
+  configured = createClient({ apiUrl, apiKey });
+  return configured;
+}
+function getCatalog(language) {
+  return getClient().getCatalog(language);
+}
+function getTranslator(language) {
+  return getClient().getTranslator(language);
+}
+function invalidate(language) {
+  getClient().invalidate(language);
+}
+export {
+  ENV_API_KEY,
+  ENV_API_URL,
+  configureTranslations,
+  getCatalog,
+  getTranslator,
+  invalidate
+};
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["// Poisons this module for the client bundle: importing it from a Client\n// Component is a build error rather than a leaked API key.\nimport \"server-only\";\nimport {\n  createClient,\n  type Catalog,\n  type Client,\n  type Translate,\n} from \"@nckdv/translation-sdk\";\n\n/** Env vars the default client reads. Both are server-only secrets. */\nexport const ENV_API_URL = \"NCK_TRANSLATION_API_URL\";\nexport const ENV_API_KEY = \"NCK_TRANSLATION_API_KEY\";\n\nlet configured: Client | undefined;\n\n/**\n * Point the server helpers at a platform explicitly, instead of via env.\n *\n * Optional — call it once at startup if you would rather pass configuration in\n * code (or in a test). Without it, the first server read builds a client from\n * `NCK_TRANSLATION_API_URL` and `NCK_TRANSLATION_API_KEY`.\n */\nexport function configureTranslations(options: {\n  apiUrl: string;\n  apiKey: string;\n  cacheMs?: number;\n}): void {\n  configured = createClient(options);\n}\n\nfunction getClient(): Client {\n  if (configured) return configured;\n\n  const apiUrl = process.env[ENV_API_URL];\n  const apiKey = process.env[ENV_API_KEY];\n  if (!apiUrl || !apiKey) {\n    throw new Error(\n      `@nckdv/translation-nextjs: set ${ENV_API_URL} and ${ENV_API_KEY}, or call ` +\n        `configureTranslations() before rendering.`,\n    );\n  }\n\n  // Kept across requests so the SDK's TTL cache spans them. The SDK also\n  // shares concurrent in-flight reads for the same language.\n  configured = createClient({ apiUrl, apiKey });\n  return configured;\n}\n\n/**\n * One language's catalog. The SDK caches successful catalogs and shares an\n * in-flight request, so concurrent Server Components make one network call.\n */\nexport function getCatalog(language: string): Promise<Catalog> {\n  return getClient().getCatalog(language);\n}\n\n/**\n * A `t()` bound to `language`, for use in Server Components.\n *\n * ```tsx\n * const t = await getTranslator(lang);\n * return <h1>{t(\"home.title\")}</h1>;\n * ```\n */\nexport function getTranslator(language: string): Promise<Translate> {\n  return getClient().getTranslator(language);\n}\n\n/**\n * Drop the cached catalog for a language (or all of them). Call after an edit\n * lands so the next render re-reads from the platform.\n */\nexport function invalidate(language?: string): void {\n  getClient().invalidate(language);\n}\n\nexport type { Catalog, Translate } from \"@nckdv/translation-sdk\";\n"],"mappings":";AAEA,OAAO;AACP;AAAA,EACE;AAAA,OAIK;AAGA,IAAM,cAAc;AACpB,IAAM,cAAc;AAE3B,IAAI;AASG,SAAS,sBAAsB,SAI7B;AACP,eAAa,aAAa,OAAO;AACnC;AAEA,SAAS,YAAoB;AAC3B,MAAI,WAAY,QAAO;AAEvB,QAAM,SAAS,QAAQ,IAAI,WAAW;AACtC,QAAM,SAAS,QAAQ,IAAI,WAAW;AACtC,MAAI,CAAC,UAAU,CAAC,QAAQ;AACtB,UAAM,IAAI;AAAA,MACR,kCAAkC,WAAW,QAAQ,WAAW;AAAA,IAElE;AAAA,EACF;AAIA,eAAa,aAAa,EAAE,QAAQ,OAAO,CAAC;AAC5C,SAAO;AACT;AAMO,SAAS,WAAW,UAAoC;AAC7D,SAAO,UAAU,EAAE,WAAW,QAAQ;AACxC;AAUO,SAAS,cAAc,UAAsC;AAClE,SAAO,UAAU,EAAE,cAAc,QAAQ;AAC3C;AAMO,SAAS,WAAW,UAAyB;AAClD,YAAU,EAAE,WAAW,QAAQ;AACjC;","names":[]}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@nckdv/translation-nextjs",
+  "version": "0.2.0",
+  "description": "Server-side Next.js bindings for nck-translation catalogs.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "require": "./dist/server.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "next": "^14.2.0 || ^15.0.0 || ^16.0.0"
+  },
+  "dependencies": {
+    "@nckdv/translation-react": "^0.2.0",
+    "@nckdv/translation-sdk": "^0.2.0",
+    "server-only": "^0.0.1"
+  },
+  "devDependencies": {
+    "next": "^16.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NiklasErath/nck-translation.git",
+    "directory": "packages/nextjs"
+  },
+  "homepage": "https://github.com/NiklasErath/nck-translation#readme",
+  "keywords": [
+    "i18n",
+    "translation",
+    "nextjs",
+    "internationalization",
+    "localization"
+  ]
+}