Localization — es-CO

Status: draft Author: Agent C (frontend bucket, round 1) Reviewers: Sophia Mann (final translation check via Mariana / Ronald), Andrew Kent; Agent E (multi-tenancy & legal); round-2 critique agent Last updated: 2026-05-10

Context

Every primary user of the LBZF CV product on the Colombian floor speaks Spanish:

Mariana Saker — Spanish primary, some English likely.
Ronald Gonzalez Suarez — Spanish only (no documented English).
Future supervisors — Spanish only.

The current site (src/pages/index.astro) is English-only. The team’s internal docs are English. The source factory artifacts (INDICADORES ABRIL.xlsx, Ref22 Slim - Angela.xlsx) and video filenames are in Pereira-Colombian Spanish with industry-specific garment vocabulary (e.g., perrilla, pespuntar, revoque).

This document specifies what “Spanish-first” actually means across copy, dates, numbers, sort orders, exports, and errors — and decides whether English mode exists at all.

Anchor artifacts:

docs/references/glossary.md (Spanish vocabulary already established)
docs/factory/operations.md (the 44 operation names in Spanish)
INDICADORES ABRIL.xlsx (Drive 1oo5s4R70XXXK4zeeCsEMNNJcnXrvEUKV) — column headers in Spanish
Ref22 Slim - Angela.xlsx — “Balanceo” tab in Spanish

Goals

A single canonical answer to “is there English mode?” with rationale.
Concrete rules for date, number, time, and currency formatting in every surface.
A copy register (executive vs operational) so Mariana’s view doesn’t feel jargon-heavy and Ronald’s view doesn’t feel patronizing.
Excel exports that match Ronald’s existing files byte-by-byte where it matters.
A glossary the implementation uses verbatim — no Spanish strings invented at code-write time.
Error and empty-state copy that is correct, polite (the Spanish formal usted, not tú, for engineering surfaces), and short.

Non-goals

Full i18n framework selection. The decision is “es-CO only on user-facing surfaces”; framework is whatever Astro + the future Flask/FastAPI app supports with minimal ceremony.
Translation memory tooling.
Multi-Spanish-locale support beyond es-CO (Argentina, Mexico, Spain) for Phase I. ITBA’s Argentine register is close enough; we use es-CO copy and accept the imperfect fit.
Pluralization edge cases beyond “operario(s)”, “puesto(s)”, “módulo(s)”.

Proposed approach

The bilingual-or-not decision

Decision: es-CO is the only mode for any user-facing surface. English exists only on /app/admin and on the documentation in this repo.

Rationale:

Ronald cannot use an English-leaking UI. Even a single English error message (“Failed to fetch”) will rotate trust.
Adding English doubles the translation work, doubles the testing surface, and creates a “if a string is missing in Spanish, fall back to English” footgun that paints English back into the very surface Ronald uses.
Sophia and Andrew can read Spanish well enough for admin work; if they cannot read a label, they fix the label, they don’t add an EN version.
Mariana speaks Spanish primary; if she occasionally wants English she does it through her browser’s auto-translate, which is fine for an executive view.
ITBA is Argentine; they read es-CO fine. The “research” view is in Spanish.
Exception: /app/admin (Sophia + Andrew only) stays English-first because all the engineering vocabulary in there (deploy status, model version, role assignment) is more naturally English. Bilingual labels acceptable here only.

If multi-tenancy ever materializes (see lbzfai-evolution-plan.md §“Tenancy posture”) with a non-Spanish-speaking customer, this decision revisits. For Phase I and the foreseeable Phase II, es-CO only.

Locale identifiers

HTML root: <html lang="es-CO">.
Accept-Language from clients ignored — we serve es-CO regardless.
Intl.DateTimeFormat / Intl.NumberFormat: locale es-CO.
Auth0 Universal Login: configure Spanish as the only language for Phase I (tenant setting).

Number formatting

Decimal separator: comma (,).
- 87,3 % not 87.3%.
- 1.234,56 not 1,234.56.
Thousand separator: period (.).
Percent sign: space before the % per RAE convention: 87,3 %. (Soft rule — internal consistency matters more than strict typography.)
Currency: N/A for Phase I (no prices in the UI). If/when added, Colombian Peso COP $.

Date and time formatting

Date: dd/mm/yyyy — 27/07/2026.
Long date: lunes 27 de julio de 2026 (lowercase month and weekday per RAE).
Time: 24-hour HH:MM — 09:14. No AM/PM. Industrial register; matches whiteboard time conventions.
Time zone: Colombia is America/Bogota (UTC-5, no DST). The Jetson is in Pereira → America/Bogota. lbzfai.com renders in the user’s local zone but defaults to America/Bogota for any displayed LBZF time (e.g., a Sophia in California sees 09:14 (Bogota)).

