From 8b272121dce6d56f689e58eb49d5642c3d158f8f Mon Sep 17 00:00:00 2001 From: Jonathan Payne Date: Mon, 5 Oct 2026 10:33:08 -0400 Subject: [PATCH 1/2] OpenConceptLab/ocl_issues#2878 | Localization guide: text-assembly rules and cross-language glossary of OCL terms Adds guides/localization.html (static page) with: - rules for developers so translated text still reads correctly once code assembles it - rules for translators (resource-name rule, never-translate list, OCL AI Assistant naming) - a glossary of canonical OCL terms in es, zh and pt-BR, pulled from the app catalogs, with open pt-BR decisions marked for the pt-BR translation lead Links it from the overview, the README and the Building Pages i18n section. Co-Authored-By: Claude Opus 5.5 --- README.md | 1 + index.html | 5 ++ public/guides/localization.html | 147 ++++++++++++++++++++++++++++++++ src/pages/BuildingPagesPage.jsx | 6 +- 4 files changed, 158 insertions(+), 1 deletion(-) create mode 100644 public/guides/localization.html diff --git a/README.md b/README.md index 1517c67..6e0ad0c 100644 --- a/README.md +++ b/README.md @@ -87,6 +87,7 @@ npm run preview # Preview the built site locally | [Typography](public/foundations/typography.html) | MUI type scale with Roboto specimens | | [Elevation](public/foundations/elevation.html) | Material 3 shadow levels | | [Logo](public/foundations/logo.html) | OCL logo variants and brand assets | +| [Localization](public/guides/localization.html) | Rules for assembling translated text; cross-language glossary of canonical OCL terms | | [Gallery](public/gallery.html) | 131 Zeplin screenshots browsable by section | | [Patterns](public/patterns/index.html) | Screen-level compositions (stubs) | diff --git a/index.html b/index.html index 553082a..0cf63c8 100644 --- a/index.html +++ b/index.html @@ -60,6 +60,11 @@

Building Pages

Developer guide to building new pages in oclweb3: page scaffold, routing, API patterns, i18n, shared utilities, and a worked example. Start here if you're building something new.

Guide · Routing · API · i18n · Utilities
+ +

Localization

+

How TBv3 and the Mapper say things in each language: rules for assembling translated text, and a glossary of canonical OCL terms (Source, Collection, Retired…) across languages.

+
Guide · i18n · Glossary · pt-BR · es · zh
+

Foundations

Color palette, typography, elevation, and the OCL logo — rendered live from the same tokens oclweb3 uses. Click a swatch to copy its hex.

diff --git a/public/guides/localization.html b/public/guides/localization.html new file mode 100644 index 0000000..4fe8d17 --- /dev/null +++ b/public/guides/localization.html @@ -0,0 +1,147 @@ + + + + + +Localization · Guides · OCL v3 Design System + + + + + + + +
+
+ OCL v3 Design System· Guides + +
+ Review + GitHub +
+
+
+ +
+
Overview · Guides · Localization
+

Localization

+

+ This page covers how the OCL web apps (TermBrowser v3 and the OCL Mapper) say things in each interface language. + It has two parts: rules for developers, so that translated text still reads correctly once the code assembles it, + and a glossary of canonical OCL terms, so every language uses the same word for the same thing in both apps. +

+
+ Interface language is not content language. This page covers the UI language a user picks in the menu. + It does not cover the locales of names in a terminology (a concept's locale, a repository's + supported_locales), or the language the OCL AI Assistant writes in. Keep those three separate in code and in copy. +
+ +

Who decides

+
    +
  • Each language's terms are decided by that language's translation lead. + Portuguese (Brasil): @filiperochalopes. + Español and 中文: open; propose yourself in a PR.
    • +
  • Product and feature names (OCL AI Assistant, Auto Match, OCL Mapper) are decided by OCL.
    • +
  • Change this page through a pull request. A translation PR that introduces or changes a term in the glossary should update the glossary in the same PR.
    • +
+ +

Rules for developers: assembling text

+

Most translation bugs come from the code, not the translation: the code joins fragments that read fine alone but break once combined. + The translator only sees the catalog, never the assembled sentence.

