Claude Code Skills para i18n: Creación de comandos de automatización de traducción personalizados

The moment I realized I was doing i18n wrong

El mes pasado estuve trabajando en una funcionalidad que afectaba a unos 15 componentes. Nada loco, sólo una revisión de la configuración. Pero cuando terminé, tenía más de 40 cadenas nuevas esparcidas por el código base, todas codificadas en inglés.

Mi flujo de trabajo habitual: terminar la función, luego pasar una hora buscando todas las cadenas codificadas, extrayéndolas a claves de traducción, ejecutando la herramienta de traducción y esperando no haberme saltado ninguna.

Entonces un colega me enseñó su configuración de Claude Code. Escribió /i18n-extract en su terminal y Claude encontró todas las cadenas codificadas en sus archivos, las extrajo a las claves de traducción, actualizó los componentes y envió las traducciones a nuestro TMS. Todo en unos 30 segundos.

Pasé el fin de semana siguiente desarrollando mis propias habilidades. Esto es todo lo que aprendí.

¿Qué son las habilidades de Claude Code?

Si no has usado Claude Code (la CLI de Anthropic para Claude), piensa que es como tener a Claude directamente en tu terminal. Puedes hacerle preguntas, editar archivos, ejecutar comandos - básicamente programación en pareja con una IA.

Las habilidades son comandos personalizados que tú defines. En lugar de explicar lo que quieres cada vez, creas una habilidad una vez y la invocas con un simple comando. Como los alias del shell, pero para flujos de trabajo asistidos por IA.

Para el trabajo de i18n, esto es perfecto. Las tareas de traducción son repetitivas, siguen patrones consistentes y se benefician enormemente de la automatización.

Configurando tu primera habilidad i18n

Empecemos con algo sencillo. Cree un archivo en .claude/commands/i18n-scan.md con instrucciones para que Claude escanee el archivo actual o archivos específicos en busca de cadenas codificadas que deban ser internacionalizadas.

Dígale qué debe buscar: Contenido de texto JSX entre etiquetas, literales de cadena en contextos orientados al usuario (etiquetas, mensajes, títulos), literales de plantilla que contengan texto visible para el usuario y texto de marcador de posición en entradas.

Dile qué debe ignorar: mensajes console.log, mensajes de error para desarrolladores (a menos que estén orientados al usuario), nombres de clases CSS, rutas de importación y claves de objetos que sean identificadores internos.

Especifique el formato de salida: para cada cadena codificada encontrada, muestre el número de línea, la cadena codificada, una clave de traducción sugerida (siguiendo el patrón namespace.section.element) y el contexto sobre dónde aparece y para qué se utiliza.

Ahora, cuando ejecute /i18n-scan en Claude Code, entenderá exactamente lo que está buscando.

La habilidad que cambió mi flujo de trabajo: i18n-extract

Esta es la habilidad que más utilizo. No sólo encuentra cadenas, sino que las extrae y actualiza tu código.

Crea .claude/commands/i18n-extract.md con una descripción del proceso: identifica todas las cadenas hardcodeadas de cara al usuario, genera las claves de traducción apropiadas siguiendo tu convención de nomenclatura, actualiza el archivo para usar la función de traducción (t() o equivalente), añade cualquier importación necesaria, y crea o actualiza el archivo de traducción con las nuevas claves.

Defina su convención de nomenclatura. Las claves deben seguir namespace.section.element. Por ejemplo:

• settings.profile.title se convierte en "Configuración del perfil"
• common.buttons.save se convierte en "Guardar"
• errors.validation.required se convierte en "Este campo es obligatorio"

Incluir instrucciones de detección del framework: si se utiliza react-i18next, utilizar el hook useTranslation y la función t(); si se utiliza next-intl, utilizar el hook useTranslations; si se utiliza vue-i18n, utilizar $t() en las plantillas y t() en la configuración; si se utiliza FormatJS, utilizar FormattedMessage o useIntl.

Esta habilidad se encarga de todo el proceso de extracción. Lo ejecuto en cada archivo que toco, y mis cadenas están correctamente internacionalizadas incluso antes de hacer commit.

Conectando a tu sistema de gestión de traducción

La verdadera potencia viene de la integración con tu TMS. Crea una habilidad que utilice MCP (Model Context Protocol) para interactuar con IntlPull.

