@almonte-devs/nombres-chilenos

Detector de género basado en nombres de pila chilenos/hispanos. Diccionario local, sin dependencias, soporta nombres compuestos.

Por qué

Los 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 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.

Objetivo: asignar un avatar/saludo razonable por defecto. Cualquier UI consumidora debe permitir al usuario corregirlo.

Instalación

El paquete se publica en GitHub Packages bajo la org Almonte-Devs. Cualquier app interna puede consumirlo así:

1. Configura el registry en el proyecto consumidor

Agrega un .npmrc en la raíz del repo consumidor:

@almonte-devs:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

El 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.

2. Instala

npm install @almonte-devs/nombres-chilenos

3. (Opcional) Next.js

Si usas Next.js, agrega a next.config.js:

const nextConfig = {
  transpilePackages: ['@almonte-devs/nombres-chilenos'],
}

Uso básico

import { detectar } from '@almonte-devs/nombres-chilenos'

detectar('María José López')
// → { genero: 'F', confianza: 1, razon: 'regla-compuesto', primerNombre: 'maria', segundoNombre: 'jose' }

detectar('José María')
// → { genero: 'M', confianza: 1, razon: 'regla-compuesto', ... }

detectar('Camila')
// → { genero: 'F', confianza: 0.95, razon: 'match-primer-nombre', ... }

detectar('Andrés Felipe')
// → { genero: 'M', confianza: 0.95, razon: 'match-primer-nombre', ... }

detectar('Alex Carolina')
// → { genero: 'F', confianza: 0.8, razon: 'match-segundo-nombre', ... }

detectar('Nombre Raro')
// → { genero: null, confianza: 0, razon: 'desconocido', ... }

Separar nombre completo (separarNombreCompleto)

Para importadores de nóminas (CSV/Excel SIGE, MINEDUC, planillas internas) que reciben un nombre completo en una sola columna y necesitan partirlo en sus 4 componentes canónicos.

import { separarNombreCompleto } from '@almonte-devs/nombres-chilenos'

separarNombreCompleto('ANDRÉS ORLANDO DE LA HOZ MARTÍNEZ')
// {
//   primerNombre: 'Andrés',
//   segundoNombre: 'Orlando',
//   primerApellido: 'De la Hoz',
//   segundoApellido: 'Martínez',
//   display: 'Andrés Orlando De la Hoz Martínez',
//   ordenDetectado: 'estandar',
//   esNombreCompuesto: false,
//   esApellidoCompuestoPaterno: true,
//   esApellidoCompuestoMaterno: false,
//   advertencias: [],
//   trazas: [...],
// }

separarNombreCompleto('MARÍA JOSÉ ÁLVAREZ ROSAS')
// → primerNombre: 'María José', primerApellido: 'Álvarez', segundoApellido: 'Rosas'

separarNombreCompleto('TOMÁS CRISTÓBAL MONTES DE OCA GÓMEZ')
// → primerNombre: 'Tomás', segundoNombre: 'Cristóbal',
//   primerApellido: 'Montes de Oca', segundoApellido: 'Gómez'

// Formato SIGE invertido (Valdivia: "Apellidos Nombres")
separarNombreCompleto('MADARIAGA MENDOZA MARÍA DE LOS ÁNGELES', { forzarOrden: 'invertido' })
// → primerNombre: 'María de los Ángeles',
//   primerApellido: 'Madariaga', segundoApellido: 'Mendoza'

Opciones

interface SeparacionOptions {
  /** 'estandar' (nombres primero) | 'invertido' (apellidos primero, formato SIGE Valdivia). */
  forzarOrden?: 'estandar' | 'invertido'
  /** Apellidos compuestos extra del dominio del consumer. */
  apellidosCompuestosExtras?: string[]
  /** Nombres compuestos extra. */
  nombresCompuestosExtras?: string[]
}

Si no se pasa forzarOrden, se detecta automáticamente comparando cuántos tokens del inicio vs. del final están en los datasets de nombres conocidos.

Datasets exportados

import {
  NOMBRES_COMPUESTOS, SET_NOMBRES_COMPUESTOS,
  APELLIDOS_COMPUESTOS, SET_APELLIDOS_COMPUESTOS,
  PARTICULAS_PREFIJO_APELLIDO, CONECTORES_APELLIDO,
} from '@almonte-devs/nombres-chilenos'

API

detectar(nombre: string): ResultadoDeteccion

Devuelve:

type ResultadoDeteccion = {
  genero: 'F' | 'M' | null
  confianza: number          // 0 a 1
  razon:
    | 'regla-compuesto'      // confianza 1.0
    | 'match-primer-nombre'  // confianza 0.95
    | 'match-segundo-nombre' // confianza 0.8
    | 'sufijo'               // confianza 0.55 (heurística débil)
    | 'ambiguo'              // confianza 0 (hay que preguntar)
    | 'desconocido'          // confianza 0
    | 'vacio'                // confianza 0
  primerNombre: string | null
  segundoNombre: string | null
}

Helpers

• esFemenino(nombre) → boolean
• esMasculino(nombre) → boolean
• esAmbiguo(nombre) → true si se detectó pero no hay género claro
• normalizar(nombre) → minúsculas + sin tildes
• tokenizar(nombre) → array de tokens normalizados

Datos crudos

import {
  NOMBRES_FEMENINOS, SET_FEMENINOS,
  NOMBRES_MASCULINOS, SET_MASCULINOS,
  NOMBRES_AMBIGUOS, SET_AMBIGUOS,
  REGLAS_COMPUESTOS,
} from '@almonte-devs/nombres-chilenos'

Algoritmo

1. Normalizar: lowercase, sin tildes, tokenizar por espacios y guiones.
2. 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).
3. Match directo: primer token en femeninos → F; en masculinos → M. Confianza 0.95.
4. Match por segundo nombre: si primer token es ambiguo o no coincide, miramos el segundo. Confianza 0.8.
5. Heurística de sufijo: último recurso — terminaciones comunes (-ela, -ina, -ita → F; -o, -er, -io → M). Confianza 0.55, usar con criterio.
6. Ambiguo / desconocido: retorna genero: null. El consumidor debe preguntar al usuario.

Limitaciones conocidas

• 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.
• Nombres unisex verdaderos (Alexis, Ariel, Cruz): requieren segundo nombre o input del usuario.
• Nombres con tildes y acentos: se normalizan, pero si el nombre tiene caracteres no-latinos (chino, árabe, cirílico) el tokenizador puede fallar.
• Personas trans / no binarias: este detector es una heurística, no una verdad. Siempre permitir corrección manual en la UI.

Extender el diccionario

Si encontrás un nombre que debería estar y no está, agregalo al archivo correspondiente en src/data/:

• femeninos.ts — nombres femeninos
• masculinos.ts — nombres masculinos
• ambiguos.ts — nombres unisex (requieren desempate)

Mantener lowercase y sin tildes. El normalizador se encarga de hacer match con variantes del input.

Proyectos que lo usan

• moraleja.mira — pre-selección de género en registro de profesor para avatar DiceBear (getDefaultAvatarUrl) + separación canónica de nombres en importador de alumnos SIGE.
• 1630.intranet.crm — importador de nóminas Excel de colegios con separarNombreCompleto.
• 1630.intranet — importador de alumnos en MIRA-2026 (sigue handoff docs/integraciones/handoff-intranet-importador-nombres.md).
• (agregar cuando se integre en otros proyectos)

Licencia

Uso interno 1630 (privado).