@pactor-app/i18n 0.0.0-stage → 1.55.0

package/dist/index.d.cts

@@ -0,0 +1,258 @@
+import { MessageBundleSet, PageDsl, I18nKeyRef, I18nInlineMessages } from '@pactor-app/core';
+
+/** i18n 包统一错误码 */
+type I18nErrorCode = 'INVALID_LOCALE_CONFIG' | 'INVALID_LOCALE' | 'UNSUPPORTED_LOCALE' | 'LOCALE_CONFLICT' | 'DUPLICATE_LOCALE_PARAM' | 'MANIFEST_INVALID' | 'MANIFEST_MISMATCH' | 'NAMESPACE_NOT_FOUND' | 'MESSAGE_BUNDLE_INVALID' | 'MESSAGE_PROTOCOL_ERROR' | 'MESSAGE_FETCH_FAILED' | 'INVALID_FIELD_PATH' | 'UNREGISTERED_I18N_FIELD' | 'I18N_DESCRIPTOR_INVALID' | 'BINDING_INVALID' | 'BINDING_CONFLICT' | 'UNSAFE_MESSAGE' | 'PAGE_LOAD_FAILED' | 'PAGE_YAML_INVALID' | 'PAGE_DSL_INVALID';
+/** 携带可识别 code 的 i18n 错误 */
+declare class I18nError extends Error {
+    readonly code: I18nErrorCode;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: I18nErrorCode, message: string, details?: Record<string, unknown> | undefined);
+}
+/** 判断错误是否为 I18nError（可选按 code 过滤） */
+declare function isI18nError(error: unknown, code?: I18nErrorCode): error is I18nError;
+
+/** 语言来源 */
+type LocaleSource = 'url-path' | 'url-query' | 'cookie' | 'accept-language' | 'application-default';
+/** resolveRequestLocale 输入：宿主把请求信息适配为普通对象 */
+interface ResolveLocaleInput {
+    /** 路径中的语言段，如 /en-US/users 提取出的 'en-US' */
+    pathLocale?: string;
+    /** 查询参数 locale；数组表示重复参数 */
+    queryLocale?: string | string[];
+    /** 已解析出的 locale Cookie 值 */
+    cookieLocale?: string;
+    /** Accept-Language 请求头原文 */
+    acceptLanguage?: string;
+}
+/** 应用语言配置 */
+interface LocaleResolverConfig {
+    supportedLocales: string[];
+    defaultLocale: string;
+    /** 无显式语言时的默认策略，缺省 'system' */
+    defaultStrategy?: 'system' | 'application';
+    /** 显式配置的别名映射，如 { en: 'en-US' } */
+    aliases?: Record<string, string>;
+    /** 语言级回退映射，如 { 'fr-CA': ['fr'] }，仅用于 Accept-Language 协商 */
+    fallbackLocales?: Record<string, string[]>;
+}
+/** 解析结果：唯一有效 locale 及来源 */
+interface ResolvedRequestLocale {
+    locale: string;
+    source: LocaleSource;
+    explicit: boolean;
+}
+/** Accept-Language 条目（已按 q 降序、同权重按出现顺序排序） */
+interface AcceptLanguageEntry {
+    tag: string;
+    q: number;
+}
+/**
+ * 规范化语言标识：语言小写、地区大写、文字系统首字母大写，`_` 归一为 `-`。
+ * 非法格式返回 undefined。
+ */
+declare function normalizeLocaleTag(value: string): string | undefined;
+/**
+ * 解析 Accept-Language 请求头。
+ * 忽略 q=0、非法语言项与无效权重；结果按 q 降序、同权重按出现顺序排列。
+ */
+declare function parseAcceptLanguage(header: string | undefined): AcceptLanguageEntry[];
+/**
+ * 解析请求有效语言。优先级：URL path/query > locale Cookie >
+ * Accept-Language（仅 system 策略）> 应用 defaultLocale。
+ *
+ * 显式值非法 / 不支持 / 冲突时抛 I18nError（INVALID_LOCALE /
+ * UNSUPPORTED_LOCALE / LOCALE_CONFLICT / DUPLICATE_LOCALE_PARAM），
+ * 不静默回退；Cookie 失效则忽略并继续解析链。
+ */
+declare function resolveRequestLocale(input: ResolveLocaleInput, config: LocaleResolverConfig): ResolvedRequestLocale;
+
+/** MessageProvider.load 输入（设计 6.0.3 统一契约） */
+interface LoadMessagesInput {
+    appId: string;
+    /** 来自服务端可信上下文，不接受浏览器任意指定 */
+    tenantId?: string;
+    locale: string;
+    namespaces: string[];
+    release: string;
+}
+/**
+ * 渲染服务统一语言包 Provider 契约。
+ * YamlMessageProvider 与 ApiMessageProvider 输出完全相同的 MessageBundleSet，
+ * 消费方（如 DslLocalizer）只依赖此接口。
+ */
+interface MessageProvider {
+    load(input: LoadMessagesInput): Promise<MessageBundleSet>;
+}
+
+/** 浏览器/Node 中立的 fetch 响应形态 */
+interface FetchLikeResponse {
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}
+/** 注入的 fetch 风格函数 */
+type FetchLike = (url: string, init?: {
+    headers?: Record<string, string>;
+}) => Promise<FetchLikeResponse>;
+interface ApiMessageProviderOptions {
+    /** 语言包 API 地址，来自服务端应用配置，不接受浏览器任意指定 */
+    endpoint: string;
+    fetch: FetchLike;
+    /** 服务端凭据等附加请求头（如 Authorization） */
+    headers?: Record<string, string>;
+}
+/** load 扩展输入：可显式传入缓存的 ETag */
+interface ApiLoadInput extends LoadMessagesInput {
+    etag?: string;
+}
+/** 携带缓存信息的加载结果 */
+interface ApiLoadResult {
+    bundleSet: MessageBundleSet;
+    etag?: string;
+    /** 304 复用已校验缓存包时为 true */
+    notModified: boolean;
+}
+/**
+ * 语言包 API Provider（设计 6.0.3 / 6.1）。
+ *
+ * 校验 HTTP 状态与 Content-Type（必须 application/json）、解析 JSON、
+ * 校验 envelope 协议字段与 format；返回 YAML 或内嵌 YAML 字符串按
+ * MESSAGE_PROTOCOL_ERROR 处理，不切换解析方式。
+ *
+ * ETag / If-None-Match：provider 内部按缓存键（appId/tenant/locale/
+ * namespaces/release）记录最近校验通过的包及其 ETag；304 时复用该缓存，
+ * 结果携带 notModified 标记。也可通过 load 输入的 etag 显式指定。
+ */
+declare class ApiMessageProvider implements MessageProvider {
+    private readonly options;
+    private readonly cache;
+    constructor(options: ApiMessageProviderOptions);
+    /** MessageProvider 契约实现 */
+    load(input: ApiLoadInput): Promise<MessageBundleSet>;
+    /** 加载并返回缓存信息（ETag / notModified） */
+    loadWithCacheInfo(input: ApiLoadInput): Promise<ApiLoadResult>;
+}
+
+declare function isValidMessageKey(key: string): boolean;
+/**
+ * 校验扁平词条表：顶层必须为普通对象，键名合法，值全部为字符串。
+ * 不合法时抛出指定 code 的 I18nError。
+ */
+declare function assertMessages(value: unknown, context: string, code: I18nErrorCode): Record<string, string>;
+/** namespace 间完整 key 冲突检查（结果与 namespace 遍历顺序无关） */
+declare function assertNoCrossNamespaceKeyConflicts(bundles: Record<string, Record<string, string>>, code: I18nErrorCode): void;
+interface EnvelopeExpectation {
+    appId: string;
+    locale: string;
+    release: string;
+    namespaces: readonly string[];
+}
+/**
+ * 校验语言包 API 的 JSON envelope（设计 6.1）。
+ * 结构/协议字段问题抛 MESSAGE_PROTOCOL_ERROR；缺失请求的 namespace 抛 NAMESPACE_NOT_FOUND。
+ */
+declare function validateBundleSetEnvelope(data: unknown, expected: EnvelopeExpectation): MessageBundleSet;
+
+declare class TranslatableFieldRegistry {
+    private readonly componentFields;
+    private readonly actionFields;
+    /** 注册组件 type 的可翻译字段路径（可重复调用，累积合并） */
+    register(componentType: string, fields: string | readonly string[]): this;
+    /** 注册动作名的可翻译参数字段路径（如 message 动作的 `params.text`） */
+    registerAction(actionName: string, fields: string | readonly string[]): this;
+    /**
+     * 判断组件字段是否已注册。`canonicalPath` 为规范化路径
+     * （数组下标段写作 `[*]`，如 `props.columns[*].title`）。
+     */
+    isTranslatable(componentType: string | undefined, canonicalPath: string): boolean;
+    /** 判断动作参数字段是否已注册 */
+    isTranslatableActionField(actionName: string, canonicalPath: string): boolean;
+    /** 已注册组件 type 列表（诊断/调试用） */
+    registeredComponents(): string[];
+    /** 已注册动作名列表（诊断/调试用） */
+    registeredActions(): string[];
+}
+/**
+ * 内置注册表（设计 4.4 常用展示字段）：
+ * Button/Text/Input/Table 列/Select 选项，以及 message / confirm 动作参数。
+ */
+declare function createDefaultTranslatableFieldRegistry(): TranslatableFieldRegistry;
+/**
+ * 共享默认注册表（惰性创建）。请勿原地修改返回的实例；
+ * 需要自定义时通过 `createDefaultTranslatableFieldRegistry()` 或
+ * `new TranslatableFieldRegistry()` 创建独立副本。
+ */
+declare function getDefaultTranslatableFieldRegistry(): TranslatableFieldRegistry;
+
+/** 转义单个 JSON Pointer 段（`~` → `~0`、`/` → `~1`） */
+declare function escapeJsonPointerSegment(segment: string): string;
+/**
+ * 解析 JSON Pointer（RFC 6901）为段数组。
+ * 空串返回 `[]`（指整个文档）；`~0`/`~1` 之外的转义、非 `/` 开头均抛 BINDING_INVALID。
+ */
+declare function parseJsonPointer(pointer: string): string[];
+/** bindings 定位结果：父容器、末段键与当前值 */
+interface ResolvedJsonPointer {
+    parent: Record<string, unknown> | unknown[];
+    key: string | number;
+    value: unknown;
+}
+/**
+ * 按段数组定位目标字段。空指针（指整个文档）、中间段或末段不存在、
+ * 数组下标非法均抛 BINDING_INVALID。
+ */
+declare function resolveJsonPointer(root: unknown, segments: readonly string[], pointer: string): ResolvedJsonPointer;
+
+/**
+ * DslLocalizer（设计第 4、6、7、8 节，缺口 G03/G04/G17）。
+ *
+ * 纯转换入口：语言包作为参数显式传入，不在遍历组件时自行请求。
+ * 统一处理三种声明方式（`$i18n.messages`、`$i18n.key`、页面 `i18n.bindings`），
+ * 返回已本地化的新对象（不修改输入）；编译后移除作者态 `i18n` 字段。
+ */
+/** 翻译描述（bindings 值与 `$i18n` 内层共用形态） */
+type TranslationDescriptor = I18nKeyRef | I18nInlineMessages;
+/** 页面作者态 i18n 字段（设计 4.2） */
+interface AuthorPageI18n {
+    namespaces?: string[];
+    bindings?: Record<string, TranslationDescriptor>;
+}
+/** 作者态 Page DSL（PageDsl + 顶层 i18n 字段） */
+type AuthorPageDsl = PageDsl & {
+    i18n?: AuthorPageI18n;
+};
+/** 显式传入的语言包链：current 为当前 locale，fallbacks 有序（显式语言级回退 → defaultLocale） */
+interface LanguageBundles {
+    current: MessageBundleSet;
+    fallbacks?: MessageBundleSet[];
+}
+/** 词条未在当前 locale 命中时的实际命中方式 */
+type MissingResolution = 'fallback-locale' | 'default-locale' | 'fallback' | 'implicit-fallback' | 'key' | 'missing-text';
+interface LocalizeDiagnostic {
+    type: 'missing-translation' | 'missing-param';
+    /** 展示用文档路径（JSON Pointer 形态，数组为真实下标） */
+    path: string;
+    locale: string;
+    key?: string;
+    param?: string;
+    resolution?: MissingResolution | 'placeholder';
+}
+interface LocalizePageDslInput {
+    page: AuthorPageDsl;
+    locale: string;
+    defaultLocale: string;
+    languageBundles: LanguageBundles;
+    registry?: TranslatableFieldRegistry;
+    onDiagnostic?: (diagnostic: LocalizeDiagnostic) => void;
+}
+/** 内联描述无 key 且所有回退失败时的统一缺失文案 */
+declare const MISSING_TRANSLATION_TEXT = "[missing translation]";
+/**
+ * 纯转换入口（设计第 6 节签名）。返回已本地化的新 Page DSL 对象，
+ * 不修改输入（page / languageBundles 均不被改写）；作者态 `i18n` 字段被移除。
+ */
+declare function localizePageDsl(input: LocalizePageDslInput): PageDsl;
+
+export { type AcceptLanguageEntry, type ApiLoadInput, type ApiLoadResult, ApiMessageProvider, type ApiMessageProviderOptions, type AuthorPageDsl, type AuthorPageI18n, type EnvelopeExpectation, type FetchLike, type FetchLikeResponse, I18nError, type I18nErrorCode, type LanguageBundles, type LoadMessagesInput, type LocaleResolverConfig, type LocaleSource, type LocalizeDiagnostic, type LocalizePageDslInput, MISSING_TRANSLATION_TEXT, type MessageProvider, type MissingResolution, type ResolveLocaleInput, type ResolvedJsonPointer, type ResolvedRequestLocale, TranslatableFieldRegistry, type TranslationDescriptor, assertMessages, assertNoCrossNamespaceKeyConflicts, createDefaultTranslatableFieldRegistry, escapeJsonPointerSegment, getDefaultTranslatableFieldRegistry, isI18nError, isValidMessageKey, localizePageDsl, normalizeLocaleTag, parseAcceptLanguage, parseJsonPointer, resolveJsonPointer, resolveRequestLocale, validateBundleSetEnvelope };

