Context Crawler: Análisis de Sitios Web y Repositorios con IA para Traducciones más Inteligentes con better-i18n

Cómo better-i18n Construye Contexto de IA a Partir de tu Producto

La mayoría de los flujos de trabajo de localización comienzan con un paso manual: alguien etiqueta cadenas, exporta archivos y espera no haber omitido nada. better-i18n adopta un enfoque diferente. El Context Crawler combina dos potentes modos de análisis — crawling de sitios web y escaneo de repositorios — para construir automáticamente un contexto enriquecido que hace que las traducciones con IA sean drásticamente más precisas.

El resultado es un flujo de trabajo en el que tu traductor de IA comprende tu marca, el vocabulario de tu producto y tu stack tecnológico antes de traducir una sola cadena.

Análisis de Sitios Web: Descubrimiento de Marca Impulsado por Firecrawl

El modo de análisis de sitios web del Context Crawler utiliza la API de Firecrawl para rastrear y extraer contenido de forma sistemática desde cualquier URL que proporciones. No se trata de un simple scraping de HTML — Firecrawl gestiona páginas renderizadas con JavaScript, SPAs y contenido dinámico para capturar lo que los usuarios realmente ven.

Cómo Funciona el Análisis de Sitios Web

1. Proporciona una URL — Ingresa el sitio de marketing de tu producto, la documentación o cualquier propiedad web. El crawler acepta cualquier URL de acceso público.
2. Extracción con Firecrawl — La API de Firecrawl renderiza páginas, sigue enlaces internos y extrae contenido estructurado, incluyendo encabezados, texto del cuerpo, etiquetas de navegación, CTAs y metadatos.
3. Detección de terminología — El análisis con IA identifica términos repetidos, lenguaje de marca, nombres de productos, nombres de funcionalidades y vocabulario específico del dominio en todas las páginas rastreadas.
4. Propuesta de candidatos — Los términos detectados se proponen como candidatos para el glosario con definiciones sugeridas, notas de contexto y datos de frecuencia. Cada candidato incluye las URLs de origen donde fue encontrado.

Qué Captura el Análisis de Sitios Web

• Terminología de marca — Nombres de productos, nombres de funcionalidades, etiquetas de planes de precios y términos acuñados que aparecen de forma consistente en tu sitio
• Patrones de navegación — Etiquetas de menú, texto de breadcrumbs y lenguaje de CTAs que definen el vocabulario de tu producto
• Vocabulario del dominio — Términos específicos del sector que utiliza tu producto y que requieren una traducción precisa y consistente
• Señales de tono y voz — Si tu contenido es formal, informal, técnico u orientado al marketing — contexto que ayuda a la IA a traducir con el registro adecuado

Casos de Uso del Análisis de Sitios Web

• Configuración de nuevo proyecto — Rastrea tu sitio de marketing antes de comenzar la localización para crear un glosario y perfil de contexto en minutos en lugar de semanas
• Análisis de la competencia — Rastrea sitios de competidores en mercados objetivo para entender cómo traducen conceptos similares, informando tus propias decisiones de glosario
• Auditoría de contenido — Vuelve a rastrear periódicamente para detectar nueva terminología que haya surgido desde tu última actualización del glosario

Análisis de Repositorios: Detección de Framework y Terminología

El modo de análisis de repositorios del Context Crawler se conecta a tu repositorio de GitHub y realiza un análisis profundo de tu codebase para extraer contexto relevante para la traducción.

Cómo Funciona el Análisis de Repositorios

1. Conecta un repositorio de GitHub — Proporciona la URL del repositorio. El crawler accede a repos públicos directamente y a repos privados a través de tu integración con GitHub.
2. Detección de framework — El analizador identifica tu stack tecnológico: React, Next.js, Vue, Angular, Svelte, Flutter, React Native y otros. Esto determina qué patrones de i18n buscar y cómo parsear tu código.
3. Reconocimiento de patrones i18n — Basándose en el framework detectado, el analizador encuentra las llamadas a funciones de traducción existentes (t(), useTranslations(), $t(), tr(), etc.) y mapea cómo tu proyecto estructura sus traducciones.
4. Extracción de terminología — El analizador identifica cadenas hardcodeadas, nombres de componentes, etiquetas de rutas y otro texto visible para el usuario que representa el vocabulario de tu producto.
5. Generación del perfil de contexto — Todos los hallazgos se compilan en un perfil de contexto que incluye frameworks detectados, uso de la librería i18n, estructura de namespaces y candidatos de terminología.

