/**
 * @copyright Sister Software
 * @license AGPL-3.0
 * @author Teffen Ellis, et al.
 *
 *   Render real address tuples into locale-specific surface strings.
 *
 *   Public address registers supply inputs such as OA, HM Land Registry and CNIG.
 *   LINZ-derived extracts also supply inputs. The module applies OpenCage templates to
 *   choose ordering and punctuation by country.
 *
 *   Keep the emitted source ids stable: they are persisted in built corpora and referenced by
 *   training configs. `recipes/sources.ts` records each one under its operation spelling
 *   (`rendered-de`) and the `synth-*` spelling it retired on 2026-09-26.
 */
import type { CanonicalRow } from "#types";
/**
 * Real address tuple (for example one OpenAddresses row).
 *
 * Street and locality are required.
 * Other tuple fields are optional.
 */
export interface LocaleBaseTuple {
    house_number?: string;
    street: string;
    locality: string;
    /**
     * Sub-locality below locality (for example suburb/district).
     * When present, it is rendered between street and locality.
     */
    dependent_locality?: string;
    region?: string;
    postcode?: string;
}
/**
 * @deprecated Alias — use LocaleBaseTuple.
 */
export type GermanBaseTuple = LocaleBaseTuple;
export interface RenderedLocaleRow {
    raw: string;
    components: CanonicalRow["components"];
    locale: string;
}
/**
 * @deprecated Alias — use RenderedLocaleRow.
 */
export type RenderedGermanRow = RenderedLocaleRow;
export interface LocaleRenderOpts {
    random?: () => number;
    /**
     * The order used to render the same components.
     *
     * `"native"` (default) uses the country's own template (DE → house-after-street, postcode-before-city).
     * `"international"` renders house-first and postcode-after-city.
     */
    order?: "native" | "international";
    /**
     * Postcode surface shape.
     *
     * `"conventional"` (default) canonicalizes to the country's rendered form
     * (NL: OA's glued `1011AB` → the spaced `1011 AB`).
     * `"as-source"` keeps the source's own surface.
     *
     * Today, only NL differs between these modes.
     */
    postcodeShape?: "conventional" | "as-source";
    /**
     * How the native-order render joins street and house number.
     *
     * The OpenCage ES template comma-joins (`Calle Mayor, 12`, the official Spanish convention).
     * OA-derived feeds and our ES eval space-join (`calle mayor 12`, the observed form on all 3,000 eval rows).
     *
     * `"template"` (default) keeps the template's own join.
     * `"space"` collapses `<street>, <house_number>` → `<street> <house_number>` after rendering.
     * International order ignores this.
     */
    nativeHouseJoin?: "template" | "space";
    /**
     * The string between rendered address lines.
     *
     * `", "` (default) is the template's own join.
     * `" "` renders the comma-free single-line register for dictation or a copy out of a
     * one-field form, as in `Neusser Str. 12 Nippes 50733 Köln` for the same components.
     *
     * Only native order uses this option.
     */
    separator?: ", " | " ";
}
/**
 * @deprecated Alias — use LocaleRenderOpts.
 */
export type GermanRenderOpts = LocaleRenderOpts;
/**
 * Render one tuple into a locale-ordered `{raw, components}` row via OpenCage templates,
 * with light variation (house number and postcode may be dropped).
 *
 * Returns `null` when the tuple is too thin or a component would not align cleanly.
 *
 * Region handling depends on order:
 * - native omits region for alignment reliability
 * - international includes region in the tail
 *
 * Pass `opts.order: "international"` to render the same components house-first and postcode-after-city
 * instead (see {@link LocaleRenderOpts.order}), matching common feed-style layouts.
 */
export declare function renderLocaleRow(base: LocaleBaseTuple, country: string, opts?: LocaleRenderOpts): RenderedLocaleRow | null;
/**
 * German wrapper over {@link renderLocaleRow}.
 *
 * Kept for the `german` recipe (`de/recipes/locale.ts`) and tests.
 */
export declare function renderGermanRow(base: LocaleBaseTuple, opts?: LocaleRenderOpts): RenderedLocaleRow | null;
//# sourceMappingURL=locale.d.ts.map