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 +264 -0
- package/fesm2022/mapa-frontend-i18n.mjs +374 -7
- package/fesm2022/mapa-frontend-i18n.mjs.map +1 -1
- package/index.d.ts +92 -2
- package/mapa-frontend-i18n-2.1.0.tgz +0 -0
- package/package.json +1 -1
- package/mapa-frontend-i18n-1.3.5.tgz +0 -0
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`.
|