Qué Detecta el Análisis de Repositorios

• Framework y librería i18n — Detección automática de tu stack para que las traducciones con IA utilicen las convenciones de formato correctas (ICU MessageFormat, interpolación de i18next, Flutter ARB, etc.)
• Estructura de namespaces — Cómo organiza tu proyecto las claves de traducción, para que las nuevas traducciones sigan los mismos patrones
• Terminología existente — Términos ya en uso en tu codebase, ayudando a identificar qué debería añadirse al glosario
• Patrones de cadenas — Patrones comunes en tus cadenas visibles para el usuario (formatos de fecha, formatos de número, enfoques de pluralización) que informan las reglas de traducción

Detección de Claves Basada en AST

Más allá de la construcción de contexto, el comando scan del CLI parsea tu código fuente a nivel de árbol sintáctico, no con frágil coincidencia de regex. Comprende de forma nativa los patrones de React JSX, useTranslations y getTranslations. Esto significa que puede distinguir entre una cadena visible para el usuario como <h1>Welcome back</h1> y una cadena técnica como className="flex items-center" sin falsos positivos.

Qué detecta:

• Texto JSX hardcodeado — contenido como <h1>Hello</h1> que debería envolverse en llamadas t()
• Atributos JSX hardcodeados — atributos visibles para el usuario como <img alt="Company logo" />
• Cadenas de toast y notificaciones — llamadas como toast.error("Something went wrong")
• Lógica ternaria basada en locale — patrones como locale === 'en' ? 'Hi' : 'Hola' que indican gestión manual del locale
• Variables de cadena — variables que contienen texto que parece estar dirigido al usuario

Qué ignora de forma inteligente:

