Archivos JSON (i18next): Guía Completa del Formato JSON de i18next

¿Qué Es el Formato JSON de i18next?

i18next es uno de los frameworks de internacionalización más populares para JavaScript, utilizado por miles de aplicaciones en todo el mundo. El formato JSON de i18next es la forma estándar de almacenar cadenas de traducción para aplicaciones que usan i18next, incluyendo React, Vue.js, Angular, Node.js y muchos otros frameworks JavaScript.

Los archivos JSON de i18next almacenan claves y valores de traducción en un formato estructurado que soporta características como interpolación, pluralización, anidamiento, variantes de contexto y más.

Por Qué AZbox Soporta el Formato JSON de i18next

En AZbox, reconocemos que i18next es la solución de localización preferida para desarrolladores JavaScript. Por eso AZbox soporta completamente la importación y exportación de archivos JSON de i18next, permitiéndote:

• Importar archivos JSON i18next existentes directamente a tu proyecto AZbox
• Exportar traducciones de vuelta al formato JSON i18next para usar en tu app
• Soportar todas las versiones de JSON i18next (v1, v2, v3, v4)
• Gestionar traducciones con nuestra potente plataforma en la nube
• Colaborar con traductores que pueden trabajar directamente con tu contenido
• Actualizar over-the-air sin reconstruir tu aplicación

Versiones de JSON i18next

i18next ha evolucionado con el tiempo, y hay cuatro versiones principales del formato JSON. AZbox las soporta todas:

Versión	Característica Principal	Formato de Plurales
v4 (Actual)	Plurales compatibles con ICU	_one, _other, _few, etc.
v3	Plurales simplificados	Sufijo _plural
v2	Índices de plural legacy	_0, _1, _2, etc.
v1	Formato original	Interpolación __value__

i18next JSON v4 (Recomendado)

El formato más reciente y recomendado, v4 usa sufijos de plural compatibles con ICU basados en la API Intl.PluralRules:

{
  "appTitle": "Mi Aplicación",
  "welcome": "¡Bienvenido a nuestra app!",
  
  "keyDeep": {
    "inner": "Valor anidado"
  },
  
  "keyNesting": "Reutilizar: $t(keyDeep.inner)",
  
  "greeting": "¡Hola, {{name}}!",
  
  "greetingUnescaped": "¡Hola, {{- name}}!",
  
  "formattedValue": "Precio: {{value, currency}}",
  
  "context_male": "Él es desarrollador",
  "context_female": "Ella es desarrolladora",
  
  "itemCount_one": "{{count}} artículo",
  "itemCount_other": "{{count}} artículos",
  
  "arabicPlural_zero": "Sin artículos",
  "arabicPlural_one": "Un artículo",
  "arabicPlural_two": "Dos artículos",
  "arabicPlural_few": "Algunos artículos",
  "arabicPlural_many": "Muchos artículos",
  "arabicPlural_other": "{{count}} artículos",
  
  "arrayValue": ["Primero", "Segundo", "Tercero"],
  
  "objectValue": {
    "title": "Título de Sección",
    "description": "Descripción de la sección"
  }
}

Sufijos de Plural en v4

Sufijo	Uso	Idiomas de Ejemplo
_zero	Cero elementos	Árabe, Letón
_one	Singular	Inglés, Español, Alemán
_two	Forma dual	Árabe, Galés, Esloveno
_few	Pocos elementos	Ruso, Polaco, Checo
_many	Muchos elementos	Ruso, Árabe, Polaco
_other	Plural por defecto/general	Todos los idiomas

i18next JSON v3

La versión 3 usa el sufijo simplificado _plural para formas plurales:

{
  "appTitle": "Mi Aplicación",
  "welcome": "¡Bienvenido a nuestra app!",
  
  "greeting": "¡Hola, {{name}}!",
  
  "context_male": "Él es desarrollador",
  "context_female": "Ella es desarrolladora",
  
  "itemCount": "{{count}} artículo",
  "itemCount_plural": "{{count}} artículos",
  
  "arabicPlural_0": "Sin artículos",
  "arabicPlural_1": "Un artículo",
  "arabicPlural_2": "Dos artículos",
  "arabicPlural_3": "Algunos artículos",
  "arabicPlural_4": "Muchos artículos",
  "arabicPlural_5": "{{count}} artículos"
}

