# Draft: l10n(pt-BR): pilot translation — Payments Direct 2.0 (@v2026.03) [DOC-6061]

## 1. What this is

Proof-of-concept pilot for the semi-automatic pt-BR localization pipeline for Ripple
Payments Direct 2.0 documentation (`@v2026.03`). This MR is a **draft** and is **not
intended to merge**. It exists to demonstrate the internal translation system end to end
and to route the pilot pages through native review. Future sessions branch off
`l10n/pt-br/pilot` rather than off a merge, so the branch is kept self-contained
(scaffolding, termbase, manifest, chrome overrides, and translations all present).

- Branch: `l10n/pt-br/pilot` (based on `l10n/pt-br/bootstrap`; neither merges to default).
- Jira: DOC-6061 (epic DOC-6059). Config lives here rather than in DOC-6062 per the bundle
decision.
- Reviewers: Tiago Leite and Luis Pain (pending confirmation). `payment-identities.md`
needs the extra-care terminology pass.
- English source is unmodified. Source defects are reported below, not fixed.


## 2. Scope of this MR

- Five pilot pages translated into `@l10n/pt-BR/products/payments-direct-2/@v2026.03/`.
- `@l10n/pt-BR/translations.yaml` chrome-key overrides (pt-PT defaults corrected to pt-BR).
- `.l10n-sync/manifest.json` updated with translation-time source-section hashes.
- Config: `.vale.ini` exclusion and the `redocly.yaml` `l10n` block (preview only).
- Not in this MR: sidebar labels (docs-team dependency), any out-of-scope product, any
`@v2025.11` / `@v2026.04` content, TM entries.


## 3. Files changed (CLAUDE.md §3: source files / sections changed)

| Source path (`@v2026.03/`) | Type | Sections translated | Screenshots referenced | Notes |
|  --- | --- | --- | --- | --- |
| `introduction/concepts/payment-identities.md` | conceptual (terminology stress) | `<fill: N/total>` | `<fill: count>` | Precedent-setter; extra review |
| `api-docs/developer-guides/create-a-payment.md` | developer guide | `<fill: N/total>` | `<fill: count>` |  |
| `api-docs/payments-direct-api/payments-direct-2-api.yml` | API reference (subset) | `info.description` + auth section + operation summaries | n/a | Only if Phase 2 render check passed (see §5) |
| `api-docs/integration-resources/latam/br.md` | Brazil corridor | `<fill: N/total>` | `<fill: count>` | Small page |
| `api-docs/integration-resources/latam/br/brl.md` | Brazil corridor | `<fill: N/total>` | `<fill: count>` | Small page |


Config and pipeline files also changed:

- `@l10n/pt-BR/translations.yaml`: `<fill: N>` chrome keys overridden to pt-BR.
- `.l10n-sync/manifest.json`: `<fill: N>` files, `<fill: N>` hashed sections recorded.
- `.vale.ini`, `redocly.yaml` (see §11).


> Confirm the exact on-disk paths from `.l10n-sync/scope.json`; correct the table if any
differ.


## 4. English source reference (CLAUDE.md §3: the English diff or link)

English is unchanged by this MR. The pt-BR files mirror these source paths at ref
`<fill: source commit SHA / branch>`:

- `<fill: link to each source file at that ref, or a single tree link>`


## 5. Mirrored-OpenAPI render check (Phase 2, gating)

Result: `<fill: RENDERED | FELL BACK TO MARKDOWN-ONLY>`

- If RENDERED: the mirrored `.yml` renders localized reference pages at the pt-br
versionless URL; the scoped subset was translated in full.
- If FELL BACK: the mirrored spec did not render localized; the `.yml` was removed from
this MR, the API-reference file is deferred, and a limitation note was filed for Redocly
support. Details: `<fill: what was observed>`.


Preview evidence: `<fill: preview URL(s) and/or screenshots>`.

## 6. Structural preservation (CLAUDE.md §5) — confirm each

- [ ] Heading hierarchy and section count preserved per page.
- [ ] Markdoc tags left in place, names/attributes untranslated.
- [ ] Code blocks byte-for-byte except explanatory comments.
- [ ] Front matter keys unchanged and in the same order; only `title` / `description`
values translated.
- [ ] `{% $env.PUBLIC_VAR_... %}` product-name variables preserved byte-for-byte.
- [ ] Do-Not-Translate terms untouched; wire-format literals in samples not reformatted.
- [ ] `#fragment` links inside pt-BR copies rewritten to translated slugs (anchor policy
§5.3); no dangling fragments remain. Rewritten links: `<fill: count>`.


