Archivos ARB: Guía Completa del Formato Application Resource Bundle

¿Qué Son los Archivos ARB?

ARB (Application Resource Bundle) es un formato de archivo de localización basado en JSON, desarrollado originalmente por Google. Es el formato estándar para gestionar traducciones en aplicaciones Flutter y se usa ampliamente en el ecosistema Dart.

Los archivos ARB almacenan cadenas de traducción junto con sus metadatos, lo que los hace particularmente potentes para manejar escenarios de localización complejos, incluyendo pluralización, género y marcadores de posición personalizados.

Por Qué AZbox Soporta Archivos ARB

En AZbox, entendemos que los desarrolladores Flutter necesitan una integración fluida con sus flujos de trabajo de localización existentes. Por eso AZbox soporta completamente la importación y exportación de archivos ARB, permitiéndote:

• Importar archivos ARB existentes directamente a tu proyecto AZbox
• Exportar traducciones de vuelta al formato ARB para usar en tu app Flutter
• 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 app

Estructura de Archivos ARB

Los archivos ARB usan una estructura basada en JSON con una convención específica para claves y metadatos. Aquí hay un ejemplo básico:

{
  "@@locale": "es",
  "@@last_modified": "2024-01-15T10:30:00.000Z",
  
  "appTitle": "Mi App Flutter",
  "@appTitle": {
    "description": "El título de la aplicación"
  },
  
  "welcomeMessage": "¡Bienvenido a nuestra app!",
  "@welcomeMessage": {
    "description": "Mensaje de bienvenida mostrado en la pantalla de inicio"
  },
  
  "itemCount": "{count, plural, =0{Sin elementos} =1{1 elemento} other{{count} elementos}}",
  "@itemCount": {
    "description": "Muestra el número de elementos",
    "placeholders": {
      "count": {
        "type": "int",
        "example": "5"
      }
    }
  }
}

Componentes Principales

Componente	Descripción
@@locale	El identificador de locale (ej: “en”, “es”, “fr”)
@@last_modified	Marca de tiempo de la última modificación
messageKey	La clave de traducción y su valor
@messageKey	Metadatos para la clave de traducción

Convención de Nombres de Archivos ARB

Los archivos ARB siguen una convención de nombres específica que incluye el locale:

• app_en.arb - Traducciones en inglés
• app_es.arb - Traducciones en español
• app_fr.arb - Traducciones en francés
• app_de.arb - Traducciones en alemán
• app_pt_BR.arb - Traducciones en portugués brasileño

El archivo base (usualmente inglés) sirve como plantilla, y los otros archivos de locale contienen las versiones traducidas.

Metadatos en Archivos ARB

Una de las características poderosas de los archivos ARB es su capacidad de almacenar metadatos ricos junto a las traducciones:

Metadatos de Descripción

{
  "loginButton": "Iniciar Sesión",
  "@loginButton": {
    "description": "Texto del botón para la acción de inicio de sesión",
    "context": "Pantalla de autenticación"
  }
}

Metadatos de Marcadores de Posición

{
  "greeting": "¡Hola, {name}!",
  "@greeting": {
    "description": "Mensaje de saludo con nombre de usuario",
    "placeholders": {
      "name": {
        "type": "String",
        "example": "Juan"
      }
    }
  }
}

Múltiples Marcadores de Posición

{
  "orderSummary": "Pedido #{orderId} - Total: {currency}{amount}",
  "@orderSummary": {
    "description": "Resumen del pedido con ID y monto total",
    "placeholders": {
      "orderId": {
        "type": "String",
        "example": "12345"
      },
      "currency": {
        "type": "String",
        "example": "€"
      },
      "amount": {
        "type": "double",
        "format": "decimalPattern",
        "example": "99.99"
      }
    }
  }
}

Pluralización en Archivos ARB

Los archivos ARB soportan ICU MessageFormat para manejar la pluralización:

{
  "messageCount": "{count, plural, =0{Sin mensajes} =1{1 mensaje} other{{count} mensajes}}",
  "@messageCount": {
    "description": "Número de mensajes",
    "placeholders": {
      "count": {
        "type": "int",
        "example": "5"
      }
    }
  }
}