+
    +
  • One key per whole sentence. Interpolate values ({{name}}) and use <Trans> for links. + Never build a sentence from fragments such as please + link + or + go_to_your: + word order differs between languages, and Portuguese renders that chain as "Por favor atualizar ou ir para seu Painel."
    • +
  • Pass translated labels, never raw API values. repo.type ("Collection") or a literal 'concept' + inside a translated sentence renders as "este Collection" or "Este concept aparece…".
    • +
  • Don't put a gendered word next to an interpolated noun. "this {{resourceType}}" needs este or esta in Portuguese and Spanish, + depending on the value. Rephrase the sentence ("a lista de {{resource}}") or use one key per type.
    • +
  • Escape once. oclweb3 does not set escapeValue: false globally (oclmap does), so a user-supplied value must pass + t(key, { name, interpolation: { escapeValue: false } }). Otherwise "O'Neil" renders as O&#39;Neil.
    • +
  • Case is part of the sentence. If a fragment can start a line in one place and sit mid-sentence in another, give it two keys, + or lowercase it only at the mid-sentence call site.
    • +
  • Shared keys stay identical. When a key exists in both oclweb3 and oclmap with the same English text, + its translation should match in every language.
    • +
  • New English keys fall back to English until a translation lands. List the new keys in the PR description so translators can catch up.
    • +
+ +

Rules for translators

+
    +
  • OCL resource names (Source, Collection, Organization…) are a per-language decision, recorded in the glossary below. + The Portuguese (Brasil) rule: translate a name when a clear cognate exists (Coleção, Organização, Repositório), and keep it in English when the + translation would be ambiguous. "Source" stays in English because "Fonte" also means font, provenance and código-fonte. + Names kept in English are masculine and capitalized ("o Source", "Versão do Source"). Spanish made the other choice ("Fuente").
    • +
  • Never translate: OCL, TermBrowser, HEAD, FHIR resource names (CodeSystem, ValueSet, ConceptMap) and parameters + (activeOnly, system-version…), $match, Elasticsearch, terminology names (LOINC, SNOMED CT, CIEL, ICD-10, ICD-11), + and UUID, JSON, CSV, URL, API.
    • +
  • OCL AI Assistant always names OCL: "Assistente de IA do OCL", never just "Assistente de IA". + OCL never says "AI recommendations"; say "recommendations from the OCL AI Assistant" or rephrase.
    • +
  • When a string has placeholders or sits next to a link, ask in the PR how it renders. Reviewers will quote the assembled sentence.
    • +
+ +

Glossary

+

