@nitrogenbuilder/connector-payload 1.1.1 → 1.2.0

package/dist/endpoints/translation-status.js

@@ -0,0 +1,105 @@
+/**
+ * Translation status route — lists per-language translation coverage for
+ * every Nitrogen-enabled document and template, for the editor's translation
+ * dashboard.
+ *
+ * The status is computed and stored (in `nitrogenTranslationStatus`) by the
+ * save handlers; this route reads the stored value and only computes on the
+ * fly for docs that have never been saved since localization was enabled.
+ */
+import { getNitrogenSettings, requireAuth } from './helpers.js';
+import { findAllDocs } from '../inventory/indexing.js';
+import { computeDocTranslationStatus, getLocalizationSettings, getPayloadLocalization, loadTranslatablePropDefs, } from '../localization.js';
+function isStoredStatus(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Docs fetched at locale 'all' carry localized fields as locale-keyed
+ * objects — read the default language's title in that case.
+ */
+function docTitle(doc, defaultLanguage) {
+    const title = doc.title;
+    if (typeof title === 'string')
+        return title;
+    if (title && typeof title === 'object' && !Array.isArray(title)) {
+        const record = title;
+        const value = record[defaultLanguage];
+        if (typeof value === 'string')
+            return value;
+        // No default-language title — fall back to the first stored one, matching
+        // the renderer's language-resolution fallback chain.
+        for (const candidate of Object.values(record)) {
+            if (typeof candidate === 'string' && candidate)
+                return candidate;
+        }
+    }
+    return '';
+}
+export function createTranslationStatusEndpoints(collections) {
+    return [
+        // GET /api/nitrogen/v1/translation-status — TranslationStatusEntry[] across
+        // configured collections + nitrogen-templates
+        {
+            path: '/nitrogen/v1/translation-status',
+            method: 'get',
+            handler: async (req) => {
+                const authError = requireAuth(req);
+                if (authError)
+                    return authError;
+                const { payload } = req;
+                const settings = await getNitrogenSettings(payload);
+                const localization = getLocalizationSettings(settings);
+                if (!localization) {
+                    return Response.json([]);
+                }
+                // One catalog load shared by every on-the-fly computation.
+                const propDefs = await loadTranslatablePropDefs(payload);
+                // With Payload-native localization, fetch docs at locale 'all' so
+                // field-level coverage can be read without per-doc re-fetches.
+                const locale = getPayloadLocalization(payload) ? 'all' : undefined;
+                const entries = [];
+                const allCollections = Array.from(new Set([...collections, 'nitrogen-templates']));
+                for (const collectionSlug of allCollections) {
+                    let docs;
+                    try {
+                        docs = await findAllDocs(payload, collectionSlug, { locale });
+                    }
+                    catch {
+                        // One bad collection shouldn't 500 the whole listing — skip it.
+                        continue;
+                    }
+                    const type = collectionSlug === 'nitrogen-templates' ? 'template' : 'page';
+                    for (const doc of docs) {
+                        let languages = null;
+                        if (isStoredStatus(doc.nitrogenTranslationStatus)) {
+                            languages = doc.nitrogenTranslationStatus;
+                        }
+                        else {
+                            try {
+                                languages = await computeDocTranslationStatus({
+                                    payload,
+                                    collectionSlug,
+                                    docId: doc.id,
+                                    nitrogenData: doc.nitrogenData,
+                                    localization,
+                                    propDefs,
+                                    localeAllDoc: locale ? doc : null,
+                                });
+                            }
+                            catch {
+                                languages = null;
+                            }
+                        }
+                        entries.push({
+                            id: doc.id,
+                            title: docTitle(doc, localization.defaultLanguage),
+                            type,
+                            languages: languages || {},
+                        });
+                    }
+                }
+                return Response.json(entries);
+            },
+        },
+    ];
+}

package/dist/frontend/NitrogenPageClient.d.ts

@@ -5,6 +5,11 @@ export interface NitrogenPageClientProps {
     dynamicData: Record<string, unknown>;
     isBuilder?: boolean;
     collection?: string;
+    /**
+     * Language to render translatable builder props in (a configured language
+     * code). Forwarded to NitrogenRenderer. Omit for the default language.
+     */
+    language?: string;
 }
 /**
  * Client component that renders Nitrogen pages using React.
@@ -12,5 +17,5 @@ export interface NitrogenPageClientProps {
  * Uses `useNitrogenData` hook for live preview updates in builder mode,
  * and `NitrogenRenderer` for React-based rendering of the component tree.
  */
-export declare function NitrogenPageClient({ pageId, pageData, dynamicData: initialDynamicData, isBuilder, collection, }: NitrogenPageClientProps): import("react/jsx-runtime").JSX.Element;
+export declare function NitrogenPageClient({ pageId, pageData, dynamicData: initialDynamicData, isBuilder, collection, language, }: NitrogenPageClientProps): import("react/jsx-runtime").JSX.Element;
 export default NitrogenPageClient;

package/dist/frontend/NitrogenPageClient.js

@@ -9,7 +9,7 @@ import { Nitrogen } from "@nitrogenbuilder/client-core";
  * Uses `useNitrogenData` hook for live preview updates in builder mode,
  * and `NitrogenRenderer` for React-based rendering of the component tree.
  */
-export function NitrogenPageClient({ pageId, pageData, dynamicData: initialDynamicData, isBuilder = false, collection, }) {
+export function NitrogenPageClient({ pageId, pageData, dynamicData: initialDynamicData, isBuilder = false, collection, language, }) {
     // Use the hook for live preview updates
     const page = useNitrogenData({
         type: "page",
@@ -50,6 +50,10 @@ export function NitrogenPageClient({ pageId, pageData, dynamicData: initialDynam
             }
         };
     }, [isBuilder]);
-    return (_jsx("div", { "data-nitrogen-location": "page", "data-page-id": pageId, "data-collection": collection, children: _jsx(NitrogenRenderer, { page: page?.data ?? [], dynamicData: page?.dynamicData ?? initialDynamicData, requestedData: {} }) }));
+    // The `language` prop is being added to NitrogenRenderer in the client-react
+    // package; spread it loosely so this compiles against both old and new
+    // renderer typings (older renderers simply ignore the extra prop).
+    const languageProp = language ? { language } : {};
+    return (_jsx("div", { "data-nitrogen-location": "page", "data-page-id": pageId, "data-collection": collection, "data-language": language, children: _jsx(NitrogenRenderer, { page: page?.data ?? [], dynamicData: page?.dynamicData ?? initialDynamicData, requestedData: {}, ...languageProp }) }));
 }
 export default NitrogenPageClient;

package/dist/frontend/NitrogenWrapper.d.ts

@@ -25,6 +25,13 @@ export interface NitrogenWrapperProps {
      * Regular page content to render when not in Nitrogen mode.
      */
     children: React.ReactNode;
+    /**
+     * Language to render the page in (a configured locale code, e.g. 'es').
+     * Dynamic data is rebuilt from the doc fetched at that locale, and the
+     * language is forwarded to the renderer so translatable builder props
+     * resolve to it. Omit for the default language.
+     */
+    language?: string;
 }
 /**
  * Server component that wraps your page content and automatically handles
@@ -45,5 +52,5 @@ export interface NitrogenWrapperProps {
  * }
  * ```
  */
-export declare function NitrogenWrapper({ page, searchParams, collection, config, children, }: NitrogenWrapperProps): Promise<import("react/jsx-runtime").JSX.Element>;
+export declare function NitrogenWrapper({ page, searchParams, collection, config, children, language, }: NitrogenWrapperProps): Promise<import("react/jsx-runtime").JSX.Element>;
 export default NitrogenWrapper;

package/dist/frontend/NitrogenWrapper.js

@@ -2,6 +2,7 @@ import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 import { getPayload } from 'payload';
 import { NitrogenPageClient } from './NitrogenPageClient.js';
 import { buildDynamicData, getNitrogenSettings } from '../endpoints/helpers.js';
+import { resolveLocaleOptions } from '../localization.js';
 /**
  * Server component that wraps your page content and automatically handles
  * Nitrogen builder mode and Nitrogen-rendered pages.
@@ -21,7 +22,7 @@ import { buildDynamicData, getNitrogenSettings } from '../endpoints/helpers.js';
  * }
  * ```
  */
-export async function NitrogenWrapper({ page, searchParams, collection, config, children, }) {
+export async function NitrogenWrapper({ page, searchParams, collection, config, children, language, }) {
     const isBuilder = searchParams['nitrogen-builder'] !== undefined;
     const hasNitrogenData = Array.isArray(page.nitrogenData) && page.nitrogenData.length > 0;
     // If not in builder mode and no Nitrogen data, render regular content
@@ -31,7 +32,28 @@ export async function NitrogenWrapper({ page, searchParams, collection, config,
     // Fetch Nitrogen settings and build dynamic data
     const payload = await getPayload({ config });
     const settings = await getNitrogenSettings(payload);
-    const dynamicData = buildDynamicData(page, settings);
-    return (_jsx(NitrogenPageClient, { pageId: String(page.id), pageData: page.nitrogenData || [], dynamicData: dynamicData, isBuilder: isBuilder, collection: collection }));
+    // When a language is requested (and Payload localization is configured),
+    // re-fetch the doc at that locale so dynamic data carries the translated
+    // field values. Falls back to the passed-in page on any failure.
+    let sourceDoc = page;
+    const localeOptions = resolveLocaleOptions(payload, language);
+    if (localeOptions.locale) {
+        try {
+            const localized = await payload.findByID({
+                collection: collection,
+                id: page.id,
+                depth: 1,
+                ...localeOptions,
+            });
+            if (localized) {
+                sourceDoc = localized;
+            }
+        }
+        catch {
+            // Locale fetch is best-effort — keep the caller's doc.
+        }
+    }
+    const dynamicData = buildDynamicData(sourceDoc, settings);
+    return (_jsx(NitrogenPageClient, { pageId: String(page.id), pageData: page.nitrogenData || [], dynamicData: dynamicData, isBuilder: isBuilder, collection: collection, language: language }));
 }
 export default NitrogenWrapper;

package/dist/index.d.ts

@@ -34,6 +34,27 @@ export interface NitrogenConnectorPluginOptions {
      * `users`).
      */
     userCollection?: string;
+    /**
+     * Enables Payload-native localization for field data. When set (and the
+     * Payload config does not already configure `localization` itself), the
+     * plugin injects `localization: { locales, defaultLocale, fallback: true }`
+     * into the Payload config and marks eligible text fields (`title` on
+     * Nitrogen-enabled collections and on the plugin's own template collection)
+     * as `localized: true`. Localize your own custom fields yourself.
+     *
+     * IMPORTANT: the locales here must match the site languages configured in
+     * the Nitrogen settings (`nitrogenConfig.localization.languages`), and
+     * `defaultLocale` must match `defaultLanguage` — Payload stores the field
+     * translations, Nitrogen stores the builder-content translations, and the
+     * language codes are the join key.
+     *
+     * If your Payload config already has `localization` configured, that config
+     * is respected and this option does not override it.
+     */
+    localization?: {
+        locales: string[];
+        defaultLocale: string;
+    };
 }
 export declare const nitrogenConnectorPlugin: (options?: NitrogenConnectorPluginOptions) => any;
 export { NitrogenTemplates } from "./collections/NitrogenTemplates.js";
@@ -41,6 +62,7 @@ export { NitrogenSettings } from "./globals/NitrogenSettings.js";
 export { NitrogenEditButton } from "./components/NitrogenEditButton.js";
 export { NitrogenViewButton } from "./components/NitrogenViewButton.js";
 export { buildDynamicData, getNitrogenSettings } from "./endpoints/helpers.js";
+export { buildDynamicDataMeta, getRequestLanguage, resolveLocaleOptions, } from "./localization.js";
 export { createCollectionEndpoints } from "./endpoints/collection-endpoints.js";
 export { nitrogen } from "@nitrogenbuilder/client-core";
 export type { ComponentSettings, ComponentSettingsToProps, } from "@nitrogenbuilder/types";

package/dist/index.js

@@ -13,6 +13,7 @@ import { createCollectionEndpoints } from "./endpoints/collection-endpoints.js";
 import { createComponentInventoryEndpoints } from './endpoints/component-inventory.js';
 import { batchEndpoints } from "./endpoints/batch.js";
 import { sitemapEndpoints } from "./endpoints/sitemap.js";
+import { createTranslationStatusEndpoints } from "./endpoints/translation-status.js";
 import { createAgentAuthEndpoints } from "./endpoints/agent-auth.js";
 import { registerCollection } from "./collection-registry.js";
 import { deleteDocumentUsage, reindexDocumentUsage, syncComponentCatalog, } from './inventory/indexing.js';
@@ -38,12 +39,57 @@ const nitrogenRequiredFields = [
             },
         },
     },
+    {
+        name: "nitrogenTranslationStatus",
+        type: "json",
+        admin: {
+            hidden: true,
+            description: "Per-language translation coverage, computed by Nitrogen on save",
+        },
+    },
 ];
+/**
+ * Marks `title` text fields as `localized: true` (recursing into rows, tabs,
+ * groups, collapsibles). Fields that already declare `localized` explicitly
+ * are left untouched.
+ */
+function localizeTitleFields(fields) {
+    return fields.map((field) => {
+        const f = field;
+        if (f.type === "text" && f.name === "title" && f.localized === undefined) {
+            return { ...field, localized: true };
+        }
+        if (Array.isArray(f.fields)) {
+            return { ...field, fields: localizeTitleFields(f.fields) };
+        }
+        if (Array.isArray(f.tabs)) {
+            return {
+                ...field,
+                tabs: f.tabs.map((tab) => ({
+                    ...tab,
+                    fields: localizeTitleFields(tab.fields || []),
+                })),
+            };
+        }
+        return field;
+    });
+}
 export const nitrogenConnectorPlugin = (options = {}) => (incomingConfig) => {
     if (options.disabled) {
         return incomingConfig;
     }
     const config = { ...incomingConfig };
+    // Payload-native localization for field data. Only injected when the host
+    // config doesn't configure localization itself — an existing config is
+    // always respected.
+    if (options.localization && !incomingConfig.localization) {
+        config.localization = {
+            locales: options.localization.locales,
+            defaultLocale: options.localization.defaultLocale,
+            fallback: true,
+        };
+    }
+    const localizationActive = Boolean(config.localization);
     // The auth collection that owns MCP agent credentials. Prefer the explicit
     // option, else the first auth-enabled collection, else `users`.
     const userCollectionSlug = options.userCollection ||
@@ -83,10 +129,19 @@ export const nitrogenConnectorPlugin = (options = {}) => (incomingConfig) => {
             },
         };
     };
