¶ ADR-016: Registro y sincronización de literales i18n por formulario
¶ 1. Estatus
ESTADO: Aprobado
FECHA: 2026-10-07
AUTOR: Carlos Alberto Torres Camargo (arquitecto)
ALCANCE: literales i18n de backend y frontend de Nebula ERP que se cargan en simappe_admin (DEV y QA)
RELACIONADOS: ADR-012 (i18n del menú servida por SimappeAdmin), reglas SAR del frente i18n (ASR-PC-I18N-01..03, ASR-PF-I18N-01..04, ASR-DB-I18N-01..02, ASR-PC-VAL-02)
IMPLEMENTACIÓN DE REFERENCIA: hoja de cálculo «i18n» (pestañas i18n - Frontend, i18n - Backend, Listas) y su formulario publicado como aplicación web de Apps Script
¶ 2. Contexto
Los literales i18n del ERP viven en simappe_admin (esquema admin, tablas translation_keys y translations, idiomas ES=2 y EN=1). Los desarrolladores de backend y frontend los necesitan a diario y no tienen acceso a esa base: los solicitan a arquitectura, que los carga en DEV y QA a la vez con un script versionado.
Hasta el 7 de octubre de 2026 la solicitud se hacía escribiendo directamente en una hoja de cálculo compartida, con un panel lateral de ayuda. Que el equipo tuviera permiso de edición sobre la hoja produjo estos incidentes, todos verificados contra la hoja y las bases:
| Fecha | Incidente | Efecto |
|---|---|---|
| 23-sep | El estado inicial se escribió con errata (Solitado) |
Quedó propagado a más de 60 filas |
| 2-oct | Literales con errores de escritura en el nombre (UDGET.…, COMMOM.…) |
No se pudieron cargar hasta corregirse |
| 2-oct | Filas marcadas Ejecutado a mano sin haberse cargado |
La hoja afirmaba algo falso: la pantalla mostraba la clave cruda |
| 2-oct | Filas escritas a mano, sin hora de registro | Se perdió la trazabilidad de quién y cuándo |
| 23-sep a 7-oct | Inglés de traducción automática sin revisar («Earrings» por Pendientes, «Asset» por Activo, «font» por fuente) | 38 textos corregidos después de cargados |
| 7-oct | Se renombró a mano el encabezado de las columnas A y B | El formulario dejó de funcionar para todo el equipo |
Además, los literales de backend (mensajes de error del servidor) y los de frontend (etiquetas de pantalla) estaban mezclados en una sola lista, aunque siguen convenciones distintas y las valida SAR con reglas distintas.
¶ 3. Decisión
¶ 3.1 Un solo punto de entrada: el formulario
Los literales se solicitan únicamente por el formulario de registro, uno a uno o por archivo (Excel o CSV, sección 4.3). La hoja es el registro de lo solicitado y de su estado, no un lugar donde escribir.
- El formulario está publicado como aplicación web que se ejecuta con la cuenta de quien lo abre: Google verifica su correo y el formulario lo llena solo en Usuario solicita. Nadie puede registrar a nombre de otro.
- Solo registran los correos de la columna «Usuarios autorizados» de la pestaña Listas. Un correo que no esté en la lista ve el formulario con el botón deshabilitado y el aviso «no está autorizado». Para dar acceso a alguien, arquitectura agrega su correo en esa columna y le comparte la hoja como Lector.
- La escritura en la hoja la hace una segunda implementación del mismo proyecto, el escritor, que se ejecuta con la cuenta de arquitectura. Solo atiende pedidos firmados con una clave interna guardada en las propiedades del script, y antes de escribir vuelve a comprobar que el correo esté autorizado y aplica las mismas reglas. El enlace del escritor no se publica ni se comparte.
- Las pestañas i18n - Frontend, i18n - Backend y Listas están protegidas: solo la cuenta de arquitectura puede editarlas. Nadie del equipo puede cambiar celdas, encabezados ni estados.
- El archivo es de acceso restringido: solo lo abren las cuentas a las que arquitectura lo compartió, y siempre como Lector (compartido sin aviso de Google). El equipo consulta el estado de lo que pidió, pero no puede editar el archivo. La única cuenta con edición es la de arquitectura.
- Ya no existe el menú «i18n» dentro de la hoja ni el panel lateral.
¶ 3.2 Backend y frontend por separado
Quien registra elige el tipo del literal: Frontend o Backend. Cada tipo se guarda en su propia pestaña y se rige por sus propias reglas (sección 5). El formulario impide registrar como Frontend un literal que ya existe como Backend, y viceversa.
¶ 3.3 Corregir es volver a registrar
Si una traducción quedó mal, se registra de nuevo el mismo literal con el texto correcto. El formulario detecta que ya existe, precarga su español, inglés y módulo vigentes para editarlos, y al guardar:
- la fila anterior pasa a Reemplazado (queda como historial),
- la nueva entra como Solicitado,
- en la carga, arquitectura actualiza el texto en DEV y QA en lugar de insertarlo.
¶ 3.4 Ciclo de vida del estado
| Estado | Quién lo pone | Significado |
|---|---|---|
| Solicitado | El formulario, al registrar | Pendiente de carga |
| Ejecutado | Arquitectura, tras cargar y verificar | Está en DEV y QA, en español e inglés, y el bundle lo sirve. Lleva fecha de ejecución |
| Reemplazado | El formulario, al registrar una corrección | Hubo un texto más nuevo para el mismo literal |
| Descartado | Arquitectura | No se carga (duplicado de una clave existente, solicitud retirada) |
Nadie del equipo cambia un estado. Una fila en Ejecutado sin fecha de ejecución es un error del registro.
¶ 3.5 La carga la hace arquitectura, siempre dual y verificada
Cada corrida de carga:
- Lee de la hoja las filas en Solicitado de las dos pestañas.
- Las valida (sección 6) y las cruza contra DEV y QA: si la clave existe, es una actualización; si choca con otra clave, se detiene.
- Genera un script versionado
VNNN__i18n_registro_formulario_<tema>.sqlennebula-erp/docs/i18n. Usa el siguiente número libre entre todas las ramas. - Lo ejecuta en DEV (nodo-01) y QA (nodo-02) en la misma corrida, y lo repite para probar que no duplica.
- Invalida el bundle en cada nodo (
POST /simappe-admin/api/v1/translation/bundle/invalidate/{es|en}) y verifica conGET …/bundle/{lang}yGET …/bundle/{lang}/validate(content: []). - Marca cada fila Ejecutado con su fecha de ejecución.
- Publica en Slack el resumen de la corrida.
Es un script de sincronización de datos: no lleva MR ni despliegue. Queda commiteado en su rama para integrarlo cuando corresponda.
¶ 4. Cómo usar el formulario
Se abre con la cuenta de Google autorizada (la que usas para registrar literales). Si tu correo no está autorizado, pídele acceso a arquitectura. Cada campo del formulario trae su propia descripción con las reglas y ejemplos de esta sección y de la siguiente.
La primera vez, Google pide autorizar el formulario con tu cuenta, porque se ejecuta con ella:
- Aparece «Se requiere autorización»: pulsa Revisar permisos y elige tu cuenta.
- Si aparece «Google no verificó esta app», entra en Configuración avanzada → Ir a Centrica - Fabrica de Software - Registro i18n (no seguro). La aplicación es interna de arquitectura y no pasa por la verificación pública de Google.
- Pulsa Permitir. No se vuelve a pedir, salvo que el formulario incorpore un permiso nuevo.
Esos permisos sirven para leer la hoja (consultar literales y la lista de autorizados), sugerir la traducción y enviarle el registro al escritor. El formulario no escribe nada con tu cuenta: la hoja sigue siendo solo de lectura para ti.
¶ 4.1 Registrar un literal nuevo
- Tipo: marca Frontend o Backend (sección 5).
- Literal: escribe la clave completa.
- Módulo: se sugiere a partir del primer segmento de la clave; revísalo.
- Español: el texto exacto que verá el usuario.
- Inglés: se sugiere al salir del campo Español (sección 4.4). La sugerencia no es una traducción revisada: léela y corrígela antes de registrar.
- Usuario solicita: se llena solo con tu correo verificado y no se edita.
- Registrar. La fila queda en Solicitado.
¶ 4.2 Corregir un literal existente
- Marca el mismo tipo con que se registró y escribe el literal.
- Al salir del campo Literal aparece el aviso amarillo «Este literal ya existe». El formulario precarga el español, el inglés y el módulo vigentes.
- Corrige lo que haga falta y pulsa Registrar corrección.
¶ 4.3 Registrar varios literales con un archivo
Para registrar muchos literales de una vez (por ejemplo, la lista que genera el código de una funcionalidad):
-
Tipo: marca Frontend o Backend. Aplica a todas las filas del archivo; si tienes de los dos tipos, súbelos en dos archivos.
-
Abre la pestaña Archivo (Excel o CSV) y descarga la plantilla, o arma el archivo con estas 4 columnas y sus encabezados en la primera fila:
Literal Módulo Español Inglés BUDGET.ITEM_CATALOG.ACTIONS.DELETEbudget Eliminar Delete budget.rubro.error.codigoduplicadobudget Ya existe un rubro con el código A budget item with code {0} already exists - Formatos:
.xlsx(primera hoja) o.csvseparado por;,,o tabulador, en UTF-8 o en la codificación de Excel en Windows. - Máximo 200 filas por archivo.
- El inglés puede ir vacío: el formulario lo sugiere (sección 4.4) y la fila queda marcada para revisión.
- Formatos:
-
Sube el archivo. El formulario muestra la vista previa: cada fila con su estado y el motivo.
- Nuevo: el literal no existe y se registrará.
- Corrección: el literal ya existe; al registrar, la fila anterior queda Reemplazado.
- Rechazado: no cumple una regla de la sección 6 (formato, módulo, marcadores, choque de prefijo, registrado con el otro tipo, repetido en el mismo archivo). No se registra.
-
Revisa el inglés en la tabla (se puede editar) y desmarca las filas que no quieras enviar. Validar de nuevo repite la revisión con tus cambios.
-
Pulsa Registrar N literales. Las filas rechazadas no impiden registrar las demás; al terminar, la tabla muestra el resultado de cada fila.
¶ 4.4 Cómo se sugiere el inglés
El inglés sugerido sale de la primera fuente que tenga respuesta, en este orden, y el formulario indica cuál usó:
- Glosario del ERP: si el texto en español es exactamente un término del glosario del módulo (o de
common), se usa su inglés. Respeta la puntuación final: «Estado:» → «Status:». - Texto ya aprobado: si ese mismo español ya está Ejecutado en la hoja, se sugiere el mismo inglés, para que el ERP diga lo mismo en todas partes. Se descarta si contradice el glosario.
- Traductor automático, solo si no hubo respuesta antes:
- Los marcadores
{{x}}y{0}se apartan antes de traducir y se reponen después; nunca se traducen. - Se ajusta la forma al español y al tipo de clave: mayúscula inicial y puntuación final iguales; en
ACTIONSyBUTTONS, verbo sin «To». - Si la frase contiene un término del glosario y la traducción no usa su inglés, aparece un aviso. Ej.: «"Vigencia" en budget se traduce "Fiscal year"».
- Los marcadores
El glosario vive en la pestaña Listas (columnas Glosario módulo, Glosario español y Glosario inglés) y lo mantiene arquitectura. Si una traducción del ERP se corrige más de una vez, su término va al glosario.
¶ 5. Reglas de nombrado (apoyadas en SAR)
El catálogo de simappe_admin es uno solo para backend y frontend, pero cada frente usa su propia convención y SAR valida cada una por separado.
¶ 5.1 Backend
| Regla | Detalle | Regla SAR |
|---|---|---|
| Patrón | servicio.entidad.tipo.detalle, todo en minúsculas, segmentos de letras y números sin guion bajo. Ej.: treasury.embargo.error.tercero |
ASR-PC-I18N-03 (FAIL para clave nueva; WARN si ya existía en BD) |
Vocabulario del tipo |
error, validation, msg, label, info, solution, solucion, message, detail, success (semilla vigente; SAR lo amplía en su tabla i18n_key_types) |
ASR-PC-I18N-03 |
| Mensaje con solución | La base es un namespace: <base>.message y <base>.solucion son hojas hermanas. Nunca x.y con texto y x.y.solucion a la vez |
ASR-DB-I18N-02 (FAIL) |
| Uso en código | Solo vía constante y <Modulo>Messages.get(...) o SimappeException. Nada de prosa en el código ni defaults literales en getOrDefault |
ASR-PC-I18N-01 (FAIL) |
| Parámetros | Placeholders {0}, {1}… idénticos en español e inglés y en la misma cantidad que los argumentos del llamado |
ASR-PC-I18N-02 (FAIL) |
| Sin archivos locales | El runtime resuelve siempre por SimappeAdmin; no se agregan claves a messages_*.properties |
ASR-PC-VAL-02 |
Claves ya registradas que no cumplen el patrón y que SAR reporta: budget.tiporecurso.categoria.NACIONAL (categoria no es un tipo y el detalle va en mayúsculas), treasury.pago.operacion.sobregiro y budget.error.formato.no.soportado (su tercer segmento no es un tipo del vocabulario). No se registran claves nuevas con esas formas.
¶ 5.2 Frontend
| Regla | Detalle | Regla SAR |
|---|---|---|
| Patrón de feature | NAMESPACE.SEGMENTO[.SEGMENTO…] en MAYÚSCULAS, con guion bajo permitido, mínimo dos segmentos. Ej.: BUDGET.FUNDING_SOURCE.TITLE.LIST |
ASR-PF-I18N-02 |
| Menú y breadcrumb | Clave de un solo segmento: OPTIONS_*, SUB_MODULES_*, MENU. Solo en posición de etiqueta (title:, label:, breadcrumb:) |
ASR-PF-I18N-02 |
| Sin prosa en templates | Todo texto de usuario del .html sale de una clave con \| translate |
ASR-PF-I18N-01 |
| Sin prosa en constantes | Las etiquetas declaradas en TypeScript (columnas, formularios, títulos) son claves resueltas con t() |
ASR-PF-I18N-03 (FAIL) |
| Clave sembrada | Toda clave que la feature usa está en un script versionado de docs/i18n. El script de la carga de este proceso cumple esta regla |
ASR-PF-I18N-04 (FAIL) |
¶ 5.3 Comunes a los dos frentes
| Regla | Detalle | Regla SAR |
|---|---|---|
| Español e inglés | Toda clave se carga con los dos idiomas, nunca uno solo | ASR-DB-I18N-01, ASR-PC-I18N-02 |
| Inglés distinto del español | Un inglés igual al español es un pendiente de traducción (WARN) | ASR-PC-I18N-02 |
| Hoja o namespace, no ambos | Ninguna clave puede ser prefijo de otra separada por punto: una sola colisión tumba todo el i18n del admin | ASR-DB-I18N-02 |
| Buscar antes de crear | Antes de pedir una clave nueva, verifica si el texto ya existe con otra clave | — |
| Texto completo | Sin espacios ni saltos de línea en los extremos, sin el inglés pegado dentro del español, sin números faltantes («Máximo caracteres») | — |
¶ 6. Reglas de control
Qué se valida, dónde y con qué efecto:
| Control | Formulario (al registrar) | Arquitectura (en la carga) |
|---|---|---|
| Tipo elegido | Obligatorio | — |
| Formato del literal (segmentos separados por punto, letras, números y guion bajo) | Rechaza | — |
| Convención del frente (sección 5) | — | Se reporta al solicitante antes de cargar |
| Español e inglés presentes | Rechaza | Rechaza |
| Módulo del ERP | Obligatorio (accounting, treasury, budget, invoicing, billing, masters, common) |
— |
| Literal registrado en el otro tipo | Rechaza | — |
| Choque hoja/namespace con otro literal de la hoja | Rechaza | Se detiene si choca con una clave de DEV o QA |
| Clave ya existente en DEV o QA | — | Se actualiza su texto (corrección) o se descarta si es idéntica |
Marcadores ({{x}}, {0}) iguales en español e inglés |
Rechaza | Se revisa antes de cargar |
| Literal repetido dentro del mismo archivo | Rechaza (desde la segunda aparición) | — |
| Choque hoja/namespace entre filas del mismo archivo | Rechaza | — |
| Término del glosario mal traducido | Aviso | Se revisa antes de cargar |
| Calidad del inglés | — | Se señalan las traducciones automáticas erróneas; la corrección pasa por el formulario |
| Carga dual y bundle sano | — | DEV y QA en la misma corrida; validate en content: [] |
¶ 7. Lo que no se hace
- No se escribe en la hoja. Ni filas, ni estados, ni encabezados. Una fila escrita a mano no se carga.
- No se inserta ni se edita un literal directamente en
simappe_admin(DEV ni QA). El texto que manda es el que pasó por el formulario; un cambio hecho a mano en la base se pierde o diverge entre ambientes. - No se registra el mismo literal con el otro tipo para «forzar» una corrección.
- No se registra un inglés sin leerlo. El traductor sugiere; quien registra responde por el texto.
- No se crea una clave nueva para corregir un texto. Se corrige registrando de nuevo el mismo literal.
¶ 8. Alternativas consideradas
| Alternativa | Por qué no |
|---|---|
| Hoja editable por el equipo (lo que había) | Es el origen de todos los incidentes de la sección 2: dos puntos de entrada y ningún control |
| Google Forms vinculado | Escribe en una hoja de respuestas aparte y no puede validar contra lo ya registrado (duplicados, choques, correcciones) |
| Panel lateral dentro de la hoja | Se ejecuta con la cuenta de quien lo usa: exige permiso de edición sobre la hoja, y con él todo lo demás |
| Que cada equipo cargue sus literales en la base | Rompe la carga dual DEV+QA y deja claves sin script versionado: es la divergencia entre ambientes que ya se midió |
¶ 9. Consecuencias
Positivas
- Un solo punto de entrada: la hoja ya no se puede dañar desde fuera.
- Trazabilidad completa: quién pidió, cuándo, qué texto y cuándo se cargó; las correcciones dejan historial.
- Backend y frontend separados, cada uno con su convención y sus reglas SAR.
- Toda clave cargada queda en un script versionado y en los dos ambientes.
- Carga por archivo con vista previa: el equipo conserva la automatización (generar la lista desde el código) sin un segundo punto de entrada.
- El inglés sugerido usa el contexto del ERP (glosario por módulo y textos ya aprobados) antes que el traductor.
Limitaciones conocidas
- Cada persona autoriza el formulario con su cuenta una vez y ve el aviso de «app no verificada» de Google (sección 4).
- Dar o quitar acceso son dos pasos que hace arquitectura: el correo en «Usuarios autorizados» (para registrar) y el acceso de Lector en el archivo (para abrir el formulario y consultar la hoja). Quitar a alguien de la lista le corta el registro aunque conserve la lectura.
- Abrir el formulario requiere tener acceso de lectura a la hoja, porque se ejecuta con la cuenta de quien lo abre y la consulta.
- El formulario valida forma y duplicados dentro de la hoja; la convención SAR de cada frente y el cruce con las bases los valida arquitectura en la carga.
- El contexto de la traducción es determinista (glosario y reglas): cubre bien etiquetas y términos del negocio, pero en frases largas el traductor sigue sin entender el contexto. Por eso el inglés siempre se revisa.
- Si la respuesta del escritor se pierde (Google devuelve un error al leerla después de escribir), el formulario confirma el registro leyendo la hoja y lo informa como «confirmado directamente en la hoja».
¶ 10. Mantenimiento del formulario
-
El código vive en el proyecto Apps Script «Centrica - Fabrica de Software - Registro i18n», ligado a la hoja (
Código.gsyPanel.html). -
El proyecto tiene dos implementaciones activas:
Implementación Ejecutar como Acceso Uso Formulario i18n Usuario que accede a la app web Cualquier persona con cuenta de Google (y solo registran los autorizados) El enlace de la sección 4 Escritor i18n (no compartir) Arquitectura Cualquiera, protegido con la clave interna CLAVE_ESCRITORde las propiedades del scriptLo llama el formulario; su enlace va en la constante URL_ESCRITORdeCódigo.gs -
Para publicar un cambio: Implementar → Administrar implementaciones → editar → Nueva versión. Así el enlace no cambia. Crear una implementación nueva genera otro enlace y obliga a recomunicarlo. Si cambia el código de
doPosto de la escritura, la nueva versión se publica también en el escritor. -
La función
instalarSeguridad()se ejecutó una vez el 7-oct-2026: creó la clave interna del escritor y la columna «Usuarios autorizados» en Listas, con los 6 correos que ya habían registrado literales y la cuenta de arquitectura. Volver a ejecutarla no cambia la clave ni duplica correos.probarEscritor()comprueba la conexión con el escritor sin escribir nada (debe responder{"ok":true}). -
La función
instalarGlosario()se ejecutó una vez el 9-oct-2026: creó en Listas las columnas del glosario con 44 términos de partida (comunes, presupuesto, contabilidad y tesorería), tomados de las correcciones de inglés ya hechas. Volver a ejecutarla no duplica términos. Después el glosario se mantiene a mano en Listas.probarSugerencias()muestra en el registro de ejecución qué sugiere el formulario para casos conocidos. -
La plantilla del archivo la sirve el mismo formulario: su enlace con
?plantilla=1descargaplantilla_literales_i18n.csv. -
La función
instalarEstructura()se ejecutó una vez el 7-oct-2026: creó i18n - Backend, movió allí los 56 literales de backend, corrigióSolitado→Solicitadoy protegió las tres pestañas. Volver a ejecutarla no duplica la pestaña ni mueve filas; reaplica la corrección del estado y la protección.
¶ HISTORIAL DE CAMBIOS
| Versión | Fecha | Autor | Descripción |
|---|---|---|---|
| 1.2.0 | 2026-10-09 | Carlos Torres | Carga por archivo (Excel o CSV de 4 columnas, hasta 200 filas) con vista previa por fila y registro en bloque; inglés sugerido con contexto del ERP (glosario por módulo en Listas, textos ya aprobados y traductor con marcadores protegidos y reglas por tipo de clave); el formulario rechaza marcadores distintos entre español e inglés; si se pierde la respuesta del escritor, el registro se confirma leyendo la hoja. Formulario y escritor en la versión 7, mismos enlaces |
| 1.1.1 | 2026-10-07 | Carlos Torres | El proyecto Apps Script pasa de «Proyecto sin título» a «Centrica - Fabrica de Software - Registro i18n» (nombre que muestra Google al autorizar el formulario); las URL no cambian |
| 1.1.0 | 2026-10-07 | Carlos Torres | Acceso por correo verificado: el formulario (versión 4, mismo enlace) se ejecuta con la cuenta de quien lo abre y solo registran los «Usuarios autorizados»; la escritura pasa a una implementación escritora protegida con clave interna; el archivo pasa de «Cualquier persona con el enlace» a acceso restringido, con Lector solo para los correos autorizados |
| 1.0.1 | 2026-10-07 | Carlos Torres | El acceso general del archivo pasa de Editor a Lector; el formulario (versión 2 de la implementación, mismo enlace) incorpora descripciones explicativas por campo |
| 1.0.0 | 2026-10-07 | Carlos Torres | Versión inicial: formulario como único punto de entrada, pestañas Backend/Frontend protegidas, correcciones por re-registro con estado Reemplazado, reglas de nombrado apoyadas en SAR y reglas de control |