Values come from the app catalogs. Agreed means the language lead's choice is recorded. + Open means a decision is pending (owner in the note). A dash means the catalog has no such string yet.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EnglishEspañol中文Português (Brasil)Status · notes
SourceFuente来源SourceAgreed pt-BR keeps the English name: "o Source", "Versão do Source", plural "Sources".
CollectionColección集合ColeçãoAgreed
OrganizationOrganización组织机构OrganizaçãoAgreed
RepositoryRepositorio存储库RepositórioAgreed Some labels use the short form "Repo".
ConceptConcepto概念ConceitoAgreed
MappingMapeo映射关系MapeamentoAgreed
Map typeTipo de mapeo映射类型Tipo de mapeamentoAgreed
Concept classClase概念分类Classe do conceitoAgreed
DatatypeTipo de dato数据类型Tipo de dadoAgreed
Reference (collection)Referencia—ReferênciaAgreed
ExpansionExpansión扩展ExpansãoAgreed
Release · Released · Unreleased— · Publicado · Sin publicar— · Released · UnreleasedPublicar · Publicado · Não publicadoOpen zh: "Released" and "Unreleased" are still in English.
HEADHEADHEADHEADAgreed Never translated.
Retired · Retire · UnretireRetirado · Retirar · Reactivar已退役 · 退役 · 重新激活Aposentado · Aposentar · ReativarOpen pt-BR lead: keep, or "Inativo · Inativar · Reativar", or "Descontinuado · Descontinuar · Reativar"?
Locale (of a name)—本地语言LocalidadeOpen pt-BR lead: "Localidade" or "Idioma"?
OwnerPropietario所有者ProprietárioAgreed
Canonical URL——URL canônicaAgreed
Code System · Value Set · Concept Map——Code System · Value Set · Concept MapAgreed FHIR resource names stay in English.
Delete——ExcluirAgreed
Include · Exclude (collection reference)Incluir · Excluir—Incluir · ExcluirAgreed Reads as a pair, so no clash with Delete.
Exclude (Mapper decision)Excluir排除ExcluirOpen pt-BR lead: collides with Delete ("Excluído em massa" reads as deleted). Suggested "Desconsiderar".
Mapping projectProyecto de mapeo映射项目Projeto de mapeamentoAgreed
Match (noun)Coincidencia匹配CorrespondênciaAgreed
Matching algorithmAlgoritmo de coincidencia匹配算法Inteligência de mapeamentoOpen pt-BR lead: elsewhere the catalog says "algoritmos de correspondência".
Auto MatchCoincidencia Automática自动匹配Correspondência AutomáticaOpen OCL: may the feature name be translated? es, zh and pt-BR all translate it today.
CandidateCandidato候选对象CandidatoAgreed
Target repositoryRepositorio objetivo目标存储库Repositório de destinoAgreed
Bridge (concept, terminology)Concepto puente · Bridge桥接概念 · BridgeConceito ponte · BridgeOpen pt-BR lead: the Mapper mixes "Ponte", "Bridge" and "bridge"; pick one.
OCL AI AssistantOCL Asistente de IAOCL AI 助手Assistente de IA do OCLOpen es lead: "Asistente de IA de OCL" may read more naturally. Always name OCL.
QuotaCuota配额CotaAgreed Quota = a per-period allowance; a cap is a limit ("Limite").
AllowanceAsignación额度PermissãoOpen pt-BR lead: "permissão" may read as permission; review suggested "Cota".
Label capitalization——Title Case, mirroring EnglishOpen pt-BR lead: sentence case ("Nome completo") is the usual pt-BR UI convention.
+
+ +

Where the catalogs live

