mapa-frontend-i18n 1.3.5 → 2.1.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.
package/README.md ADDED
@@ -0,0 +1,264 @@
1
+ # mapa-frontend-i18n
2
+
3
+ Biblioteca Angular de internacionalização (i18n) construída sobre
4
+ [`@angular/localize`](https://angular.dev/guide/i18n). Fornece os catálogos de
5
+ tradução do produto MAPA (pt-BR, en, es) e funções para inicializar o idioma da
6
+ aplicação.
7
+
8
+ A partir da **2.0**, as traduções podem ser carregadas de **arquivos JSON
9
+ hospedados na AWS (S3/CloudFront)**, permitindo corrigir termos e acentuação
10
+ **sem republicar a lib nem fazer redeploy das aplicações**. Os catálogos
11
+ embutidos continuam no pacote como _fallback_.
12
+
13
+ > **Compatibilidade:** a 2.0 é aditiva — a API síncrona da 1.x
14
+ > (`initializeAppLanguage`, `getMapaUiTexts`, tipos e catálogos) continua igual.
15
+ > O carregamento remoto é **opt-in** via `initializeAppLanguageAsync`. O major
16
+ > marca a mudança de arquitetura (traduções podem vir da rede), não uma quebra
17
+ > de API.
18
+
19
+ ---
20
+
21
+ ## Sumário
22
+
23
+ - [Instalação](#instalação)
24
+ - [Como funciona](#como-funciona)
25
+ - [Inicialização](#inicialização)
26
+ - [Modo 1 — Embutido (síncrono)](#modo-1--embutido-síncrono)
27
+ - [Modo 2 — Remoto com fallback (recomendado)](#modo-2--remoto-com-fallback-recomendado)
28
+ - [Modo 3 — Host distribui aos MFEs](#modo-3--host-distribui-aos-mfes)
29
+ - [Opções de carregamento remoto](#opções-de-carregamento-remoto)
30
+ - [Cache e revalidação](#cache-e-revalidação)
31
+ - [Arquivos de tradução na AWS](#arquivos-de-tradução-na-aws)
32
+ - [Gerar/atualizar os JSON](#geraratualizar-os-json)
33
+ - [Processo de hotfix de termo](#processo-de-hotfix-de-termo-sem-republicar)
34
+ - [Requisitos de infraestrutura](#requisitos-de-infraestrutura-aws)
35
+ - [Outras APIs](#outras-apis)
36
+ - [Idiomas suportados](#idiomas-suportados)
37
+
38
+ ---
39
+
40
+ ## Instalação
41
+
42
+ ```bash
43
+ npm install mapa-frontend-i18n
44
+ ```
45
+
46
+ `peerDependency`: `@angular/localize ~20.3.0` (já presente nas aplicações MAPA).
47
+
48
+ ---
49
+
50
+ ## Como funciona
51
+
52
+ - As traduções são um **mapa achatado** `{ "chave.do.localize": "texto" }`,
53
+ injetado no `@angular/localize` via `loadTranslations()`.
54
+ - O `$localize` resolve cada mensagem **no momento em que ela é avaliada**, usando
55
+ o mapa global. Por isso, **as traduções precisam ser carregadas antes do
56
+ `bootstrapApplication()`** — caso contrário a tela aparece com o texto-fonte
57
+ (pt-BR) ou com as chaves cruas.
58
+ - O carregamento remoto faz o merge `{ ...embutido, ...remoto }`: o remoto
59
+ **sobrescreve** o embutido, e qualquer chave ausente no remoto ainda resolve
60
+ pelo embutido. Ou seja, **arquivos remotos parciais são seguros**.
61
+
62
+ ---
63
+
64
+ ## Inicialização
65
+
66
+ ### Modo 1 — Embutido (síncrono)
67
+
68
+ Usa apenas os catálogos embutidos no pacote. É o comportamento clássico, sem
69
+ rede.
70
+
71
+ ```ts
72
+ import { initializeAppLanguage } from "mapa-frontend-i18n";
73
+
74
+ initializeAppLanguage(); // lê o idioma do localStorage e carrega o embutido
75
+ ```
76
+
77
+ ### Modo 2 — Remoto com fallback (recomendado)
78
+
79
+ Carrega da AWS, com cache local e _fallback_ automático para o embutido. **Deve
80
+ ser aguardado antes do bootstrap.**
81
+
82
+ ```ts
83
+ // main.ts
84
+ import { bootstrapApplication } from "@angular/platform-browser";
85
+ import { initializeAppLanguageAsync } from "mapa-frontend-i18n";
86
+ import { AppComponent } from "./app/app.component";
87
+ import { appConfig } from "./app/app.config";
88
+ import { environment } from "./environments/environment";
89
+
90
+ initializeAppLanguageAsync({ baseUrl: environment.i18nBaseUrl })
91
+ .catch(() => undefined) // nunca lança; em falha já usa o fallback embutido
92
+ .then(() => bootstrapApplication(AppComponent, appConfig));
93
+ ```
94
+
95
+ `environment.i18nBaseUrl` aponta para a pasta que contém os JSON por idioma, por
96
+ ambiente (dev/staging/prod). Ex.: `https://cdn.mapa.com.br/i18n`.
97
+
98
+ ### Modo 3 — Host distribui aos MFEs
99
+
100
+ Em micro-frontends, o **host** busca as traduções uma única vez e as repassa para
101
+ cada MFE, evitando um request por MFE. Use quando cada MFE roda em um contexto de
102
+ `@angular/localize` próprio.
103
+
104
+ ```ts
105
+ // no host (antes do bootstrap):
106
+ import { getStoredAppLanguage, loadRemoteTranslations } from "mapa-frontend-i18n";
107
+
108
+ const language = getStoredAppLanguage();
109
+ const remote = await loadRemoteTranslations(language, {
110
+ baseUrl: environment.i18nBaseUrl,
111
+ });
112
+ // disponibilize `language` + `remote` para os MFEs (window, store compartilhado, etc.)
113
+ ```
114
+
115
+ ```ts
116
+ // em cada MFE (antes do seu bootstrap):
117
+ import { initializeAppLanguageFromData } from "mapa-frontend-i18n";
118
+
119
+ initializeAppLanguageFromData(language, remote ?? {});
120
+ ```
121
+
122
+ > Se os MFEs compartilham o mesmo `@angular/localize` (singleton via module
123
+ > federation), basta o host chamar `initializeAppLanguageAsync` uma vez.
124
+
125
+ ---
126
+
127
+ ## Opções de carregamento remoto
128
+
129
+ `RemoteTranslationOptions` (usado por `initializeAppLanguageAsync` e
130
+ `loadRemoteTranslations`):
131
+
132
+ | Opção | Tipo | Padrão | Descrição |
133
+ | ------------ | -------------------------- | -------------- | ------------------------------------------------------------------------- |
134
+ | `baseUrl` | `string` | — (obrigatório) | URL base dos JSON, sem barra final. Busca `${baseUrl}/${idioma}.json`. |
135
+ | `version` | `string` | `undefined` | Tag de versão (`?v=`) para _cache-busting_ manual (requer CloudFront com query string na chave de cache). |
136
+ | `timeoutMs` | `number` | `5000` | Aborta o request após esse tempo (o boot não trava se a AWS demorar). |
137
+ | `fetchImpl` | `typeof fetch` | `globalThis.fetch` | `fetch` customizado (testes/SSR). |
138
+ | `onError` | `(error: unknown) => void` | `undefined` | Notificação de erro de fetch/parse (não-fatal; o _fallback_ é usado). |
139
+
140
+ ---
141
+
142
+ ## Cache e revalidação
143
+
144
+ Estratégia _stale-while-revalidate_:
145
+
146
+ - Cache em `localStorage`, chave `i18n.cache.<idioma>` (apenas o idioma ativo).
147
+ - **1º acesso:** aguarda o fetch; em falha, usa o embutido.
148
+ - **Acessos seguintes:** aplica o cache **na hora** (boot instantâneo) e revalida
149
+ em segundo plano. Se o conteúdo mudou, o cache é atualizado e **a nova versão
150
+ entra no próximo reload**.
151
+
152
+ O request é um **GET simples** (sem cabeçalhos customizados) com `cache:
153
+ "no-cache"`: a revalidação contra o CDN é feita pelo próprio browser via
154
+ `ETag`/`Last-Modified`, de forma transparente. Isso evita _preflight_ CORS — o
155
+ servidor só precisa do cabeçalho `Access-Control-Allow-Origin`.
156
+
157
+ Cadeia de _fallback_ em qualquer falha: `cache → catálogo embutido` (nunca a
158
+ chave crua).
159
+
160
+ ---
161
+
162
+ ## Arquivos de tradução na AWS
163
+
164
+ Um arquivo JSON **por idioma**, contendo o mapa achatado já mesclado de todos os
165
+ módulos:
166
+
167
+ ```
168
+ ${baseUrl}/pt-BR.json
169
+ ${baseUrl}/en.json
170
+ ${baseUrl}/es.json
171
+ ```
172
+
173
+ Formato (mesmo shape consumido pelo `loadTranslations()`):
174
+
175
+ ```json
176
+ {
177
+ "common.cancel": "Cancelar",
178
+ "common.close": "Fechar",
179
+ "home.title": "Painel"
180
+ }
181
+ ```
182
+
183
+ ---
184
+
185
+ ## Gerar/atualizar os JSON
186
+
187
+ O script de export gera os arquivos a partir dos catálogos embutidos. Use para
188
+ **semear** o conteúdo inicial na AWS e para manter o _fallback_ embutido
189
+ sincronizado a cada release.
190
+
191
+ ```bash
192
+ npm run export:i18n
193
+ # escreve dist/i18n-remote/{pt-BR,en,es}.json
194
+ ```
195
+
196
+ ---
197
+
198
+ ## Processo de hotfix de termo (sem republicar)
199
+
200
+ 1. Edite o termo/acentuação diretamente no JSON do idioma na AWS (ou ajuste só as
201
+ chaves alteradas — arquivos parciais são suportados).
202
+ 2. Faça upload para o S3.
203
+ 3. Invalide o cache do CloudFront **ou** confie no `ETag` + `Cache-Control` curto
204
+ (a revalidação aplica a mudança no próximo reload dos usuários).
205
+
206
+ Nenhuma publicação de versão da lib nem redeploy das aplicações é necessária.
207
+
208
+ > Os catálogos `*.ts` embutidos seguem como _fallback_ (último-bom-conhecido).
209
+ > Para mantê-los alinhados com a AWS, rode `npm run export:i18n` periodicamente e
210
+ > publique uma release quando quiser atualizar o _fallback_.
211
+
212
+ ---
213
+
214
+ ## Requisitos de infraestrutura (AWS)
215
+
216
+ - **S3** (com ou sem CloudFront) servindo `/i18n/{idioma}.json` por ambiente.
217
+ - **CORS (obrigatório):** basta `Access-Control-Allow-Origin` liberando as origens
218
+ das aplicações no GET (não há _preflight_, pois o request é simples). Bucket
219
+ público **não** dispensa CORS — sem ele o browser bloqueia a leitura via `fetch`.
220
+ Ver config de exemplo em [`examples/aws/s3-cors.json`](../../examples/aws/s3-cors.json).
221
+ - **`ETag`** (o S3 já envia) para a revalidação condicional do browser funcionar.
222
+ - **Propagação de hotfix:**
223
+ - **S3 direto (sem CDN):** a alteração é **imediata** no próximo reload.
224
+ - **Via CloudFront:** use `Cache-Control` curto (ex.: `max-age=300`) **ou
225
+ invalide** o caminho a cada hotfix — senão o edge serve a versão antiga até a
226
+ TTL padrão (24h).
227
+
228
+ ---
229
+
230
+ ## Outras APIs
231
+
232
+ ```ts
233
+ import {
234
+ // Idioma
235
+ getStoredAppLanguage,
236
+ persistAppLanguage,
237
+ applyDocumentLanguage,
238
+ getAngularLocale,
239
+ getIntlLocale,
240
+ resolveAppLanguage,
241
+ APP_LANGUAGE_OPTIONS,
242
+ DEFAULT_APP_LANGUAGE,
243
+
244
+ // Textos de UI (validações, paginador, etc.)
245
+ getMapaUiTexts,
246
+ applyPaginatorIntl,
247
+ } from "mapa-frontend-i18n";
248
+ ```
249
+
250
+ `getMapaUiTexts(language)` retorna textos de UI reutilizáveis (filtros, tabela,
251
+ validações). Alguns valores são **funções** (paginador e validações com
252
+ interpolação) e permanecem no código da lib — não são externalizados para JSON.
253
+
254
+ ---
255
+
256
+ ## Idiomas suportados
257
+
258
+ | Código | Idioma | Padrão |
259
+ | ------- | ---------- | ------ |
260
+ | `pt-BR` | Português | ✅ (fonte/fallback) |
261
+ | `es` | Español | |
262
+ | `en` | English | |
263
+
264
+ O idioma escolhido é persistido em `localStorage` na chave `menu.language`.