ARB File Import

Azbox fully supports ARB (Application Resource Bundle) files, the standard localization format used by Flutter applications. This guide explains what ARB files are, their structure, and how to import them into Azbox.

What are ARB Files?

ARB (Application Resource Bundle) is a JSON-based localization file format originally created by Google and adopted as the standard format for Flutter internationalization. ARB files are used by the intl and flutter_localizations packages to manage translations in Flutter applications.

Each ARB file typically contains translations for a single locale, with the filename following the pattern intl_<locale>.arb (e.g., intl_en.arb, intl_es.arb).

ARB File Structure

An ARB file is essentially a JSON file with a specific structure:

{
  "@@locale": "en",
  "greeting": "Hello, World!",
  "@greeting": {
    "description": "A simple greeting message"
  },
  "welcomeMessage": "Welcome to {appName}!",
  "@welcomeMessage": {
    "description": "Welcome message with app name",
    "placeholders": {
      "appName": {
        "type": "String",
        "example": "Azbox"
      }
    }
  }
}

Key Components

Component	Description
@@locale	Global metadata specifying the locale code (e.g., en, es, fr)
Translation keys	Regular keys containing the translated text
@key metadata	Optional metadata for each translation key (description, placeholders, etc.)

ARB Format Features

1. Locale Identification

The locale can be specified in two ways:

Via @@locale key:

{
  "@@locale": "en"
}

Via filename:

• intl_en.arb → English
• intl_es.arb → Spanish
• app_fr.arb → French

2. Placeholders

ARB supports dynamic placeholders using curly braces:

{
  "greeting": "Hello, {userName}!",
  "@greeting": {
    "description": "Greeting with user name",
    "placeholders": {
      "userName": {
        "type": "String",
        "example": "John"
      }
    }
  }
}

3. Pluralization

ARB supports ICU message format for plurals:

{
  "itemCount": "{count, plural, =0{No items} =1{One item} other{{count} items}}",
  "@itemCount": {
    "description": "Number of items",
    "placeholders": {
      "count": {
        "type": "int"
      }
    }
  }
}

Plural categories:

• =0, zero - Zero items
• =1, one - Exactly one item
• two - Two items (used in some languages)
• few - A few items (language-specific)
• many - Many items (language-specific)
• other - Required - Default case

4. Gender Selection

{
  "welcomeGender": "{gender, select, male{Welcome, Mr. {name}} female{Welcome, Ms. {name}} other{Welcome, {name}}}",
  "@welcomeGender": {
    "placeholders": {
      "gender": {
        "type": "String"
      },
      "name": {
        "type": "String"
      }
    }
  }
}

5. Metadata Keys

The @key entries provide additional information:

{
  "submitButton": "Submit",
  "@submitButton": {
    "description": "Label for the submit button",
    "context": "Form submission"
  }
}

Important

Metadata keys (starting with @) should only be present in the main/source language file. Translation files should only contain the @@locale key and the actual translations.

Complete ARB Example

Here's a complete example of an English ARB file:

intl_en.arb

{
  "@@locale": "en",
  "@@last_modified": "2024-01-15T10:30:00.000Z",
  
  "appTitle": "My Application",
  "@appTitle": {
    "description": "The title of the application"
  },
  
  "loginButton": "Log In",
  "@loginButton": {
    "description": "Button text for login action"
  },
  
  "welcomeUser": "Welcome back, {userName}!",
  "@welcomeUser": {
    "description": "Welcome message for returning users",
    "placeholders": {
      "userName": {
        "type": "String",
        "example": "Alice"
      }
    }
  },
  
  "notificationCount": "{count, plural, =0{No new notifications} =1{1 new notification} other{{count} new notifications}}",
  "@notificationCount": {
    "description": "Notification count message",
    "placeholders": {
      "count": {
        "type": "int"
      }
    }
  },
  
  "lastLogin": "Last login: {date}",
  "@lastLogin": {
    "description": "Shows the last login date",
    "placeholders": {
      "date": {
        "type": "DateTime",
        "format": "yMMMd"
      }
    }
  }
}

And its Spanish translation:

intl_es.arb

{
  "@@locale": "es",
  "appTitle": "Mi Aplicación",
  "loginButton": "Iniciar Sesión",
  "welcomeUser": "¡Bienvenido de nuevo, {userName}!",
  "notificationCount": "{count, plural, =0{Sin notificaciones nuevas} =1{1 notificación nueva} other{{count} notificaciones nuevas}}",
  "lastLogin": "Último acceso: {date}"
}

Importing ARB Files into Azbox

Step 1: Access the Import Dialog

1. Navigate to your project in Azbox
2. Click on the Import button in the dashboard
3. The Import Keywords dialog will appear

Step 2: Select ARB Format

1. In the File Format dropdown, select Flutter (.arb)
2. A language selector will appear below

Step 3: Choose Target Language

Select the language that corresponds to your ARB file(s). This tells Azbox which language column to populate with the imported translations.

Multiple Files

You can select multiple ARB files at once. Azbox will parse each file and import all translations into the selected language.

Step 4: Import Files

1. Click the Import button
2. Select one or more .arb files from your computer
3. Azbox will parse the files and show the import progress

Step 5: Review Results

After import, Azbox displays a summary showing:

• ✅ Number of successfully imported keywords
• ⏭️ Number of skipped keywords (if any)
• ⚠️ Warnings (e.g., missing @@locale, naming convention issues)
• ❌ Errors (if any parsing errors occurred)

What Azbox Extracts

When importing ARB files, Azbox extracts:

Element	Imported
Translation keys	✅ Yes
Translation values	✅ Yes
Placeholders in text	✅ Yes (preserved in translation)
Plural forms	✅ Yes (ICU format preserved)
@key metadata	⚠️ Parsed for validation
@@locale	✅ Used for language detection

Validation & Warnings

Azbox performs validation during import:

• Missing @@locale: Warning if the locale is not specified
• Placeholder validation: Checks that placeholders in text are defined in metadata
• Plural validation: Ensures other case is present in plural strings
• Naming convention: Warns if keys don't follow camelCase convention

Best Practices

1. Use consistent key naming: Prefer camelCase for all translation keys
2. Include @@locale: Always specify the locale in your ARB files
3. One file per language: Keep translations for each language in separate files
4. Main file has metadata: Only include @key metadata in your source language file

Exporting Back to ARB

After managing your translations in Azbox, you can export them back to ARB format to use in your Flutter application.

---

Related Resources

• Flutter Internationalization Guide
• ARB File Specification
• ICU Message Format