# pt-BR Localization Pilot Report — Session 2 (2026-07-21) — DOC-6061

Follows the bootstrap session (DOC-6060 / `BOOTSTRAP-REPORT.md`). This session **translates
content**. Branch: `l10n/pt-br/pilot`, based on `l10n/pt-br/bootstrap` (stacked PoC; neither
merges to the default branch `main-enterprise-product-docs`). Source ref at translation
time: `3dc80784c`. English source is unmodified.

## 1. Outcome summary

- **4 of 5 pilot files translated** (Markdown-only pilot). The API-reference `.yml` was
**deferred** after the Phase 2 gating check (see §2).
- Manifest updated (5 files / 69 sections; 4 marked translated, 1 deferred); drift check
**green**.
- `translations.yaml`: ~23 chrome keys corrected pt-PT → pt-BR.
- Config: `redocly.yaml` `l10n` block (preview only) + `.vale.ini` `@l10n/**` exclusion.
- `tm.jsonl` untouched (TM is harvested from approved segments, not drafts).
- One bundled **draft** MR (kept in draft; not for merge).


## 2. Phase 2 — mirrored-OpenAPI render check (GATING): FELL BACK to Markdown-only

**Result: could not verify locally; the mirror is NOT the cause. Fell back to Markdown-only
per owner decision.**

What happened:

- Created the mirrored spec byte-for-byte with only `info.description` translated; it linted
clean in `@redocly/cli` and was valid YAML (only lines 9–47 differed; 6,449 lines total).
- `npx @redocly/cli preview` **crashed** during OAS loading:
`Error in "load-oas" loader: "undefined" is not valid JSON` — no server ever started.
- **Controlled baseline test:** stashed ALL pilot changes (clean bootstrap tree — no `l10n`
block, no mirrored spec) and re-ran preview. It crashes **identically**. So the failure is
**pre-existing on the English build in this local environment and is not caused by the
mirror**.
- Root cause: the spec's `info.description` contains a `{% $env.PUBLIC_VAR_RPD %}` Markdoc
tag (1 occurrence). The local preview's OAS menu-builder (`@redocly/openapi-docs` →
`Markdoc.fromJSON`) can't resolve `$env` in a spec description, serializes it to
`"undefined"`, and `JSON.parse` throws — taking down the whole preview server. Loading the
`.env.*` vars did not help (crash still ~3s in). Hosted Reunite tolerates this via
`reunite.ignoreMarkdocErrors: true`; the local NPX preview's OAS loader does not honor it.


Decision (owner, this session): **remove the mirrored spec, ship the 4 Markdown pages only,
defer the API-reference file to a later session.** The spec remains listed in
`.l10n-sync/scope.json` (in scope, `translated: false` in the manifest); the target
directory keeps its `.gitkeep` skeleton.

**For Redocly support (flagged):** local `@redocly/cli preview` (realm 0.133.1) fails to
load any OpenAPI definition whose `description` contains a `{% $env %}` Markdoc tag, in
English or pt-BR; `ignoreMarkdocErrors` is not honored by the local OAS loader. Mirrored-OAS
localization rendering must be validated on the **Reunite MR preview** instead.

## 3. Per-file translation notes

| Source (`@v2026.03/`) | Words | Sections | Notes |
|  --- | --- | --- | --- |
| `introduction/concepts/payment-identities.md` | 4,036 | 36/36 | Terminology-stress page; extra-care review. Structural parity verified (34 headings, 12 tables, 4 admonitions, 6 code fences, 1 `$env`). 1 same-page fragment rewritten. |
| `api-docs/developer-guides/create-a-payment.md` | 2,045 | 25/25 | Parity verified (23 headings, 24 fences, 14 Markdoc tags, 3 `$env`). Code blocks byte-identical except 2 explanatory comments translated. 1 cross-page fragment to out-of-scope `quotes.md` kept English. |
| `api-docs/integration-resources/latam/br.md` | 41 | 3/3 | Corridor landing. `title` + `description` front matter translated. |
| `api-docs/integration-resources/latam/br/brl.md` | 139 | 4/4 | BRL data requirements; purpose-code enum table. 1 same-page fragment rewritten. Enum values/types kept. |
| `api-docs/payments-direct-api/payments-direct-2-api.yml` | — | — | **Deferred** (Phase 2). Not translated this session. |


Rules applied per CLAUDE.md §4/§5/§10: code identifiers, enum values, field/property names,
types, HTTP status codes, example values, code blocks, and `{% $env.PUBLIC_VAR_* %}` vars
preserved byte-for-byte; prose/headings/table-cell prose/admonition text/front-matter
`title`+`description` translated; `você` register, gerunds, pt-BR spellings, requisição/
resposta, and DNT terms honored; prose numbers localized (`10,000 USD` → `10.000 USD`), wire
values in samples untouched.

### Anchor policy (§5.3)

