Buenas prácticas para gestionar las claves de traducción en 2026

Respuesta rápida

La mejor práctica para las claves de traducción es la nomenclatura jerárquica con espacios de nombres basados en características: feature.component.element (por ejemplo, checkout.cart.removeButton). Utilice snake_case o camelCase de forma coherente, mantenga las claves por debajo de 50 caracteres, añada descripciones para contextualizar y organice por características en lugar de por páginas. IntlPull aplica estos patrones automáticamente a través de la validación CLI y proporciona sugerencias basadas en IA cuando las claves no siguen las convenciones.

Por qué es importante la gestión de claves

Una mala gestión de claves crea problemas complejos:

El coste es real: Los equipos con una mala higiene de las claves dedican entre 2 y 3 veces más tiempo a la gestión de la traducción que los equipos con buenas convenciones.

Naming Convention: La base

Formato recomendado

{namespace}.{component}.{element}.{modifier}

Ejemplos:

Reglas que funcionan

1. Utilizar estructura jerárquica

❌ loginSubmitButton
❌ login_submit_button
✅ auth.login.submitButton

2. Sea específico, no genérico

❌ button.text
❌ title
✅ checkout.payment.submitButton
✅ dashboard.analytics.pageTitle

**3. Evite los nombres posicionales

❌ sidebar.firstItem
❌ modal.button1
✅ sidebar.dashboard
✅ modal.confirmButton

**4. Utilizar mayúsculas y minúsculas coherentes

❌ auth.Login.Submit (mixed)
✅ auth.login.submit (camelCase throughout)
✅ auth.login.submit (or snake_case: auth.login.submit_button)

IntlPull Enforcement

IntlPull valida los nombres clave en su canalización CI/CD:

TerminalCopy
1npx @intlpullhq/cli lint --strict
2
3# Output:
4# ❌ loginBtn -> auth.login.submitButton (suggested)
5# ❌ error_msg -> common.errors.generic (suggested)
6# ✅ checkout.cart.itemCount (valid)

Arquitectura del espacio de nombres

Organización basada en características (recomendada)

Organización por características, no por páginas o tipos de archivo:

messages/
├── auth/
│   ├── en.json
│   └── es.json
├── checkout/
│   ├── en.json
│   └── es.json
├── dashboard/
│   ├── en.json
│   └── es.json
└── common/
    ├── en.json
    └── es.json

Beneficios:

• Facilidad para encontrar claves relacionadas con una característica
• Puede cargar espacios de nombres a petición (división de código)
• Coincide con la forma en que los desarrolladores piensan en la aplicación
• Propiedad clara para cada espacio de nombres

Claves planas frente a anidadas

Ambos enfoques funcionan; elija uno y sea coherente.

Plano (recomendado para <1000 claves):

JSONCopy
1{
2  "auth.login.title": "Sign In",
3  "auth.login.submitButton": "Continue",
4  "auth.login.forgotPassword": "Forgot password?"
5}

Anidado (recomendado para más de 1000 claves):

JSONCopy
1{
2  "auth": {
3    "login": {
4      "title": "Sign In",
5      "submitButton": "Continue",
6      "forgotPassword": "Forgot password?"
7    }
8  }
9}

IntlPull soporta ambos formatos y puede convertirlos automáticamente.

Descripciones de Claves: Contexto para traductores

**Los traductores necesitan contexto para traducir con precisión.

Qué incluir en las descripciones

En IntlPull

JSONCopy
1{
2  "checkout.cart.itemCount": {
3    "value": "{count, plural, one {# item} other {# items}}",
4    "description": "Shows item count in cart badge. Max 15 chars. {count} is number of items.",
5    "maxLength": 15,
6    "screenshot": "https://..."
7  }
8}

IntlPull muestra las descripciones directamente en la interfaz de traducción, lo que garantiza que los traductores siempre tengan contexto.

Manejo de variables y plurales

Nomenclatura de variables

Utilice nombres de variables significativos, no posicionales:

❌ "Hello {0}, you have {1} messages"
✅ "Hello {name}, you have {count} messages"

Plural Handling (ICU Format)

JSONCopy
{
  "cart.items": "{count, plural, =0 {No items} one {# item} other {# items}}"
}

Género y Selección

JSONCopy
{
  "profile.greeting": "{gender, select, male {He} female {She} other {They}} updated their profile"
}

IntlPull valida la sintaxis de ICU durante la carga y resalta los errores antes de que lleguen a producción.

Evitar errores comunes

1. Concatenación de cadenas

JavaScriptCopy
1// ❌ Breaks in many languages (word order varies)
2t('cart.total') + ': ' + price
3
4// ✅ Use variables
5t('cart.totalWithPrice', { price })
6// "Total: {price}" or "{price}: Total" depending on language

2. Puntuación codificada

JavaScriptCopy
1// ❌ Some languages use different punctuation
2t('question') + '?'
3
4// ✅ Include punctuation in the key
5t('question') // "Are you sure?"

3. Dividir frases