Categorías de Pluralización

Categoría	Descripción	Idiomas de Ejemplo
zero	Cero elementos	Árabe, Letón
one	Singular	Inglés, Español
two	Dual	Árabe, Galés
few	Pocos elementos	Ruso, Polaco
many	Muchos elementos	Ruso, Árabe
other	Por defecto/plural	Todos los idiomas

Ejemplo de Pluralización Compleja

{
  "cartItems": "{count, plural, =0{Tu carrito está vacío} =1{Tienes 1 artículo en tu carrito} other{Tienes {count} artículos en tu carrito}}",
  "@cartItems": {
    "description": "Conteo de artículos del carrito de compras",
    "placeholders": {
      "count": {
        "type": "int",
        "example": "3"
      }
    }
  }
}

Selección de Género en Archivos ARB

Los archivos ARB también soportan selección de mensajes basada en género:

{
  "userWelcome": "{gender, select, male{Bienvenido, Sr. {name}} female{Bienvenida, Sra. {name}} other{Bienvenido/a, {name}}}",
  "@userWelcome": {
    "description": "Mensaje de bienvenida específico por género",
    "placeholders": {
      "gender": {
        "type": "String"
      },
      "name": {
        "type": "String",
        "example": "García"
      }
    }
  }
}

Mensajes ICU Anidados

Para escenarios complejos, puedes anidar declaraciones de plural y select:

{
  "notificationMessage": "{gender, select, male{{count, plural, =0{Él no tiene notificaciones} =1{Él tiene 1 notificación} other{Él tiene {count} notificaciones}}} female{{count, plural, =0{Ella no tiene notificaciones} =1{Ella tiene 1 notificación} other{Ella tiene {count} notificaciones}}} other{{count, plural, =0{No tiene notificaciones} =1{Tiene 1 notificación} other{Tiene {count} notificaciones}}}}",
  "@notificationMessage": {
    "description": "Conteo de notificaciones con género",
    "placeholders": {
      "gender": {
        "type": "String"
      },
      "count": {
        "type": "int",
        "example": "5"
      }
    }
  }
}

Formateo de Fechas y Números

Los archivos ARB soportan marcadores de posición formateados para fechas y números:

Formateo de Fechas

{
  "lastLogin": "Último acceso: {date}",
  "@lastLogin": {
    "description": "Muestra la fecha del último acceso",
    "placeholders": {
      "date": {
        "type": "DateTime",
        "format": "yMMMd",
        "example": "15 ene 2024"
      }
    }
  }
}

Formateo de Números

{
  "productPrice": "Precio: {price}",
  "@productPrice": {
    "description": "Visualización del precio del producto",
    "placeholders": {
      "price": {
        "type": "double",
        "format": "currency",
        "optionalParameters": {
          "symbol": "€",
          "decimalDigits": 2
        },
        "example": "19,99 €"
      }
    }
  }
}

Importar Archivos ARB a AZbox

Paso 1: Prepara tus Archivos ARB

Asegúrate de que tus archivos ARB sigan la convención de nombres estándar y contengan JSON válido:

localization/
├── app_en.arb    (archivo base)
├── app_es.arb
├── app_fr.arb
└── app_de.arb

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 ARB como formato
5. Sube tus archivos ARB
6. AZbox detectará automáticamente el locale de cada archivo

Paso 3: Revisar y Gestionar

Después de importar, puedes:

• Ver todas las traducciones en una interfaz unificada
• Editar traducciones directamente en la plataforma
• Añadir nuevos idiomas
• Usar traducción automática para rellenar traducciones faltantes
• Colaborar con traductores

Exportar Archivos ARB desde AZbox

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

1. Ve a Importar/Exportar en tu proyecto AZbox
2. Selecciona Exportar y elige el formato ARB
3. Selecciona los idiomas que quieres exportar
4. Descarga los archivos ARB generados
5. Colócalos en el directorio lib/l10n/ de tu proyecto Flutter

Usar Archivos ARB en Flutter

