ARB Files: Complete Guide to Application Resource Bundle Format

What Are ARB Files?

ARB (Application Resource Bundle) is a localization file format based on JSON, originally developed by Google. It’s the standard format for managing translations in Flutter applications and is widely used in the Dart ecosystem.

ARB files store translation strings along with their metadata, making them particularly powerful for handling complex localization scenarios including pluralization, gender, and custom placeholders.

Why AZbox Supports ARB Files

At AZbox, we understand that Flutter developers need seamless integration with their existing localization workflows. That’s why AZbox fully supports ARB file import and export, allowing you to:

• Import existing ARB files directly into your AZbox project
• Export translations back to ARB format for use in your Flutter app
• Manage translations with our powerful cloud-based platform
• Collaborate with translators who can work directly with your content
• Update over-the-air without rebuilding your app

ARB File Structure

ARB files use a JSON-based structure with a specific convention for keys and metadata. Here’s a basic example:

{
  "@@locale": "en",
  "@@last_modified": "2024-01-15T10:30:00.000Z",
  
  "appTitle": "My Flutter App",
  "@appTitle": {
    "description": "The title of the application"
  },
  
  "welcomeMessage": "Welcome to our app!",
  "@welcomeMessage": {
    "description": "Welcome message shown on the home screen"
  },
  
  "itemCount": "{count, plural, =0{No items} =1{1 item} other{{count} items}}",
  "@itemCount": {
    "description": "Shows the number of items",
    "placeholders": {
      "count": {
        "type": "int",
        "example": "5"
      }
    }
  }
}

Key Components

Component	Description
@@locale	The locale identifier (e.g., “en”, “es”, “fr”)
@@last_modified	Timestamp of last modification
messageKey	The translation key and value
@messageKey	Metadata for the translation key

ARB File Naming Convention

ARB files follow a specific naming convention that includes the locale:

• app_en.arb - English translations
• app_es.arb - Spanish translations
• app_fr.arb - French translations
• app_de.arb - German translations
• app_pt_BR.arb - Brazilian Portuguese translations

The base file (usually English) serves as the template, and other locale files contain the translated versions.

Metadata in ARB Files

One of the powerful features of ARB files is their ability to store rich metadata alongside translations:

Description Metadata

{
  "loginButton": "Sign In",
  "@loginButton": {
    "description": "Button text for user login action",
    "context": "Authentication screen"
  }
}

Placeholder Metadata

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

Multiple Placeholders

{
  "orderSummary": "Order #{orderId} - Total: {currency}{amount}",
  "@orderSummary": {
    "description": "Order summary with ID and total amount",
    "placeholders": {
      "orderId": {
        "type": "String",
        "example": "12345"
      },
      "currency": {
        "type": "String",
        "example": "$"
      },
      "amount": {
        "type": "double",
        "format": "decimalPattern",
        "example": "99.99"
      }
    }
  }
}

Pluralization in ARB Files

ARB files support ICU MessageFormat for handling pluralization:

{
  "messageCount": "{count, plural, =0{No messages} =1{1 message} other{{count} messages}}",
  "@messageCount": {
    "description": "Number of messages",
    "placeholders": {
      "count": {
        "type": "int",
        "example": "5"
      }
    }
  }
}

Pluralization Categories

Category	Description	Example Languages
zero	Zero items	Arabic, Latvian
one	Singular	English, Spanish
two	Dual	Arabic, Welsh
few	Few items	Russian, Polish
many	Many items	Russian, Arabic
other	Default/plural	All languages

Complex Pluralization Example

{
  "cartItems": "{count, plural, =0{Your cart is empty} =1{You have 1 item in your cart} other{You have {count} items in your cart}}",
  "@cartItems": {
    "description": "Shopping cart item count",
    "placeholders": {
      "count": {
        "type": "int",
        "example": "3"
      }
    }
  }
}

Gender Selection in ARB Files

ARB files also support gender-based message selection:

{
  "userWelcome": "{gender, select, male{Welcome, Mr. {name}} female{Welcome, Ms. {name}} other{Welcome, {name}}}",
  "@userWelcome": {
    "description": "Gender-specific welcome message",
    "placeholders": {
      "gender": {
        "type": "String"
      },
      "name": {
        "type": "String",
        "example": "Smith"
      }
    }
  }
}

Nested ICU Messages

For complex scenarios, you can nest plural and select statements:

{
  "notificationMessage": "{gender, select, male{{count, plural, =0{He has no notifications} =1{He has 1 notification} other{He has {count} notifications}}} female{{count, plural, =0{She has no notifications} =1{She has 1 notification} other{She has {count} notifications}}} other{{count, plural, =0{They have no notifications} =1{They have 1 notification} other{They have {count} notifications}}}}",
  "@notificationMessage": {
    "description": "Notification count with gender",
    "placeholders": {
      "gender": {
        "type": "String"
      },
      "count": {
        "type": "int",
        "example": "5"
      }
    }
  }
}