JSXCopy
1// ❌ Impossible to translate naturally
2<span>{t('click')}</span> <a>{t('here')}</a> <span>{t('toContinue')}</span>
3
4// ✅ Use rich text support
5<Trans i18nKey="clickToContinue">
6  Click <a>here</a> to continue
7</Trans>

4. Asumir la longitud del texto

CSSCopy
1/* ❌ German is ~30% longer than English */
2.button { width: 100px; }
3
4/* ✅ Allow for expansion */
5.button { min-width: 100px; padding: 0 1rem; }

Patrones de flujo de trabajo

Flujo de trabajo del desarrollador

1. Crear clave en código con texto de marcador de posición
2. CLI extrae claves automáticamente (npx @intlpullhq/cli extract)
3. Pulsar a IntlPull (npx @intlpullhq/cli upload)
4. AI traduce o asigna a traductor
5. Traducciones pull (npx @intlpullhq/cli download)

Flujo de trabajo de revisión

1. El desarrollador crea una clave con valor en inglés
2. IntlPull AI genera las traducciones
3. El revisor aprueba o edita en el panel de control
4. Las traducciones aprobadas se sincronizan con el código base

Flujo de trabajo de limpieza (trimestral)

TerminalCopy
1# Find unused keys
2npx @intlpullhq/cli unused
3
4# Remove orphaned keys
5npx @intlpullhq/cli prune --dry-run
6npx @intlpullhq/cli prune --confirm

IntlPull rastrea el uso de claves y marca las claves que no han sido referenciadas en su código base.

Patrones de escalado

Para 100-1.000 Teclas

• Un único espacio de nombres está bien
• La estructura plana de claves funciona
• La revisión manual es manejable

Para 1.000-10.000 claves

• Se necesitan espacios de nombres basados en características
• Estructura de claves anidada
• Validación automatizada esencial
• Revisiones semanales de limpieza

Para más de 10.000 claves

• Gobierno estricto del espacio de nombres
• Propietarios de código por espacio de nombres
• Detección automática de huérfanos
• Proceso de auditoría mensual

IntlPull se amplía a más de 100.000 claves con permisos a nivel de espacio de nombres, comprobaciones de calidad automatizadas y análisis de uso.

Preguntas frecuentes

¿Cuál es la mejor convención de nomenclatura para las claves de traducción?

Utilizar notación jerárquica por puntos: feature.component.element (por ejemplo, auth.login.submitButton). Esto proporciona un contexto claro, una búsqueda fácil y una agrupación natural. Evite nombres genéricos como button.text o nombres posicionales como modal.button1. Sea coherente con las mayúsculas y minúsculas (camelCase o snake_case en todo el texto).

¿Cómo debo organizar las claves de traducción para una aplicación grande?

**Cree archivos/espacios de nombres separados para auth, checkout, dashboard, settings, etc., más un common espacio de nombres para cadenas compartidas. Esto permite la división de código, la propiedad clara, y un mantenimiento más fácil. IntlPull soporta permisos a nivel de espacio de nombres para grandes equipos.

¿Cómo manejo las descripciones de las claves de traducción?

**Incluya: dónde aparece (contexto), longitud máxima de caracteres, explicación de variables, guía de tono y enlaces a capturas de pantalla/diseños. IntlPull muestra las descripciones en la interfaz del traductor y puede marcar las teclas a las que les falten descripciones.

¿Con qué frecuencia debo limpiar las claves de traducción no utilizadas?

Ejecute la detección de huérfanos mensualmente, la limpieza completa trimestralmente. Las claves no utilizadas hinchan los paquetes y confunden a los traductores. El comando npx @intlpullhq/cli unused de IntlPull identifica las claves no referenciadas en su código base. Ejecute prune con --dry-run primero para previsualizar las eliminaciones antes de confirmar.

¿Debo utilizar estructuras de claves de traducción planas o anidadas?

Utilizar estructura plana para <1.000 claves, anidada para proyectos más grandes. La plana (auth.login.title: Sign In) es más sencilla y fácil de buscar. Anidado (auth: { login: { title: ... } }) se adapta mejor a la estructura del código. IntlPull soporta ambos formatos y puede convertirlos.

¿Cómo evito las incoherencias en los nombres de las claves de traducción?

**La CLI de IntlPull incluye un comando lint que valida los nombres de las claves contra reglas configurables. Ejecute npx @intlpullhq/cli lint --strict en su pipeline para detectar inconsistencias antes de que se fusionen. La CLI también sugiere correcciones para claves malformadas.

Resumen

Mejores prácticas clave:

1. Utilice una nomenclatura jerárquica: feature.component.element
2. Organizar por características con espacios de nombres
3. Añadir descripciones para el contexto del traductor
4. Uso del formato ICU para plurales y variables
5. Validación automática con herramientas CLI
6. Limpie regularmente las claves no utilizadas

IntlPull refuerza estos patrones a través de la validación CLI, sugerencias automatizadas y seguimiento de uso. Nuestra IA aprende incluso las convenciones de su proyecto y le sugiere nombres de claves coherentes a medida que trabaja.

¿Listo para traducciones organizadas? Comience gratis con IntlPull - Sugerencias de claves basadas en IA incluidas.