# pt-BR Localization Bootstrap Report — Session 1 (2026-07-21)

Scope: `products/payments-direct-2/@v2026.03/` → `@l10n/pt-BR/` mirror.
Branch: `l10n/pt-br/bootstrap`. No content translated in this session by design.

## 1. Environment

- Tooling: git 2.50.1, node v22.21.0, yarn 1.22.22, @redocly/cli 2.31.6, vale 3.15.1,
glab 1.109.0 (authenticated to gitlab.com).
- Termbase imported to `.l10n-sync/termbase/` (xlsx = source of record): 153 term
pairs, 26 Do-Not-Translate entries, 22 idiom traps, 18 sources. CSVs are generated
by `termbase/export_csv.py` (openpyxl).


## 2. l10n × versioning mechanics — VERIFIED

Empirically confirmed with a local preview build (throwaway branch, since discarded):

- **Mirror convention holds:** `@l10n/pt-BR/products/payments-direct-2/@v2026.03/<page>.md`
renders in Portuguese. Repo-root `@l10n/<locale>/` mirrors the full source path
**including the `@v` version folder**.
- Locale codes are lowercased in URLs: `/pt-br/...` (uppercase 404s).
- The default version (v2026.03) serves at the **versionless** URL in both locales;
non-default versions serve at `/products/payments-direct-2/v2025.11/...` (no `@`).
- Untranslated pages fall back to English at the pt-br URL — no 404s.
- **Version isolation:** the translated @v2026.03 file does not leak into
`/pt-br/.../v2025.11/...`.
- The language picker ("Português (Brasil)") appears **portal-wide** the moment the
`l10n` block is added — confirming the staging concern in CLAUDE.md §7.2.
- Consistency check: `products/payments-direct-2/versions.yaml` designates
**v2026.03 as default**; `@v2026.04` is config-ignored pending Quotes V3
(mid-August target). Matches the confirmed program status.


## 3. Inventory (in scope: @v2026.03 + dependencies)

- **142 Markdown pages, ~87,400 words.** api-docs 92 (integration-resources 72:
apac 25, emea 20, latam 12, na 4, digital-assets 3, top-level 8; developer-guides 8;
error-handling 4; payment-monitoring 3; get-started 3; getting-started 1),
user-interface 28, introduction 20, root 2 (`index.md`, `change-history.md`).
- The payments-direct-2 entries in the root `redocly.yaml` ignore list are stale
v2025.11 paths — none exist in @v2026.03; no exclusions apply.
- **Markdoc:** `table` ×462, `admonition` ×386, `width` ×381, `tab`/`tabs` ×80,
`raw-partial` ×5, 9 landing-component tags (one each), `bankCodes` ×1. Product
names via `{% $env.PUBLIC_VAR_RPD/RP/RNH/RNAPI %}` (×156, defined in `.env.*`) —
preserve byte-for-byte.
- **Partials (exact inclusion set, all via `raw-partial` in user-interface pages):**
`partials/login.md` (×2 incl.), `partials/support.md`, `partials/users.md`,
`partials/switch-organizations.md`. The `products/payments-direct-2/partials`
entry in `partialsFolders` does not exist on disk.
- **Front matter:** 103/142 pages; renderable keys = `title` (101), `description`
(71). `toc`/`tocMaxDepth`/`excludeFromSearch` are config.
- **Anchors/links:** 85 internal `#fragment` links, all against auto-generated slugs
(0 explicit anchor IDs). No cross-product links, no absolute docs.ripple.com links.
- **Landing/React surface:** 9 components serve in-scope routes
(PaymentsDirect2Landing3; Direct2 Concepts/PayoutNetwork/Features/UserGuides/
IntegrationResources/Monitor/DeveloperGuides Landing3-or-4;
Direct2CombinedDataRequirementsPicker). **All hardcoded English JSX, zero
translation keys** → source defect (see §5). Sidebar: 74 labels + 47 groups +
3 separators, inline English with no `labelTranslationKey` entries → also a
docs-team dependency (see §5.2).
- **API reference:** binds to in-version, git-tracked
`api-docs/payments-direct-api/payments-direct-2-api.yml` (6,449 lines, 675
`description:` fields). **Hand-maintained, not generated** (no generator markers;
targeted human edits in git history between bulk release imports). Root
`api-docs/payments-direct-api/dist/` is an empty ignored husk. → Hand-translate
the mirrored copy; bulk spec refreshes surface as stale manifest sections.
- **Hazards:** 56 unique images referenced (52 = English UI screenshots under
`images/ripplenet-home/`) — logged as gaps per page when translated; all image
refs carry translatable alt text; corridor pages are enum/wire-format heavy
(code, untouched).
- **CI:** `.gitlab-ci.yml` is the stock GitLab starter template (echo jobs only) —
no Vale/docs jobs in GitLab CI today; builds evidently run via Redocly Reunite.
`.vale.ini` lints `*.{md,mdx,tsx,txt}` with English rulesets and no path filter —
exclusion needed before pt-BR content lands (proposed diff in §6).