DateTime and Number Formatting

ARB files support formatted placeholders for dates and numbers:

Date Formatting

{
  "lastLogin": "Last login: {date}",
  "@lastLogin": {
    "description": "Shows the last login date",
    "placeholders": {
      "date": {
        "type": "DateTime",
        "format": "yMMMd",
        "example": "Jan 15, 2024"
      }
    }
  }
}

Number Formatting

{
  "productPrice": "Price: {price}",
  "@productPrice": {
    "description": "Product price display",
    "placeholders": {
      "price": {
        "type": "double",
        "format": "currency",
        "optionalParameters": {
          "symbol": "$",
          "decimalDigits": 2
        },
        "example": "$19.99"
      }
    }
  }
}

Importing ARB Files to AZbox

Step 1: Prepare Your ARB Files

Ensure your ARB files follow the standard naming convention and contain valid JSON:

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

Step 2: Import via AZbox Dashboard

1. Log in to your AZbox dashboard
2. Navigate to your project
3. Go to Import/Export section
4. Select Import and choose ARB as the format
5. Upload your ARB files
6. AZbox will automatically detect the locale from each file

Step 3: Review and Manage

After importing, you can:

• View all translations in a unified interface
• Edit translations directly in the platform
• Add new languages
• Use machine translation to fill in missing translations
• Collaborate with translators

Exporting ARB Files from AZbox

When you’re ready to use your translations in your Flutter app:

1. Go to Import/Export in your AZbox project
2. Select Export and choose ARB format
3. Select the languages you want to export
4. Download the generated ARB files
5. Place them in your Flutter project’s lib/l10n/ directory

Using ARB Files in Flutter

Project Setup

Add the localization package to your pubspec.yaml:

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

flutter:
  generate: true

Create l10n.yaml in your project root:

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

Generate Localization Code

Run the Flutter command to generate localization code:

flutter gen-l10n

This generates AppLocalizations class that you can use in your 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);
  }
}

Best Practices for ARB Files

1. Use Descriptive Key Names

Bad:

{
  "msg1": "Submit"
}

Good:

{
  "buttonSubmitForm": "Submit"
}

2. Always Include Descriptions

{
  "deleteConfirmation": "Are you sure you want to delete this item?",
  "@deleteConfirmation": {
    "description": "Confirmation dialog message when user attempts to delete an item"
  }
}

3. Provide Examples for Placeholders

{
  "welcomeUser": "Welcome back, {username}!",
  "@welcomeUser": {
    "placeholders": {
      "username": {
        "type": "String",
        "example": "JohnDoe123"
      }
    }
  }
}

4. Organize Keys by Feature

{
  "auth_loginTitle": "Sign In",
  "auth_loginButton": "Log In",
  "auth_logoutButton": "Log Out",
  
  "settings_title": "Settings",
  "settings_language": "Language",
  "settings_theme": "Theme"
}

5. Handle Edge Cases in Plurals

{
  "daysRemaining": "{days, plural, =0{Expires today} =1{1 day remaining} other{{days} days remaining}}",
  "@daysRemaining": {
    "placeholders": {
      "days": {
        "type": "int"
      }
    }
  }
}

Common ARB File Issues and Solutions

Issue: Invalid JSON Syntax

Problem: ARB files must be valid JSON. Common mistakes include:

• Trailing commas
• Missing quotes around strings
• Unescaped special characters

Solution: Use a JSON validator or IDE with JSON support to catch syntax errors.

Issue: Mismatched Placeholders

Problem: Placeholders in translations don’t match the base file.

Solution: AZbox automatically validates placeholder consistency across translations.

Issue: ICU Message Format Errors

Problem: Incorrect plural or select syntax.

Solution: Use AZbox’s built-in ICU message format validation.

AZbox ARB Features

When you import ARB files to AZbox, you benefit from:

• Automatic metadata preservation - All descriptions and placeholder info is maintained
• ICU message validation - Ensures plurals and selects are correctly formatted
• Placeholder consistency checks - Validates placeholders across all translations
• Visual editor - Edit ICU messages with a user-friendly interface
• Translation memory - Leverage previous translations for consistency
• Machine translation - Fill gaps with AI-powered translation
• Over-the-air updates - Update translations without app store approval

Conclusion

ARB files are the standard for Flutter localization, offering powerful features for handling complex translation scenarios. With AZbox’s full ARB support, you can:

1. Import existing ARB files with all metadata preserved
2. Manage translations in a collaborative cloud platform
3. Export ARB files ready for use in your Flutter project
4. Update translations over-the-air without rebuilding your app

Ready to streamline your Flutter localization workflow?

Start Your Free Trial | View Pricing

---

AZbox provides comprehensive support for ARB files, making it the ideal localization platform for Flutter developers. Import, manage, and export your translations with ease.