Para usar el formato v3 en i18next:

i18next.init({
  compatibilityJSON: 'v3'
});

i18next JSON v2

La versión 2 usa índices numéricos para formas plurales complejas:

{
  "appTitle": "Mi Aplicación",
  
  "greeting": "¡Hola, {{name}}!",
  
  "itemCount": "{{count}} artículo",
  "itemCount_plural": "{{count}} artículos",
  
  "arabicPlural_0": "Sin artículos",
  "arabicPlural_1": "Un artículo",
  "arabicPlural_2": "Dos artículos",
  "arabicPlural_3": "Algunos artículos",
  "arabicPlural_11": "Muchos artículos",
  "arabicPlural_100": "{{count}} artículos"
}

i18next JSON v1

El formato original usa dobles guiones bajos para interpolación:

{
  "appTitle": "Mi Aplicación",
  
  "greeting": "¡Hola, __name__!",
  
  "greetingHTML": "¡Hola, __nameHTML__!",
  
  "itemCount": "__count__ artículo",
  "itemCount_plural": "__count__ artículos"
}

Características Principales del JSON de i18next

1. Interpolación

Inserta valores dinámicos en tus traducciones:

{
  "welcome": "¡Bienvenido, {{username}}!",
  "orderStatus": "El pedido #{{orderId}} está {{status}}",
  "score": "Has conseguido {{points}} puntos"
}

Uso en JavaScript:

t('welcome', { username: 'Juan' })
// Salida: "¡Bienvenido, Juan!"

t('orderStatus', { orderId: '12345', status: 'enviado' })
// Salida: "El pedido #12345 está enviado"

2. Interpolación Sin Escapar

Para contenido HTML, usa la sintaxis {{- value}}:

{
  "richContent": "Bienvenido a {{- companyName}}",
  "htmlMessage": "Haz clic en {{- link}} para más info"
}

Uso:

t('richContent', { companyName: '<strong>AZbox</strong>' })
// Salida: "Bienvenido a <strong>AZbox</strong>"

3. Anidamiento

Reutiliza traducciones dentro de otras traducciones:

{
  "appName": "AZbox",
  "welcome": "¡Bienvenido a $t(appName)!",
  "tagline": "$t(appName) - Localización simplificada"
}

Salida:

t('welcome')    // "¡Bienvenido a AZbox!"
t('tagline')    // "AZbox - Localización simplificada"

4. Contexto

Crea variantes basadas en contexto (género, formalidad, etc.):

{
  "friend": "Un amigo",
  "friend_male": "Un novio",
  "friend_female": "Una novia",
  
  "greeting": "Hola",
  "greeting_formal": "Buenos días",
  "greeting_informal": "¡Ey!"
}

Uso:

t('friend', { context: 'male' })     // "Un novio"
t('friend', { context: 'female' })   // "Una novia"
t('greeting', { context: 'formal' }) // "Buenos días"

5. Pluralización

Maneja formas singulares y plurales:

{
  "message_one": "Tienes {{count}} mensaje",
  "message_other": "Tienes {{count}} mensajes",
  
  "item_one": "{{count}} artículo en el carrito",
  "item_other": "{{count}} artículos en el carrito"
}

Uso:

t('message', { count: 1 })  // "Tienes 1 mensaje"
t('message', { count: 5 })  // "Tienes 5 mensajes"

6. Formateo

Aplica formato a valores interpolados:

{
  "price": "Total: {{value, currency(EUR)}}",
  "date": "Creado el {{date, datetime}}",
  "percentage": "Progreso: {{value, number(percent)}}"
}

7. Objetos Anidados

Organiza traducciones jerárquicamente:

{
  "nav": {
    "home": "Inicio",
    "about": "Sobre Nosotros",
    "contact": "Contacto",
    "products": {
      "list": "Todos los Productos",
      "featured": "Destacados",
      "sale": "En Oferta"
    }
  },
  "auth": {
    "login": "Iniciar Sesión",
    "logout": "Cerrar Sesión",
    "register": "Crear Cuenta"
  }
}

