Quickstart · Flutter

Target: from an empty project to your first translated string, in under ten minutes. Every command and snippet here comes from the published package, not from memory.

Before you start

• Flutter 3.x with a project you can run
• An AZbox account
• Your existing app_en.arb, or any handful of strings

1 · Create the project and import your strings

Keywords are created in the AZbox panel, not from code. There is no API call in the SDK that uploads them.

1. In the dashboard, Create Project. Set a name, the source language and the target languages.
2. Import your .arb file, or add keywords one by one with Add Keyword.
3. From the project, copy the Project ID and your API key.

If you already have app_en.arb, importing it is the fastest path: AZbox reads ARB natively and keeps the @key metadata and placeholders.

2 · Install the SDK

The package on pub.dev is called azbox. Not azbox_localization — that name does not exist and flutter pub add will fail on it.

# pubspec.yaml
dependencies:
  azbox: ^1.0.16

flutter pub get

3 · Initialise

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

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

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

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

Wrapping the app in Azbox is what makes the localisation delegates available downstream:

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

4 · Read a string

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

Run the app. If the string comes back translated, you are done — the rest is scale.

5 · Over-the-air updates

This is the part a spreadsheet cannot do. Change the Spanish text in the panel, and the next time the app fetches translations it picks up the new value. No new build, no store review.

Worth deciding deliberately: how often your app refreshes, and what it shows if the fetch fails. Falling back to the last known value is almost always better than falling back to an empty string.

6 · In CI

Keep the credentials out of the repository:

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

If something fails

• flutter pub add azbox_localization fails — that package does not exist. It is azbox.
• The string renders as its key — the keyword is not in the project, or it has no translation in that language yet. The key is the honest fallback; check the panel.
• Nothing updates over the air — confirm the language code in your project matches the locale the app is requesting.

Next

• ARB file reference
• All integration guides