Flutter ARB file (.arb)

Documentation

What is ARB file?

ARB stands for Application Resource Bundle. It is actually a JSON file on steroids intended for localization, with .arb extension. Since it is based on JSON, it just defines standardized ways how to add more information around key-value pairs.

ARB files offer a lot of capabilities, but here we will mention only those relevant for Flutter applications.

Sample ARB file

{
  "@@locale" : "en",

  "appName" : "Demo app",
  
  "pageLoginUsername" : "Your username",
  "@pageLoginUsername" : {},
  
  "pageLoginPassword" : "Your password",
  "@pageLoginPassword" : {},

  "pageHomeTitle" : "Welcome {firstName}",
  "@pageHomeTitle" : {
      "description" : "Welcome message on the Home screen",
      "placeholders": {
          "firstName": {}
      }
  },

  "pageHomeInboxCount" : "{count, plural, zero{You have no new messages} one{You have 1 new message} other{You have {count} new messages}}",
  "@pageHomeInboxCount" : {
      "description" : "New messages count on the Home screen",
      "placeholders": {
          "count": {}
      }
  },

  "pageHomeBirthday": "{sex, select, male{His birthday} female{Her birthday} other{Their birthday}}",
  "@pageHomeBirthday": {
      "description": "Birthday message on the Home screen",
      "placeholders": {
          "sex": {}
      }
  },

  "commonVehicleType": "{vehicleType, select, sedan{Sedan} cabriolet{Solid roof cabriolet} truck{16 wheel truck} other{Other}}",
  "@commonVehicleType": {
      "description": "Vehicle type",
      "placeholders": {
          "vehicleType": {}
      }
  }
}

In the given example we have the following:

“@@locale” – (optional) a global attribute that defined locale for translated strings
“appName” – a minimal key-value pair with translation
“@pageLoginUsername” – a key prefixed with @ represents a json object with additional attributes for the same key. It is optional if using Flutter Intl IDE plugin
“description” – (optional) short text describing the string key and how it is being used in the app, explaining the context to translators
“placeholders” – A map of placeholder ids. It is optional if using Flutter Intl IDE plugin. Otherwise, all placeholders from translation should be listed.

Tired of manually editing translation files?

Our platform streamlines software localization for you.

Try now for Free

ARB file features

All localization file formats have some specific features. Here we will list those for ARB file, relevant for Flutter apps.

Placeholder

Placeholder is marked by curly brackets. Variable name inside {} must be a valid identifier, like {firstName}.

The simplest placeholder example:

"pageHomeTitle" : "Welcome {firstName}",
"@pageHomeTitle" : {
    "placeholders": {
        "firstName": {}
    }
}

Note that @pageHomeTitle object is not needed if using Flutter Intl IDE plugin.

The placeholder example with all possible parameters for DateTime and double types:

"pageHomeBalance" : "Your balance is {amount} on {date}",
"@pageHomeBalance" : {
    "placeholders": {
        "amount": {
            "type": "double",
            "format": "currency",
            "example": "$1000.00",
            "description": "Account balance",
            "optionalParameters": {
                "decimalDigits": 2,
                "name": "USD",
                "symbol": "$",
                "customPattern": "¤#0.00"
            }
        },
        "date": {
            "type": "DateTime",
            "format": "yMd",
            "example": "11/10/2021",
            "description": "Balance date"
        }
    }
}

Placeholder’s type parameter can have one of the following values: String, Object, int, double, num, DateTime.

optionalParameters are available for int, double and num placeholder types, and depend on the format value:

“format” value	Available “optionalParameters”	Example output for “1 200 000”
compact	–	“1.2M”
compactCurrency	name (example: “USD”), symbol (example: “$”), decimalDigits (example: 2)	“USD1.2M”
compactSimpleCurrency	name (example: “USD”), decimalDigits (example: 2)	“$1.2M”
compactLong	–	“1.2 million”
currency	name (example: “USD”), symbol (example: “$”), decimalDigits (example: 2), customPattern (example: “¤#0.00”)	“USD1,200,000.00”
decimalPattern	–	“1,200,000”
decimalPercentPattern	decimalDigits (example: 2)	“120,000,000%”
percentPattern	–	“120,000,000%”
scientificPattern	–	“1E6”
simpleCurrency	name (example: “USD”), decimalDigits (example: 2)	“$1,200,000.00”

DateTime placeholder types support different predefined format options, such as yMd, Hms and similar. The full list of format options is derived from DateFormat class constructors. In case you need a custom date-time format, set isCustomDateFormat to "true" and define your format:

"commonCustomDateFormat": "Custom date format: {date}",
"@commonCustomDateFormat": {
    "placeholders": {
        "date": {
            "type": "DateTime",
            "format": "EEE, M/d/y",
            "isCustomDateFormat": "true"
        }
    }
}

Plural

Plurals are defined with ICU syntax.

"pageHomeInboxCount" : "{count, plural, zero{You have no new messages} one{You have 1 new message} other{You have {count} new messages}}",
"@pageHomeInboxCount" : {
    "description" : "New messages count on the Home screen",
    "placeholders": {
        "count": {}
    }
},

other is a mandatory case.

Gender

Genders are defined with ICU syntax.

"pageHomeBirthday": "{sex, select, male{His birthday} female{Her birthday} other{Their birthday}}",
"@pageHomeBirthday": {
    "description": "Birthday message on the Home screen",
        "placeholders": {
        "sex": {}
    }
},

other is a mandatory case.

Select

Custom selects are defined with ICU syntax.

"commonVehicleType": "{vehicleType, select, sedan{Sedan} cabriolet{Solid roof cabriolet} truck{16 wheel truck} other{Other}}",
"@commonVehicleType": {
    "description": "Vehicle type",
    "placeholders": {
        "vehicleType": {}
    }
}

other is a mandatory case.

Newline

Since ARB file is based on JSON structure, a new line needs to be escaped with `\n` character.
Note that actual printing on the screen depends on the widget used.

"pageHomeTitle": "Welcome,\n{firstName}",

Previous: Supported file formats

Tired of manually editing translation files?

Our platform streamlines software localization for you.

Try now for Free

Flutter ARB file (.arb)

Documentation

What is ARB file?

Sample ARB file

ARB file features

Placeholder

Plural

Gender

Select

Newline

Documentation

About

Resources

Boring stuff