package/dist/index.d.ts

@@ -0,0 +1,258 @@
+import { MessageBundleSet, PageDsl, I18nKeyRef, I18nInlineMessages } from '@pactor-app/core';
+
+/** i18n 包统一错误码 */
+type I18nErrorCode = 'INVALID_LOCALE_CONFIG' | 'INVALID_LOCALE' | 'UNSUPPORTED_LOCALE' | 'LOCALE_CONFLICT' | 'DUPLICATE_LOCALE_PARAM' | 'MANIFEST_INVALID' | 'MANIFEST_MISMATCH' | 'NAMESPACE_NOT_FOUND' | 'MESSAGE_BUNDLE_INVALID' | 'MESSAGE_PROTOCOL_ERROR' | 'MESSAGE_FETCH_FAILED' | 'INVALID_FIELD_PATH' | 'UNREGISTERED_I18N_FIELD' | 'I18N_DESCRIPTOR_INVALID' | 'BINDING_INVALID' | 'BINDING_CONFLICT' | 'UNSAFE_MESSAGE' | 'PAGE_LOAD_FAILED' | 'PAGE_YAML_INVALID' | 'PAGE_DSL_INVALID';
+/** 携带可识别 code 的 i18n 错误 */
+declare class I18nError extends Error {
+    readonly code: I18nErrorCode;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: I18nErrorCode, message: string, details?: Record<string, unknown> | undefined);
+}
+/** 判断错误是否为 I18nError（可选按 code 过滤） */
+declare function isI18nError(error: unknown, code?: I18nErrorCode): error is I18nError;
+
+/** 语言来源 */
+type LocaleSource = 'url-path' | 'url-query' | 'cookie' | 'accept-language' | 'application-default';
+/** resolveRequestLocale 输入：宿主把请求信息适配为普通对象 */
+interface ResolveLocaleInput {
+    /** 路径中的语言段，如 /en-US/users 提取出的 'en-US' */
+    pathLocale?: string;
+    /** 查询参数 locale；数组表示重复参数 */
+    queryLocale?: string | string[];
+    /** 已解析出的 locale Cookie 值 */
+    cookieLocale?: string;
+    /** Accept-Language 请求头原文 */
+    acceptLanguage?: string;
+}
+/** 应用语言配置 */
+interface LocaleResolverConfig {
+    supportedLocales: string[];
+    defaultLocale: string;
+    /** 无显式语言时的默认策略，缺省 'system' */
+    defaultStrategy?: 'system' | 'application';
+    /** 显式配置的别名映射，如 { en: 'en-US' } */
+    aliases?: Record<string, string>;
+    /** 语言级回退映射，如 { 'fr-CA': ['fr'] }，仅用于 Accept-Language 协商 */
+    fallbackLocales?: Record<string, string[]>;
+}
+/** 解析结果：唯一有效 locale 及来源 */
+interface ResolvedRequestLocale {
+    locale: string;
+    source: LocaleSource;
+    explicit: boolean;
+}
+/** Accept-Language 条目（已按 q 降序、同权重按出现顺序排序） */
+interface AcceptLanguageEntry {
+    tag: string;
+    q: number;
+}
+/**
+ * 规范化语言标识：语言小写、地区大写、文字系统首字母大写，`_` 归一为 `-`。
+ * 非法格式返回 undefined。
+ */
+declare function normalizeLocaleTag(value: string): string | undefined;
+/**
+ * 解析 Accept-Language 请求头。
+ * 忽略 q=0、非法语言项与无效权重；结果按 q 降序、同权重按出现顺序排列。
+ */
+declare function parseAcceptLanguage(header: string | undefined): AcceptLanguageEntry[];
+/**
+ * 解析请求有效语言。优先级：URL path/query > locale Cookie >
+ * Accept-Language（仅 system 策略）> 应用 defaultLocale。
+ *
+ * 显式值非法 / 不支持 / 冲突时抛 I18nError（INVALID_LOCALE /
+ * UNSUPPORTED_LOCALE / LOCALE_CONFLICT / DUPLICATE_LOCALE_PARAM），
+ * 不静默回退；Cookie 失效则忽略并继续解析链。
+ */
+declare function resolveRequestLocale(input: ResolveLocaleInput, config: LocaleResolverConfig): ResolvedRequestLocale;
+
+/** MessageProvider.load 输入（设计 6.0.3 统一契约） */
+interface LoadMessagesInput {
+    appId: string;
+    /** 来自服务端可信上下文，不接受浏览器任意指定 */
+    tenantId?: string;
+    locale: string;
+    namespaces: string[];
+    release: string;
+}
+/**
+ * 渲染服务统一语言包 Provider 契约。
+ * YamlMessageProvider 与 ApiMessageProvider 输出完全相同的 MessageBundleSet，
+ * 消费方（如 DslLocalizer）只依赖此接口。
+ */
+interface MessageProvider {
+    load(input: LoadMessagesInput): Promise<MessageBundleSet>;
+}
+
+/** 浏览器/Node 中立的 fetch 响应形态 */
+interface FetchLikeResponse {
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}
+/** 注入的 fetch 风格函数 */
+type FetchLike = (url: string, init?: {
+    headers?: Record<string, string>;
+}) => Promise<FetchLikeResponse>;
+interface ApiMessageProviderOptions {
+    /** 语言包 API 地址，来自服务端应用配置，不接受浏览器任意指定 */
+    endpoint: string;
+    fetch: FetchLike;
+    /** 服务端凭据等附加请求头（如 Authorization） */
+    headers?: Record<string, string>;
+}
+/** load 扩展输入：可显式传入缓存的 ETag */
+interface ApiLoadInput extends LoadMessagesInput {
+    etag?: string;
+}
+/** 携带缓存信息的加载结果 */
+interface ApiLoadResult {
+    bundleSet: MessageBundleSet;
+    etag?: string;
+    /** 304 复用已校验缓存包时为 true */
+    notModified: boolean;
+}
+/**
+ * 语言包 API Provider（设计 6.0.3 / 6.1）。
+ *
+ * 校验 HTTP 状态与 Content-Type（必须 application/json）、解析 JSON、
+ * 校验 envelope 协议字段与 format；返回 YAML 或内嵌 YAML 字符串按
+ * MESSAGE_PROTOCOL_ERROR 处理，不切换解析方式。
+ *
+ * ETag / If-None-Match：provider 内部按缓存键（appId/tenant/locale/
+ * namespaces/release）记录最近校验通过的包及其 ETag；304 时复用该缓存，
+ * 结果携带 notModified 标记。也可通过 load 输入的 etag 显式指定。
+ */
+declare class ApiMessageProvider implements MessageProvider {
+    private readonly options;
+    private readonly cache;
+    constructor(options: ApiMessageProviderOptions);
+    /** MessageProvider 契约实现 */
+    load(input: ApiLoadInput): Promise<MessageBundleSet>;
+    /** 加载并返回缓存信息（ETag / notModified） */
+    loadWithCacheInfo(input: ApiLoadInput): Promise<ApiLoadResult>;
+}
+
+declare function isValidMessageKey(key: string): boolean;
+/**
+ * 校验扁平词条表：顶层必须为普通对象，键名合法，值全部为字符串。
+ * 不合法时抛出指定 code 的 I18nError。
+ */
+declare function assertMessages(value: unknown, context: string, code: I18nErrorCode): Record<string, string>;
+/** namespace 间完整 key 冲突检查（结果与 namespace 遍历顺序无关） */
+declare function assertNoCrossNamespaceKeyConflicts(bundles: Record<string, Record<string, string>>, code: I18nErrorCode): void;
+interface EnvelopeExpectation {
+    appId: string;
+    locale: string;
+    release: string;
+    namespaces: readonly string[];
+}
+/**
+ * 校验语言包 API 的 JSON envelope（设计 6.1）。
+ * 结构/协议字段问题抛 MESSAGE_PROTOCOL_ERROR；缺失请求的 namespace 抛 NAMESPACE_NOT_FOUND。
+ */
+declare function validateBundleSetEnvelope(data: unknown, expected: EnvelopeExpectation): MessageBundleSet;
+
+declare class TranslatableFieldRegistry {
+    private readonly componentFields;
+    private readonly actionFields;
+    /** 注册组件 type 的可翻译字段路径（可重复调用，累积合并） */
+    register(componentType: string, fields: string | readonly string[]): this;
+    /** 注册动作名的可翻译参数字段路径（如 message 动作的 `params.text`） */
+    registerAction(actionName: string, fields: string | readonly string[]): this;
+    /**
+     * 判断组件字段是否已注册。`canonicalPath` 为规范化路径
+     * （数组下标段写作 `[*]`，如 `props.columns[*].title`）。
+     */
+    isTranslatable(componentType: string | undefined, canonicalPath: string): boolean;
+    /** 判断动作参数字段是否已注册 */
+    isTranslatableActionField(actionName: string, canonicalPath: string): boolean;
+    /** 已注册组件 type 列表（诊断/调试用） */
+    registeredComponents(): string[];
+    /** 已注册动作名列表（诊断/调试用） */
+    registeredActions(): string[];
+}
+/**
+ * 内置注册表（设计 4.4 常用展示字段）：
+ * Button/Text/Input/Table 列/Select 选项，以及 message / confirm 动作参数。
+ */
+declare function createDefaultTranslatableFieldRegistry(): TranslatableFieldRegistry;
+/**
+ * 共享默认注册表（惰性创建）。请勿原地修改返回的实例；
+ * 需要自定义时通过 `createDefaultTranslatableFieldRegistry()` 或
+ * `new TranslatableFieldRegistry()` 创建独立副本。
+ */
+declare function getDefaultTranslatableFieldRegistry(): TranslatableFieldRegistry;
+
+/** 转义单个 JSON Pointer 段（`~` → `~0`、`/` → `~1`） */
+declare function escapeJsonPointerSegment(segment: string): string;
+/**
+ * 解析 JSON Pointer（RFC 6901）为段数组。
+ * 空串返回 `[]`（指整个文档）；`~0`/`~1` 之外的转义、非 `/` 开头均抛 BINDING_INVALID。
+ */
+declare function parseJsonPointer(pointer: string): string[];
+/** bindings 定位结果：父容器、末段键与当前值 */
+interface ResolvedJsonPointer {
+    parent: Record<string, unknown> | unknown[];
+    key: string | number;
+    value: unknown;
+}
+/**
+ * 按段数组定位目标字段。空指针（指整个文档）、中间段或末段不存在、
+ * 数组下标非法均抛 BINDING_INVALID。
+ */
+declare function resolveJsonPointer(root: unknown, segments: readonly string[], pointer: string): ResolvedJsonPointer;
+
+/**
+ * DslLocalizer（设计第 4、6、7、8 节，缺口 G03/G04/G17）。
+ *
+ * 纯转换入口：语言包作为参数显式传入，不在遍历组件时自行请求。
+ * 统一处理三种声明方式（`$i18n.messages`、`$i18n.key`、页面 `i18n.bindings`），
+ * 返回已本地化的新对象（不修改输入）；编译后移除作者态 `i18n` 字段。
+ */
+/** 翻译描述（bindings 值与 `$i18n` 内层共用形态） */
+type TranslationDescriptor = I18nKeyRef | I18nInlineMessages;
+/** 页面作者态 i18n 字段（设计 4.2） */
+interface AuthorPageI18n {
+    namespaces?: string[];
+    bindings?: Record<string, TranslationDescriptor>;
+}
+/** 作者态 Page DSL（PageDsl + 顶层 i18n 字段） */
+type AuthorPageDsl = PageDsl & {
+    i18n?: AuthorPageI18n;
+};
+/** 显式传入的语言包链：current 为当前 locale，fallbacks 有序（显式语言级回退 → defaultLocale） */
+interface LanguageBundles {
+    current: MessageBundleSet;
+    fallbacks?: MessageBundleSet[];
+}
+/** 词条未在当前 locale 命中时的实际命中方式 */
+type MissingResolution = 'fallback-locale' | 'default-locale' | 'fallback' | 'implicit-fallback' | 'key' | 'missing-text';
+interface LocalizeDiagnostic {
+    type: 'missing-translation' | 'missing-param';
+    /** 展示用文档路径（JSON Pointer 形态，数组为真实下标） */
+    path: string;
+    locale: string;
+    key?: string;
+    param?: string;
+    resolution?: MissingResolution | 'placeholder';
+}
+interface LocalizePageDslInput {
+    page: AuthorPageDsl;
+    locale: string;
+    defaultLocale: string;
+    languageBundles: LanguageBundles;
+    registry?: TranslatableFieldRegistry;
+    onDiagnostic?: (diagnostic: LocalizeDiagnostic) => void;
+}
+/** 内联描述无 key 且所有回退失败时的统一缺失文案 */
+declare const MISSING_TRANSLATION_TEXT = "[missing translation]";
+/**
+ * 纯转换入口（设计第 6 节签名）。返回已本地化的新 Page DSL 对象，
+ * 不修改输入（page / languageBundles 均不被改写）；作者态 `i18n` 字段被移除。
+ */
+declare function localizePageDsl(input: LocalizePageDslInput): PageDsl;
+
+export { type AcceptLanguageEntry, type ApiLoadInput, type ApiLoadResult, ApiMessageProvider, type ApiMessageProviderOptions, type AuthorPageDsl, type AuthorPageI18n, type EnvelopeExpectation, type FetchLike, type FetchLikeResponse, I18nError, type I18nErrorCode, type LanguageBundles, type LoadMessagesInput, type LocaleResolverConfig, type LocaleSource, type LocalizeDiagnostic, type LocalizePageDslInput, MISSING_TRANSLATION_TEXT, type MessageProvider, type MissingResolution, type ResolveLocaleInput, type ResolvedJsonPointer, type ResolvedRequestLocale, TranslatableFieldRegistry, type TranslationDescriptor, assertMessages, assertNoCrossNamespaceKeyConflicts, createDefaultTranslatableFieldRegistry, escapeJsonPointerSegment, getDefaultTranslatableFieldRegistry, isI18nError, isValidMessageKey, localizePageDsl, normalizeLocaleTag, parseAcceptLanguage, parseJsonPointer, resolveJsonPointer, resolveRequestLocale, validateBundleSetEnvelope };

