docs(i18n): ship Spanish translations of buyer-facing docs
Adds README.es.md, docs/README.es.md, docs/USER-GUIDE.es.md, and docs/CLI-REFERENCE.es.md mirroring the English client-facing set. Each English doc gains a one-line language-switch banner pointing at its Spanish counterpart; the docs index advertises both language sets in the buyer-facing section. Internal docs (TECHNICAL, DECISIONS, REQUIREMENTS, BUSINESS, RECOVERY) stay English-only by design — they don't ship with the product. The CLI itself emits English only, so CLI-REFERENCE.es.md notes that flags and values are language-invariant while translating the prose. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
239
docs/CLI-REFERENCE.es.md
Normal file
239
docs/CLI-REFERENCE.es.md
Normal file
@@ -0,0 +1,239 @@
|
||||
> 🌐 **Idioma:** Español · [English](CLI-REFERENCE.md)
|
||||
|
||||
# Referencia de la CLI
|
||||
|
||||
> ⚠️ Los comandos, banderas y valores de las opciones son **idénticos en ambos idiomas**. La CLI emite todos sus mensajes en inglés; este documento traduce las explicaciones, no los comandos.
|
||||
|
||||
Tres módulos de CLI, uno por cada herramienta Lista:
|
||||
|
||||
| Módulo | Comando | Propósito |
|
||||
|--------|---------|---------|
|
||||
| `src.cli` | `python -m src.cli FILE` | Eliminador de duplicados |
|
||||
| `src.cli_text_clean` | `python -m src.cli_text_clean FILE` | Limpiador de texto |
|
||||
| `src.cli_analyze` | `python -m src.cli_analyze FILE` | Analizador (escaneo de solo lectura) |
|
||||
|
||||
Cada comando es **previsualización por defecto** — añade `--apply` para escribir la salida.
|
||||
|
||||
---
|
||||
|
||||
# Eliminador de duplicados
|
||||
|
||||
```
|
||||
python -m src.cli ARCHIVO_ENTRADA [OPCIONES]
|
||||
```
|
||||
|
||||
## Opciones
|
||||
|
||||
### Generales
|
||||
- `--apply` — escribe los archivos de salida (por defecto: previsualización).
|
||||
- `-o, --output RUTA` — ruta de salida (por defecto `{input}_deduplicated.csv`).
|
||||
|
||||
### Selección de columnas
|
||||
- `-s, --subset COLS` — columnas separadas por comas en las que hacer la coincidencia (por defecto: detección automática).
|
||||
- `-k, --key COLS` — columnas de clave fuerte; cada una se convierte en una estrategia independiente de coincidencia exacta (`fb_id`, `ein`, `sku`).
|
||||
|
||||
### Coincidencia difusa
|
||||
- `--fuzzy COLS` — columnas separadas por comas para coincidencia difusa.
|
||||
- `-a, --algorithm ALG` — `levenshtein` / `jaro_winkler` (por defecto) / `token_set_ratio`.
|
||||
- `-t, --threshold N` — similitud 0-100 (por defecto 85).
|
||||
|
||||
### Normalización
|
||||
- `--normalize COL:TIPO` — pares `col:tipo` separados por comas. Tipos: `email`, `phone`, `name`, `address`, `string`.
|
||||
|
||||
| Tipo | Efecto | Ejemplo |
|
||||
|------|--------|---------|
|
||||
| `email` | minúsculas, elimina puntos de Gmail, elimina `+etiqueta` | `John.Doe+x@gmail.com` → `johndoe@gmail.com` |
|
||||
| `phone` | E.164 (extensión preservada) | `(555) 123-4567 ext 100` → `+15551234567;ext=100` |
|
||||
| `name` | elimina títulos + sufijos + partículas, baja a minúsculas | `Dr. Charles de Gaulle Jr.` → `charles gaulle` |
|
||||
| `address` | abreviaturas USPS + nombre de estado → 2 letras, minúsculas | `123 Main Street, California` → `123 main st ca` |
|
||||
| `string` | recorta + colapsa + minúsculas | ` HELLO WORLD ` → `hello world` |
|
||||
|
||||
### Selección del superviviente
|
||||
- `--survivor REGLA` — `first` (por defecto) / `last` / `most-complete` / `most-recent`.
|
||||
- `--date-column COL` — obligatoria para `most-recent`.
|
||||
- `--merge` — rellena los huecos del superviviente desde las filas eliminadas.
|
||||
|
||||
### Revisión interactiva
|
||||
- `--review` — pregunta s/n/saltar por cada grupo de coincidencias con diff lado a lado.
|
||||
|
||||
### Configuración
|
||||
- `--config RUTA` — carga toda la configuración desde un JSON.
|
||||
- `--save-config RUTA` — guarda la configuración actual en un JSON.
|
||||
|
||||
### Manejo de archivos
|
||||
- `--sheet NOMBRE|N` — nombre de hoja de Excel o índice base 0.
|
||||
- `--encoding ENC` — anula la codificación autodetectada.
|
||||
- `--header-row N` — fila de encabezado en base 0.
|
||||
|
||||
## Recetas
|
||||
|
||||
```bash
|
||||
# Deduplicación básica con autodetección
|
||||
python -m src.cli customers.csv [--apply]
|
||||
|
||||
# Coincidencia difusa de nombres al 80%
|
||||
python -m src.cli customers.csv --fuzzy name --threshold 80 --apply
|
||||
|
||||
# Múltiples claves fuertes (lógica OR)
|
||||
python -m src.cli donors.csv --key fb_id,ein --apply
|
||||
|
||||
# Fila más completa + fusionar campos faltantes
|
||||
python -m src.cli contacts.csv --survivor most-complete --merge --apply
|
||||
|
||||
# Más reciente + fusión
|
||||
python -m src.cli contacts.csv --survivor most-recent --date-column updated_at --merge --apply
|
||||
|
||||
# Revisión interactiva
|
||||
python -m src.cli customers.csv --review --apply
|
||||
|
||||
# Guardar / cargar perfil
|
||||
python -m src.cli customers.csv --fuzzy name --threshold 80 --save-config dedup.json
|
||||
python -m src.cli new.csv --config dedup.json --apply
|
||||
|
||||
# Excel
|
||||
python -m src.cli data.xlsx --sheet "Sales" --apply
|
||||
```
|
||||
|
||||
## Algoritmos
|
||||
|
||||
- **`jaro_winkler`** (por defecto) — el mejor para cadenas cortas (nombres); pondera los primeros caracteres.
|
||||
- **`levenshtein`** — ratio de distancia de edición; errores tipográficos y transposiciones.
|
||||
- **`token_set_ratio`** — el mejor para direcciones; ignora el orden de las palabras.
|
||||
|
||||
## Detección automática
|
||||
|
||||
Cuando no se pasan banderas `--subset` / `--fuzzy`, las columnas se detectan por su nombre:
|
||||
|
||||
| Patrón | Algoritmo | Umbral | Normalizador | Clave |
|
||||
|---------|-----------|-----------|------------|-----|
|
||||
| Email | exacto | 100% | email | fuerte |
|
||||
| Teléfono | exacto | 100% | phone | fuerte |
|
||||
| Nombre | jaro_winkler | 85% | name | débil |
|
||||
| Dirección | token_set_ratio | 80% | address | débil |
|
||||
|
||||
**Reglas de estrategia**: claves fuertes → OR independiente; claves débiles → AND emparejadas con cada clave fuerte; sin claves fuertes → las débiles se promueven a independientes; sin patrones → coincidencia exacta en todas las columnas.
|
||||
|
||||
## Archivos de salida (con `--apply`)
|
||||
|
||||
| Archivo | Contenido |
|
||||
|------|----------|
|
||||
| `{stem}_deduplicated.csv` | Datos limpios |
|
||||
| `{stem}_removed.csv` | Filas eliminadas |
|
||||
| `{stem}_match_groups.csv` | `_group_id`, `_is_survivor`, `_confidence`, `_matched_on`, `_original_row` + columnas originales |
|
||||
|
||||
Registro: `logs/dedup_YYYYMMDD_HHMMSS.log`.
|
||||
|
||||
---
|
||||
|
||||
# Limpiador de texto
|
||||
|
||||
```
|
||||
python -m src.cli_text_clean ARCHIVO_ENTRADA [OPCIONES]
|
||||
```
|
||||
|
||||
Higiene a nivel de carácter. Ver [TECHNICAL.md §10.2](TECHNICAL.md) (solo en inglés) para la especificación.
|
||||
|
||||
## Opciones
|
||||
|
||||
### Generales
|
||||
- `--apply` — escribe la salida (por defecto: previsualización).
|
||||
- `-o, --output RUTA` — ruta de salida (por defecto `{input}_cleaned.csv`).
|
||||
- `--preset NOMBRE` — `minimal` / `excel-hygiene` (por defecto) / `paranoid`.
|
||||
|
||||
### Alcance
|
||||
- `--columns COLS` — columnas separadas por comas a limpiar (por defecto: todas las columnas de texto).
|
||||
- `--skip COLS` — excluye estas columnas.
|
||||
|
||||
### Anulaciones por operación (anulan el preset activo)
|
||||
- `--no-trim`, `--no-collapse`, `--no-nfc`, `--nfkc`, `--no-smart-chars`, `--no-zero-width`, `--no-bom`, `--no-control`, `--no-line-endings`.
|
||||
|
||||
### Mayúsculas / minúsculas
|
||||
- `--case MODO` — `upper` / `lower` / `title` / `sentence`. O por columna: `--case title:name,upper:sku`.
|
||||
- El modo título preserva los tokens en mayúsculas (`USA`) y deja en minúsculas las partículas internas (`of`, `and`).
|
||||
|
||||
### Auditoría + configuración
|
||||
- `--full-changelog` — escribe todos los cambios (por defecto se limita a los primeros 1000).
|
||||
- `--config RUTA` / `--save-config RUTA`.
|
||||
|
||||
### Archivo
|
||||
- `--sheet`, `--encoding`, `--header-row` — iguales que en el Eliminador de duplicados.
|
||||
|
||||
## Presets
|
||||
|
||||
| Preset | Qué hace |
|
||||
|--------|--------------|
|
||||
| `minimal` | Solo recorte y colapso. |
|
||||
| `excel-hygiene` (por defecto) | Recorte, colapso, NFC, plegado de caracteres tipográficos, eliminación de caracteres invisibles, eliminación de BOM, eliminación de caracteres de control, normalización de finales de línea. |
|
||||
| `paranoid` | `excel-hygiene` + plegado de compatibilidad NFKC (con pérdida). |
|
||||
|
||||
## Recetas
|
||||
|
||||
```bash
|
||||
# Valores por defecto seguros (previsualiza, luego aplica)
|
||||
python -m src.cli_text_clean messy.csv [--apply]
|
||||
|
||||
# Solo recorte y colapso, sin tocar Unicode
|
||||
python -m src.cli_text_clean messy.csv --preset minimal --apply
|
||||
|
||||
# Nombres en formato título, SKUs en mayúsculas
|
||||
python -m src.cli_text_clean people.csv --case title:name,upper:sku --apply
|
||||
|
||||
# Limpiar solo columnas concretas
|
||||
python -m src.cli_text_clean orders.csv --columns vendor,product --apply
|
||||
|
||||
# Excluir una columna de notas en texto libre
|
||||
python -m src.cli_text_clean tickets.csv --skip notes --apply
|
||||
```
|
||||
|
||||
## Archivos de salida (con `--apply`)
|
||||
|
||||
| Archivo | Contenido |
|
||||
|------|----------|
|
||||
| `{stem}_cleaned.csv` | Datos limpios |
|
||||
| `{stem}_changes.csv` | `row`, `column`, `old`, `new`, `ops_applied` (limitado a 1000; `--full-changelog` quita el límite) |
|
||||
|
||||
Registro: `logs/text_clean_YYYYMMDD_HHMMSS.log`.
|
||||
|
||||
---
|
||||
|
||||
# Analizador
|
||||
|
||||
```
|
||||
python -m src.cli_analyze ARCHIVO_ENTRADA [OPCIONES]
|
||||
```
|
||||
|
||||
Escaneo de solo lectura; muestra todos los hallazgos del detector sin modificar el archivo.
|
||||
|
||||
## Opciones
|
||||
- `--sample-rows N` — límite de filas escaneadas (por defecto 1000).
|
||||
- `--json` — imprime los hallazgos como un array JSON en stdout.
|
||||
- `--strict` — sale con código no cero ante cualquier hallazgo `warn`/`error`.
|
||||
|
||||
## Esquema JSON (un objeto por hallazgo)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "smart_punctuation_in_data",
|
||||
"severity": "warn",
|
||||
"confidence": "high",
|
||||
"fix_action": "fold_smart_punctuation",
|
||||
"pre_applied": false,
|
||||
"tool": "02_text_cleaner",
|
||||
"count": 17,
|
||||
"description": "17 cell(s) contain curly quotes…",
|
||||
"column": null,
|
||||
"samples": [{"row": 3, "column": "name", "value": "“Alice”"}]
|
||||
}
|
||||
```
|
||||
|
||||
## Significado de los campos
|
||||
- `severity` — `info` / `warn` / `error`. Solo `error` bloquea la verificación de la GUI.
|
||||
- `confidence` — `high` (un clic), `medium` (previsualiza), `low` (opt-in).
|
||||
- `fix_action` — id del algoritmo en `src/core/fixes.py`. Vacío si es solo informativo.
|
||||
- `pre_applied` — `true` para correcciones ya aplicadas durante la lectura a nivel de bytes.
|
||||
|
||||
## Detectores
|
||||
|
||||
Puntuación tipográfica, espacios NBSP / Unicode, caracteres de ancho cero, encabezados sucios, relleno con espacios, centinelas tipo null, huellas de mojibake, columnas de email con mayúsculas/minúsculas mezcladas, formatos de fecha inconsistentes, filas casi duplicadas, identificadores con ceros a la izquierda, finales de línea mezclados, fallo de decodificación de codificación, presencia de U+FFFD.
|
||||
|
||||
Agregar un detector: añade la entrada en `analyze.py` y la corrección correspondiente en `fixes.py`. Ningún otro punto de llamada cambia.
|
||||
Reference in New Issue
Block a user