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 asplease+ 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: falseglobally (oclmap does), so a user-supplied value must pass +t(key, { name, interpolation: { escapeValue: false } }). Otherwise "O'Neil" renders asO'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", 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 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.
+
+
+
+
+
+ | English | Español | 中文 | Português (Brasil) | Status · notes |
|---|---|---|---|---|
| Source | Fuente | 来源 | Source | Agreed pt-BR keeps the English name: "o Source", "Versão do Source", plural "Sources". |
| Collection | Colección | 集合 | Coleção | Agreed |
| Organization | Organización | 组织机构 | Organização | Agreed |
| Repository | Repositorio | 存储库 | Repositório | Agreed Some labels use the short form "Repo". |
| Concept | Concepto | 概念 | Conceito | Agreed |
| Mapping | Mapeo | 映射关系 | Mapeamento | Agreed |
| Map type | Tipo de mapeo | 映射类型 | Tipo de mapeamento | Agreed |
| Concept class | Clase | 概念分类 | Classe do conceito | Agreed |
| Datatype | Tipo de dato | 数据类型 | Tipo de dado | Agreed |
| Reference (collection) | Referencia | — | Referência | Agreed |
| Expansion | Expansión | 扩展 | Expansão | Agreed |
| Release · Released · Unreleased | — · Publicado · Sin publicar | — · Released · Unreleased | Publicar · Publicado · Não publicado | Open zh: "Released" and "Unreleased" are still in English. |
| HEAD | HEAD | HEAD | HEAD | Agreed Never translated. |
| Retired · Retire · Unretire | Retirado · Retirar · Reactivar | 已退役 · 退役 · 重新激活 | Aposentado · Aposentar · Reativar | Open pt-BR lead: keep, or "Inativo · Inativar · Reativar", or "Descontinuado · Descontinuar · Reativar"? |
| Locale (of a name) | Idioma (TBv3) · Configuración regional (Mapper) | 本地语言 | Localidade | Open pt-BR lead: "Localidade" or "Idioma"? es lead: the two apps differ. |
| Owner | Propietario | 所有者 | Proprietário | Agreed |
| Canonical URL | URL canónica | 规范型 URL | URL canônica | Open zh lead: the Mapper's algorithm form also uses 规范 URL. |
| Code System · Value Set · Concept Map | — | — | Code System · Value Set · Concept Map | Agreed FHIR resource names stay in English. |
| Delete | Eliminar | 删除 | Excluir | Agreed Spanish keeps Delete (Eliminar) apart from Exclude (Excluir). |
| Include · Exclude (collection reference) | Incluir · Excluir | 包含 · 排除 | Incluir · Excluir | Agreed Reads as a pair, so no clash with Delete. |
| Exclude (Mapper decision) | Excluir | 排除 | Excluir | Open pt-BR lead: collides with Delete ("Excluído em massa" reads as deleted). Suggested "Desconsiderar". |
| Mapping project | Proyecto de mapeo | 映射项目 | Projeto de mapeamento | Agreed |
| Match (noun) | Coincidencia | 匹配 | Correspondência | Agreed |
| Matching algorithm | Algoritmo de coincidencia | 匹配算法 | Inteligência de mapeamento | Open pt-BR lead: elsewhere the catalog says "algoritmos de correspondência". |
| Auto Match | Coincidencia Automática | 自动匹配 | Correspondência Automática | Open OCL: may the feature name be translated? es, zh and pt-BR all translate it today. |
| Candidate | Candidato | 候选对象 | Candidato | Agreed |
| Target repository | Repositorio objetivo | 目标存储库 | Repositório de destino | Agreed |
| Bridge (concept, terminology) | Concepto puente · Bridge | 桥接概念 · Bridge | Conceito ponte · Bridge | Open pt-BR lead: the Mapper mixes "Ponte", "Bridge" and "bridge"; pick one. |
| OCL AI Assistant | OCL Asistente de IA | OCL AI 助手 | Assistente de IA do OCL | Open es lead: "Asistente de IA de OCL" may read more naturally. Always name OCL. |
| Quota | Cuota | 配额 | Cota | Agreed A quota is an allowance, per period or one-time (e.g. the preview). A cap limits how much you can hold ("Limite"). |
| Allowance | Asignación | 额度 | Permissão | Open pt-BR lead: "permissão" may read as permission; review suggested "Cota". |
| Label capitalization | — | — | Title Case, mirroring English | Open pt-BR lead: sentence case ("Nome completo") is the usual pt-BR UI convention. |
Where the catalogs live
+-
+
- oclweb3:
src/i18n/locales/[lang]/translations.json
+ - oclmap:
src/i18n/locales/[lang]/translations.json
+ - History: Portuguese (Brasil) was added in ocl_issues#2866. + Code-side assembly fixes are tracked in #2877, and this guide in + #2878. +