Flutter ARB file (.arb)

What is an ARB file?

ARB stands for Application Resource Bundle. It is essentially a JSON file enhanced for localization, with an .arb extension. Since it is based on JSON, it just defines standardized ways of adding additional information to key-value pairs.

ARB files provide various capabilities, but here we will only mention those relevant to 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 defines locale for translated strings.
“appName” – a basic 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 the 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 the Flutter Intl IDE plugin. Otherwise, all placeholders from the translation should be listed.

Tired of manually editing translation files?

Our platform streamlines software localization for you.

Try now for Free

ARB file features

Every localization file format is designed with specific capabilities. Here, we will explore all the features of the ARB file format, which are relevant for the localization of Flutter applications.

Placeholder

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

The most basic placeholder example:

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

The example that illustrates the use of all available parameters for placeholders of the double and DateTime 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"
        }
    }
}

The type parameter of a placeholder can have one of the following values: String, Object, int, double, num, or DateTime.

Placeholders of types int, double, and num allow certain optional parameters (optionalParameters) as well. These optional parameters vary depending on the specified format value:

“format” value	Available “optionalParameters”	Example output for “1 200 000”
compact	–	“1.2M”
compactCurrency	name (example: “USD”), symbol (example: “$”), decimalDigits (example: 2)	“$1.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”)	“$1200000.00”
decimalPattern	–	“1,200,000”
decimalPatternDigits	decimalDigits (example: 2)	“1,200,000.00”
decimalPercentPattern	decimalDigits (example: 2)	“120,000,000.00%”
percentPattern	–	“120,000,000%”
scientificPattern	–	“1E6”
simpleCurrency	name (example: “USD”), decimalDigits (example: 2)	“$1,200,000.00”

Placeholders based on the DateTime type offer a variety of predefined format options, such as yMd and Hms, among others. These options are derived from the constructors of the DateFormat class. If the 41 provided format options do not meet your requirements, you have the flexibility to implement a custom date-time format. To do this, simply set isCustomDateFormat to "true" and specify your desired format.

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

Moreover, you can specify multiple DateTime formats for a single placeholder by separating them with a "+". This approach also enables the creation of custom formats by combining predefined ones.

"commonMultipleDateFormats": "Custom date format: {date}",
"@commonMultipleDateFormats": {
    "placeholders": {
        "date": {
            "type": "DateTime",
            "format": "yMEd+Hm"
        }
    }
}

To define a DateTime placeholder and its format within a translation, you can utilize the ICU Message Format syntax. This approach simplifies the application of different DateTime formats to the same placeholder across different ARB files.

"commonInlineDateFormat": "Date format: {currDate, date, ::yMd}",
"@commonInlineDateFormat": {
    "placeholders": {
        "currDate": {}
    }
}

Note: If you're using the gen-l10n tool and the ARB Editor extension in VS Code for ARB file editing, be aware that the ARB Editor might incorrectly flag localization messages that utilize custom date formats, incorporate multiple formats, or use ICU Message Format Syntax for dates as problematic. This issue may occur because the ARB Editor may not yet have added support for the placeholder syntax that was recently introduced.

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 an ARB file is based on the JSON format, a new line is indicated by the newline character \n.
Note that the actual display on the screen depends on the widget used.

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

Special chars

In certain situations during the localization process, you may need to treat special characters, such as { and }, as regular text. The method to achieve this largely depends on the localization tool being used. For instance, if you are using the gen-l10n tool, you should enclose the relevant section of the message in single quotes and enable the escaping mechanism by setting use-escaping to true in your l10n.yaml file.

Note that other tools may not support this functionality or they might require a different approach.

"escapingExample": "In math, '{1, 2, 3}' denotes a set."

HTML tags

In some cases, you might use HTML tags in localization messages. This is known to be beneficial as it prevents the message from being divided into smaller parts for styling purposes or other advantages. An example of such a message is shown below.

"htmlExample": "<i>Discover <b>Flutter</b></i>"

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 an ARB file?

Sample ARB file

ARB file features

Placeholder

Plural

Gender

Select

Newline

Special chars

HTML tags

Documentation

About

Resources

Free tools

Boring stuff

Newsletter