@proulr/rosetta 0.1.2

package/README.md

@@ -0,0 +1,49 @@
+# @proulr/rosetta
+
+Fonte única de i18n do Proulr (padrão Rosetta): copy de produto para BFFs e app nativo.
+
+- **GitHub:** https://github.com/saviorbp/proulr-rosetta
+- **npm:** https://www.npmjs.com/package/@proulr/rosetta
+- **Guia:** [docs/ROSETTA.md](./docs/ROSETTA.md)
+- **CI/CD:** [docs/npm-publish-cicd.md](./docs/npm-publish-cicd.md)
+
+## Formato
+
+```
+src/locales/<locale>/<domain>.json   # editar (flat JSON)
+src/generated/locale-messages.ts     # gerado — Metro importa só .ts
+```
+
+`pt-BR` = source of truth das keys. Após editar JSON: `npm run locale:generate`.
+
+## Uso rápido
+
+```ts
+import { t, tFormat, resolveLocaleFromQuery } from '@proulr/rosetta';
+
+const locale = resolveLocaleFromQuery(ctx.query);
+t('discover.filter.all', locale);
+```
+
+## Scripts
+
+```bash
+npm run locale:add -- es       # novo idioma (JSON vazio + wiring)
+npm run locale:generate        # regenera types/catalog
+npm run validate:locales       # parity de keys + imports (pre-commit)
+npm run check:locales:strict   # sem valores vazios
+npm run typecheck
+```
+
+## Pre-commit
+
+Ao commit, o hook roda `validate:locales`:
+
+- Key nova → deve existir em **todos** os idiomas
+- Key removida → deve sumir de **todos** os idiomas
+- Locale novo → todos os domains + `PROULR_LOCALES` + imports em `catalog.ts`
+
+## Regras
+
+- BFFs/app só consomem `t()` — zero dicionário local
+- Default / fallback: `pt-BR`

package/docs/ROSETTA.md