package/dist/index.js

@@ -0,0 +1,40 @@
+import {
+  ApiMessageProvider,
+  I18nError,
+  MISSING_TRANSLATION_TEXT,
+  TranslatableFieldRegistry,
+  assertMessages,
+  assertNoCrossNamespaceKeyConflicts,
+  createDefaultTranslatableFieldRegistry,
+  escapeJsonPointerSegment,
+  getDefaultTranslatableFieldRegistry,
+  isI18nError,
+  isValidMessageKey,
+  localizePageDsl,
+  normalizeLocaleTag,
+  parseAcceptLanguage,
+  parseJsonPointer,
+  resolveJsonPointer,
+  resolveRequestLocale,
+  validateBundleSetEnvelope
+} from "./chunk-3YCHXWF6.js";
+export {
+  ApiMessageProvider,
+  I18nError,
+  MISSING_TRANSLATION_TEXT,
+  TranslatableFieldRegistry,
+  assertMessages,
+  assertNoCrossNamespaceKeyConflicts,
+  createDefaultTranslatableFieldRegistry,
+  escapeJsonPointerSegment,
+  getDefaultTranslatableFieldRegistry,
+  isI18nError,
+  isValidMessageKey,
+  localizePageDsl,
+  normalizeLocaleTag,
+  parseAcceptLanguage,
+  parseJsonPointer,
+  resolveJsonPointer,
+  resolveRequestLocale,
+  validateBundleSetEnvelope
+};