Sort orders

Spanish collation. Sort using Intl.Collator('es-CO', { sensitivity: 'base' }). The default browser locale is not safe to rely on.
Operator names (e.g., Adriana, Adelaida, Carlina): Spanish accents and ñ collated correctly.
Workstation order by numeric workstation ID, not alphabetic. Puesto 1, Puesto 2, …, Puesto 21 — never Puesto 1, Puesto 10, Puesto 11, Puesto 2, ….
Operation order in tables: manufacturing sequence (the order in Ref22 Slim - Angela.xlsx “Balanceo” tab), not alphabetic. The sequence has semantic meaning (collar → cuffs → assembly → inspection → pack); alphabetic ordering destroys it.
Lost-time codes: C001 → C022 order, not alphabetic, not frequency-of-use, not most-recently-used. Ronald’s mental model maps to that order.

Copy register

Two registers, used consistently within their respective surfaces:

Register	Audience	Tone	Pronoun
Operational	Ronald’s dashboard (Jetson :5000)	Industrial. Short. Verb-first. Numbers prominent.	`usted` formal but rarely surfaced — most strings are nouns, not commands.
Executive	Mariana’s view (`/app/ejecutivo`)	Concise, high-level. Avoid the C001–C022 codes; show grouped categories.	`usted` formal.

No tú. No vos. No regional slang.

Glossary — authoritative strings

The following strings are canonical and must be used verbatim. Any new Spanish string introduced anywhere in the app must be added here first.

Section names

Concept	es-CO
Dashboard (Ronald’s)	`Monitoreo de Producción`
Dashboard (Mariana’s)	`Resumen ejecutivo`
Module	`Módulo` (plural `Módulos`)
Workstation	`Puesto` (plural `Puestos`)
Operator	`Operario` (plural `Operarios`, feminine `Operaria` allowed)
Operation	`Operación` (plural `Operaciones`)
Shift	`Jornada`
Hour	`Hora`
Goal (per hour or per shift)	`Meta`
Actual (achieved)	`Real`
Achievement / attainment	`Logro` (alt: `% Cumplimiento`) — OPEN: confirm which Ronald prefers
Standard time	`SAM` (industry-standard acronym; do not translate)
Cycle time	`Tiempo de ciclo`
Efficiency	`Eficiencia`
Performance	`Rendimiento`
Trend	`Tendencia`
Last update	`Última actualización`
Threshold (general)	`Umbral` (plural `Umbrales`)
Lost time	`Tiempo perdido`
Settings	`Ajustes` (Mariana) / `Configuración` (Ronald)
Export	`Exportar`
History	`Historial`
Cameras	`Cámaras`

Status labels

Status	es-CO
On pace	`En meta`
Below pace	`Bajo meta`
Above pace	`Sobre meta`
OK	`OK` (keep)
Warning	`Atención`
Critical	`Crítico`
Coming soon	`Próximamente`
Pending	`Pendiente`
Not assigned	`Sin asignar`
Empty station	`Puesto vacío`
Active break (mandated Colombian labor law)	`Pausa activa`
Mechanic wait	`Espera mecánico`
Infirmary	`Enfermería`

Buttons / actions

Action	es-CO
Sign in	`Iniciar sesión`
Sign out	`Cerrar sesión`
Open dashboard	`Abrir tablero` (alt: `Abrir panel`) — OPEN: pick one
Export Excel	`Exportar a Excel`
Code lost time	`Codificar tiempo perdido`
Adjust thresholds	`Ajustar umbrales`
View cameras	`Ver cámaras`
Save	`Guardar`
Cancel	`Cancelar`
Try again	`Reintentar`
Close	`Cerrar`
Back	`Atrás`

Error / empty / degraded states

Situation	es-CO
Loading	`Cargando…`
Session expired	`Sesión vencida. Vuelva a iniciar sesión.`
No data yet today	`Sin datos aún. La jornada inicia a las 06:00.`
All cameras down	`Sin señal de cámaras.`
One camera down	`Cámara del puesto {n} sin señal. Último cuadro: hace {duration}.`
Network down	`Sin conexión con la planta. Datos al {HH:MM}.`
Save failed	`No se pudo guardar. Reintentar.`
Access denied	`No tiene acceso a esta vista.`
Access pending	`Acceso pendiente. Contacte a Sophia.`
Generic unknown error	`Ocurrió un error inesperado. Recargue la página.`

Operations (preserve the Ref22 Slim vocabulary)

All ~44 Ref22 Slim operations are kept verbatim as they appear in Ref22 Slim - Angela.xlsx and the video filenames. Do not normalize, sentence-case, or translate them.

