{"_id":"@almonte-devs/nombres-chilenos","name":"@almonte-devs/nombres-chilenos","dist-tags":{"latest":"1.3.0"},"versions":{"1.3.0":{"name":"@almonte-devs/nombres-chilenos","version":"1.3.0","description":"Diccionario maestro de nombres y apellidos chilenos/hispanos. Canonicaliza ortografía + capitalización y detecta género a partir del nombre. Diccionario local, sin dependencias, multi-proyecto.","main":"./dist/index.js","types":"./dist/index.d.ts","scripts":{"build":"tsc","prepublishOnly":"tsc","test":"npx tsx tests/run.ts"},"keywords":["chile","nombres","apellidos","genero","gender-detection","canonicalizar","hispano"],"repository":{"type":"git","url":"git+https://github.com/Almonte-Devs/nombres-chilenos.git"},"homepage":"https://github.com/Almonte-Devs/nombres-chilenos#readme","bugs":{"url":"https://github.com/Almonte-Devs/nombres-chilenos/issues"},"publishConfig":{"access":"public"},"devDependencies":{"typescript":"^5.4.0"},"license":"UNLICENSED","private":false,"_id":"@almonte-devs/nombres-chilenos@1.3.0","gitHead":"45bec7d2e201ab33468d2cae2d4a82b77896e5f1","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-+X3uFSg1+7fz29MNEM5eHOnnx+EweJhROdt+0xTIet9MLpAMM4h0TjG8h4QaK+tBtnAX6ksEnJlWYlMns84z2Q==","shasum":"b2d8b5bab52022cafb03d4328b37818ea82e80ac","tarball":"https://registry.npmjs.org/@almonte-devs/nombres-chilenos/-/nombres-chilenos-1.3.0.tgz","fileCount":31,"unpackedSize":466000,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDZIxnXEMVQCnH96TiNiKN/PVK3MYGbHZT1Gw17BHK68AIgPyIa6CVfQGKYXWVfaHUcWKkIeFYqNWIXPwBHbnofzlA="}]},"_npmUser":{"name":"aomardon","email":"aomardon@gmail.com"},"directories":{},"maintainers":[{"name":"aomardon","email":"aomardon@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/nombres-chilenos_1.3.0_1783123651869_0.2814609858216641"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-04T00:07:31.734Z","1.3.0":"2026-07-04T00:07:32.065Z","modified":"2026-07-04T00:07:32.287Z"},"maintainers":[{"name":"aomardon","email":"aomardon@gmail.com"}],"description":"Diccionario maestro de nombres y apellidos chilenos/hispanos. Canonicaliza ortografía + capitalización y detecta género a partir del nombre. Diccionario local, sin dependencias, multi-proyecto.","homepage":"https://github.com/Almonte-Devs/nombres-chilenos#readme","keywords":["chile","nombres","apellidos","genero","gender-detection","canonicalizar","hispano"],"repository":{"type":"git","url":"git+https://github.com/Almonte-Devs/nombres-chilenos.git"},"bugs":{"url":"https://github.com/Almonte-Devs/nombres-chilenos/issues"},"license":"UNLICENSED","readme":"# @almonte-devs/nombres-chilenos\n\nDetector de género basado en nombres de pila chilenos/hispanos. Diccionario local, sin dependencias, soporta nombres compuestos.\n\n## Por qué\n\nLos nombres chilenos comunes (Camila, Andrés, María José, Juan Pablo...) tienen un género fuertemente asociado. Este paquete usa un diccionario de ~11.5K nombres — combinación de curaduría manual sobre registros educacionales chilenos + el dataset [`rivaquiroga/guaguas`](https://github.com/rivaquiroga/guaguas) del Registro Civil de Chile (inscripciones 1920–2021) — más reglas para compuestos típicos (\"María José\" vs \"José María\") para inferir el género sin pedirlo al usuario.\n\n**Objetivo**: asignar un avatar/saludo razonable por defecto. Cualquier UI consumidora debe permitir al usuario corregirlo.\n\n## Instalación\n\nEl paquete se publica en **GitHub Packages** bajo la org `Almonte-Devs`. Cualquier app interna puede consumirlo así:\n\n### 1. Configura el registry en el proyecto consumidor\n\nAgrega un `.npmrc` en la raíz del repo consumidor:\n\n```\n@almonte-devs:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}\n```\n\nEl token debe ser un **Personal Access Token (classic)** con scope `read:packages`, expuesto como env var `GITHUB_TOKEN`. En local, guárdalo en `~/.credentials/global.env`. En CI/Vercel, configúralo como secret.\n\n### 2. Instala\n\n```bash\nnpm install @almonte-devs/nombres-chilenos\n```\n\n### 3. (Opcional) Next.js\n\nSi usas Next.js, agrega a `next.config.js`:\n\n```js\nconst nextConfig = {\n  transpilePackages: ['@almonte-devs/nombres-chilenos'],\n}\n```\n\n## Uso básico\n\n```ts\nimport { detectar } from '@almonte-devs/nombres-chilenos'\n\ndetectar('María José López')\n// → { genero: 'F', confianza: 1, razon: 'regla-compuesto', primerNombre: 'maria', segundoNombre: 'jose' }\n\ndetectar('José María')\n// → { genero: 'M', confianza: 1, razon: 'regla-compuesto', ... }\n\ndetectar('Camila')\n// → { genero: 'F', confianza: 0.95, razon: 'match-primer-nombre', ... }\n\ndetectar('Andrés Felipe')\n// → { genero: 'M', confianza: 0.95, razon: 'match-primer-nombre', ... }\n\ndetectar('Alex Carolina')\n// → { genero: 'F', confianza: 0.8, razon: 'match-segundo-nombre', ... }\n\ndetectar('Nombre Raro')\n// → { genero: null, confianza: 0, razon: 'desconocido', ... }\n```\n\n## Separar nombre completo (`separarNombreCompleto`)\n\nPara importadores de nóminas (CSV/Excel SIGE, MINEDUC, planillas internas) que reciben un\nnombre completo en una sola columna y necesitan partirlo en sus 4 componentes canónicos.\n\n```ts\nimport { separarNombreCompleto } from '@almonte-devs/nombres-chilenos'\n\nsepararNombreCompleto('ANDRÉS ORLANDO DE LA HOZ MARTÍNEZ')\n// {\n//   primerNombre: 'Andrés',\n//   segundoNombre: 'Orlando',\n//   primerApellido: 'De la Hoz',\n//   segundoApellido: 'Martínez',\n//   display: 'Andrés Orlando De la Hoz Martínez',\n//   ordenDetectado: 'estandar',\n//   esNombreCompuesto: false,\n//   esApellidoCompuestoPaterno: true,\n//   esApellidoCompuestoMaterno: false,\n//   advertencias: [],\n//   trazas: [...],\n// }\n\nsepararNombreCompleto('MARÍA JOSÉ ÁLVAREZ ROSAS')\n// → primerNombre: 'María José', primerApellido: 'Álvarez', segundoApellido: 'Rosas'\n\nsepararNombreCompleto('TOMÁS CRISTÓBAL MONTES DE OCA GÓMEZ')\n// → primerNombre: 'Tomás', segundoNombre: 'Cristóbal',\n//   primerApellido: 'Montes de Oca', segundoApellido: 'Gómez'\n\n// Formato SIGE invertido (Valdivia: \"Apellidos Nombres\")\nsepararNombreCompleto('MADARIAGA MENDOZA MARÍA DE LOS ÁNGELES', { forzarOrden: 'invertido' })\n// → primerNombre: 'María de los Ángeles',\n//   primerApellido: 'Madariaga', segundoApellido: 'Mendoza'\n```\n\n### Opciones\n\n```ts\ninterface SeparacionOptions {\n  /** 'estandar' (nombres primero) | 'invertido' (apellidos primero, formato SIGE Valdivia). */\n  forzarOrden?: 'estandar' | 'invertido'\n  /** Apellidos compuestos extra del dominio del consumer. */\n  apellidosCompuestosExtras?: string[]\n  /** Nombres compuestos extra. */\n  nombresCompuestosExtras?: string[]\n}\n```\n\nSi no se pasa `forzarOrden`, se detecta automáticamente comparando cuántos tokens del inicio\nvs. del final están en los datasets de nombres conocidos.\n\n### Datasets exportados\n\n```ts\nimport {\n  NOMBRES_COMPUESTOS, SET_NOMBRES_COMPUESTOS,\n  APELLIDOS_COMPUESTOS, SET_APELLIDOS_COMPUESTOS,\n  PARTICULAS_PREFIJO_APELLIDO, CONECTORES_APELLIDO,\n} from '@almonte-devs/nombres-chilenos'\n```\n\n## API\n\n### `detectar(nombre: string): ResultadoDeteccion`\n\nDevuelve:\n\n```ts\ntype ResultadoDeteccion = {\n  genero: 'F' | 'M' | null\n  confianza: number          // 0 a 1\n  razon:\n    | 'regla-compuesto'      // confianza 1.0\n    | 'match-primer-nombre'  // confianza 0.95\n    | 'match-segundo-nombre' // confianza 0.8\n    | 'sufijo'               // confianza 0.55 (heurística débil)\n    | 'ambiguo'              // confianza 0 (hay que preguntar)\n    | 'desconocido'          // confianza 0\n    | 'vacio'                // confianza 0\n  primerNombre: string | null\n  segundoNombre: string | null\n}\n```\n\n### Helpers\n\n- `esFemenino(nombre)` → boolean\n- `esMasculino(nombre)` → boolean\n- `esAmbiguo(nombre)` → true si se detectó pero no hay género claro\n- `normalizar(nombre)` → minúsculas + sin tildes\n- `tokenizar(nombre)` → array de tokens normalizados\n\n### Datos crudos\n\n```ts\nimport {\n  NOMBRES_FEMENINOS, SET_FEMENINOS,\n  NOMBRES_MASCULINOS, SET_MASCULINOS,\n  NOMBRES_AMBIGUOS, SET_AMBIGUOS,\n  REGLAS_COMPUESTOS,\n} from '@almonte-devs/nombres-chilenos'\n```\n\n## Algoritmo\n\n1. **Normalizar**: lowercase, sin tildes, tokenizar por espacios y guiones.\n2. **Regla de compuestos**: si el par (primer, segundo) está en `REGLAS_COMPUESTOS`, retorna con confianza 1. Resuelve casos como \"María José\" (F) vs \"José María\" (M), \"Juan Pablo\" (M), \"Ana María\" (F).\n3. **Match directo**: primer token en femeninos → F; en masculinos → M. Confianza 0.95.\n4. **Match por segundo nombre**: si primer token es ambiguo o no coincide, miramos el segundo. Confianza 0.8.\n5. **Heurística de sufijo**: último recurso — terminaciones comunes (`-ela`, `-ina`, `-ita` → F; `-o`, `-er`, `-io` → M). Confianza 0.55, usar con criterio.\n6. **Ambiguo / desconocido**: retorna `genero: null`. El consumidor debe preguntar al usuario.\n\n## Limitaciones conocidas\n\n- **Sesgo**: el diccionario no cubre nombres mapuches, indígenas de pueblos originarios, o de migrantes poco comunes. Si un nombre no está listado y tampoco calza el sufijo, retorna `desconocido`.\n- **Nombres unisex verdaderos** (Alexis, Ariel, Cruz): requieren segundo nombre o input del usuario.\n- **Nombres con tildes y acentos**: se normalizan, pero si el nombre tiene caracteres no-latinos (chino, árabe, cirílico) el tokenizador puede fallar.\n- **Personas trans / no binarias**: este detector es una **heurística**, no una verdad. Siempre permitir corrección manual en la UI.\n\n## Extender el diccionario\n\nSi encontrás un nombre que debería estar y no está, agregalo al archivo correspondiente en `src/data/`:\n\n- `femeninos.ts` — nombres femeninos\n- `masculinos.ts` — nombres masculinos\n- `ambiguos.ts` — nombres unisex (requieren desempate)\n\nMantener **lowercase y sin tildes**. El normalizador se encarga de hacer match con variantes del input.\n\n## Proyectos que lo usan\n\n- `moraleja.mira` — pre-selección de género en registro de profesor para avatar DiceBear\n  (`getDefaultAvatarUrl`) + separación canónica de nombres en importador de alumnos SIGE.\n- `1630.intranet.crm` — importador de nóminas Excel de colegios con `separarNombreCompleto`.\n- `1630.intranet` — importador de alumnos en MIRA-2026 (sigue handoff\n  `docs/integraciones/handoff-intranet-importador-nombres.md`).\n- _(agregar cuando se integre en otros proyectos)_\n\n## Licencia\n\nUso interno 1630 (privado).\n","readmeFilename":"README.md","_rev":"1-3dc2893895172ddccfcba863a8131f35"}