mapa-frontend-i18n 1.3.5 → 2.0.0

package/README.md

@@ -0,0 +1,264 @@
+# mapa-frontend-i18n
+
+Biblioteca Angular de internacionalização (i18n) construída sobre
+[`@angular/localize`](https://angular.dev/guide/i18n). Fornece os catálogos de
+tradução do produto MAPA (pt-BR, en, es) e funções para inicializar o idioma da
+aplicação.
+
+A partir da **2.0**, as traduções podem ser carregadas de **arquivos JSON
+hospedados na AWS (S3/CloudFront)**, permitindo corrigir termos e acentuação
+**sem republicar a lib nem fazer redeploy das aplicações**. Os catálogos
+embutidos continuam no pacote como _fallback_.
+
+> **Compatibilidade:** a 2.0 é aditiva — a API síncrona da 1.x
+> (`initializeAppLanguage`, `getMapaUiTexts`, tipos e catálogos) continua igual.
+> O carregamento remoto é **opt-in** via `initializeAppLanguageAsync`. O major
+> marca a mudança de arquitetura (traduções podem vir da rede), não uma quebra
+> de API.
+
+---
+
+## Sumário
+
+- [Instalação](#instalação)
+- [Como funciona](#como-funciona)
+- [Inicialização](#inicialização)
+  - [Modo 1 — Embutido (síncrono)](#modo-1--embutido-síncrono)
+  - [Modo 2 — Remoto com fallback (recomendado)](#modo-2--remoto-com-fallback-recomendado)
+  - [Modo 3 — Host distribui aos MFEs](#modo-3--host-distribui-aos-mfes)
+- [Opções de carregamento remoto](#opções-de-carregamento-remoto)
+- [Cache e revalidação](#cache-e-revalidação)
+- [Arquivos de tradução na AWS](#arquivos-de-tradução-na-aws)
+- [Gerar/atualizar os JSON](#geraratualizar-os-json)
+- [Processo de hotfix de termo](#processo-de-hotfix-de-termo-sem-republicar)
+- [Requisitos de infraestrutura](#requisitos-de-infraestrutura-aws)
+- [Outras APIs](#outras-apis)
+- [Idiomas suportados](#idiomas-suportados)
+
+---
+
+## Instalação
+
+```bash
+npm install mapa-frontend-i18n
+```
+
+`peerDependency`: `@angular/localize ~20.3.0` (já presente nas aplicações MAPA).
+
+---
+
+## Como funciona
+
+- As traduções são um **mapa achatado** `{ "chave.do.localize": "texto" }`,
+  injetado no `@angular/localize` via `loadTranslations()`.
+- O `$localize` resolve cada mensagem **no momento em que ela é avaliada**, usando
+  o mapa global. Por isso, **as traduções precisam ser carregadas antes do
+  `bootstrapApplication()`** — caso contrário a tela aparece com o texto-fonte
+  (pt-BR) ou com as chaves cruas.
+- O carregamento remoto faz o merge `{ ...embutido, ...remoto }`: o remoto
+  **sobrescreve** o embutido, e qualquer chave ausente no remoto ainda resolve
+  pelo embutido. Ou seja, **arquivos remotos parciais são seguros**.
+
+---
+
+## Inicialização
+
+### Modo 1 — Embutido (síncrono)
+
+Usa apenas os catálogos embutidos no pacote. É o comportamento clássico, sem
+rede.
+
+```ts
+import { initializeAppLanguage } from "mapa-frontend-i18n";
+
+initializeAppLanguage(); // lê o idioma do localStorage e carrega o embutido
+```
+
+### Modo 2 — Remoto com fallback (recomendado)
+
+Carrega da AWS, com cache local e _fallback_ automático para o embutido. **Deve
+ser aguardado antes do bootstrap.**
+
+```ts
+// main.ts
+import { bootstrapApplication } from "@angular/platform-browser";
+import { initializeAppLanguageAsync } from "mapa-frontend-i18n";
+import { AppComponent } from "./app/app.component";
+import { appConfig } from "./app/app.config";
+import { environment } from "./environments/environment";
+
+initializeAppLanguageAsync({ baseUrl: environment.i18nBaseUrl })
+  .catch(() => undefined) // nunca lança; em falha já usa o fallback embutido
+  .then(() => bootstrapApplication(AppComponent, appConfig));
+```
+
+`environment.i18nBaseUrl` aponta para a pasta que contém os JSON por idioma, por
+ambiente (dev/staging/prod). Ex.: `https://cdn.mapa.com.br/i18n`.
+
+### Modo 3 — Host distribui aos MFEs
+
+Em micro-frontends, o **host** busca as traduções uma única vez e as repassa para
+cada MFE, evitando um request por MFE. Use quando cada MFE roda em um contexto de
+`@angular/localize` próprio.
+
+```ts
+// no host (antes do bootstrap):
+import { getStoredAppLanguage, loadRemoteTranslations } from "mapa-frontend-i18n";
+
+const language = getStoredAppLanguage();
+const remote = await loadRemoteTranslations(language, {
+  baseUrl: environment.i18nBaseUrl,
+});
+// disponibilize `language` + `remote` para os MFEs (window, store compartilhado, etc.)
+```
+
+```ts
+// em cada MFE (antes do seu bootstrap):
+import { initializeAppLanguageFromData } from "mapa-frontend-i18n";
+
+initializeAppLanguageFromData(language, remote ?? {});
+```
+
+> Se os MFEs compartilham o mesmo `@angular/localize` (singleton via module
+> federation), basta o host chamar `initializeAppLanguageAsync` uma vez.
+
+---
+
+## Opções de carregamento remoto
+
+`RemoteTranslationOptions` (usado por `initializeAppLanguageAsync` e
+`loadRemoteTranslations`):
+
+| Opção        | Tipo                       | Padrão         | Descrição                                                                 |
+| ------------ | -------------------------- | -------------- | ------------------------------------------------------------------------- |
+| `baseUrl`    | `string`                   | — (obrigatório) | URL base dos JSON, sem barra final. Busca `${baseUrl}/${idioma}.json`.   |
+| `version`    | `string`                   | `undefined`    | Tag de versão (`?v=`) para _cache-busting_ manual (requer CloudFront com query string na chave de cache). |
+| `timeoutMs`  | `number`                   | `5000`         | Aborta o request após esse tempo (o boot não trava se a AWS demorar).    |
+| `fetchImpl`  | `typeof fetch`             | `globalThis.fetch` | `fetch` customizado (testes/SSR).                                     |
+| `onError`    | `(error: unknown) => void` | `undefined`    | Notificação de erro de fetch/parse (não-fatal; o _fallback_ é usado).    |
+
+---
+
+## Cache e revalidação
+
+Estratégia _stale-while-revalidate_:
+
+- Cache em `localStorage`, chave `i18n.cache.<idioma>` (apenas o idioma ativo).
+- **1º acesso:** aguarda o fetch; em falha, usa o embutido.
+- **Acessos seguintes:** aplica o cache **na hora** (boot instantâneo) e revalida
+  em segundo plano. Se o conteúdo mudou, o cache é atualizado e **a nova versão
+  entra no próximo reload**.
+
+O request é um **GET simples** (sem cabeçalhos customizados) com `cache:
+"no-cache"`: a revalidação contra o CDN é feita pelo próprio browser via
+`ETag`/`Last-Modified`, de forma transparente. Isso evita _preflight_ CORS — o
+servidor só precisa do cabeçalho `Access-Control-Allow-Origin`.
+
+Cadeia de _fallback_ em qualquer falha: `cache → catálogo embutido` (nunca a
+chave crua).
+
+---
+
+## Arquivos de tradução na AWS
+
+Um arquivo JSON **por idioma**, contendo o mapa achatado já mesclado de todos os
+módulos:
+
+```
+${baseUrl}/pt-BR.json
+${baseUrl}/en.json
+${baseUrl}/es.json
+```
+
+Formato (mesmo shape consumido pelo `loadTranslations()`):
+
+```json
+{
+  "common.cancel": "Cancelar",
+  "common.close": "Fechar",
+  "home.title": "Painel"
+}
+```
+
+---
+
+## Gerar/atualizar os JSON
+
+O script de export gera os arquivos a partir dos catálogos embutidos. Use para
+**semear** o conteúdo inicial na AWS e para manter o _fallback_ embutido
+sincronizado a cada release.
+
+```bash
+npm run export:i18n
+# escreve dist/i18n-remote/{pt-BR,en,es}.json
+```
+
+---
+
+## Processo de hotfix de termo (sem republicar)
+
+1. Edite o termo/acentuação diretamente no JSON do idioma na AWS (ou ajuste só as
+   chaves alteradas — arquivos parciais são suportados).
+2. Faça upload para o S3.
+3. Invalide o cache do CloudFront **ou** confie no `ETag` + `Cache-Control` curto
+   (a revalidação aplica a mudança no próximo reload dos usuários).
+
+Nenhuma publicação de versão da lib nem redeploy das aplicações é necessária.
+
+> Os catálogos `*.ts` embutidos seguem como _fallback_ (último-bom-conhecido).
+> Para mantê-los alinhados com a AWS, rode `npm run export:i18n` periodicamente e
+> publique uma release quando quiser atualizar o _fallback_.
+
+---
+
+## Requisitos de infraestrutura (AWS)
+
+- **S3** (com ou sem CloudFront) servindo `/i18n/{idioma}.json` por ambiente.
+- **CORS (obrigatório):** basta `Access-Control-Allow-Origin` liberando as origens
+  das aplicações no GET (não há _preflight_, pois o request é simples). Bucket
+  público **não** dispensa CORS — sem ele o browser bloqueia a leitura via `fetch`.
+  Ver config de exemplo em [`examples/aws/s3-cors.json`](../../examples/aws/s3-cors.json).
+- **`ETag`** (o S3 já envia) para a revalidação condicional do browser funcionar.
+- **Propagação de hotfix:**
+  - **S3 direto (sem CDN):** a alteração é **imediata** no próximo reload.
+  - **Via CloudFront:** use `Cache-Control` curto (ex.: `max-age=300`) **ou
+    invalide** o caminho a cada hotfix — senão o edge serve a versão antiga até a
+    TTL padrão (24h).
+
+---
+
+## Outras APIs
+
+```ts
+import {
+  // Idioma
+  getStoredAppLanguage,
+  persistAppLanguage,
+  applyDocumentLanguage,
+  getAngularLocale,
+  getIntlLocale,
+  resolveAppLanguage,
+  APP_LANGUAGE_OPTIONS,
+  DEFAULT_APP_LANGUAGE,
+
+  // Textos de UI (validações, paginador, etc.)
+  getMapaUiTexts,
+  applyPaginatorIntl,
+} from "mapa-frontend-i18n";
+```
+
+`getMapaUiTexts(language)` retorna textos de UI reutilizáveis (filtros, tabela,
+validações). Alguns valores são **funções** (paginador e validações com
+interpolação) e permanecem no código da lib — não são externalizados para JSON.
+
+---
+
+## Idiomas suportados
+
+| Código  | Idioma     | Padrão |
+| ------- | ---------- | ------ |
+| `pt-BR` | Português  | ✅ (fonte/fallback) |
+| `es`    | Español    |        |
+| `en`    | English    |        |
+
+O idioma escolhido é persistido em `localStorage` na chave `menu.language`.

package/fesm2022/mapa-frontend-i18n.mjs

@@ -15329,6 +15329,125 @@ function getAppLanguageOption(language) {
         ?? APP_LANGUAGE_OPTIONS[0];
 }
 
+const CACHE_KEY_PREFIX = "i18n.cache.";
+const DEFAULT_TIMEOUT_MS = 5000;
+function getCacheKey(language) {
+    return `${CACHE_KEY_PREFIX}${language}`;
+}
+function buildUrl(baseUrl, language, version) {
+    const normalized = baseUrl.replace(/\/+$/, "");
+    const url = `${normalized}/${language}.json`;
+    return version ? `${url}?v=${encodeURIComponent(version)}` : url;
+}
+/** True only for a plain object whose every value is a string. */
+function isFlatTranslations(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    return Object.values(value).every((entry) => typeof entry === "string");
+}
+function resolveFetch(options) {
+    if (options.fetchImpl) {
+        return options.fetchImpl;
+    }
+    return typeof fetch === "undefined" ? undefined : fetch;
+}
+function withTimeout(timeoutMs) {
+    if (typeof AbortController === "undefined") {
+        return { signal: undefined, done: () => undefined };
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    return { signal: controller.signal, done: () => clearTimeout(timer) };
+}
+/**
+ * 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).
+ */
+function readCachedTranslations(language) {
+    if (typeof localStorage === "undefined") {
+        return null;
+    }
+    try {
+        const raw = localStorage.getItem(getCacheKey(language));
+        if (!raw) {
+            return null;
+        }
+        const parsed = JSON.parse(raw);
+        if (!isFlatTranslations(parsed.data)) {
+            return null;
+        }
+        return {
+            version: typeof parsed.version === "string" ? parsed.version : null,
+            data: parsed.data,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function writeCachedTranslations(language, payload) {
+    if (typeof localStorage === "undefined") {
+        return;
+    }
+    try {
+        localStorage.setItem(getCacheKey(language), JSON.stringify(payload));
+    }
+    catch {
+        // Quota exceeded or storage disabled: ignore, the in-memory result still applies.
+    }
+}
+/**
+ * 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.
+ */
+async function loadRemoteTranslations(language, options) {
+    const fetchImpl = resolveFetch(options);
+    if (!fetchImpl || !options.baseUrl) {
+        return null;
+    }
+    const cached = readCachedTranslations(language);
+    const url = buildUrl(options.baseUrl, language, options.version);
+    const { signal, done } = withTimeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    try {
+        const response = await fetchImpl(url, {
+            cache: "no-cache",
+            signal,
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to load translations: HTTP ${response.status}`);
+        }
+        const data = await response.json();
+        if (!isFlatTranslations(data)) {
+            throw new Error("Remote translations payload is not a flat string map");
+        }
+        writeCachedTranslations(language, {
+            version: options.version ?? null,
+            fetchedAt: Date.now(),
+            data,
+        });
+        return data;
+    }
+    catch (error) {
+        options.onError?.(error);
+        return cached?.data ?? null;
+    }
+    finally {
+        done();
+    }
+}
+
 function getStoredAppLanguage() {
     if (typeof window === "undefined") {
         return DEFAULT_APP_LANGUAGE;
@@ -15365,6 +15484,64 @@ function initializeAppLanguage(options = {}) {
     }
     return language;
 }
+/**
+ * Merges the embedded (build-time) catalog for a language with an optional
+ * remote map and hands the result to `@angular/localize`. The remote entries
+ * override the embedded ones, while any key missing remotely still resolves
+ * from the embedded fallback — so partial remote files are safe.
+ */
+function applyTranslations(language, remote) {
+    const merged = {
+        ...(ANGULAR_RUNTIME_TRANSLATIONS[language] ?? {}),
+        ...(remote ?? {}),
+    };
+    if (Object.keys(merged).length > 0) {
+        loadTranslations(merged);
+    }
+}
+/**
+ * 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).
+ */
+async function initializeAppLanguageAsync(options) {
+    const language = getStoredAppLanguage();
+    if (options.clearExistingTranslations) {
+        clearTranslations();
+    }
+    applyDocumentLanguage(language);
+    const cached = readCachedTranslations(language);
+    if (cached) {
+        applyTranslations(language, cached.data);
+        // Fire-and-forget revalidation; the refreshed cache applies on next reload.
+        void loadRemoteTranslations(language, options).catch(() => undefined);
+        return language;
+    }
+    const remote = await loadRemoteTranslations(language, options);
+    applyTranslations(language, remote);
+    return language;
+}
+/**
+ * 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}.
+ */
+function initializeAppLanguageFromData(language, remote, options = {}) {
+    if (options.clearExistingTranslations) {
+        clearTranslations();
+    }
+    applyDocumentLanguage(language);
+    applyTranslations(language, remote);
+    return language;
+}
 
 const PAGINATOR_COPY_BY_LANGUAGE = {
     "pt-BR": {
@@ -15629,5 +15806,5 @@ function getMapaUiTexts(language) {
  * Generated bundle index. Do not edit.
  */
 
-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 { 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 };
 //# sourceMappingURL=mapa-frontend-i18n.mjs.map