Cómo Traducir una App Flutter con Azbox: Guía Completa

Traducir tu app Flutter es esencial para llegar a una audiencia global. Azbox proporciona un potente SDK de Flutter que simplifica el proceso de localización gestionando las traducciones en la nube y sincronizándolas automáticamente con tu app. Esta guía te guiará a través del proceso de traducir una app Flutter usando el SDK de Azbox Flutter.

Entendiendo el SDK de Azbox Flutter

El SDK de Azbox Flutter proporciona una forma fluida de gestionar traducciones para tu app Flutter. Te permite:

• Gestionar traducciones en la plataforma en la nube de Azbox
• Sincronizar traducciones automáticamente con tu app
• Soportar múltiples idiomas sin reconstruir
• Actualizar traducciones over-the-air
• Colaborar con traductores a través de la plataforma Azbox

Requisitos

Antes de comenzar, asegúrate de tener:

• iOS: Dispositivo iOS 12+ o iPadOS 12+ (iPhone, iPad) para probar. El simulador de Xcode 14+ funciona ejecutando iOS 16+
• Desarrollo iOS: Mac con Xcode 12+
• Android: Dispositivo o emulador Android 5.0+ con “Google Play Store (Services)” instalado
• Cuenta Azbox: Plan de Azbox de pago (Starter o superior)
• Proyecto Azbox: Proyecto Azbox configurado con tus traducciones

Paso 1: Instalar el SDK de Azbox Flutter

Añade el SDK de Azbox Flutter a tu pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  azbox-localization: ^1.0.0  # Usa la última versión

Luego ejecuta:

flutter pub get

Para encontrar la última versión, consulta la documentación del SDK de Azbox Flutter o la página del paquete en pub.dev.

Paso 2: Obtener tus Credenciales de Azbox

Antes de configurar el SDK, necesitarás:

1. API Key: Se encuentra en la configuración de tu proyecto Azbox
2. Project ID: El identificador de tu proyecto Azbox

Puedes encontrar estos en tu panel de Azbox bajo Configuración del Proyecto.

Paso 3: Inicializar Azbox en tu App

Inicializa Azbox en tu archivo main.dart antes de ejecutar tu app:

lib/main.dart:

import 'package:flutter/material.dart';
import 'package:azbox_localization/azbox_localization.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Inicializar Azbox antes de ejecutar la app
  await Azbox.ensureInitialized(
    apiKey: 'Tu API Key',
    projectId: 'Tu project ID',
  );
  
  runApp(
    Azbox(
      child: MyApp(),
    ),
  );
}

Notas Importantes:

• Siempre llama a WidgetsFlutterBinding.ensureInitialized() antes de inicializar Azbox
• El widget Azbox debe envolver tu widget raíz de la app
• Mantén tu API key segura y nunca la subas al control de versiones

Paso 4: Configurar MaterialApp para Localización

Configura tu MaterialApp para soportar localización usando Azbox:

lib/main.dart:

import 'package:flutter/material.dart';
import 'package:azbox_localization/azbox_localization.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      // Usa los delegados de localización de Azbox
      localizationsDelegates: context.localizationDelegates,
      
      // Usa los locales soportados de Azbox
      supportedLocales: context.supportedLocales,
      
      // Usa el locale actual de Azbox
      locale: context.locale,
      
      title: 'My Flutter App',
      home: MyHomePage(),
    );
  }
}

El SDK de Azbox proporciona automáticamente:

• localizationDelegates: Maneja la carga de traducciones
• supportedLocales: Lista de idiomas configurados en tu proyecto Azbox
• locale: Locale activo actual

Paso 5: Usar Traducciones en tu App

Azbox proporciona múltiples formas convenientes de traducir tus textos:

Método 1: Usando Extensión en Widget Text

La forma más simple es usar la extensión en el widget Text:

import 'package:flutter/material.dart';
import 'package:azbox_localization/azbox_localization.dart';

class MyHomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('welcome_title').translate(),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text('welcome_message').translate(),
            SizedBox(height: 20),
            Text('button_submit').translate(),
          ],
        ),
      ),
    );
  }
}

Método 2: Usando Extensión en String