## 4. Decisions made (2026-07-21, recorded in CLAUDE.md)

1. **Anchor policy (§5.3):** translate headings; rewrite `#fragment` links inside
pt-BR copies to translated slugs; add a fragment-link check to the sync task.
2. **Pilot set (§12):** `introduction/concepts/payment-identities.md`;
`api-docs/developer-guides/create-a-payment.md`; mirrored
`payments-direct-2-api.yml` (info.description + auth section + operation
summaries); `latam/br.md`; `latam/br/brl.md`. Corridor pages proved tiny
(41/139 words); payment-identities.md carries the Brazil-terminology stress.
3. **Landing pages (§6): IN pilot scope as a docs-team dependency** — blocked until
the docs team adds translation keys to the 9 hardcoded components (defect
reported); keys will be translated in `@l10n/pt-BR/translations.yaml` when they
exist; English fallback meanwhile.
4. **Staging (§7.2):** preview-first; l10n block merges only after pilot approval and
preview sign-off; production enablement as its own small MR; **no picker
suppression** (high-maintenance theme override; pt-br URLs reachable regardless).


## 5. Source defects reported (not fixed — docs team's call)

1. **Hardcoded strings in all 9 Direct2/PaymentsDirect2 landing components**
(`@theme/markdoc/pages/...`): no `useTranslate`/translation-key usage anywhere;
e.g. `PaymentsDirect2Landing3.tsx:49` `header="Payments Direct Documentation"`,
`Direct2CombinedDataRequirementsPicker.tsx:714` `placeholder="Select Type"`.
Blocks landing-page localization (pilot dependency — decision §4.3).
2. **Sidebar labels not localizable:** `@v2026.03/sidebars.yaml` (74 labels, 47
groups, 3 separators) has no `labelTranslationKey` entries, and Realm's translate
command only collects `*TranslationKey` keys. Docs team must add
`labelTranslationKey` entries to the English sidebars.yaml for sidebar l10n.
3. **Stale ignore entries** in root `redocly.yaml` for payments-direct-2 (version-less
paths that no longer exist in @v2026.03, e.g.
`/products/payments-direct-2/api-docs/tutorials/...`).
4. **Dead `partialsFolders` entry** `./products/payments-direct-2/partials` (folder
absent).
5. **Empty legacy tree** root `api-docs/` (`payments-direct-api/dist/`, `examples/`,
`non-orchestration/` all empty; whole tree config-ignored) — candidate for removal.
6. `.gitlab-ci.yml` is the unmodified GitLab sample template (echo jobs) — runs no
real checks on any MR.


## 6. Scaffolding delivered on `l10n/pt-br/bootstrap`

