[paynejd]

Part of OpenConceptLab/ocl_issues#2878.

Adds a Localization guide, guides/localization.html (a static page under public/). It came out of the pt-BR translation review in OpenConceptLab/oclweb3#60 and OpenConceptLab/oclmap#90:

• Rules for developers so translated text still reads correctly once the code assembles it: one key per sentence, translated labels instead of raw API values, no gendered word next to an interpolated noun, escapeValue in oclweb3, shared keys kept identical.
• Rules for translators: how to decide on OCL resource names (pt-BR keeps "Source", translates Coleção / Organização / Repositório), a never-translate list, and naming for the OCL AI Assistant.
• Glossary of canonical OCL terms in es, zh and pt-BR, with values taken from the app catalogs. Open items are marked with their owner: the pt-BR lead (@filiperochalopes) for Portuguese terms, OCL for feature names such as Auto Match.

Also links the guide from the overview, the README and the Building Pages i18n section. That section's language list was out of date; it now includes pt-BR and notes zh isn't in the menu.

Still to do under #2878: link the guide from the oclweb3 and oclmap i18n folders, and an optional catalog check. Both will come once the pt-BR PRs merge.

Verified: vite build passes, and the page renders correctly (checked in headless Chrome).

🤖 Generated with Claude Code

[paynejd]

Codex adversarial review, pass 1 (codex-cli 0.160.0, commit 8b27212). All five findings were addressed in 3d3c95d.

Findings

• public/guides/localization.html:108,112,117,124,127 — Catalog capitalization differs. Use pt-BR Classe do Conceito, Não Publicado, URL Canônica, and Repositório de Destino; Spanish Algoritmo de Coincidencia and Repositorio Objetivo. These are the corresponding catalog labels. Confidence: high.

• public/guides/localization.html:115,117,119,120 — Several dashes incorrectly imply missing translations. Locale has Spanish Idioma in oclweb3 and Configuración regional in oclmap. Canonical URL has Spanish URL canónica and Chinese 规范型 URL (also 规范 URL for the Mapper algorithm label). Mapper Delete has Eliminar / 删除. Collection Include has Chinese 包含; common.exclude has 排除, although reference.exclude is missing. Fix: identify app/key differences explicitly instead of using blanket dashes. Confidence: high.

• public/guides/localization.html:122,123,126,128,130,131 — Some purported catalog values are inferred terms, not complete catalog strings. Spanish/pt-BR singular Mapping project and Candidate, Spanish/Chinese standalone Match, all standalone Quota/Allowance values, and bare Bridge do not occur as exact catalog values. For example, the catalogs contain Proyectos de Mapeo, Candidatos, and Bridge:; Chinese bridge_canonical_short is 桥接：. Fix: distinguish extracted/proposed terminology from verbatim catalog labels and cite the source keys. Confidence: high.

• public/guides/localization.html:89 — “OCL never says ‘AI recommendations’” contradicts existing copy. Mapper’s preview_estimate_ai_all and preview_estimate_ai_partial explicitly use “AI recommendations”; pt-BR preview_quota_ai_calls also uses Chamadas do Assistente de IA without OCL. Fix: describe this as the intended naming rule and flag existing exceptions. Confidence: high.

• public/guides/localization.html:130 — Quota is defined too narrowly. The apps also implement one-time preview quotas (quota.period_one_time, preview_quota_tooltip_title). Fix: say an allowance can be recurring or one-time. Confidence: high.

Checked and fine

• Compared both apps’ English/Spanish/Chinese catalogs at origin/main and pt-BR at HEAD; remaining glossary labels match, with HEAD appropriately treated as a literal identifier.
• Escape configuration claim is correct; English fallback and the Chinese catalog/menu distinction are correct.
• New relative links and guide assets resolve correctly beneath /ocl-design-system/; README’s source link is valid.
• All 13 JSX page entries compiled and bundled in memory with zero errors. git diff --check passed. Full Vite build was not run because it writes files.
• No secrets or obvious sensitive information found. No files modified.

[paynejd]

Codex adversarial review, pass 2 (codex-cli 0.160.0, commit 3d3c95d). Clean.

Reviewed 3d3c95d and the full page against both apps’ catalogs: en/es/zh at origin/main, pt-BR at HEAD.

Pass-1 finding	Status
Catalog capitalization differs	RESOLVED — glossary now explicitly normalizes terms to sentence case.
Dashes incorrectly imply missing translations	RESOLVED — missing values filled; Spanish Locale and Chinese Canonical URL differences documented.
Inferred terms presented as exact catalog strings	RESOLVED — introduction identifies entries as normalized base terms rather than verbatim labels.
AI naming rule contradicts existing copy	RESOLVED — existing Mapper exceptions explicitly acknowledged.
Quota defined too narrowly	RESOLVED — definition now includes one-time allowances.

NEW findings: None.

No files modified.