Wiki Editor y Auto-traduccion

Editor markdown integrado en workspace.crearack.com que permite editar articulos de la wiki directamente desde el navegador, con traduccion automatica al ingles para alimentar el Help Widget de CreaRack Pro.

Arquitectura general

Editor (workspace)          Cloudflare Pages Functions          GitHub API
     |                              |                              |
     |  POST /api/wiki/content      |                              |
     |  (content_b64)               |                              |
     |----------------------------->|  PUT contents/wiki/file.md   |
     |                              |----------------------------->|
     |                              |           commit ES          |
     |                              |<-----------------------------|
     |   200 OK (commit sha)        |                              |
     |<-----------------------------|                              |
     |                              |                              |
     |  POST /api/wiki/translate    |                              |
     |----------------------------->|  GET wiki/file.md (ES)       |
     |                              |----------------------------->|
     |                              |<-----------------------------|
     |                              |                              |
     |                              |  Gemini 2.5 Flash            |
     |                              |  (traduce title+desc+body)   |
     |                              |                              |
     |                              |  PUT wiki-en/file.md (EN)    |
     |                              |----------------------------->|
     |                              |  PUT wiki-en/titles.json     |
     |                              |----------------------------->|
     |   200 OK                     |                              |
     |<-----------------------------|                              |

Flujo completo paso a paso

1. Acceder al editor

Cada articulo de la wiki tiene un boton Editar en la esquina superior derecha. Al pulsarlo, navega a:

/wiki/edit?file=crearack--conceptos--que-es-crearack.md&return=/wiki/crearack/conceptos/que-es-crearack

El parametro file usa el formato de nombre de archivo plano (con -- como separador), no el slug (con /). La pagina [...slug].astro se encarga de la conversion automaticamente.

2. Cargar el contenido

El editor llama a GET /api/wiki/content?file=<nombre>.md que:

Lee el archivo desde GitHub API (rama main)
Devuelve: contenido raw (con frontmatter), SHA del archivo, y ruta

3. Editar

El editor presenta dos paneles side-by-side:

Izquierda: textarea con el markdown raw (incluyendo frontmatter YAML)
Derecha: vista previa HTML renderizada en tiempo real

Funcionalidades:

Ctrl+S guarda
Tab inserta 2 espacios
Wide mode se activa automaticamente (el editor necesita todo el ancho)
Aviso de cambios sin guardar al intentar salir

4. Guardar (commit en GitHub)

Al pulsar Guardar, el editor:

Codifica el contenido en base64 (necesario para evitar que Cloudflare WAF bloquee markdown como XSS)
Envia POST /api/wiki/content con { file, content_b64, sha }
La CF Pages Function decodifica y commitea en GitHub via API
Refetch del SHA para permitir ediciones sucesivas

5. Auto-traduccion (commit EN en GitHub)

Inmediatamente despues de guardar, el editor dispara (fire-and-forget):

POST /api/wiki/translate { file: "nombre-del-archivo.md" }

La CF Pages Function translate.ts:

Lee el archivo ES recien commiteado desde GitHub API
Traduce frontmatter quirurgicamente — solo title y description via Gemini, category_label via mapa estatico. NO envia el YAML completo a Gemini (esto causaba alucinaciones)
Traduce el body completo con Gemini 2.5 Flash
Commitea la version EN en src/content/wiki-en/
Actualiza wiki-en/titles.json (mapa ES→EN de titulos)

El editor muestra el estado: “Guardado — traduciendo EN…” → “Guardado + traducido EN” o “Guardado (traduccion fallida)”.