Uso:

t('nav.home')              // "Inicio"
t('nav.products.featured') // "Destacados"
t('auth.login')            // "Iniciar Sesión"

8. Arrays

Almacena múltiples valores:

{
  "colors": ["Rojo", "Verde", "Azul"],
  "sizes": ["Pequeño", "Mediano", "Grande", "Extra Grande"]
}

Uso:

t('colors', { returnObjects: true })
// ["Rojo", "Verde", "Azul"]

Convención de Nombres de Archivos

Los archivos JSON de i18next típicamente siguen esta estructura:

locales/
├── en/
│   ├── translation.json    (namespace por defecto)
│   ├── common.json         (namespace común)
│   └── errors.json         (namespace de errores)
├── es/
│   ├── translation.json
│   ├── common.json
│   └── errors.json
└── fr/
    ├── translation.json
    ├── common.json
    └── errors.json

O usando una estructura plana:

locales/
├── en.json
├── es.json
├── fr.json
└── de.json

Importar JSON i18next a AZbox

Paso 1: Prepara tus Archivos JSON

Asegúrate de que tus archivos sean JSON válido y sigan las convenciones de i18next:

locales/
├── en/
│   └── translation.json
├── es/
│   └── translation.json
└── fr/
    └── translation.json

Paso 2: Importar vía Panel de AZbox

1. Inicia sesión en tu panel de AZbox
2. Navega a tu proyecto
3. Ve a la sección Importar/Exportar
4. Selecciona Importar y elige JSON (i18next) como formato
5. Sube tus archivos JSON
6. Selecciona la versión de i18next (v3 o v4)
7. AZbox parseará e importará todas las traducciones

Paso 3: Revisar y Gestionar

Después de importar:

• Ver todas las traducciones en una interfaz unificada
• Editar traducciones con editor consciente del contexto
• Añadir nuevos idiomas al instante
• Usar traducción automática para strings faltantes
• Colaborar con traductores en tiempo real

Exportar JSON i18next desde AZbox

Cuando estés listo para usar las traducciones en tu app:

1. Ve a Importar/Exportar en tu proyecto
2. Selecciona Exportar y elige el formato JSON (i18next)
3. Selecciona la versión de i18next a exportar
4. Elige los idiomas destino
5. Descarga los archivos JSON generados
6. Colócalos en el directorio locales/ de tu proyecto

Usar JSON i18next en Tu Aplicación

React con react-i18next

Instalación:

npm install i18next react-i18next

Configuración:

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import en from './locales/en/translation.json';
import es from './locales/es/translation.json';

i18n
  .use(initReactI18next)
  .init({
    resources: {
      en: { translation: en },
      es: { translation: es }
    },
    lng: 'es',
    fallbackLng: 'en',
    interpolation: {
      escapeValue: false
    }
  });

export default i18n;

Uso en componentes:

import { useTranslation } from 'react-i18next';

function Welcome() {
  const { t } = useTranslation();
  
  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('greeting', { name: 'Usuario' })}</p>
    </div>
  );
}

Vue.js con vue-i18next

import Vue from 'vue';
import i18next from 'i18next';
import VueI18Next from '@panter/vue-i18next';

Vue.use(VueI18Next);

i18next.init({
  lng: 'es',
  resources: {
    en: { translation: require('./locales/en.json') },
    es: { translation: require('./locales/es.json') }
  }
});

const i18n = new VueI18Next(i18next);

new Vue({
  i18n,
  render: h => h(App)
}).$mount('#app');

Node.js

const i18next = require('i18next');

i18next.init({
  lng: 'es',
  resources: {
    en: { translation: require('./locales/en.json') },
    es: { translation: require('./locales/es.json') }
  }
});

console.log(i18next.t('welcome'));
console.log(i18next.t('greeting', { name: 'Mundo' }));

Mejores Prácticas para JSON i18next

1. Usa Namespaces para Proyectos Grandes