- `@l10n/pt-BR/products/payments-direct-2/@v2026.03/` skeleton dirs for the pilot set
(`.gitkeep` placeholders only — no translated files, per session constraints).
- `.l10n-sync/`: `scope.json` (pilot file list), `generate-manifest.mjs`
(zero-dependency Node; `--check` = drift check), `manifest.json` (5 files,
69 hashed sections), `tm.jsonl` (empty, append-only), `termbase/` (xlsx + 3 CSVs +
exporter), `README.md` (pipeline doc + CI drift-check snippet), this report.
- `@l10n/pt-BR/translations.yaml` generated via `realm translate pt-BR` (441 keys).
Findings from generation:
  - The CLI **prompts interactively** ("Continue?") — pipe `echo y |` in automation
(the un-piped run hangs forever with zero output).
  - The generated values are Redocly's **built-in Portuguese chrome defaults and look
pt-PT, not pt-BR** ("Transferir descrição", "Abrir em novo separador" — pt-BR
would be "Baixar", "aba"). These keys must be reviewed/overridden in the pilot,
per the CLAUDE.md rule that pt-PT is never a reference.
  - The command collects only `*TranslationKey` entries from config/sidebars plus
built-in defaults. `@v2026.03/sidebars.yaml` has **zero `labelTranslationKey`
entries**, so **no sidebar labels are currently localizable** — adding
`labelTranslationKey` to the English sidebars.yaml is a **docs-team dependency**
(same class as the landing-component defect; added to §5).
- **Proposed diff — `redocly.yaml` (NOT applied; needs approval + staging per §4.4):**

```yaml
# add at top level:
l10n:
  defaultLocale: en
  locales:
    - code: en
      name: English
    - code: pt-BR
      name: Português (Brasil)
```
- **Proposed diff — `.vale.ini` (NOT applied; touches shared lint config):**

```ini
# add below the Packages line:
[@l10n/**]
BasedOnStyles =
```
(Empty style set disables the English rulesets for all mirrored pt-BR content.
A pt-BR-specific minimal ruleset can replace this later if wanted.)


## 7. Risks / watch items

- **OpenAPI mirror rendering:** the pilot must verify a mirrored `.yml` actually
renders localized reference pages (Realm docs are thin here — same class of risk
as the now-verified page mirroring). If it does not, fall back to translating
only the Markdown pages and flag the reference for Redocly support.
- **Vale:** any Reunite-side Vale run will flood on pt-BR files until the `.vale.ini`
exclusion merges. Land it before or with the first content MR.
- **Portal-wide picker:** once `pt-BR` is enabled in production, all products show
the picker; out-of-scope products get localized chrome + English content.
Stakeholder sign-off happens in preview (decision §4.4).
- **Landing-page dependency:** pilot completeness now depends on the docs team adding
translation keys to 9 React components (defect §5.1). Track in #tmp-brvasp.
- **glab:** authenticated; draft MRs can be opened from the CLI.
- **@v2026.04 carry-forward:** release delayed (Quotes V3, mid-August target). When
rescheduled, seed from TM + manifest (README §Version carry-forward); expect high
reuse. Do not start until instructed.
- **Reviewers:** Tiago Leite and Luis Pain proposed for this track — still pending
confirmation; route the pilot MR to them once confirmed.


## 8. Next session plan

1. Get approvals: `.vale.ini` exclusion MR (or bundle with pilot MR per reviewer
preference); confirm native reviewers.
2. Translate the 5-file pilot set (partials none required — pilot pages include no
raw-partials) following CLAUDE.md §4/§5/§10 and the termbase; fragment links per
anchor policy; log English-screenshot gaps per page.
3. Translate the sidebar/translation keys that render on Payments Direct 2.0 pages in
`@l10n/pt-BR/translations.yaml`.
4. Verify the mirrored OpenAPI spec renders localized (preview build) — the one
remaining mechanics unknown.
5. Open the pilot MR (per §3 template); after merge, harvest TM pairs and run the
demo: edit one English page → sync → targeted section-level MR.