From d41a94b57de92d6754232c462569f525291f84aa Mon Sep 17 00:00:00 2001
From: Jordan Diaz <panksft@hotmail.com>
Date: Fri, 17 Apr 2026 10:24:43 +0000
Subject: [PATCH] Ajustes de translate

---
 docs/quick-reference.md |  2 +-
 docs/twig-filters.md    | 35 ++++++++++++++++++++++++++++++++++-
 2 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/docs/quick-reference.md b/docs/quick-reference.md
index 137e0e7..a073e61 100644
--- a/docs/quick-reference.md
+++ b/docs/quick-reference.md
@@ -55,7 +55,7 @@
 | `module` | `'module_id' \| module({params})` |
 | `queryDB` | `'SELECT ...' \| queryDB()` |
 | `imagec` | `path \| imagec(width)` |
-| `translate` | `'text' \| translate` |
+| `translate` | `'text' \| translate` — tabla `textos_generales` (editar/traducir), no crear JSONs i18n |
 | `json_decode` | `'json_string' \| json_decode` |
 | `raw` | `variable \| raw` |
 | `truncate` | `text \| truncate(100)` |
diff --git a/docs/twig-filters.md b/docs/twig-filters.md
index 6382801..dab9a85 100644
--- a/docs/twig-filters.md
+++ b/docs/twig-filters.md
@@ -91,13 +91,46 @@ Usar solo cuando `get` no sea suficiente.
              {{ record.image[0].urlPath | imagec(800) }} 800w" />
 ```
 
-## `translate` — Traducción
+## `translate` — Texto editable y traducción
+
+Cualquier string con `| translate` se resuelve contra la tabla
+`textos_generales` del proyecto. Esta tabla cumple **dos funciones a la vez**:
+
+1. **Traducción**: cada fila guarda la versión del texto por cada idioma
+   habilitado del proyecto.
+2. **Edición de contenidos**: es el canal oficial para que el usuario final
+   (o el agente) **modifique esos textos sin tocar código**. El filtro
+   `| translate` no es solo i18n — es el mecanismo por el que un texto
+   "hardcodeado" en una plantilla se vuelve editable desde el CMS.
 
 ```twig
 {{ 'Bienvenido' | translate }}
 {{ variable | translate }}
 ```
 
+**Cómo funciona:**
+- Los strings envueltos en `| translate` en las plantillas o en el código de
+  los módulos se buscan en `textos_generales`.
+- Si existe la fila, devuelve el valor guardado (en el idioma activo).
+- Si no existe, devuelve el texto original tal cual (fallback).
+- Las filas se editan desde el admin del CMS o via `cmsApi` (update sobre
+  `textos_generales`).
+
+**Reglas críticas para el agente:**
+- **No crees archivos JSON de traducciones, `.po`, ni ningún sistema i18n
+  externo**. El único sistema de textos traducibles/editables es la tabla
+  `textos_generales`.
+- **No hardcodees los textos en el código del módulo** si se espera que el
+  usuario pueda cambiarlos. Envuélvelos siempre en `| translate`:
+  `{{ 'Contáctanos' | translate }}` en vez de `Contáctanos`.
+- Para **cambiar un texto** (traducirlo o editarlo), el flujo correcto es
+  editar la fila correspondiente en `textos_generales` — nunca modificar
+  el código de la plantilla.
+- Para **añadir un texto nuevo editable**, basta con escribir el string en
+  el código con `| translate`; el sistema lo recogerá y el usuario podrá
+  editarlo desde el admin. No hace falta insertar la fila manualmente
+  (aunque se puede via `cmsApi` si quieres pre-cargar traducciones).
+
 ## `raw` — Renderizar HTML sin escapar
 
 ```twig