@@ -0,0 +1,247 @@
+# @proulr/rosetta — guia completo
+
+Pacote de i18n do Proulr (inspirado na Rosetta da Nubank): **única fonte de copy** para BFFs (wire SDUI) e app nativo (auth, alerts, hybrids).
+
+---
+
+## O que foi feito
+
+| Entrega | Detalhe |
+|---------|---------|
+| Pacote `@proulr/rosetta` | `t` / `tFormat` / resolve de locale |
+| Formato JSON por locale | `src/locales/<locale>/<domain>.json` (escala para ~13 idiomas) |
+| `pt-BR` | Fonte das keys; fallback se tradução vazia/ausente |
+| Idiomas iniciais | `pt-BR`, `en` |
+| App | `locale` em todo fetch SDUI; preferência AsyncStorage; auth com globe + tagline ciclando |
+| BFFs | `resolveLocaleFromQuery` + `t()` nos builders BDC |
+| Scripts | `locale:add`, `locale:generate`, `check:locales`, `validate:locales` |
+| Pre-commit | Valida parity de keys + wiring (imports / `PROULR_LOCALES`) |
+
+Consumidores (app + BFFs) **não** guardam dicionário de produto — só chamam `t(key, locale)`.
+
+---
+
+## Arquitetura
+
+```
+preferência (system | pt-BR | en | …)
+        ↓
+app resolve locale (device / navigator)
+        ↓
+fetch SDUI ?locale=…
+        ↓
+BFF: t(key, locale) → wire já traduzido
+        ↓
+SduiScreenRenderer (não traduz)
+
+App nativo (auth/Alert/hybrid): mesmo t() do Rosetta
+```
+
+| Quem | Papel |
+|------|--------|
+| **Rosetta** | Keys + traduções + `t` / `tFormat` |
+| **BFFs** | Traduz na autoria BDC → wire |
+| **App** | Resolve locale; nativo usa `t`; SDUI só renderiza |
+| **SO** | Diálogos de permissão (fora do Rosetta) |
+
+---
+
+## Formato dos arquivos
+
+```
+src/locales/
+  pt-BR/                 # source of truth (editar aqui)
+    common.json
+    …
+  en/
+    …
+
+src/generated/
+  locale-messages.ts     # AUTO-GERADO (Metro-safe) — não editar
+```
+
+Edite só os JSON. Depois rode `npm run locale:generate` (o pre-commit também roda).
+
+Cada JSON é **flat** (key → string):
+
+```json
+{
+  "auth.login.title": "Bem-vindo de volta",
+  "auth.login.submit": "Entrar"
+}
+```
+
+**Não** misturar idiomas no mesmo objeto. Um locale = uma pasta.
+
+---
+
+## Uso no código
+
+### BFF
+
+```ts
+import { t, tFormat, resolveLocaleFromQuery } from '@proulr/rosetta';
+
+const locale = resolveLocaleFromQuery(ctx.query);
+title={t('shell.settings.title', locale)}
+subtitle={tFormat('discover.subtitle.huntingIn', locale, { label: city })}
+```
+
+### App nativo
+
+```ts
+import { t } from '@proulr/rosetta';
+import { getResolvedAppLocale } from '@/lib/app-locale-service';
+// ou
+import { useAppLocale } from '@/hooks/use-app-locale';
+
+const { t, locale, setPref } = useAppLocale();
+t('auth.welcome.signIn');
+```
+
+### Query SDUI
+
+O app envia `locale` (resolvido) em todo `buildSduiScreenFetchQuery`. Em settings também envia `app_locale` (preferência: `system` | idioma explícito).
+
+---
+
+## Scripts
+
+Rodar **dentro** de `proulr-rosetta/`:
+
+| Comando | O que faz |
+|---------|-----------|
+| `npm run locale:add -- es` | Cria pasta do idioma com keys vazias + regenera types/catalog |
+| `npm run locale:add -- es-ES --force` | Idem, sobrescreve templates |
+| `npm run locale:generate` | Regenera `locale-types.ts` + `catalog.ts` a partir de `src/locales` |
+| `npm run check:locales` | Keys de `pt-BR` presentes em todos; vazios = warning |
+| `npm run check:locales:strict` | Idem, mas valor vazio = erro |
+| `npm run validate:locales` | Coverage + wiring (imports, `PROULR_LOCALES`, domains) |
+| `npm run validate:locales:strict` | Validate + sem valores vazios |
+| `npm run typecheck` | `validate:locales` + `tsc` |
+| `npm run lint` | ESLint |
+
+### Exemplos
+
+```bash
+# Novo idioma
+npm run locale:add -- es
+# editar src/locales/es/*.json
+npm run check:locales:strict
+
+# Nova key de copy
+# 1. adicionar em src/locales/pt-BR/<domain>.json
+# 2. adicionar a MESMA key em en/ (e demais locales)
+# 3. npm run validate:locales
+
+# Remover key
+# apagar a key de TODOS os locales/<id>/<domain>.json
+```
+
+---
+
+## Pre-commit
+
+Hook em `.husky/pre-commit` (requer git no pacote — `git init` se ainda não houver remote):
+
+1. **`npm run locale:generate`** — sincroniza `src/generated/locale-messages.ts` a partir dos JSON
+2. **`npm run validate:locales`** — falha o commit se:
+   - Key nova em `pt-BR` sem a mesma key nos outros idiomas
+   - Key removida de `pt-BR` mas ainda presente em outro idioma
+   - Key “sobrando” em um locale sem existir em `pt-BR`
+   - Pasta de locale sem todos os `*.json` de domínio
+   - Locale no disco **sem** estar em `PROULR_LOCALES` / no `locale-messages.ts` gerado
+3. **`lint-staged`** — ESLint nos arquivos staged
+4. **`proulr-bump-and-sync-deps`** (se existir no monorepo) — bump de versão publishable
+
+```bash
+cd proulr-rosetta
+npm install          # prepare → husky
+npm run validate:locales
+```
+
+---
+
+## Workflows
+
+### Nova string de produto
+
+1. Escolher domínio (`auth`, `shell`, `discover`, …)
+2. Adicionar key em **`pt-BR/<domain>.json`**
+3. Adicionar a **mesma key** em **todos** os outros locales (mesmo que temporariamente com `""` ou já traduzido)
+4. Usar `t('domain.key', locale)` no BFF ou app
+5. Commit → pre-commit valida parity
+
+### Novo idioma
+
+1. `npm run locale:add -- <id>` (ex.: `es`, `zh-CN`)
+2. Traduzir os JSONs gerados
+3. `npm run check:locales:strict`
+4. Atualizar UI do app (picker Settings / globe na ante-tela) para incluir o novo locale no ciclo de preferência
+5. Commit
+
+## Detecção de idioma (app)
+
+| Preferência | Comportamento |
+|-------------|---------------|
+| `system` (default) | Mobile: `expo-localization`; Web: `navigator.languages` |
+| `pt-BR` / `en` / … | Força o locale |
+
+Troca na ante-tela (globe) ou em Settings → limpa cache SDUI → próximo fetch no novo idioma.
+
+---
+
+## CI/CD (GitHub Actions + npm)
+
+Detalhes: [`docs/npm-publish-cicd.md`](./npm-publish-cicd.md).
+
+Workflow: [`.github/workflows/publish-npm.yml`](../.github/workflows/publish-npm.yml)
+
+| Evento | O que roda |
+|--------|------------|
+| PR / push em `main` (src, scripts, package*) | `npm run typecheck` |
+| Push em `main` após CI ok | `npm publish --access public` via **Trusted Publishing (OIDC)** |
+
+### Setup Trusted Publishing (primeira vez)
+
+1. Em https://www.npmjs.com → scope `@proulr` → criar/`@proulr/rosetta` se precisar
+2. **Trusted Publisher** → GitHub Actions
+3. Repository: `saviorbp/proulr-rosetta`
+4. Workflow filename: `publish-npm.yml`
+5. Environment: vazio
+
+Sem Trusted Publisher, o job `publish` falha (404/401). Depois do publish, consumers usam `"@proulr/rosetta": "^0.1.1"`.
+
+---
+
+## Regras
+
+- Identificadores EN; copy via Rosetta; default `pt-BR`
+- **Proibido** literal de produto em BFF/app
+- Nova copy = PR no Rosetta (keys em todos os locales)
+- Renderer SDUI **não** traduz
+- Pre-commit deve passar antes do commit
+
+---
+
+## Estrutura do pacote
+
+```
+proulr-rosetta/
+  src/
+    locales/           # JSON por locale/domínio
+    catalog.ts         # merge + getMessage (gerado em parte via locale:generate)
+    locale-types.ts    # ProulrLocale (gerado via locale:generate)
+    translate.ts       # t / tFormat
+    resolve-locale.ts  # query / pref / system tags
+    domains.ts
+    index.ts
+  scripts/
+    add-locale.mjs
+    generate-locale-wiring.mjs
+    check-locale-coverage.mjs
+    validate-locales.mjs
+  .husky/pre-commit
+  docs/ROSETTA.md      # este guia
+  README.md            # resumo + link
+```