A non-exhaustive sample (the full list lives in docs/factory/operations.md): DOBLADILLAR BANDA CUELLO, PRENDER Y ASENTAR BANDA DEL CUELLO, CERRAR CUELLO, REVOCAR CUELLO, VOLTEAR Y PLUMILLA CUELLO, PESPUNTAR CUELLO, PESPUNTAR BANDA CUELLO, CERRAR PUÑO, VOLTEAR PUÑO, PESPUNTAR PUÑO, MARQUILLAR ALMILLA, ALMILLAR, PLANCHAR ESPALDA, …

Display convention: small caps or upper-case if it appears in the spreadsheet that way; otherwise Title Case per visible rendering preference. Internal/database storage uses the verbatim spreadsheet string.

Garment vocabulary (preserve)

Cuello (collar), Puño (cuff), Almilla (yoke), Manga (sleeve), Bolsillo (pocket), Espalda (back), Frente (front), Perrilla / Perrillas (cuff placket), Ruedo (hem), Camisa (shirt). See docs/references/glossary.md.

Lost-time codes (preserve C001–C022 order and Spanish names)

The codes’ Spanish labels come from INDICADORES ABRIL.xlsx. Sample:

Code	es-CO
C001 (illustrative)	`Reprocesos culposos`
C002 (illustrative)	`Reprocesos no culposos`
C003 (illustrative)	`Falta de balanceo`
C004 (illustrative)	`Espera mecánico`
…	(full list lives in the spreadsheet; OPEN: verify the exact code↔label mapping)

OPEN: extract and freeze the full C001–C022 list from INDICADORES ABRIL.xlsx. Owner: Sophia, blocking: Phase I dashboard, target: 2026-06-01.

Machine codes (preserve as-is)

MPP, MREV, MOJA, MBOT, PLCH. Do not translate or rename.

Excel export — formatting rules

The exported .xlsx must:

