ADR-001-b — Language Conventions

ADR-001-b — Language Conventions

Status

Accepted

Context

Coveris targets Argentine healthcare organizations and its end users speak Spanish. At the same time, the entire technical stack (Python, Angular, SQL, HTTP) is built on English-first tooling, conventions, and ecosystems. Two extremes were considered and rejected:

• Full Spanish — Spanish identifiers, model names, endpoint paths, and variable names. Results in friction with frameworks, impossible to onboard non-Spanish contributors, and at odds with every library and linter in the stack.
• Mixed on a case-by-case basis — Some entities use Spanish terms when they “feel more natural” (e.g., Nomina, Puesto, Guardia). Results in inconsistent naming across the backend model, the API contract, and the Angular service layer, making cross-referencing fragile and error-prone.

Canonical names for all domain entities are defined in [[adr-001-a-naming-glossary|ADR-001-a]].

Decision

English is the default language for all code artifacts. Spanish enters the system only at the final rendering step — the HTML template.

The rule applies to:

Artifact	Language	Example
Python model names	English	Employee, OrgUnit, Position
Python field names	English	contract_type, required_hours, coverage_state
Enum members & TextChoices values	English	CLINIC, ACTIVE, BLOCKING (the human-readable label may be Spanish — it renders)
Django URL patterns	English	/api/v1/employees/, /api/v1/org-units/
DRF serializer fields	English	assigned_hours, is_active
Angular component names	English	EmployeeListComponent, OrgChartNodeComponent
Angular signal / variable names	English	selectedEmployee, coverageState
Angular route paths	English	/employees, /org-chart, /positions
Database table and column names	English	employees, org_units, required_hours
Git branch names	English	feat/employee-fsm, fix/coverage-calc
Test identifiers and fixture keys	English	test_employee_onboarding_transition

The only exception: HTML template display strings. Labels, headings, button text, placeholder text, and user-facing messages are in Spanish because that is what the end user reads.

<!-- Correct -->
<p-tag [value]="employee.status | statusLabel" />

<!-- statusLabel pipe returns 'Activo' / 'En Licencia' — Spanish only here -->

Prose documentation (ADRs, inline comments, docstrings) is written in English. Entity names, field names, HTTP verbs, and framework concepts use their canonical English form — never translated. Writing empleados or nómina when referring to the Employee model, or punto final when referring to an endpoint, is a violation of this rule.

Consequences

• Any AI agent, developer, or reviewer reading a Python model, an API endpoint, or an Angular service will find English identifiers — no ambiguity about which “nómina” maps to which endpoint.
• ADRs, comments, and docstrings use English with canonical entity names. Example: “The Employee model includes the contract_type field…” — not “El modelo Empleado incluye el campo tipo_contrato…”.
• Translation is a one-way valve: business logic (English) → display pipe → user-facing string (Spanish). It never flows backwards.