En .claude/commands/i18n-translate.md, describe un proceso para encontrar cadenas que existen en el idioma de origen pero a las que les faltan traducciones, y traducirlas. Tenga en cuenta los requisitos previos: el servidor MCP de IntlPull debe estar conectado y el proyecto debe estar configurado en IntlPull.

El proceso debe utilizar IntlPull MCP para obtener el estado actual del proyecto, identificar las claves con traducciones faltantes para los idiomas de destino, y para cada traducción faltante obtener el texto de origen, obtener cualquier traducción existente para el contexto, generar traducciones apropiadas, y empujar a IntlPull con la bandera de calidad "needs_review".

Para el manejo de idiomas, traducir a todos los idiomas del proyecto por defecto, o especificar el idioma de destino con /i18n-translate spanish.

Para el control de calidad, marque todas las traducciones generadas por la IA como "needs_review", incluya notas de traducción para los términos ambiguos y marque cualquier término que deba usar entradas de glosario.

Ahora /i18n-translate spanish envía las cadenas que faltan para la traducción de la IA, marcadas para revisión humana.

Habilidad para comprobar la cobertura de la traducción

Antes de desplegar, quiero saber si falta algo. Crea .claude/commands/i18n-status.md para obtener un informe de cobertura de traducción.

El informe debe incluir el porcentaje de cobertura global por idioma, los espacios de nombres en los que faltan traducciones, las claves añadidas recientemente sin traducción, las claves marcadas como "necesita_revisión" y las traducciones potencialmente obsoletas en las que la fuente haya cambiado después de la traducción.

Muéstrelo en forma de tabla con el idioma, el porcentaje de cobertura, el recuento de claves que faltan y el recuento de claves que necesitan revisión. A continuación, enumere las claves específicas que faltan agrupadas por espacios de nombres.

Si IntlPull MCP está conectado, extraiga los datos en tiempo real. De lo contrario, analice los archivos de traducción locales.

Habilidad para operaciones masivas

A veces es necesario actualizar muchas traducciones a la vez. Cree .claude/commands/i18n-bulk.md para operaciones por lotes con seguridad incorporada.

Las operaciones disponibles podrían incluir: rename-namespace (renombra un espacio de nombres en todos los idiomas), delete-unused (encuentra y opcionalmente borra las claves de traducción que no se usan en el código), merge-namespaces (combina múltiples espacios de nombres en uno), y sync-keys (añade las claves que faltan del idioma de origen a todos los idiomas de destino con valores vacíos).

Por motivos de seguridad, muestre siempre una vista previa de los cambios antes de aplicarlos, exija confirmación explícita para las operaciones destructivas, cree copias de seguridad de los archivos afectados antes de realizar cambios masivos y registre todos los cambios con fines de auditoría.

Hacer descubribles las competencias

Después de crear varias habilidades, añada una habilidad de ayuda en .claude/commands/i18n-help.md que enumere las habilidades disponibles relacionadas con i18n y su uso.

Crea una tabla con columnas para comando y descripción:

Incluye una sección de inicio rápido: abre un archivo con cadenas codificadas, ejecuta /i18n-extract para internacionalizarlo, ejecuta /i18n-translate para generar traducciones y ejecuta /i18n-status para verificar la cobertura.

Habilidad de validación para la integración CI

Crear .claude/commands/i18n-validate.md para detectar problemas comunes de traducción antes del despliegue. Este está diseñado para ejecutarse en CI pero también funciona localmente.

Las comprobaciones deben cubrir problemas estructurales (traducciones que faltan en idiomas que no son de origen, claves huérfanas que existen en las traducciones pero no en el código, sintaxis JSON/YAML no válida en los archivos de traducción, anidamiento incoherente entre idiomas), problemas de contenido (traducciones vacías, desajustes de marcadores de posición en los que {nombre} está en el código fuente pero no en la traducción, traducciones sospechosamente largas que podrían romper la interfaz de usuario, traducciones sospechosamente cortas que podrían estar incompletas, contenido no traducido que es el mismo que el del idioma de origen), y problemas de código (llamadas a t() con claves inexistentes, cadenas codificadas en cambios por etapas, construcción dinámica de claves).

Los niveles de salida deben ser: Error (debe corregirse antes del despliegue), Advertencia (debe revisarse) e Información (para conocimiento).

Códigos de salida: salida 0 si no hay errores, salida 1 si se encuentran errores, para integración CI.

Consejos profesionales de uso en producción

Después de meses de usar estas habilidades, esto es lo que he aprendido:

**Las habilidades genéricas funcionan, pero las habilidades específicas de la pila funcionan mejor. Si estás usando Next.js con next-intl, crea habilidades que entiendan específicamente esa configuración. Cuanto más contexto le des, mejor será el resultado.

**Empieza con /i18n-extract y /i18n-status. Añade más habilidades sólo cuando te encuentres repitiendo las mismas instrucciones. Las habilidades deben resolver fricciones reales, no problemas teóricos.

Controla la versión de tus habilidades. Pon .claude/commands/ en git. Cuando los compañeros de equipo actualicen su instalación de Claude Code, obtendrán tus habilidades automáticamente. Esto es especialmente valioso para la incorporación de nuevos desarrolladores.

Combínalo con las reglas del proyecto. En tu CLAUDE.md, añade directrices i18n: todas las cadenas de cara al usuario deben estar internacionalizadas, usa el formato namespace.section.element key, ejecuta /i18n-extract en cualquier archivo con cambios en la interfaz de usuario, ejecuta /i18n-validate antes de crear PRs. Ahora Claude sigue estas normas incluso fuera de las invocaciones de habilidades.

**Las habilidades son poderosas por sí solas, pero con la integración MCP, pueden interactuar con servicios externos. El servidor MCP de IntlPull permite a las competencias crear y actualizar claves de traducción, extraer traducciones actuales, enviar nuevas traducciones, comprobar el estado del proyecto y activar flujos de trabajo de traducción. Esto convierte a los skills de "sugerencias de IA" en "acciones de IA"

Ejemplo de flujo de trabajo real

Este es el aspecto que tiene ahora mi flujo de trabajo diario:

1. Iniciar la rama feature con git checkout -b feature/user-settings

2. Escribir código con cadenas codificadas. No me preocupo por i18n mientras construyo la característica. Iteración más rápida.

3. Antes de confirmar, en cada archivo modificado, ejecuta /i18n-extract. Claude actualiza el componente y crea claves de traducción.

4. Genera traducciones ejecutando /i18n-translate. Todos los idiomas soportados obtienen traducciones AI, marcadas para revisión.

5. Valídalas ejecutando /i18n-validate para detectar cualquier problema.

6. Confirmar. Todos los cambios, incluyendo las traducciones, van en un commit atómico.

Tiempo total añadido a mi flujo de trabajo: quizás 2-3 minutos por función. Compárelo con la hora que solía emplear.

Ideas de habilidades para tu equipo

Más allá de lo básico, he aquí algunas habilidades que he visto desarrollar a los equipos:

Para las transferencias de diseño: /i18n-from-figma para analizar la exportación de Figma y crear claves de traducción a partir del texto del diseño.

Para los equipos de contenidos: /i18n-suggest-improvements para revisar el tono, la claridad y la voz de la marca en las traducciones.

Para móviles: /i18n-length-check para marcar las traducciones que no se ajusten a las restricciones de la interfaz de usuario móvil.

Para la accesibilidad: /i18n-alt-text para generar traducciones de texto alternativo para las imágenes.

Para legal: /i18n-legal-review para marcar las traducciones que necesitan una revisión legal/de conformidad.

El futuro: Agentes de Claude Code para i18n

De cara al futuro, Claude Code está añadiendo soporte para flujos de trabajo multipaso más complejos. Imagina un agente que monitorice tus git diffs e internacionalice automáticamente las nuevas cadenas, una validación en segundo plano que detecte problemas de i18n antes de que confirmes, o una actualización automática de la traducción cuando cambien las cadenas fuente.

Estamos incorporando algunas de estas funciones al servidor MCP de IntlPull. La combinación de las habilidades de Claude Code y las integraciones MCP está cambiando realmente la forma en que los desarrolladores gestionan la localización.

Empezar hoy mismo

1. Instale Claude Code si no lo ha hecho: npm install -g @anthropic-ai/claude-code

2. Crea .claude/commands/ en tu proyecto

3. Añade la habilidad i18n-extract de este post

4. Pruébalo en un archivo con cadenas codificadas

5. Itere en función de lo que funcione para su pila

La inversión es tal vez una hora para configurar. El ahorro de tiempo se multiplica cada día.

---

*¿Quieres el paquete completo de habilidades? IntlPull mantiene una colección de habilidades de Claude Code listas para usar para i18n. Nuestro servidor MCP le da a Claude acceso directo para crear, actualizar y gestionar traducciones sin salir de su terminal