También puedes usar la extensión directamente en strings:

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final title = 'app_title'.translate();
    final description = 'app_description'.translate();
    
    return Column(
      children: [
        Text(title),
        Text(description),
      ],
    );
  }
}

Método 3: Usando Función Estática

Usa la función estática translate:

import 'package:azbox_localization/azbox_localization.dart';

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final title = translate('app_title');
    final subtitle = translate('app_subtitle');
    
    return Column(
      children: [
        Text(title),
        Text(subtitle),
      ],
    );
  }
}

Método 4: Usando Extensión BuildContext

Usa el método translate en BuildContext:

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text(context.translate('app_title')),
        Text(context.translate('app_subtitle')),
      ],
    );
  }
}

Paso 6: Usar Parámetros en Traducciones

Azbox soporta tanto argumentos posicionales como nombrados en las traducciones.

Argumentos Posicionales

Usa argumentos posicionales cuando tengas parámetros ordenados:

En el Panel de Azbox:

// Clave de traducción: "welcome_user"
// Inglés: "Welcome, {0}! You have {1} messages."
// Español: "¡Bienvenido, {0}! Tienes {1} mensajes."

En Flutter:

Text('welcome_user').translate(
  args: ['John', '5'],
)
// Inglés: "Welcome, John! You have 5 messages."
// Español: "¡Bienvenido, John! Tienes 5 mensajes."

Argumentos Nombrados

Usa argumentos nombrados para mejor legibilidad:

En el Panel de Azbox:

// Clave de traducción: "user_greeting"
// Inglés: "Hello, {name}! You are using {app}."
// Español: "¡Hola, {name}! Estás usando {app}."

En Flutter:

Text('user_greeting').translate(
  namedArgs: {
    'name': 'John',
    'app': 'Flutter',
  },
)
// Inglés: "Hello, John! You are using Flutter."
// Español: "¡Hola, John! Estás usando Flutter."

Paso 7: Manejar Pluralización

Azbox soporta pluralización usando el formato de mensaje ICU:

En el Panel de Azbox:

// Clave de traducción: "items_count"
// Inglés: "{count, plural, =0{No items} one{1 item} other{{count} items}}"
// Español: "{count, plural, =0{No hay elementos} one{1 elemento} other{{count} elementos}}"

En Flutter:

class ItemCountWidget extends StatelessWidget {
  final int count;
  
  ItemCountWidget({required this.count});
  
  @override
  Widget build(BuildContext context) {
    return Text('items_count').translate(
      namedArgs: {'count': count.toString()},
    );
  }
}

// Uso:
// ItemCountWidget(count: 0) → "No items" (Inglés) / "No hay elementos" (Español)
// ItemCountWidget(count: 1) → "1 item" (Inglés) / "1 elemento" (Español)
// ItemCountWidget(count: 5) → "5 items" (Inglés) / "5 elementos" (Español)

Paso 8: Cambiar Idioma Programáticamente

Permite a los usuarios cambiar idiomas:

import 'package:flutter/material.dart';
import 'package:azbox_localization/azbox_localization.dart';

class LanguageSwitcher extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return DropdownButton<String>(
      value: context.locale.languageCode,
      items: [
        DropdownMenuItem(value: 'en', child: Text('English')),
        DropdownMenuItem(value: 'es', child: Text('Español')),
        DropdownMenuItem(value: 'fr', child: Text('Français')),
      ],
      onChanged: (String? newLocale) {
        if (newLocale != null) {
          Azbox.setLocale(Locale(newLocale));
        }
      },
    );
  }
}

Paso 9: Manejar Estados de Carga

Muestra indicadores de carga mientras se obtienen las traducciones:

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      localizationsDelegates: context.localizationDelegates,
      supportedLocales: context.supportedLocales,
      locale: context.locale,
      builder: (context, child) {
        // Mostrar carga mientras se cargan las traducciones
        if (!Azbox.isInitialized) {
          return MaterialApp(
            home: Scaffold(
              body: Center(child: CircularProgressIndicator()),
            ),
          );
        }
        return child!;
      },
      home: MyHomePage(),
    );
  }
}

Paso 10: Configurar Claves de Traducción en Azbox

Antes de usar traducciones, configúralas en tu panel de Azbox:

1. Inicia sesión en el Panel de Azbox
2. Navega a tu proyecto
3. Ve a la sección Traducciones
4. Añade claves de traducción para cada texto que quieras traducir
5. Añade traducciones para cada idioma que soportes

Ejemplo de Claves de Traducción:

• app_title: “My Flutter App” (Inglés), “Mi Aplicación Flutter” (Español)
• welcome_message: “Welcome to our app!” (Inglés), “¡Bienvenido a nuestra aplicación!” (Español)
• button_submit: “Submit” (Inglés), “Enviar” (Español)

Mejores Prácticas

1. Usar Claves de Traducción Descriptivas

Malo:

Clave: "msg1"
Valor: "Submit"

Bueno:

Clave: "button_submit"
Valor: "Submit"

2. Organizar Claves por Característica

Agrupa traducciones relacionadas:

auth_login
auth_logout
auth_signup

dashboard_title
dashboard_welcome

settings_language
settings_theme

3. Proporcionar Contexto en los Nombres de Claves

Usa nombres descriptivos que indiquen contexto:

button_delete_item
button_delete_account
action_delete_comment

4. Manejar Traducciones Faltantes

Azbox proporciona fallback al idioma por defecto. Siempre asegúrate de que tu idioma por defecto (generalmente inglés) tenga todas las traducciones:

// Si falta la traducción, Azbox recurre al idioma por defecto
Text('some_key').translate() // Recurre al inglés si falta la traducción

5. Probar Todos los Idiomas

Prueba tu app en todos los idiomas soportados para asegurar:

• Todas las traducciones están presentes
• El diseño de la UI acomoda texto más largo
• Los idiomas RTL se muestran correctamente (si están soportados)

6. Mantener la API Key Segura

Nunca subas tu API key al control de versiones:

Usa variables de entorno:

import 'package:flutter_dotenv/flutter_dotenv.dart';

void main() async {
  await dotenv.load(fileName: ".env");
  
  await Azbox.ensureInitialized(
    apiKey: dotenv.env['AZBOX_API_KEY']!,
    projectId: dotenv.env['AZBOX_PROJECT_ID']!,
  );
  
  runApp(Azbox(child: MyApp()));
}

Crea archivo .env (añade a .gitignore):

AZBOX_API_KEY=tu_api_key_aqui
AZBOX_PROJECT_ID=tu_project_id_aqui

Errores Comunes

1. Olvidar Inicializar Azbox

Siempre inicializa Azbox antes de ejecutar tu app:

// ❌ No funcionará
void main() {
  runApp(MyApp());
}

// ✅ Correcto
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Azbox.ensureInitialized(apiKey: '...', projectId: '...');
  runApp(Azbox(child: MyApp()));
}

2. No Envolver la App con el Widget Azbox

El widget Azbox debe envolver tu app raíz:

// ❌ No funcionará
runApp(MyApp());

// ✅ Correcto
runApp(Azbox(child: MyApp()));

3. No Configurar MaterialApp

Asegúrate de usar los delegados de localización de Azbox:

// ❌ No funcionará
MaterialApp(
  home: MyHomePage(),
)

// ✅ Correcto
MaterialApp(
  localizationsDelegates: context.localizationDelegates,
  supportedLocales: context.supportedLocales,
  locale: context.locale,
  home: MyHomePage(),
)

4. Codificar Cadenas

Malo:

Text('Welcome')

Bueno:

Text('welcome_message').translate()

Avanzado: Detección Personalizada de Locale

Detecta y establece el locale basándose en la configuración del dispositivo:

import 'package:flutter/material.dart';
import 'package:azbox_localization/azbox_localization.dart';
import 'dart:ui' as ui;

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Obtener locale del dispositivo
  final deviceLocale = ui.PlatformDispatcher.instance.locale;
  
  await Azbox.ensureInitialized(
    apiKey: 'Tu API Key',
    projectId: 'Tu project ID',
  );
  
  // Establecer locale basándose en el dispositivo
  final supportedLocales = ['en', 'es', 'fr'];
  final locale = supportedLocales.contains(deviceLocale.languageCode)
      ? deviceLocale
      : Locale('en');
  
  Azbox.setLocale(locale);
  
  runApp(Azbox(child: MyApp()));
}

Avanzado: Persistir Preferencia de Idioma

