isr-engine 4.3.0 → 4.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -38,6 +38,7 @@ import type { IntlPayload, PageSeoMeta } from './seo-runtime';
38
38
  import type {
39
39
  DynamicSeoResolver,
40
40
  ISRConfig,
41
+ LanguageCatalogEntry,
41
42
  RuntimeI18nConfig,
42
43
  RuntimeSeoConfig,
43
44
  } from '../../types';
@@ -88,6 +89,8 @@ export type RuntimeServiceBase = string | ((ctx: SiteRuntimeContext) => string |
88
89
  export type IntlMessagesByLocale = Record<string, Record<string, unknown>>;
89
90
 
90
91
  export interface CreateAdminIntlLoaderOptions {
92
+ /** Supported routes, independent of which dictionaries are present in the local fallback. */
93
+ locales?: readonly string[];
91
94
  /** 远端字典端点;相对路径会用 runtime.services.api 拼接 */
92
95
  endpoint?: string;
93
96
  /** 本地兜底字典,通常来自 ssr.config.ts runtime.i18n.fallbackLocal */
@@ -296,7 +299,7 @@ export function createAdminIntlLoader(
296
299
  const endpoint = options.endpoint ?? '/api/i18n/{locale}/manifest';
297
300
  const fallbackMessages = options.fallbackMessages ?? {};
298
301
  const defaultLocale = options.defaultLocale;
299
- const supportedLocales = Object.keys(fallbackMessages);
302
+ const supportedLocales = options.locales ?? Object.keys(fallbackMessages);
300
303
 
301
304
  return async (locale, ctx) => {
302
305
  const normalizedLocale =
@@ -304,10 +307,13 @@ export function createAdminIntlLoader(
304
307
  ? (matchConfiguredLocale(locale, supportedLocales) ?? defaultLocale)
305
308
  : locale;
306
309
  const remoteUrl = resolveAdminUrl(endpoint, { locale: normalizedLocale }, ctx);
307
- const remote = remoteUrl
308
- ? await fetchMetadataJson(remoteUrl, options.timeoutMs, ctx[MARK_METADATA_DEGRADED])
310
+ const markDegraded = ctx[MARK_METADATA_DEGRADED];
311
+ const remoteMessages = remoteUrl
312
+ ? extractIntlMessagesOrNull(
313
+ await fetchMetadataJson(remoteUrl, options.timeoutMs, markDegraded),
314
+ options.endpoint ? markDegraded : undefined
315
+ )
309
316
  : null;
310
- const remoteMessages = extractIntlMessagesOrNull(remote);
311
317
  const localMessages =
312
318
  fallbackMessages[normalizedLocale] ??
313
319
  (defaultLocale ? fallbackMessages[defaultLocale] : undefined) ??
@@ -431,6 +437,7 @@ function createAdminSiteHooks(
431
437
  prefixDefault: i18n.prefixDefault ?? runtimeI18n.prefixDefault,
432
438
  detect: i18n.detect,
433
439
  load: createAdminIntlLoader({
440
+ locales,
434
441
  endpoint: i18n.endpoint ?? runtimeI18n.endpoint,
435
442
  fallbackMessages,
436
443
  defaultLocale,
@@ -469,6 +476,7 @@ export interface ServerHooksOutput {
469
476
  engineCtx: { traceId: string; startedAt: number }
470
477
  ) => Promise<Record<string, unknown>>;
471
478
  loadIntl: (req: Request) => Promise<IntlPayload | null>;
479
+ loadLanguageCatalog?: () => Promise<readonly LanguageCatalogEntry[]>;
472
480
  loadSeoMeta: (req: Request) => Promise<PageSeoMeta | null>;
473
481
  onError: (
474
482
  err: unknown,
@@ -487,7 +495,7 @@ export function defineSiteHooks(config: SiteHooksConfig): ServerHooksOutput {
487
495
  export function applyRuntimeToServerHooks<T extends object>(
488
496
  hooks: T,
489
497
  runtime: SiteRuntimeConfig
490
- ): T {
498
+ ): T & Pick<ServerHooksOutput, 'loadLanguageCatalog'> {
491
499
  const maybeRuntimeAware = hooks as T & {
492
500
  __configureRuntime?: (runtime: SiteRuntimeConfig) => T;
493
501
  };
@@ -499,6 +507,7 @@ export function applyRuntimeToServerHooks<T extends object>(
499
507
  apiBaseUrl?: string;
500
508
  intl?: unknown;
501
509
  loadIntl?: unknown;
510
+ loadLanguageCatalog?: ServerHooksOutput['loadLanguageCatalog'];
502
511
  loadSeoMeta?: unknown;
503
512
  beforeRequest?: SiteHooksConfig['beforeRequest'];
504
513
  onError?: SiteHooksConfig['onError'];
@@ -526,6 +535,7 @@ export function applyRuntimeToServerHooks<T extends object>(
526
535
  intl: runtimeHooks.intl,
527
536
  beforeRequest: runtimeHooks.beforeRequest,
528
537
  loadIntl: runtimeHooks.loadIntl,
538
+ loadLanguageCatalog: runtimeHooks.loadLanguageCatalog,
529
539
  loadSeoMeta: runtimeHooks.loadSeoMeta,
530
540
  onError: runtimeHooks.onError,
531
541
  } as T;
@@ -545,6 +555,8 @@ export function applyRuntimeToServerHooks<T extends object>(
545
555
  ...hooks,
546
556
  siteBaseUrl,
547
557
  apiBaseUrl,
558
+ loadLanguageCatalog:
559
+ baseHooks.loadLanguageCatalog ?? createLanguageCatalog(runtime, runtime.i18n?.locales),
548
560
  ...(runtimeSeoHook && { loadSeoMeta: runtimeSeoHook }),
549
561
  } as T;
550
562
  }
@@ -633,20 +645,21 @@ function createSiteHooks(config: SiteHooksConfig, runtime: SiteRuntimeConfig): S
633
645
  return r ?? { locale, messages: {}, direction: rtlOf(locale) };
634
646
  }
635
647
  if (intlCfg.endpoint) {
636
- const url = fillTemplate(intlCfg.endpoint, { locale });
637
- const json = await fetchJson(url, markDegraded);
648
+ const url = resolveAdminUrl(intlCfg.endpoint, { locale }, runtimeCtx);
649
+ const json = url ? await fetchMetadataJson(url, null) : null;
638
650
  if (json !== null && intlCfg.transform) {
639
651
  const transformed = await intlCfg.transform(json, locale);
640
- if (transformed) {
652
+ if (transformed && isUsableDictionary(transformed.messages)) {
641
653
  return {
642
654
  ...transformed,
643
655
  direction: transformed.direction ?? rtlOf(transformed.locale),
644
656
  };
645
657
  }
646
658
  }
659
+ const messages = extractIntlMessagesOrNull(json, url ? markDegraded : undefined);
647
660
  return {
648
661
  locale,
649
- messages: extractIntlMessages(json),
662
+ messages: messages ?? {},
650
663
  direction: rtlOf(locale),
651
664
  };
652
665
  }
@@ -739,6 +752,7 @@ function createSiteHooks(config: SiteHooksConfig, runtime: SiteRuntimeConfig): S
739
752
  async loadIntl(req) {
740
753
  return intlLoader(detectLocale(req));
741
754
  },
755
+ loadLanguageCatalog: createLanguageCatalog(runtime, runtimeLocale?.locales ?? supportedLocales),
742
756
  async loadSeoMeta(req) {
743
757
  const url = new URL(req.url);
744
758
  const locale = detectLocale(req);
@@ -819,20 +833,83 @@ function matchConfiguredLocale(
819
833
  return supportedLocales.find(locale => locale.toLowerCase().split('-')[0] === prefix);
820
834
  }
821
835
 
822
- function extractIntlMessages(data: unknown): Record<string, unknown> {
823
- return extractIntlMessagesOrNull(data) ?? {};
824
- }
825
-
826
- function extractIntlMessagesOrNull(data: unknown): Record<string, unknown> | null {
827
- if (!data || typeof data !== 'object') return null;
828
- const raw = data as Record<string, unknown>;
829
- const dataValue = raw.data;
836
+ function extractIntlMessagesOrNull(
837
+ data: unknown,
838
+ markDegraded?: () => void
839
+ ): Record<string, unknown> | null {
840
+ const body = isRecord(data) ? data : {};
841
+ const dataValue = body.data;
830
842
  const candidate =
831
- raw.strings ??
832
- raw.messages ??
843
+ body.strings ??
844
+ body.messages ??
833
845
  (isRecord(dataValue) && 'strings' in dataValue ? dataValue.strings : dataValue);
834
- if (!candidate || typeof candidate !== 'object') return null;
835
- return normalizeMessages(candidate as Record<string, unknown>);
846
+ if (body.status !== false && isUsableDictionary(candidate)) return normalizeMessages(candidate);
847
+ markDegraded?.();
848
+ return null;
849
+ }
850
+
851
+ function isUsableDictionary(value: unknown): value is Record<string, unknown> {
852
+ return isRecord(value) && Object.values(value).some(hasMessageValue);
853
+ }
854
+
855
+ function hasMessageValue(value: unknown): boolean {
856
+ if (typeof value === 'string') return value.trim().length > 0;
857
+ if (typeof value === 'boolean' || typeof value === 'number') return true;
858
+ return !!value && typeof value === 'object' && Object.values(value).some(hasMessageValue);
859
+ }
860
+
861
+ function displayLanguageName(locale: string): string {
862
+ try {
863
+ return (
864
+ new Intl.DisplayNames([locale], { type: 'language', fallback: 'none' }).of(locale) ?? locale
865
+ );
866
+ } catch (error) {
867
+ if (error instanceof RangeError) return locale;
868
+ throw error;
869
+ }
870
+ }
871
+
872
+ function createLanguageCatalog(runtime: SiteRuntimeConfig, locales: readonly string[] = []) {
873
+ const defaults = locales.map(locale => ({ locale, name: displayLanguageName(locale) }));
874
+ const config = runtime.i18n?.catalog;
875
+ if (!config || !locales.length) return async () => defaults;
876
+
877
+ const ctx: SiteRuntimeContext = { runtime, services: resolveRuntimeServices(runtime) };
878
+ const url = resolveAdminUrl(config.endpoint, {}, ctx);
879
+ const load = createCachedFetcher<void, readonly LanguageCatalogEntry[]>({
880
+ key: () => 'language-catalog',
881
+ ttl: config.ttl ?? runtime.i18n?.ttl,
882
+ onDegraded: markUncacheable,
883
+ fallback: () => defaults,
884
+ fetch: async () => {
885
+ const json = url ? await fetchMetadataJson(url, runtime.i18n?.timeoutMs) : null;
886
+ const entries: unknown = isRecord(json) ? json.data : json;
887
+ if (!Array.isArray(entries)) throw new TypeError('Invalid language catalog response');
888
+
889
+ const names = new Map<string, string>();
890
+ for (const entry of entries as unknown[]) {
891
+ if (
892
+ !isRecord(entry) ||
893
+ typeof entry.locale !== 'string' ||
894
+ typeof entry.name !== 'string'
895
+ ) {
896
+ throw new TypeError('Invalid language catalog entry');
897
+ }
898
+ const name = entry.name.trim();
899
+ if (name) names.set(entry.locale.toLowerCase(), name);
900
+ }
901
+ return defaults.map(({ locale, name }) => ({
902
+ locale,
903
+ name: names.get(locale.toLowerCase()) ?? name,
904
+ }));
905
+ },
906
+ });
907
+ const invalidate: Parameters<typeof registerContentInvalidator>[0] = scopes => {
908
+ if (scopes.allPageMetadata || scopes.locales.length) load.invalidate();
909
+ };
910
+ Object.defineProperty(load, CONTENT_INVALIDATOR, { value: invalidate });
911
+ registerContentInvalidator(invalidate, { weak: true });
912
+ return load;
836
913
  }
837
914
 
838
915
  function normalizeMessages(messages: Record<string, unknown>): Record<string, unknown> {
@@ -98,6 +98,18 @@ export interface RuntimeExperimentTrackingConfig {
98
98
  enabled: boolean | undefined;
99
99
  }
100
100
 
101
+ export interface LanguageCatalogEntry {
102
+ readonly locale: string;
103
+ readonly name: string;
104
+ }
105
+
106
+ export interface RuntimeLanguageCatalogConfig {
107
+ /** Returns an array of locale/name entries, optionally wrapped in { data }. */
108
+ endpoint: string;
109
+ /** Catalog cache TTL in milliseconds. Defaults to the dictionary TTL. */
110
+ ttl?: number;
111
+ }
112
+
101
113
  export interface RuntimeI18nConfig {
102
114
  /** 支持的 locale 列表,用于 URL locale 前缀解析和请求协商 */
103
115
  locales: readonly string[];
@@ -107,6 +119,8 @@ export interface RuntimeI18nConfig {
107
119
  prefixDefault: boolean;
108
120
  /** Opt in to remembering LocaleLink selections for the unprefixed root in prefixDefault mode. */
109
121
  rememberLocale?: boolean;
122
+ /** Optional bulk source for the display names of the configured locales. */
123
+ catalog?: RuntimeLanguageCatalogConfig;
110
124
  /** 远端字典端点;相对路径会拼到 services.api 上 */
111
125
  endpoint: string | undefined;
112
126
  /** 本地兜底字典;配置 API 不可用时使用 */