mapa-frontend-i18n 1.3.4 → 2.0.0

package/index.d.ts

@@ -36,6 +36,56 @@ declare const MP_TRANSLATIONS: Record<AppLanguage, Record<string, string>>;
 
 declare const MV_TRANSLATIONS: Record<AppLanguage, Record<string, string>>;
 
+/**
+ * Flat map of `$localize` message id -> translated text, the shape expected by
+ * `@angular/localize`'s `loadTranslations()` and the shape served per language
+ * from the remote (AWS) JSON files.
+ */
+type FlatTranslations = Record<string, string>;
+interface RemoteTranslationOptions {
+    /**
+     * Base URL where the per-language JSON files live (without trailing slash or
+     * file name). Each language is fetched from `${baseUrl}/${language}.json`,
+     * e.g. `https://cdn.example.com/i18n` -> `https://cdn.example.com/i18n/pt-BR.json`.
+     */
+    baseUrl: string;
+    /**
+     * Optional version/build tag appended as `?v=` for manual cache-busting
+     * (requires the CDN to vary its cache key by query string).
+     */
+    version?: string;
+    /** Abort the request after this many milliseconds. Defaults to 5000. */
+    timeoutMs?: number;
+    /** Custom fetch implementation (tests / SSR). Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Invoked when a fetch/parse error happens. Non-fatal: a fallback is used. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Reads the cached translations for a language from localStorage. Returns
+ * `null` when there is no cache, it is unreadable, or its shape is invalid.
+ * Safe to call during SSR (returns `null` when localStorage is unavailable).
+ */
+declare function readCachedTranslations(language: AppLanguage): {
+    version: string | null;
+    data: FlatTranslations;
+} | null;
+/**
+ * Fetches the remote translations for a language, updating the localStorage
+ * cache.
+ *
+ * Uses a plain GET (no custom request headers) on purpose: this keeps it a
+ * "simple" CORS request, so the only server requirement is an
+ * `Access-Control-Allow-Origin` header — no OPTIONS preflight. Freshness is
+ * delegated to the HTTP layer via `cache: "no-cache"`, which makes the browser
+ * revalidate against the CDN's `ETag`/`Last-Modified` transparently (a 304 is
+ * resolved by the browser and surfaces here as a normal 200).
+ *
+ * Resolution order on failure: cached data (if any), otherwise `null` so the
+ * caller can fall back to the embedded catalogs. Never throws.
+ */
+declare function loadRemoteTranslations(language: AppLanguage, options: RemoteTranslationOptions): Promise<FlatTranslations | null>;
+
 declare function getStoredAppLanguage(): AppLanguage;
 declare function persistAppLanguage(language: AppLanguage): void;
 declare function getAngularLocale(language: AppLanguage): string;
@@ -45,6 +95,32 @@ interface InitializeAppLanguageOptions {
     clearExistingTranslations?: boolean;
 }
 declare function initializeAppLanguage(options?: InitializeAppLanguageOptions): AppLanguage;
+interface InitializeAppLanguageAsyncOptions extends RemoteTranslationOptions {
+    clearExistingTranslations?: boolean;
+}
+/**
+ * Initializes translations by loading them from the remote (AWS) JSON files,
+ * with the embedded catalogs as a fallback. MUST be awaited before the host
+ * application bootstraps, because `$localize` resolves messages at evaluation
+ * time from the global map populated here.
+ *
+ * Behaviour:
+ * - With a local cache: applies the cached copy immediately (instant boot) and
+ *   revalidates in the background; an updated copy takes effect on the next reload.
+ * - Without a cache: awaits the remote fetch and, on any failure, falls back to
+ *   the embedded catalogs (never the raw keys).
+ */
+declare function initializeAppLanguageAsync(options: InitializeAppLanguageAsyncOptions): Promise<AppLanguage>;
+interface InitializeAppLanguageFromDataOptions {
+    clearExistingTranslations?: boolean;
+}
+/**
+ * Initializes translations from data the caller already fetched. Intended for
+ * micro-frontend setups where a host fetches the remote translations once and
+ * shares them with each MFE, avoiding one network request per MFE. The data is
+ * merged over the embedded fallback, like {@link initializeAppLanguageAsync}.
+ */
+declare function initializeAppLanguageFromData(language: AppLanguage, remote: FlatTranslations, options?: InitializeAppLanguageFromDataOptions): AppLanguage;
 
 interface ValidationContext {
     actualLength?: number;
@@ -183,5 +259,5 @@ declare const MAPA_UI_TEXTS_PT_BR: {
 };
 declare function getMapaUiTexts(language: AppLanguage): PartialMapaUiTexts;
 
-export { ANGULAR_RUNTIME_TRANSLATIONS, APP_LANGUAGE_OPTIONS, APP_LANGUAGE_STORAGE_KEY, DEFAULT_APP_LANGUAGE, MAPA_UI_TEXTS_PT_BR, MA_TRANSLATIONS, MCA_TRANSLATIONS, MENU_TRANSLATIONS, MF_TRANSLATIONS, MGA_TRANSLATIONS, MGC_TRANSLATIONS, MO_TRANSLATIONS, MP_TRANSLATIONS, MV_TRANSLATIONS, applyDocumentLanguage, applyPaginatorIntl, formatPaginatorRange, formatPaginatorShowingRange, getAngularLocale, getAppLanguageOption, getIntlLocale, getMapaUiTexts, getPaginatorNavigationLabels, getStoredAppLanguage, initializeAppLanguage, isAppLanguage, persistAppLanguage, resolveAppLanguage };
-export type { AppLanguage, AppLanguageOption, InitializeAppLanguageOptions, MapaUiTextGroups, PartialMapaUiTexts, ValidationContext, ValidationTextResolver };
+export { ANGULAR_RUNTIME_TRANSLATIONS, APP_LANGUAGE_OPTIONS, APP_LANGUAGE_STORAGE_KEY, DEFAULT_APP_LANGUAGE, MAPA_UI_TEXTS_PT_BR, MA_TRANSLATIONS, MCA_TRANSLATIONS, MENU_TRANSLATIONS, MF_TRANSLATIONS, MGA_TRANSLATIONS, MGC_TRANSLATIONS, MO_TRANSLATIONS, MP_TRANSLATIONS, MV_TRANSLATIONS, applyDocumentLanguage, applyPaginatorIntl, formatPaginatorRange, formatPaginatorShowingRange, getAngularLocale, getAppLanguageOption, getIntlLocale, getMapaUiTexts, getPaginatorNavigationLabels, getStoredAppLanguage, initializeAppLanguage, initializeAppLanguageAsync, initializeAppLanguageFromData, isAppLanguage, loadRemoteTranslations, persistAppLanguage, readCachedTranslations, resolveAppLanguage };
+export type { AppLanguage, AppLanguageOption, FlatTranslations, InitializeAppLanguageAsyncOptions, InitializeAppLanguageFromDataOptions, InitializeAppLanguageOptions, MapaUiTextGroups, PartialMapaUiTexts, RemoteTranslationOptions, ValidationContext, ValidationTextResolver };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mapa-frontend-i18n",
-  "version": "1.3.4",
+  "version": "2.0.0",
   "peerDependencies": {
     "@angular/localize": "~20.3.0"
   },