• Nombres de clases de Tailwind y CSS
• URLs, rutas de archivo y fuentes de imágenes
• Entidades HTML (&, ")
• Constantes técnicas en SCREAMING_CASE
• Números y valores no textuales

better-i18n scan              # Escanea el directorio actual
better-i18n scan --dir ./src  # Escanea un directorio específico
better-i18n scan --staged     # Solo archivos en staging (para hooks pre-commit)
better-i18n scan --ci         # Exit code 1 si se encuentran problemas
better-i18n scan --format json # Salida JSON para herramientas
better-i18n scan --verbose    # Salida detallada con auditoría del escaneo

Resolución de Namespaces

El scanner utiliza seguimiento de scope léxico para resolver namespaces automáticamente tanto para componentes cliente como servidor. Esto es importante porque significa que las claves detectadas incluyen su ruta completa de namespace, no solo el nombre de la clave.

Para componentes cliente que usan hooks:

const t = useTranslations('hero');
return <h1>{t('title')}</h1>; // Detectado como: hero.title

Para componentes servidor que usan funciones async:

const t = await getTranslations('welcome');
return <h1>{t('title')}</h1>; // Detectado como: welcome.title

El scanner también gestiona la forma de objeto (getTranslations({ locale, namespace: 'settings' })) y traductores con scope raíz donde no se proporciona namespace. Los namespaces dinámicos que usan variables o template literals se reportan en modo --verbose y se excluyen de las métricas para evitar falsos positivos.

Del Análisis al Glosario: El Pipeline Completo

Los modos de análisis de sitios web y repositorios del Context Crawler alimentan directamente el sistema de Gestión de Glosarios:

1. Rastrear — El análisis de sitios web via Firecrawl extrae terminología de marca; el análisis de repositorios detecta contexto del framework y términos existentes.
2. Proponer — Los términos detectados se proponen como candidatos del glosario con estado de borrador.
3. Revisar — Tu equipo revisa los términos propuestos, editando definiciones y traducciones según sea necesario.
4. Aprobar — Los términos aprobados se aplican inmediatamente en la traducción con IA y en el editor de revisión.
5. Sincronizar — Los términos aprobados pueden sincronizarse con DeepL para su aplicación a nivel de proveedor.

Este pipeline significa que puedes pasar de "no tenemos glosario" a "nuestras traducciones con IA aplican 200 términos de marca" en una sola tarde.

Sync: Comparando Local vs Cloud

El comando sync cierra la brecha entre lo que utiliza tu código y lo que existe en better-i18n. Escanea tu codebase de la misma forma que scan, luego consulta la API de better-i18n para comparar conjuntos de claves.

El resultado es un informe de comparación claro:

• Faltantes en Remote — claves referenciadas en tu código pero que aún no se han subido a better-i18n. Estas son cadenas que tus usuarios podrían ver sin traducir.
• No utilizadas en el Código — claves que existen en better-i18n pero que ya no están referenciadas en ningún lugar de tu código fuente. Estas son candidatas para limpieza.

better-i18n sync              # Salida en árbol agrupado
better-i18n sync --summary    # Solo métricas de cobertura de alto nivel
better-i18n sync --format json # Salida JSON para automatización CI
better-i18n sync -d ./src     # Escanea un directorio específico

La salida en árbol agrupa las claves por namespace, facilitando ver qué partes de tu aplicación tienen brechas. El flag --verbose proporciona un registro detallado de auditoría que incluye comprobaciones de invariantes, resúmenes de scoping y sondas de claves específicas.

Métricas de Cobertura

El comando sync proporciona métricas de cobertura basadas en porcentajes:

• Cobertura Local a Remote: Qué porcentaje de claves utilizadas en tu código existen en better-i18n
• Uso en Remote: Qué porcentaje de claves en better-i18n se utilizan realmente en tu código

Estos números dan a tu equipo una imagen clara del estado de las traducciones en cualquier momento. Puedes verlos en la salida del terminal o extraerlos de la salida JSON para dashboards y reportes personalizados.

Integración con CI

Tanto scan como sync están diseñados para ejecutarse en pipelines automatizados. Usa --ci con scan para fallar los builds cuando se detecten cadenas hardcodeadas, y canaliza la salida de sync a través de jq para bloquear deploys según el número de claves faltantes.

# Ejemplo de GitHub Actions
name: i18n Check
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @better-i18n/cli scan --ci
      - run: |
          npx @better-i18n/cli sync --format json \
            | jq -e '.comparison.missingCount == 0' > /dev/null || exit 1

Para hooks pre-commit, escanea solo los archivos en staging para mantener el feedback rápido:

npx husky init
echo "npx @better-i18n/cli scan --staged --ci" > .husky/pre-commit

Qué No Hace

Para establecer expectativas claras:

• Sin captura de contexto visual — el CLI trabaja a nivel de código, no en la UI renderizada. No hay capturas de pantalla ni vistas previas visuales de dónde aparecen las cadenas.
• Sin monitorización en tiempo real — scan y sync se ejecutan bajo demanda o en pipelines CI; no son observadores en segundo plano ni monitores del sistema de archivos
• Sin detección de traducciones obsoletas — el comando sync muestra claves faltantes y no utilizadas, pero no detecta si una traducción existente está desactualizada en relación con un cambio en el texto fuente

Primeros Pasos

Instala el CLI y ejecuta tu primer escaneo en menos de un minuto:

npm install -g @better-i18n/cli
better-i18n scan --dir ./src

Luego conéctate a tu proyecto de better-i18n y compara con el cloud:

better-i18n sync

Para iniciar el análisis de sitios web, visita la sección AI Context en el dashboard de tu proyecto, ingresa una URL y deja que Firecrawl extraiga la terminología de tu marca. Para el análisis de repositorios, conecta tu repo de GitHub y deja que el analizador detecte tu framework y la terminología existente.

Consulta la documentación completa del CLI para opciones de configuración, reglas de detección y uso avanzado.

¿Listo para automatizar tu contexto de traducción y el descubrimiento de terminología? Crea tu cuenta y conecta tu primer proyecto — o descubre cómo el sistema de Gestión de Glosarios aplica los términos que descubre el crawler.