Guarda la elección de idioma del usuario:

import 'package:shared_preferences/shared_preferences.dart';

class LanguageService {
  static const String _languageKey = 'selected_language';
  
  static Future<void> saveLanguage(String languageCode) async {
    final prefs = await SharedPreferences.getInstance();
    await prefs.setString(_languageKey, languageCode);
    Azbox.setLocale(Locale(languageCode));
  }
  
  static Future<Locale?> getSavedLanguage() async {
    final prefs = await SharedPreferences.getInstance();
    final languageCode = prefs.getString(_languageKey);
    return languageCode != null ? Locale(languageCode) : null;
  }
}

// Uso en inicialización de la app
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  await Azbox.ensureInitialized(
    apiKey: 'Tu API Key',
    projectId: 'Tu project ID',
  );
  
  // Cargar idioma guardado
  final savedLocale = await LanguageService.getSavedLanguage();
  if (savedLocale != null) {
    Azbox.setLocale(savedLocale);
  }
  
  runApp(Azbox(child: MyApp()));
}

Avanzado: Manejar Actualizaciones de Traducciones

Azbox puede actualizar traducciones over-the-air. Maneja eventos de actualización:

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    
    // Escuchar actualizaciones de traducciones
    Azbox.onTranslationsUpdated = () {
      setState(() {
        // Reconstruir UI con nuevas traducciones
      });
    };
  }
  
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      localizationsDelegates: context.localizationDelegates,
      supportedLocales: context.supportedLocales,
      locale: context.locale,
      home: MyHomePage(),
    );
  }
}

Avanzado: Manejo de Errores

Maneja errores durante la inicialización:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  try {
    await Azbox.ensureInitialized(
      apiKey: 'Tu API Key',
      projectId: 'Tu project ID',
    );
    
    runApp(Azbox(child: MyApp()));
  } catch (e) {
    // Manejar error de inicialización
    print('Fallo en la inicialización de Azbox: $e');
    
    // Fallback: Ejecutar app sin Azbox (usar traducciones codificadas)
    runApp(MyApp());
  }
}

Probar tu Implementación

Probar en iOS

1. Abre tu proyecto en Xcode
2. Selecciona un simulador (iOS 16+)
3. Ejecuta la app
4. Prueba el cambio de idioma

Probar en Android

1. Usa un dispositivo o emulador Android 5.0+
2. Asegúrate de que Google Play Services esté instalado
3. Ejecuta la app
4. Prueba el cambio de idioma

Probar Actualizaciones de Traducciones

1. Actualiza una traducción en el panel de Azbox
2. La app debería obtener y mostrar automáticamente la traducción actualizada
3. ¡No se requiere reconstruir la app!

Conclusión

Localizar tu app Flutter con Azbox es sencillo cuando sigues estos pasos:

1. Instala el paquete azbox-localization
2. Obtén tu API key y Project ID del panel de Azbox
3. Inicializa Azbox en tu main.dart antes de ejecutar la app
4. Envuelve tu app con el widget Azbox
5. Configura MaterialApp con los delegados de localización de Azbox
6. Usa traducciones en toda tu app con los métodos de extensión convenientes
7. Maneja parámetros y pluralización según sea necesario
8. Prueba exhaustivamente en todos los idiomas soportados

Al usar Azbox, te beneficias de:

• Gestión de traducciones basada en la nube - Actualiza traducciones sin actualizaciones de la app
• Flujo de trabajo colaborativo - Trabaja con traductores a través de la plataforma Azbox
• Sincronización automática - Las traducciones se sincronizan automáticamente con tu app
• Actualizaciones over-the-air - Actualiza traducciones sin reconstruir tu app

Comienza con Azbox

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

1. Regístrate en Azbox - Obtén un plan Starter o superior
2. Crea un proyecto - Configura tu proyecto Flutter en Azbox
3. Añade traducciones - Importa o añade tus claves de traducción
4. Instala el SDK - Sigue esta guía para integrar Azbox
5. Comienza a localizar - Usa las potentes características de Azbox para gestionar traducciones

Explora la plataforma de localización de AZbox y optimiza tu flujo de trabajo de traducción:

Ver Planes y Precios de AZbox

Lee la Documentación del SDK de Flutter