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, AutoMatch, 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 passt(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" and "Sources" stay 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").
- pt-BR decisions are recorded, with reasons, in ocl_issues#2878.
- Never translate: OCL, TermBrowser, AutoMatch, 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. For pt-BR, values follow the decisions in ocl_issues#2878; a catalog may lag until its next translation PR merges. The catalog labels themselves may be plural or Title Case. 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"; the plural "Sources" also stays in English (decided). |
| 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 | 已退役 · 退役 · 重新激活 | Descontinuado · Descontinuar · Restaurar | Agreed pt-BR: applies to the OCL domain status/action, not unrelated homonyms. |
| Locale (of a name) | Idioma (TBv3) · Configuración regional (Mapper) | 本地语言 | Idioma | Open pt-BR: "Idioma" is decided. Open only for es: the es lead must reconcile TBv3 "Idioma" with Mapper "Configuración regional". |
| 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 | — | — | CodeSystem (Code System) · ValueSet (Value Set) · ConceptMap (Concept Map) | Agreed pt-BR keeps FHIR resource names in English; never translate the component words when they form these names. |
| 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. pt-BR search-filter Include/Exclude also keeps "Incluir · Excluir". |
| Exclude (Mapper decision) | Excluir | 排除 | Desconsiderar | Agreed pt-BR: resulting state "Desconsiderado". Applies to the Mapper decision, its filters, bulk action and activity/log messages; destructive Delete stays "Excluir". |
| Mapping project | Proyecto de mapeo | 映射项目 | Projeto de mapeamento | Agreed |
| Match (noun) | Coincidencia | 匹配 | Correspondência | Agreed |
| Matching algorithm | Algoritmo de coincidencia | 匹配算法 | Métodos de mapeamento · algoritmo de mapeamento | Agreed pt-BR: "Métodos de mapeamento" is the project-configuration section title, which carries a description of the algorithms; use "algoritmo de mapeamento" for standalone/smaller labels. "Algoritmo" alone has a clinical-flowchart connotation. |
| AutoMatch | AutoMatch | AutoMatch | AutoMatch | Agreed OCL decision (for now): the feature is "AutoMatch", one word and never translated, in every language. The state label is "AutoMatched" in English and a "with/via AutoMatch" form elsewhere (es "Con AutoMatch", pt-BR "Com AutoMatch", zh "已通过 AutoMatch 匹配"). Catalogs updated in ocl_issues#2885. |
| Candidate | Candidato | 候选对象 | Candidato | Agreed |
| Target repository | Repositorio objetivo | 目标存储库 | Repositório de destino | Agreed |
| Bridge (concept, terminology) | Concepto puente · Bridge | 桥接概念 · Bridge | Conceito de conexão (Bridge) · Candidatos de mapeamento cruzado (Bridge) · Candidatos de mapeamento cruzado (via CIEL Bridge terminology) | Agreed pt-BR keeps "Bridge" as the domain term. These forms name the concept, Bridge Candidates and CIEL Bridge Terminology Candidates, respectively; they are context-specific, not interchangeable. |
| 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 | 额度 | Cota | Agreed pt-BR: "cota" for an allocated/consumable quantity (one-time or periodic); "limite" for a maximum/restriction; "acesso"/"permissão" only for authorization. |
| Label capitalization | — | — | Sentence case (e.g. "Nome completo") | Agreed pt-BR: proper names, acronyms and official brand capitalization remain unchanged. |
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.