/**
 * 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 {};