+ +
+ + diff --git a/src/pages/BuildingPagesPage.jsx b/src/pages/BuildingPagesPage.jsx index ecd74aa..6336ba9 100644 --- a/src/pages/BuildingPagesPage.jsx +++ b/src/pages/BuildingPagesPage.jsx @@ -224,7 +224,11 @@ const MyComponent = () => {

oclweb3 uses react-i18next. Translation files are in{' '} src/i18n/locales/[lang]/translations.json. Supported - languages: English (en), Spanish (es), Chinese (zh). + languages: English (en), Spanish (es), Portuguese (pt-BR, in review); + a Chinese (zh) catalog exists but isn't in the language menu. Before + adding strings, read the{' '} + Localization guide: one key per whole + sentence, and the canonical term for each language.

Date: Mon, 5 Oct 2026 10:37:06 -0400 Subject: [PATCH 2/2] OpenConceptLab/ocl_issues#2878 | Glossary: fill es/zh cells from both apps, note app differences, base-term convention, AI naming exceptions Addresses Codex review pass 1 on ocl-design-system#13. Co-Authored-By: Claude Opus 5.5 --- public/guides/localization.html | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/public/guides/localization.html b/public/guides/localization.html index 4fe8d17..54a0412 100644 --- a/public/guides/localization.html +++ b/public/guides/localization.html @@ -86,14 +86,18 @@

Rules for translators

  • Never translate: OCL, TermBrowser, HEAD, FHIR resource names (CodeSystem, ValueSet, ConceptMap) and parameters (activeOnly, system-version…), $match, Elasticsearch, terminology names (LOINC, SNOMED CT, CIEL, ICD-10, ICD-11), and UUID, JSON, CSV, URL, API.
    • -
  • OCL AI Assistant always names OCL: "Assistente de IA do OCL", never just "Assistente de IA". - OCL never says "AI recommendations"; say "recommendations from the OCL AI Assistant" or rephrase.
    • +
  • OCL AI Assistant always names OCL: "Assistente de IA do OCL", not just "Assistente de IA". + Don't write "AI recommendations"; say "recommendations from the OCL AI Assistant" or rephrase. Some existing English Mapper strings + still break both rules (e.g. preview_estimate_ai_*, labels that say "AI Assistant"). They'll be fixed in English and every + language together, so don't treat them as precedent.
  • When a string has placeholders or sits next to a link, ask in the PR how it renders. Reviewers will quote the assembled sentence.

    • Glossary

    -

    Values come from the app catalogs. Agreed means the language lead's choice is recorded. - Open means a decision is pending (owner in the note). A dash means the catalog has no such string yet.

    +

    Values come from the app catalogs and are shown as the base term, singular and in sentence case. The catalog labels themselves may be plural or Title Case + (capitalization is still an open pt-BR question, last row). Where the two apps use different words, the note says so. + Agreed means the language lead's choice is recorded. Open means a decision is pending (owner in the note). + A dash means neither catalog has the term yet.

    @@ -112,12 +116,12 @@

    Glossary

    - + - + - - + + @@ -127,7 +131,7 @@

    Glossary

    - +
    EnglishEspañol中文Português (Brasil)Status · notes
    Release · Released · Unreleased— · Publicado · Sin publicar— · Released · UnreleasedPublicar · Publicado · Não publicadoOpen zh: "Released" and "Unreleased" are still in English.
    HEADHEADHEADHEADAgreed Never translated.
    Retired · Retire · UnretireRetirado · Retirar · Reactivar已退役 · 退役 · 重新激活Aposentado · Aposentar · ReativarOpen pt-BR lead: keep, or "Inativo · Inativar · Reativar", or "Descontinuado · Descontinuar · Reativar"?
    Locale (of a name)—本地语言LocalidadeOpen pt-BR lead: "Localidade" or "Idioma"?
    Locale (of a name)Idioma (TBv3) · Configuración regional (Mapper)本地语言LocalidadeOpen pt-BR lead: "Localidade" or "Idioma"? es lead: the two apps differ.
    OwnerPropietario所有者ProprietárioAgreed
    Canonical URL——URL canônicaAgreed
    Canonical URLURL canónica规范型 URLURL canônicaOpen zh lead: the Mapper's algorithm form also uses 规范 URL.
    Code System · Value Set · Concept Map——Code System · Value Set · Concept MapAgreed FHIR resource names stay in English.
    Delete——ExcluirAgreed
    Include · Exclude (collection reference)Incluir · Excluir—Incluir · ExcluirAgreed Reads as a pair, so no clash with Delete.
    DeleteEliminar删除ExcluirAgreed Spanish keeps Delete (Eliminar) apart from Exclude (Excluir).
    Include · Exclude (collection reference)Incluir · Excluir包含 · 排除Incluir · ExcluirAgreed Reads as a pair, so no clash with Delete.
    Exclude (Mapper decision)Excluir排除ExcluirOpen pt-BR lead: collides with Delete ("Excluído em massa" reads as deleted). Suggested "Desconsiderar".
    Mapping projectProyecto de mapeo映射项目Projeto de mapeamentoAgreed
    Match (noun)Coincidencia匹配CorrespondênciaAgreed
    Target repositoryRepositorio objetivo目标存储库Repositório de destinoAgreed
    Bridge (concept, terminology)Concepto puente · Bridge桥接概念 · BridgeConceito ponte · BridgeOpen pt-BR lead: the Mapper mixes "Ponte", "Bridge" and "bridge"; pick one.
    OCL AI AssistantOCL Asistente de IAOCL AI 助手Assistente de IA do OCLOpen es lead: "Asistente de IA de OCL" may read more naturally. Always name OCL.
    QuotaCuota配额CotaAgreed Quota = a per-period allowance; a cap is a limit ("Limite").
    QuotaCuota配额CotaAgreed A quota is an allowance, per period or one-time (e.g. the preview). A cap limits how much you can hold ("Limite").
    AllowanceAsignación额度PermissãoOpen pt-BR lead: "permissão" may read as permission; review suggested "Cota".
    Label capitalization——Title Case, mirroring EnglishOpen pt-BR lead: sentence case ("Nome completo") is the usual pt-BR UI convention.