- Same-page fragments rewritten to translated-heading slugs:
`#validating-identities-for-specific-payout-rails` →
`#validando-identidades-para-trilhos-de-pagamento-específicos` (payment-identities.md);
`#purpose-of-payment-codes` → `#códigos-de-finalidade-do-pagamento` (brl.md).
- Cross-page fragment to the **untranslated** `quotes.md` (`#funding-model-payincategory`)
kept in English — its target renders English via fallback with English slugs.
- **Open risk:** the two rewritten slugs contain accents. Realm's auto-slugger accent
behavior could not be verified locally (preview unavailable, §2). **Verify these two
fragments resolve in the Reunite preview.** (The sync pipeline's fragment-link check
should also catch mismatches.)


## 4. Terminology decisions worth promoting to the termbase

Harvested mostly from `payment-identities.md`. All Seed status, pending native-reviewer
promotion. Full list in the MR (§7). Highlights / precedent-setting:

- **payout rail → trilho de pagamento** (precedent; alt: keep "rails" in EN, or "meios de
pagamento"). High frequency.
- **first-party / third-party → primeira parte / (de) terceiros** (precedent; alt: "em nome
próprio / em nome de terceiros").
- **PII → informações de identificação pessoal (PII)** (acronym kept).
- **payment identity → identidade de pagamento**; **financial instrument → instrumento
financeiro**; **quote collection → coleção de cotações**; **natural persons → pessoas
físicas**.
- Kept in English as established BR dev usage: `schema` (in "versão do schema"), `timestamp`,
`upstream`, `tenant`, plus DNT terms (Pix, CPF/CNPJ, endpoint, webhook, sandbox, etc.).
- Reaffirmed existing termbase pairs: originator → ordenante; cross-border payment →
pagamento internacional; purpose of payment → finalidade do pagamento; quote → cotação.


## 5. Cross-cutting translation decisions (reviewer confirmation requested)

1. **Markdoc visible-title attributes translated.** Admonition `name=` and tab `label=`
values that render as visible titles were translated (e.g. `name="O que verificar"`,
`label="Pagamento de primeira parte"`), while product/feature names were kept
(`name="Identity Management v3"`). Structural attributes (`type=`, `width=`) untouched.
2. **Link text to out-of-scope (untranslated) pages kept in English** to match the
English-fallback destination titles: Payout network, Financial instruments, Create and
manage identities, Funding model, Error handling, Create and manage financial instruments.
3. **`compliance` kept in English** (vs. `conformidade`) — house-style call.
4. **`schema` kept in English** in prose (vs. `esquema`, which the generated chrome uses) —
note the inconsistency for a house-style decision.


## 6. English-screenshot gap log

**None.** None of the four pilot pages reference any image (`![...]`, `images/`, `img`).
0 localization image gaps this session. (The 52 English UI screenshots noted at bootstrap
live under `user-interface/` pages, which are out of the pilot set.)

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

Newly found this session:

1. `introduction/concepts/payment-identities.md:22` — "instead of **of** embedding" (duplicated word).
2. `introduction/concepts/payment-identities.md:119` — admonition `name="Identities & financial istruments"` — typo "istruments" → "instruments".
3. `api-docs/developer-guides/create-a-payment.md:176` — "Key **requirede** fields" (typo).
4. `api-docs/developer-guides/create-a-payment.md:390` — "Endpoint" line is not an `###` heading, unlike the other steps (inconsistent structure).
5. `api-docs/developer-guides/create-a-payment.md:470` — stray tab-indented "3." breaks the numbered list in "Summary and next steps".
6. `ci/vale/styles/Ripple/MeaningfulLinkWords.yml:10` — `scope: link` is unsupported in the installed Vale 3.15.1 (`E201`); Vale cannot load the Ripple style locally. (Affects local linting only; separate from the pt-BR exclusion.)


Referenced from bootstrap (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`.

## 8. Config status

- `redocly.yaml`: `l10n` block added (en + pt-BR). **Preview only** — branch does not merge,
so no production locale enablement here. If promoted, enablement needs its staging
treatment (bootstrap §4.4 / CLAUDE.md §7.2) as its own change.
- `.vale.ini`: `[@l10n/**]` section with empty `BasedOnStyles` added. Verified by inspection
only (local Vale can't run — defect §7.6); takes effect where Vale runs (Reunite).
- `manifest.json`: regenerated; drift check `--check` green.


## 9. Remaining open steps / human calls

1. **Confirm native reviewers** (Tiago Leite, Luis Pain) — still pending; MR left unassigned.
2. **Mirrored-OAS rendering** — verify on the Reunite MR preview; pursue the Redocly-support
item (§2) before re-attempting the API-reference file in a later session.
3. **Fragment-slug accents** — verify the two rewritten same-page anchors resolve in the
Reunite preview (§3).
4. **TM-harvest trigger redefinition** — TM is defined as post-merge harvest, but this PoC
branch will not merge. The trigger must be redefined to key off **reviewer approval on the
draft branch** instead. Flagged only; harvesting logic unchanged this session.
5. **Terminology sign-off** — promote the proposed pairs (esp. payout rail, first-party/
third-party, PII) from Seed after native review; harvest approved pairs into the termbase.
6. **Chrome sweep completeness** — only doc-rendering chrome families were corrected;
`catalog.*` (marketplace) and `asyncapi.*` (unused API type) pt-PT defaults remain, to be
handled in a dedicated chrome pass with reviewer input.