## 7. Terminology and termbase (CLAUDE.md §3: new termbase entries proposed)

Proposed new entries, harvested mostly from `payment-identities.md`. All Seed status,
pending native-reviewer promotion.

| EN | pt-BR | Domain | First seen (page) | Rationale / ambiguity note | Status |
|  --- | --- | --- | --- | --- | --- |
| `<fill>` | `<fill>` | `<fill>` | `<fill>` | `<fill>` | Seed |


Termbase conflicts or ambiguity-trap calls made this session (saldo/balanço,
tarifa/imposto/taxa, reembolso/estorno, "chave", "token", etc.):

- `<fill: term / decision made / where / why>`


## 8. Reviewer attention items (CLAUDE.md §3)

Call out anything ambiguous or precedent-setting, especially from the terminology-stress
page. Keep each item actionable.

- **`payment-identities.md`:** `<fill: specific terms / phrasings needing a native call>`
- `<fill: other items, page by page>`


## 9. English-screenshot gap log (CLAUDE.md §5.5)

Every English-text image referenced by a translated page, logged as a localization gap
(images not edited).

| Page | Image path | What it shows | Note |
|  --- | --- | --- | --- |
| `<fill>` | `<fill>` | `<fill>` | English UI; localization gap |


Total gaps logged: `<fill: count>`.

## 10. Source defects found (CLAUDE.md §9 — reported, not fixed)

Already reported at bootstrap (BOOTSTRAP-REPORT.md §5), referenced for context, not
re-filed: hardcoded strings in the 9 Direct2 landing components; sidebar labels not
localizable (no `labelTranslationKey`); stale `redocly.yaml` ignore entries; dead
`partialsFolders` entry; empty legacy `api-docs/` tree; stock `.gitlab-ci.yml`.

Newly found during translation:

| Defect | Location | Impact on l10n | Suggested owner |
|  --- | --- | --- | --- |
| `<fill or "none">` | `<fill>` | `<fill>` | docs team |


## 11. Config changes (preview only; do not enable in production here)

**`.vale.ini`**: exclude mirrored pt-BR content so English rulesets do not flood:

```ini
[@l10n/**]
BasedOnStyles =
```

**`redocly.yaml`**: `l10n` block so the preview renders pt-BR. Present for preview only;
because this branch will not merge, production locale enablement does not happen here and
would need its staging treatment (implementation plan §7.2 / bootstrap §4.4) as its own
change if this PoC is later promoted:

```yaml
l10n:
  defaultLocale: en
  locales:
    - code: en
      name: English
    - code: pt-BR
      name: Português (Brasil)
```

Portal-wide-picker note: once `pt-BR` is enabled in production, the language picker appears
on all products and out-of-scope content falls back to English. Sign-off happens in
preview per the staging decision. No picker suppression (bootstrap §4.4).

## 12. Translation memory

`tm.jsonl` is unchanged this session; TM is harvested from approved segments, not drafts.
Open item: because this PoC branch will not merge, the harvest trigger (currently defined
as post-merge) needs redefining to key off reviewer approval on the draft branch. Flagged
for the decision log (DOC-6065); logic unchanged for now.

## 13. Pipeline / manifest

- `manifest.json` updated: `<fill: N>` files, `<fill: N>` sections, source hashes at
translation time.
- Drift check `generate-manifest.mjs --check`: `<fill: green on fresh set | details>`.


## 14. Review gate

Native pt-BR review required before this could ever be considered for merge. Do not
self-approve, mark ready, merge, or resolve discussions. Route to Tiago Leite and Luis
Pain once confirmed; unassigned until then.

Reviewer checklist:

- [ ] Terminology on `payment-identities.md` is correct and precedent-worthy.
- [ ] Register and variant are pt-BR (você, gerunds, no pt-PT surface forms).
- [ ] Do-Not-Translate terms and wire formats untouched.
- [ ] Chrome overrides read pt-BR (e.g. "Baixar", "aba").
- [ ] Proposed termbase entries approved or amended (promote from Seed).


## 15. Open items and human calls

1. Confirm native reviewers (Tiago Leite, Luis Pain).
2. Mirrored-OpenAPI render outcome and any Redocly-support follow-up (§5).
3. TM-harvest trigger redefinition for a non-merging PoC (§12).
4. `<fill: anything else surfaced this session>`