Use the same column headers as INDICADORES ABRIL.xlsx: jornada, #operarios, OP, SAM, units, total minutos productivos, eficiencia, rendimiento módulo, plus the lost-time-code columns.
Numeric cells: Colombian decimal/thousand separators preserved as cell format (#.##0,00), not as embedded strings.
Dates as dd/mm/yyyy cell format.
Percentages as Excel percent format (0,00%), not as 0.873 written into a string cell.
Sheet name: INDICADORES (uppercase, matches Ronald’s file).
Filename: INDICADORES_<Modulo>_<YYYY-MM>.xlsx — e.g., INDICADORES_Angela_2026-07.xlsx.
OPEN: do we preserve the workbook’s macros / conditional formatting / hidden tabs? Owner: Agent B + Ronald, blocking: byte-compat acceptance, target: 2026-06-01.

Tenant Settings → Languages: Spanish only. Universal Login templates render in Spanish.
The brand-mark and welcome text on the login screen are Spanish.
Email templates (password reset, account verification) are Spanish.

Astro implementation notes

<html lang="es-CO"> on every page.

Centralize all user-facing strings in src/lib/i18n/es-CO.ts (file does not exist yet). Pattern:

export const t = {
  appName: 'LBZF — Monitoreo de Producción',
  nav: { dashboard: 'Tablero', logout: 'Cerrar sesión' },
  errors: {
    sessionExpired: 'Sesión vencida. Vuelva a iniciar sesión.',
    offline: 'Sin conexión con la planta. Datos al {time}.',
  },
  // ...
} as const;

No i18next for Phase I. Single-locale = a typed object is sufficient and avoids a dependency.
For interpolation, write a tiny template helper rather than a library.
Number/date formatting: use Intl.NumberFormat('es-CO') and Intl.DateTimeFormat('es-CO') directly; do not wrap.

Jetson (Flask/FastAPI) implementation notes

Jinja templates use the same canonical strings — either by sharing a JSON file between Astro and Flask, or (simpler for Phase I) by maintaining two copies and keeping them in sync via this doc as canonical reference.
Babel / Flask-Babel is overkill for single-locale. Just write the Spanish strings in the templates.
Date/number formatting: Python babel.numbers.format_decimal(value, locale='es_CO'), babel.dates.format_datetime(value, locale='es_CO').

What if a string is missing in Spanish?

There is no English fallback. Missing strings are bugs and surface as a placeholder like ??(missing.key). Development should fail loudly on missing strings, not silently fall back.

Alternatives considered

EN/ES bilingual with a language switcher. Rejected — doubles work, creates fallback footguns, no real user wants it.
Latin-American Spanish (generic) instead of es-CO. Rejected — Pereira-specific industrial vocabulary in the spreadsheets (perrilla, balanceo, rendimiento módulo) is concrete. Generic LatAm Spanish would force us to relabel and confuse Ronald.
Auto-translate everything from English source. Rejected — machine translation gets garment terms wrong (puño → “fist”) and breaks Ronald’s trust in week 1.
Use i18next even for one locale. Rejected — added dependency for zero feature gain in Phase I. Reintroduce if/when a second locale appears.
Mirror English admin labels in Spanish for completeness. Rejected — /app/admin is English-only because the audience (Sophia + Andrew) is English-speaking and the vocabulary (deploys, claims, tokens) is more natural in English.

Open questions

OPEN: Ronald’s preferred word for “attainment / cumplimiento / logro”. Owner: Sophia via Armando → Ronald, target: 2026-06-01. Default: % Cumplimiento.
OPEN: tablero vs panel for “dashboard”. Owner: Sophia + Ronald, target: 2026-06-01. Default: tablero (more Colombian).
OPEN: Full C001–C022 label list verbatim from INDICADORES ABRIL.xlsx. Owner: Sophia, blocking: dashboard, target: 2026-06-01.
OPEN: Excel export — preserve Ronald’s macros + conditional formatting + hidden tabs? Owner: Agent B + Ronald, blocking: adoption, target: 2026-06-01.
OPEN: Do we want a Universal Login custom-text pass to remove every English string Auth0 ships with by default? Owner: Sophia, target: 2026-06-15.
OPEN: ITBA’s Argentine register — any words that read poorly in es-AR? Owner: Sophia + Andrew (ask ITBA in Buenos Aires 2026-05-15), target: 2026-05-22. Default: ship es-CO, fix only if ITBA complains.
OPEN: When (if ever) do we add English mode? Owner: Agent E (tenancy posture). Trigger: signed multi-tenant customer whose primary users do not read Spanish.

Cross-bucket dependencies

From backend/integration (Agent B):
- Excel export endpoint that respects this doc’s formatting rules.
- API response strings (validation errors, status codes) — must use the same canonical Spanish strings. We should expose error strings as enums on the API and resolve to localized copy on the client, rather than have the server send pre-localized strings.
From hardware/ML (Agent A, D): none directly; indirectly, Spanish naming of operations and machine codes (already done — they’re in the spreadsheets).
From business/cross-cutting (Agent E):
- Privacy-policy copy in Spanish that meets Colombian labor-law disclosure requirements.
- Sign-off on the es-CO-only decision from Mariana (paper trail in case of multi-tenant pivot).
From hardware (Agent A): no direct dependency.

What’s weak in this doc

No native speaker has reviewed any of the canonical strings. Sophia speaks Spanish (presumably native or near-native via family) but no formal review has happened. Round 2 critical action: print this glossary, ask Mariana and Ronald to mark up the strings in person.
The Excel export rules are aspirational. We have not opened INDICADORES ABRIL.xlsx and verified our .xlsx writer produces byte-comparable output. Until we do, “matches INDICADORES ABRIL.xlsx” is a wish.
No fallback for partial data corruption. If the database has a row that’s missing a Spanish label, the proposal says “fail loudly”. That’s correct for development but may panic Ronald at 7am. We need a softer production failure mode: show the row, show a placeholder, log the issue, don’t crash.
Pluralization rules are stubbed. Spanish has straightforward pluralization (-s / -es), but feminine/masculine agreement matters for operator descriptions (“la operaria Operario A” vs “el operario Manuel”). We haven’t decided whether to track gender of named operators.
No accessibility checks for Spanish-language screen readers. A VoiceOver pronunciation pass would catch surprises (e.g., SAM read as a word vs spelled out).
Argentina’s es-AR is treated as “close enough”. If ITBA’s PI feels otherwise, the doc has no plan B beyond “we’ll add an es-AR locale later”.

Rollout

Argentina demo (2026-05-13): Universal Login already in Spanish; the marketing landing has a Spanish subhead.
2026-05-22: all canonical strings extracted to src/lib/i18n/es-CO.ts; full landing page in Spanish; Auth0 Universal Login Spanish-only.
2026-06-01: full C001–C022 list, frozen.
2026-06-15: Excel export matches INDICADORES ABRIL.xlsx columns and number formatting.
2026-06-22: Ronald walk-through; copy corrections applied.
2026-07-01: all UI surfaces es-CO; admin surfaces English-only.
Phase II: consider whether to add an es-AR locale for ITBA’s twin if their team requests it.

Appendix / references

docs/references/glossary.md
docs/factory/operations.md
INDICADORES ABRIL.xlsx (Drive 1oo5s4R70XXXK4zeeCsEMNNJcnXrvEUKV)
Ref22 Slim - Angela.xlsx (same folder)
This bucket’s ../../business/ronald-dashboard-ux.md
This bucket’s ../../business/mariana-dashboard-ux.md
This bucket’s information-architecture.md