Configuración del Proyecto

Añade el paquete de localización a tu pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: ^0.18.0

flutter:
  generate: true

Crea l10n.yaml en la raíz de tu proyecto:

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart

Generar Código de Localización

Ejecuta el comando Flutter para generar el código de localización:

flutter gen-l10n

Esto genera la clase AppLocalizations que puedes usar en tus widgets:

import 'package:flutter_gen/gen_l10n/app_localizations.dart';

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Text(AppLocalizations.of(context)!.welcomeMessage);
  }
}

Mejores Prácticas para Archivos ARB

1. Usa Nombres de Claves Descriptivos

Mal:

{
  "msg1": "Enviar"
}

Bien:

{
  "buttonSubmitForm": "Enviar"
}

2. Siempre Incluye Descripciones

{
  "deleteConfirmation": "¿Estás seguro de que quieres eliminar este elemento?",
  "@deleteConfirmation": {
    "description": "Mensaje del diálogo de confirmación cuando el usuario intenta eliminar un elemento"
  }
}

3. Proporciona Ejemplos para los Marcadores de Posición

{
  "welcomeUser": "¡Bienvenido de nuevo, {username}!",
  "@welcomeUser": {
    "placeholders": {
      "username": {
        "type": "String",
        "example": "JuanGarcia123"
      }
    }
  }
}

4. Organiza las Claves por Funcionalidad

{
  "auth_loginTitle": "Iniciar Sesión",
  "auth_loginButton": "Entrar",
  "auth_logoutButton": "Cerrar Sesión",
  
  "settings_title": "Configuración",
  "settings_language": "Idioma",
  "settings_theme": "Tema"
}

5. Maneja Casos Límite en Plurales

{
  "daysRemaining": "{days, plural, =0{Expira hoy} =1{1 día restante} other{{days} días restantes}}",
  "@daysRemaining": {
    "placeholders": {
      "days": {
        "type": "int"
      }
    }
  }
}

Problemas Comunes y Soluciones

Problema: Sintaxis JSON Inválida

Problema: Los archivos ARB deben ser JSON válido. Errores comunes incluyen:

• Comas finales
• Comillas faltantes alrededor de strings
• Caracteres especiales sin escapar

Solución: Usa un validador JSON o un IDE con soporte JSON para detectar errores de sintaxis.

Problema: Marcadores de Posición No Coincidentes

Problema: Los marcadores de posición en las traducciones no coinciden con el archivo base.

Solución: AZbox valida automáticamente la consistencia de marcadores de posición entre traducciones.

Problema: Errores de Formato ICU Message

Problema: Sintaxis incorrecta de plural o select.

Solución: Usa la validación integrada de formato ICU message de AZbox.

Funcionalidades ARB de AZbox

Cuando importas archivos ARB a AZbox, te beneficias de:

• Preservación automática de metadatos - Todas las descripciones e info de marcadores se mantienen
• Validación de mensajes ICU - Asegura que plurales y selects estén correctamente formateados
• Verificación de consistencia de marcadores - Valida marcadores en todas las traducciones
• Editor visual - Edita mensajes ICU con una interfaz amigable
• Memoria de traducción - Aprovecha traducciones anteriores para consistencia
• Traducción automática - Rellena huecos con traducción impulsada por IA
• Actualizaciones over-the-air - Actualiza traducciones sin aprobación de app store

Conclusión

Los archivos ARB son el estándar para localización en Flutter, ofreciendo funcionalidades potentes para manejar escenarios de traducción complejos. Con el soporte completo de ARB de AZbox, puedes:

1. Importar archivos ARB existentes con todos los metadatos preservados
2. Gestionar traducciones en una plataforma colaborativa en la nube
3. Exportar archivos ARB listos para usar en tu proyecto Flutter
4. Actualizar traducciones over-the-air sin reconstruir tu app

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

Comienza tu Prueba Gratuita | Ver Precios

---

AZbox proporciona soporte completo para archivos ARB, convirtiéndolo en la plataforma de localización ideal para desarrolladores Flutter. Importa, gestiona y exporta tus traducciones con facilidad.