Mi Copiloto pasó de molesto a indispensable
Hace seis meses, estaba dispuesto a desactivar Copilot para todo lo relacionado con i18n. Seguía sugiriendo cadenas codificadas cuando yo quería claves de traducción. Autocompletaba "Cargando..." cuando yo quería t('common.loading'). No entendía nuestras convenciones de nomenclatura de claves. Frustrante.
Entonces descubrí la función de instrucciones personalizadas de Copilot. Pasé una tarde configurándola correctamente, y ahora es todo lo contrario. Copilot realmente ayuda con la localización en lugar de luchar contra ella.
Esta es la configuración que transformó mi flujo de trabajo.
El problema con el comportamiento por defecto de Copilot
Fuera de la caja, Copilot no sabe que usted quiere claves i18n en lugar de cadenas codificadas, sus convenciones de nomenclatura de claves, que la biblioteca de traducción que está utilizando, o que cierto texto no debe ser traducido (registros, mensajes dev).
Así que sugiere lo que hace la mayoría del código en GitHub: cadenas en inglés codificadas en todas partes.
La solución es enseñar a Copilot el enfoque i18n de TU proyecto.
Configurar las instrucciones personalizadas de Copilot
VS Code Copilot lee las instrucciones de .github/copilot-instructions.md. Crea este archivo en la raíz de tu proyecto.
Comienza con una sección sobre internacionalización. Explica que este proyecto utiliza react-i18next para todo el texto de cara al usuario y que NUNCA debe utilizar cadenas codificadas.
Cuando escriba texto de cara al usuario, utilice la función t() de useTranslation(). Utilice el componente Trans para la interpolación compleja. Siga el formato de clave namespace.section.element.
Ponga ejemplos: para los botones utilice t('common.buttons.save') y no "Save". Para los títulos, utilice t('settings.profile.title') y no "Configuración del perfil". Para los mensajes, utilice t('errors.network.timeout') y no "Se ha agotado el tiempo de espera de la conexión".
Especifica qué NO traducir: mensajes console.log, mensajes de error en bloques catch (para depuración), nombres de clases CSS, identificadores técnicos y etiquetas de entorno de desarrollo.
Enumera tus espacios de nombres: común para elementos de interfaz de usuario compartidos (botones, etiquetas), errores para mensajes de error, validación para mensajes de validación de formularios, autenticación para autenticación, configuración para la página de configuración y espacios de nombres específicos de funciones.
Después de añadir este archivo, las sugerencias de Copilot cambian radicalmente. Empieza a proponer claves de traducción en lugar de cadenas.
Hacer que Copilot entienda tu biblioteca de traducción
Diferentes proyectos utilizan diferentes bibliotecas i18n. Personalice sus instrucciones en consecuencia.
Para react-i18next, documenta el patrón de importación: import useTranslation from 'react-i18next', then destructure t from useTranslation('namespace'). Para componentes con HTML, utiliza Trans de react-i18next con una i18nKey y components prop. Para plurales, utilice t('items.count', { count: items.length }).
Para next-intl, en Server Components importa getTranslations de 'next-intl/server' y espéralo. En los componentes cliente, importa useTranslations de 'next-intl'. Ten en cuenta que los mensajes están en /messages/{locale}.json.
Para Vue I18n, en plantillas usa {{ $t('key.path') }}. En la configuración, desestructure t de useI18n() y llame a t('key.path').
Enseñar a Copilot tus convenciones de nomenclatura de claves
Aquí es donde ocurre la magia. Sea específico sobre cómo deben ser nombradas las claves.
Documente la estructura: las claves siguen namespace.section.element.
Documente los patrones:
- Títulos de página:
{page}.title(por ejemplo,settings.title) - Cabeceras de sección:
{page}.{section}.heading(por ejemplo,settings.profile.heading) - Botones:
{namespace}.buttons.{action}(por ejemplo,common.buttons.save) - Etiquetas:
{page}.form.{field}.label(por ejemplo,auth.form.email.label) - Marcadores de posición: CÓDIGO_BLOQUE_8
- Mensajes de error:
errors.{category}.{type}(por ejemplo,errors.validation.required) - Mensajes de éxito:
messages.success.{action}(por ejemplo,messages.success.saved)
Reglas de denominación de documentos: utilice camelCase para claves de varias palabras, sea descriptivo (deleteConfirmation no msg1), evite abreviaturas (numberOfItems no numItems) y agrupe claves relacionadas (todos los campos de formulario bajo .form.).
Con estos patrones, cuando se escribe t(' después de un botón, Copilot sugiere common.buttons. como prefijo.
Configuraciones específicas del espacio de trabajo
Para proyectos más grandes, es posible que desee diferentes configuraciones por espacio de trabajo.
En .vscode/settings.json, puedes establecer github.copilot.chat.localeOverride a "en-US" y configurar qué tipos de archivo tienen Copilot habilitado.
También puedes crear archivos de instrucciones específicos para cada espacio de trabajo que amplíen el principal.
Avisos que funcionan bien para tareas i18n
Más allá de las sugerencias pasivas, Copilot Chat es excelente para el trabajo activo de i18n. Estas son algunas de las instrucciones que utilizo habitualmente:
Extraer cadenas: "Extraer todas las cadenas codificadas de este archivo a claves de traducción. Utilice el espacio de nombres de configuración. Actualizar el JSX para usar t() y añadir las claves a mi archivo en.json"
Crear archivos de traducción: "Crear un archivo de traducción para español (es) basado en mi archivo inglés. Traducir las cadenas de UI de forma natural, mantener los términos técnicos, mantener la sintaxis de los marcadores de posición como {{name}}."
Encontrar cadenas codificadas: "Encuentra todas las cadenas hardcoded de cara al usuario en este componente que deberían ser internacionalizadas. No incluya console.log ni mensajes de error para depuración"
Generar claves perdidas: "Mira mi componente y compáralo con mi fichero de traducción. ¿Qué claves estoy usando que no existen en el archivo de traducción?"
Revisar traducciones: "Revisar estas traducciones al español para: flujo natural del lenguaje, manejo apropiado del plural, terminología consistente y cualquier problema de longitud que rompa la UI"
Integración con sistemas de gestión de traducción
Copilot no puede llamar directamente a las API (sin herramientas compatibles con MCP), pero aún así puede agilizar el flujo de trabajo.
Opción 1: Generar JSON listo para TMS. Añada a sus instrucciones que al generar nuevas claves de traducción, Claude también debe crear un archivo de importación TMS en formato JSON con los campos clave, valor, contexto (para traductores) y maxLength.
Opción 2: Integración CLI. Documente en sus instrucciones que después de añadir nuevas claves, el desarrollador debe ejecutar npx @intlpullhq/cli upload para enviar las nuevas claves a TMS y npx @intlpullhq/cli download para extraer las últimas traducciones.
Opción 3: Utilizar extensiones de Copilot. GitHub está desarrollando extensiones de Copilot que pueden llamar a API externas. Esté atento a las integraciones TMS disponibles. Esto permitirá una verdadera automatización de extremo a extremo.
Errores y correcciones comunes de Copilot i18n
Error 1: Sugerir una sintaxis de biblioteca incorrecta. Si Copilot sigue sugiriendo i18n.t() cuando utiliza t(), añada a las instrucciones: "NUNCA use: i18n.t(), i18next.t(), this.$t(). SIEMPRE use: t() del hook useTranslation()"
Error 2: Olvidar la importación del espacio de nombres. Si los componentes omiten la importación useTranslation, añade: "Cada componente con traducciones debe tener: import { useTranslation } from 'react-i18next'; and const { t } = useTranslation('namespace'); dentro del componente"
**Error 3: Inconsistencia en el nombre de las claves: "La denominación de las claves DEBE ser coherente. CORRECTO: settings.profileTitle (camelCase). INCORRECTO: settings.profile_title (snake_case). INCORRECTO: settings.profile-title (kebab-case)"
Error 4: Traducir contenido técnico. Añadir: "NO traducir: nombres de variables, puntos finales de API, mensajes de registro (a menos que estén orientados al usuario), nombres de clases, atributos de ID."
Avanzado: Agentes de espacio de trabajo con Copilot
El chat Copilot de VS Code soporta el agente @workspace que puede buscar en su código base. Úselo para auditorías i18n:
@workspace find all files with hardcoded strings that should use translation keys
@workspace show me all t() calls that reference keys not in our translation files
@workspace what namespaces are used in the settings feature?
El agente @workspace tiene acceso al contexto de su proyecto, lo que hace que estas consultas sean precisas.
Comparación: Copilot vs Claude Code vs Cursor para i18n
Habiendo usado los tres extensivamente:
| GitHub Copilot, Claude Code y Cursor |---------|---------------|-------------|--------| | Sugerencias en línea Excelente Bueno Excelente | Instrucciones personalizadas Excelente Excelente Excelente | Soporte MCP Próximamente | Integración TMS Manual Vía MCP Vía MCP | Edición de múltiples archivos Limitada Nativo | Integración con VS Code | Nativo | CLI | Aplicación independiente | Nativo
Mi opinión: Usa Copilot si ya estás en VS Code y quieres asistencia ligera. Usa Claude Code si necesitas flujos de trabajo autónomos de múltiples pasos. Usa Cursor si quieres una UX estilo Copilot con capacidades MCP.
No son mutuamente excluyentes. Yo uso Copilot para sugerencias rápidas y Claude Code para operaciones complejas.
El archivo de instrucciones que funciona
Después de mucha iteración, aquí está mi estructura completa copilot-instructions.md:
Empieza con el framework: la librería es react-i18next v14+, el formato del archivo es JSON con estructura anidada, la ubicación es /public/locales/{lang}/{namespace}.json.
Uso de la función de traducción de documentos: importar useTranslation de react-i18next, desestructurar t de useTranslation('namespace'), y usar t() en JSX.
Nomenclatura de la clave del documento: formato namespace.section.element. Las páginas utilizan el nombre de la página como namespace (settings, dashboard, auth). Los elementos compartidos utilizan el espacio de nombres "common". Los errores utilizan el espacio de nombres "errors". La validación utiliza el espacio de nombres "validación".
Reglas de la lista: NUNCA use cadenas de texto codificadas para el usuario, SIEMPRE use t() para cualquier texto que vean los usuarios, SIEMPRE incluya namespace en useTranslation(), SIEMPRE use camelCase para las claves, SIEMPRE añada descripciones de contexto para texto ambiguo.
Documente patrones clave para botones, etiquetas, marcadores de posición, títulos, mensajes y errores.
Documente los plurales: utilice el formato ICU con t('items.count', { count: n }). En el JSON, utilice count_one para el singular y count_other para el plural.
Añadir recordatorio CLI: después de añadir claves, ejecute npx @intlpullhq/cli upload.
Empezando
- Crea .github/copilot-instructions.md en tu proyecto
- Añada las especificaciones de su biblioteca i18n
- Documente sus convenciones de nomenclatura clave
- Incluya ejemplos de uso correcto
- Enumere lo que NO debe traducirse
- Pruebe escribiendo un nuevo componente. Copiloto debe sugerir claves
La inversión es de tal vez 30 minutos para configurar. La recompensa es Copilot que realmente ayuda con i18n en lugar de trabajar en contra de usted.
¿Utiliza IntlPull? Añade nuestros comandos CLI a tus instrucciones de Copilot. Después de que Copilot le ayude a escribir las claves de traducción, un comando las sincroniza con su TMS.
