Guía rápida · Flutter

Objetivo: de un proyecto vacío a tu primer texto traducido, en menos de diez minutos. Cada comando y cada snippet salen del paquete publicado, no de la memoria.

Antes de empezar

• Flutter 3.x con un proyecto que puedas ejecutar
• Una cuenta de AZbox
• Tu app_en.arb, o un puñado de textos cualquiera

1 · Crea el proyecto e importa tus textos

Las keywords se crean en el panel de AZbox, no desde el código. No hay ninguna llamada en el SDK que las suba.

1. En el panel, Create Project. Pon nombre, idioma de origen e idiomas de destino.
2. Importa tu archivo .arb, o añade keywords una a una con Add Keyword.
3. Desde el proyecto, copia el Project ID y tu API key.

Si ya tienes app_en.arb, importarlo es el camino más rápido: AZbox lee ARB de forma nativa y conserva los metadatos @key y los placeholders.

2 · Instala el SDK

El paquete en pub.dev se llama azbox. No azbox_localization: ese nombre no existe y flutter pub add falla con él.

# pubspec.yaml
dependencies:
  azbox: ^1.0.16

flutter pub get

3 · Inicializa

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

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Azbox.ensureInitialized(
    apiKey: 'tu-api-key',
    projectId: 'tu-project-id',
  );

  runApp(Azbox(child: MyApp()));
}

Envolver la app en Azbox es lo que deja disponibles los delegados de localización más abajo:

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      localizationsDelegates: context.localizationDelegates,
      supportedLocales: context.supportedLocales,
      locale: context.locale,
      home: MyHomePage(),
    );
  }
}

4 · Lee un texto

Text('home.title'.tr())

Ejecuta la app. Si el texto vuelve traducido, ya está — lo demás es escala.

5 · Actualizaciones over-the-air

Esto es lo que una hoja de cálculo no puede hacer. Cambia el texto en español desde el panel y, la próxima vez que la app pida traducciones, recoge el valor nuevo. Sin build, sin revisión de tienda.

Conviene decidirlo a conciencia: cada cuánto refresca tu app y qué muestra si la petición falla. Caer en el último valor conocido casi siempre es mejor que caer en una cadena vacía.

6 · En CI

Las credenciales, fuera del repositorio:

# .github/workflows/build.yml
env:
  AZBOX_API_KEY: ${{ secrets.AZBOX_API_KEY }}
  AZBOX_PROJECT_ID: ${{ secrets.AZBOX_PROJECT_ID }}

Si algo falla

• flutter pub add azbox_localization falla — ese paquete no existe. Es azbox.
• El texto sale como su clave — la keyword no está en el proyecto, o no tiene traducción todavía en ese idioma. La clave es el fallback honesto; míralo en el panel.
• No llega nada por OTA — comprueba que el código de idioma del proyecto coincide con el locale que pide la app.

Siguiente

• Referencia de archivos ARB
• Todas las guías de integración