El Help Widget de CreaRack Pro (/api/help/*) lee automaticamente las versiones EN:

/api/help/wiki — lista categorias y articulos (titulos EN via titles.json)
/api/help/article?path=wiki-en/... — contenido HTML del articulo traducido

No requiere ningun paso adicional — al estar en GitHub, el Help Widget lo lee en la siguiente peticion.

Archivos del sistema

Workspace (CreaRackSL-workspace)

Archivo	Funcion
`src/pages/wiki/edit.astro`	Pagina del editor (UI + logica JS)
`src/pages/wiki/[...slug].astro`	Boton “Editar” en cada articulo
`functions/api/wiki/content.ts`	GET (leer) + POST (guardar) via GitHub API
`functions/api/wiki/translate.ts`	Traduccion individual ES→EN via Gemini
`functions/api/biblioteca/wiki-titles.ts`	Servir titles.json (mapa titulos ES→EN)
`src/content/wiki/`	Articulos en espanol (fuente de verdad)
`src/content/wiki-en/`	Articulos traducidos al ingles
`src/content/wiki-en/titles.json`	Mapa de titulos ES→EN

CreaRack Pro

Archivo	Funcion
`core/api_help.py`	Proxy `/api/help/*` — transforma ES→EN para el widget
`static/js/alpine-components.js`	Componente Alpine `helpWidget`
`templates/base.html`	HTML del panel Help (en todas las paginas)

Script legacy

Archivo	Funcion
`scripts/translate-wiki.mjs`	Batch translation (manual). Tiene bug de alucinacion en frontmatter — usar el endpoint `translate.ts` en su lugar

Variables de entorno requeridas (CF Pages)

Variable	Proposito
`GH_PAT`	GitHub Personal Access Token con Contents: Read and write
`GOOGLE_AI_API_KEY`	API key de Google AI para Gemini (traduccion)

Gotchas y consideraciones

Formato del parametro file

Los articulos wiki usan dos formatos:

Slug (URLs): crearack/conceptos/que-es-crearack (con /)
Filename (archivos): crearack--conceptos--que-es-crearack.md (con -- y .md)

La API siempre espera el formato filename. La conversion se hace en [...slug].astro (al generar el enlace Editar) y en edit.astro (al normalizar el parametro recibido).

Cloudflare WAF y base64

Cloudflare WAF inspecciona el body de las peticiones POST y bloquea contenido que parezca XSS/injection (markdown con headers #, HTML, code blocks). La solucion es enviar el contenido codificado en base64:

// Browser (edit.astro)
content_b64: btoa(unescape(encodeURIComponent(textareaEl.value)))

// Server (content.ts) — pasa directo a GitHub API que tambien espera base64
const base64 = content_b64;

Traduccion quirurgica del frontmatter

El script legacy (translate-wiki.mjs) enviaba el frontmatter YAML completo a Gemini, que alucinaba contenido inventado (ej: “Installation Guide” en vez de traducir). El endpoint translate.ts resuelve esto traduciendo solo los campos title y description como strings individuales, y usando un mapa estatico para category_label.

GH_PAT permisos

El token necesita Contents: Read and write (fine-grained) o scope repo (classic) para poder commitear via GitHub API. Solo con Read, las escrituras devuelven 403.

Doble commit

Cada edicion genera dos commits en GitHub:

wiki: update <nombre> — version ES
wiki-en: auto-translate <nombre> — version EN + titles.json

Esto es normal y esperado.

Véase también

[[workspace-tech—tecnico—workspace-technical]] — stack técnico
[[runbook—wiki—obsidian-setup]] — Obsidian setup
[[workspace-tech—tecnico—ai-workflow]] — AI workflow
[[feature—biblioteca—escriba-drift]] — escriba drift
[[crearack-tech—backend—biblioteca]] — biblioteca técnica
[[feature—ux—help-widget]] — Help Widget + Wiki EN que consume el editor

Wiki Editor y Auto-traduccion

Wiki Editor y Auto-traduccion

Arquitectura general

Flujo completo paso a paso

1. Acceder al editor

2. Cargar el contenido

3. Editar

4. Guardar (commit en GitHub)

5. Auto-traduccion (commit EN en GitHub)

6. Servir en Help Widget

Archivos del sistema

Workspace (CreaRackSL-workspace)

CreaRack Pro

Script legacy

Variables de entorno requeridas (CF Pages)

Gotchas y consideraciones

Formato del parametro file

Cloudflare WAF y base64

Traduccion quirurgica del frontmatter

GH_PAT permisos

Doble commit

Véase también