locales/es/
├── common.json      (elementos UI compartidos)
├── auth.json        (autenticación)
├── dashboard.json   (funciones del dashboard)
├── errors.json      (mensajes de error)
└── validation.json  (validación de formularios)

2. Usa Claves Descriptivas y Jerárquicas

Mal:

{
  "btn1": "Enviar",
  "msg": "Ocurrió un error"
}

Bien:

{
  "form": {
    "submit": "Enviar",
    "cancel": "Cancelar"
  },
  "errors": {
    "generic": "Ha ocurrido un error",
    "network": "Error de red"
  }
}

3. Mantén las Traducciones Consistentes

{
  "actions": {
    "save": "Guardar",
    "cancel": "Cancelar",
    "delete": "Eliminar",
    "edit": "Editar"
  }
}

4. Maneja Todas las Formas Plurales

{
  "notification_zero": "Sin notificaciones",
  "notification_one": "{{count}} notificación",
  "notification_other": "{{count}} notificaciones"
}

5. Proporciona Contexto con Nombres de Claves

{
  "button_save_document": "Guardar Documento",
  "button_save_settings": "Guardar Configuración",
  "title_main_dashboard": "Panel Principal",
  "title_user_profile": "Tu Perfil"
}

Problemas Comunes y Soluciones

Problema: Plurales No Funcionan

Problema: Las formas plurales no se muestran correctamente.

Solución: Asegúrate de usar el sufijo de plural correcto para tu versión de i18next:

• v4: _one, _other, _few, _many, _zero, _two
• v3: _plural

Problema: Interpolación No Se Reemplaza

Problema: {{value}} aparece literalmente en la salida.

Solución: Verifica que estás pasando los valores de interpolación:

// Incorrecto
t('greeting')

// Correcto
t('greeting', { name: 'Juan' })

Problema: Claves Anidadas No Encontradas

Problema: t('nav.home') devuelve la clave en lugar del valor.

Solución: Asegúrate de que tu estructura JSON coincida con la ruta de la clave y que los recursos estén cargados correctamente.

Funcionalidades i18next de AZbox

Cuando importas JSON i18next a AZbox, obtienes:

• Detección automática de versión - AZbox detecta formato v3 o v4
• Soporte de namespaces - Gestiona múltiples namespaces por proyecto
• Validación de formas plurales - Asegura que todas las variantes plurales estén presentes
• Resaltado de interpolación - Marcadores visuales para {{variables}}
• Soporte de anidamiento - Maneja referencias $t() correctamente
• Gestión de variantes de contexto - Fácil gestión de claves de contexto
• Memoria de traducción - Aprovecha traducciones anteriores
• Traducción automática - Rellena huecos con traducción impulsada por IA
• Actualizaciones over-the-air - Actualiza sin redesplegar

Migrar Entre Versiones

Migración de v3 a v4

Si actualizas de v3 a v4, las claves plurales necesitan actualizarse:

v3:

{
  "item": "{{count}} artículo",
  "item_plural": "{{count}} artículos"
}

v4:

{
  "item_one": "{{count}} artículo",
  "item_other": "{{count}} artículos"
}

Usa el i18next-v4-format-converter para automatizar la migración.

Conclusión

El JSON de i18next es el estándar de la industria para localización JavaScript, ofreciendo funcionalidades potentes para manejar escenarios de traducción complejos. Con el soporte completo de i18next de AZbox, puedes:

1. Importar archivos JSON existentes con todas las funcionalidades preservadas
2. Soportar todas las versiones de i18next (v1-v4)
3. Gestionar traducciones en una plataforma colaborativa en la nube
4. Exportar archivos JSON listos para usar en cualquier proyecto i18next
5. Actualizar traducciones over-the-air sin reconstruir

¿Listo para optimizar tu flujo de trabajo de localización JavaScript?

Comienza tu Prueba Gratuita | Ver Precios

---

AZbox proporciona soporte completo para el formato JSON de i18next, convirtiéndolo en la plataforma de localización ideal para desarrolladores JavaScript. Importa, gestiona y exporta tus traducciones con facilidad.

Referencias:

• Documentación del Formato JSON de i18next
• Sitio Oficial de i18next