package/docs/npm-publish-cicd.md

@@ -0,0 +1,50 @@
+# Publicação automática no npm (CI/CD)
+
+`@proulr/rosetta` publica no npm quando há push em `main` — mesmo fluxo de `@proulr/sdui-contract` e `@proulr/bff-core`.
+
+## Fluxo
+
+1. Altere o código da lib.
+2. **Suba a versão** em `package.json` (ex.: `0.1.1` → `0.1.2`).
+3. Rode `npm install` se mudou dependências (atualiza `package-lock.json`).
+4. Commit, merge e push em `main`.
+5. O workflow `.github/workflows/publish-npm.yml` roda typecheck e publica se a versão ainda não existir no npm.
+
+Se a versão já estiver publicada, o job **pula** o publish (CI verde, sem erro).
+
+## Autenticação no npm
+
+### Bootstrap (1ª publicação do pacote)
+
+OIDC/Trusted Publishing **só funciona depois que o pacote existe** no npm. Igual ao bootstrap de contract/core:
+
+1. Crie um token **Automation** em https://www.npmjs.com/settings/~/tokens (ou reutilize o dos outros `@proulr/*`)
+2. No GitHub:
+
+```bash
+gh secret set NPM_TOKEN -R saviorbp/proulr-rosetta
+```
+
+3. Push / re-run do workflow → cria `@proulr/rosetta` no registry
+
+### Trusted Publishing (depois do bootstrap — modo steady-state)
+
+1. https://www.npmjs.com/package/@proulr/rosetta → **Settings** → **Trusted Publisher** → **GitHub Actions**
+2. Preencha:
+
+| Campo | Valor |
+| --- | --- |
+| Organization or user | `saviorbp` |
+| Repository | `proulr-rosetta` |
+| Workflow filename | `publish-npm.yml` |
+| Environment | *(vazio)* |
+
+O workflow já tem `id-token: write`. Com Trusted Publisher configurado, o publish usa OIDC (o `NPM_TOKEN` fica só como fallback).
+
+**Repositório privado no GitHub:** sem `--provenance`.
+
+## Consumidores (app / BFFs)
+
+```bash
+npm install @proulr/rosetta@^0.1.2
+```

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@proulr/rosetta",
+  "version": "0.1.2",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "docs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saviorbp/proulr-rosetta.git"
+  },
+  "scripts": {
+    "prepare": "husky",
+    "locale:add": "node ./scripts/add-locale.mjs",
+    "locale:generate": "node ./scripts/generate-locale-wiring.mjs",
+    "check:locales": "node ./scripts/check-locale-coverage.mjs",
+    "check:locales:strict": "node ./scripts/check-locale-coverage.mjs --strict",
+    "validate:locales": "node ./scripts/validate-locales.mjs",
+    "validate:locales:strict": "node ./scripts/validate-locales.mjs --strict",
+    "typecheck": "npm run locale:generate && npm run validate:locales && tsc --noEmit",
+    "prepublishOnly": "npm run typecheck",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "version:sync": "node ../scripts/proulr-bump-and-sync-deps.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@types/node": "^22.20.0",
+    "eslint": "^9.0.0",
+    "globals": "^16.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.61.1"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/src/catalog.ts

@@ -0,0 +1,42 @@
+import type { ProulrLocale } from './locale-types';
+import { DEFAULT_PROULR_LOCALE } from './locale-types';
+import { ROSETTA_DOMAINS } from './domains';
+import {
+  MESSAGES_BY_LOCALE,
+  PT_BR_MESSAGES,
+  type FlatMessages,
+  type ProulrMessageKey,
+  EN_MESSAGES,
+} from './generated/locale-messages';
+
+export { PT_BR_MESSAGES, type ProulrMessageKey };
+
+/**
+ * Legacy nested shape (key → locale → string). Prefer `t(key, locale)`.
+ */
+export const PROULR_LOCALE_CATALOG = Object.fromEntries(
+  (Object.keys(PT_BR_MESSAGES) as ProulrMessageKey[]).map((key) => [
+    key,
+    {
+      'pt-BR': PT_BR_MESSAGES[key],
+      'en': EN_MESSAGES[key] ?? PT_BR_MESSAGES[key],
+    },
+  ]),
+) as {
+  [K in ProulrMessageKey]: Record<ProulrLocale, string>;
+};
+
+export function getLocaleMessages(locale: ProulrLocale): FlatMessages {
+  return MESSAGES_BY_LOCALE[locale] ?? MESSAGES_BY_LOCALE[DEFAULT_PROULR_LOCALE];
+}
+
+export function getMessage(
+  key: ProulrMessageKey,
+  locale: ProulrLocale = DEFAULT_PROULR_LOCALE,
+): string {
+  const primary = getLocaleMessages(locale)[key];
+  if (typeof primary === 'string' && primary.length > 0) return primary;
+  return PT_BR_MESSAGES[key] ?? key;
+}
+
+export { ROSETTA_DOMAINS };

package/src/domains.ts

@@ -0,0 +1,18 @@
+/**
+ * Domain catalog files under `src/locales/<locale>/<domain>.json`.
+ * `pt-BR` is the source of truth for message keys.
+ */
+export const ROSETTA_DOMAINS = [
+  'common',
+  'shell',
+  'discover',
+  'chat',
+  'flash',
+  'profile',
+  'social',
+  'auth',
+  'alerts',
+  'hybrid',
+] as const;
+
+export type RosettaDomain = (typeof ROSETTA_DOMAINS)[number];