-    // Add Nitrogen templates collection
+    // Add Nitrogen templates collection. With localization active, template
+    // titles are localized (translated in the Payload admin's locale
+    // switcher); internal catalog/usage collections stay non-localized —
+    // their text fields are machine identifiers, not content.
+    const templatesCollection = localizationActive
+        ? {
+            ...NitrogenTemplates,
+            fields: localizeTitleFields(NitrogenTemplates.fields),
+        }
+        : NitrogenTemplates;
     config.collections = [
         ...(config.collections || []),
-        withInventoryHooks(NitrogenTemplates, 'nitrogen-templates'),
+        withInventoryHooks(templatesCollection, 'nitrogen-templates'),
         NitrogenComponentCatalog,
         NitrogenComponentUsage,
     ];
@@ -103,6 +158,7 @@ export const nitrogenConnectorPlugin = (options = {}) => (incomingConfig) => {
         ...menuEndpoints,
         ...batchEndpoints,
         ...sitemapEndpoints,
+        ...createTranslationStatusEndpoints(options.collections || []),
         ...createAgentAuthEndpoints(userCollectionSlug),
         ...createComponentInventoryEndpoints({
             collections: inventoryCollections,
@@ -191,6 +247,16 @@ export const nitrogenConnectorPlugin = (options = {}) => (incomingConfig) => {
                 fields: [...existing.fields, ...fieldsToAdd],
             };
         }
+        // With localization active, the collection's title becomes localized so
+        // it can be translated via the Payload admin's native locale switcher.
+        // (Users localize their own custom fields themselves.)
+        if (localizationActive) {
+            const current = config.collections[existingIndex];
+            config.collections[existingIndex] = {
+                ...current,
+                fields: localizeTitleFields(current.fields),
+            };
+        }
         // Inject NitrogenEditButton admin component
         const col = config.collections[existingIndex];
         const adminConfig = col.admin || {};
@@ -301,6 +367,7 @@ export { NitrogenEditButton } from "./components/NitrogenEditButton.js";
 export { NitrogenViewButton } from "./components/NitrogenViewButton.js";
 // Helper exports for consumers building custom frontend routes
 export { buildDynamicData, getNitrogenSettings } from "./endpoints/helpers.js";
+export { buildDynamicDataMeta, getRequestLanguage, resolveLocaleOptions, } from "./localization.js";
 // Collection endpoint factory for consumers who need custom endpoint generation
 export { createCollectionEndpoints } from "./endpoints/collection-endpoints.js";
 // Re-export @nitrogenbuilder packages for convenience

package/dist/inventory/indexing.d.ts

@@ -16,6 +16,8 @@ type ReindexResult = {
 export declare function extractComponentUsageRecords(modules: unknown): ComponentUsageRecord[];
 export declare function findAllDocs<T extends object>(payload: Payload, collection: string, options?: {
     limit?: number;
+    /** e.g. 'all' to fetch every locale's value for localized fields */
+    locale?: string;
     select?: Record<string, true>;
     where?: Where;
 }, req?: PayloadRequest): Promise<T[]>;

package/dist/inventory/indexing.js

@@ -62,6 +62,7 @@ export async function findAllDocs(payload, collection, options, req) {
             collection: collection,
             depth: 0,
             limit: options?.limit ?? 200,
+            locale: options?.locale,
             page,
             overrideAccess: true,
             pagination: true,

package/dist/localization.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Localization support — locale threading for read endpoints, dynamic-data
+ * translation metadata, and per-language translation status for builder
+ * content.
+ *
+ * Two independent layers cooperate here:
+ *
+ * 1. **Payload-native localization** (field data). When the host project's
+ *    Payload config has `localization` configured (either directly or injected
+ *    from the plugin's `localization` option), eligible text fields are
+ *    localized and read endpoints thread `?lang=` through to
+ *    `payload.find`/`findByID` as `locale` + `fallbackLocale`.
+ * 2. **Nitrogen settings localization** (builder content). Site languages live
+ *    in the `nitrogen-settings` global under `nitrogenConfig.localization`.
+ *    Translatable prop values inside `nitrogenData` are stored language-keyed
+ *    with the language as the OUTER key (`{ en: ..., es: ... }`); legacy bare
+ *    values read as the default language.
+ *
+ * Everything is gated: with no localization configured anywhere, every helper
+ * returns null/empty and callers behave exactly as before.
+ */
+import type { Field, Payload, PayloadRequest, SanitizedCollectionConfig } from 'payload';
+import type { ComponentManifestProp, DynamicDataMeta, LanguageStatus, LocalizationSettings } from '@nitrogenbuilder/types';
+import type { NitrogenSettingsGlobal } from './types.js';
+export interface PayloadLocaleConfig {
+    locales: string[];
+    defaultLocale: string;
+}
+/**
+ * Reads the sanitized Payload localization config at runtime. Returns null
+ * when the project has no Payload-level localization configured.
+ */
+export declare function getPayloadLocalization(payload: Payload): PayloadLocaleConfig | null;
+/** Reads `?lang=` (alias `?locale=`) off a request URL. */
+export declare function getRequestLanguage(req: PayloadRequest): string | null;
+export interface LocaleQueryOptions {
+    locale?: string;
+    fallbackLocale?: string;
+}
+/**
+ * Turns a requested language into `locale`/`fallbackLocale` options for
+ * `payload.find`/`findByID`. Returns `{}` (default behavior) when no language
+ * was requested, the project has no Payload localization, or the language is
+ * not a configured locale.
+ */
+export declare function resolveLocaleOptions(payload: Payload, lang?: string | null): LocaleQueryOptions;
+export declare function getCollectionConfig(payload: Payload, collectionSlug: string): SanitizedCollectionConfig | undefined;
+/**
+ * Dot-paths of localized text-typed fields of a collection config. Walks
+ * groups, rows, collapsibles, and tabs; named groups/tabs contribute a path
+ * segment.
+ */
+export declare function getLocalizedTextFieldPaths(fields: Field[] | undefined, prefix?: string): string[];
+/**
+ * The site language config from the `nitrogen-settings` global. Null when
+ * localization is absent or disabled — callers must treat null as
+ * "no localization behavior at all".
+ */
+export declare function getLocalizationSettings(settings: NitrogenSettingsGlobal): LocalizationSettings | null;
+/**
+ * Fetches a doc with every locale's value for localized fields (one
+ * `locale: 'all'` query). Returns null when the project has no Payload
+ * localization configured or the doc can't be read — advisory callers keep
+ * their default behavior in that case.
+ */
+export declare function fetchLocaleAllDoc(payload: Payload, collectionSlug: string, docId: string | number): Promise<Record<string, unknown> | null>;
+/**
+ * The default-locale title from a `locale: 'all'` doc, for editor-facing
+ * single-doc responses. The editor edits default-language field data only
+ * (the CMS admin owns field translations), so the `title` it displays and
+ * PATCHes back on save must never be a locale-resolved one. Returns null when
+ * there is nothing to override (no localization, title not localized, or no
+ * stored title) — callers then keep the response title as-is.
+ */
+export declare function getDefaultLocaleTitle(payload: Payload, localeAllDoc: Record<string, unknown> | null): string | null;
+/**
+ * Builds the connector-provided metadata the editor uses to badge
+ * untranslated CMS fields. Eligible keys are the localized text-typed fields
+ * of the collection config; translated keys per language are the fields whose
+ * locale-specific value exists (checked via one `locale: 'all'` fetch, or a
+ * caller-preloaded `localeAllDoc` to avoid a duplicate query).
+ *
+ * Returns null when the project has no Payload localization configured, so
+ * callers can attach `dynamic_data_meta` conditionally with zero change to
+ * the default response shape.
+ */
+export declare function buildDynamicDataMeta(payload: Payload, collectionSlug: string, docId?: string | number, localeAllDoc?: Record<string, unknown> | null): Promise<DynamicDataMeta | null>;
+type CatalogPropDef = ComponentManifestProp & {
+    translatable?: boolean;
+};
+/**
+ * componentName → group key → propKey → prop definition. Module prop values
+ * are stored group-keyed (`props[groupKey][propKey]`, mirroring the renderer's
+ * `spreadProps`), so the group level is preserved for lookups during the walk.
+ */
+export type TranslatablePropDefs = Map<string, Record<string, Record<string, CatalogPropDef>>>;
+/**
+ * Loads component prop definitions from the nitrogen-component-catalog
+ * collection so translatable props can be identified precisely. Returns an
+ * empty map when the catalog is unavailable — the walk then falls back to the
+ * lang-map heuristic.
+ */
+export declare function loadTranslatablePropDefs(payload: Payload): Promise<TranslatablePropDefs>;
+export interface ComputeTranslationStatusArgs {
+    payload: Payload;
+    collectionSlug: string;
+    docId: string | number;
+    nitrogenData: unknown;
+    localization: LocalizationSettings;
+    /** Preloaded catalog defs (avoids a re-fetch when batching). */
+    propDefs?: TranslatablePropDefs;
+    /** Preloaded `locale: 'all'` doc (avoids a re-fetch when batching). */
+    localeAllDoc?: Record<string, unknown> | null;
+}
+/**
+ * Computes per-language translation status for one page/template. Returns a
+ * `{ [langCode]: LanguageStatus }` map covering every configured non-default
+ * language, or null when there is nothing to compute.
+ */
+export declare function computeDocTranslationStatus(args: ComputeTranslationStatusArgs): Promise<Record<string, LanguageStatus> | null>;
+export {};