Flutter is an open-source UI software development kit by Google used to develop applications for Android, iOS, Linux, Mac, Windows, Google Fuchsia, and web from a single codebase.

Technical information

Overview

Format name:
Application Resource Bundle (ARB)

File extensions:
.arb

Common use cases:
Managing localized text strings in Flutter applications, including support for placeholders, plurals, and gender-specific translations.

Technical details:

Structure: ARB files are JSON-like files that store localizable resources as key-value pairs, with additional metadata for context, description, placeholders, and other attributes.
Encoding: UTF-8

Example:
Here's an example of a typical ARB file:

{
  "@@locale": "en_US",
  "title_bar": "My Cool Home",
  "@title_bar": {
    "type": "text",
    "context": "HomePage",
    "description": "Page title."
  },
  "MSG_OK": "Everything works fine.",
  "FOO_123": "Your pending cost is {COST}",
  "@FOO_123": {
    "type": "text",
    "context": "HomePage:MainPanel",
    "description": "balance statement.",
    "source_text": "Your pending cost is {COST}",
    "placeholders": {
      "COST": {
        "example": "$123.45",
        "description": "cost presented with currency symbol"
      }
    },
    "screen": "data:image/png;base64,iVBORw0KGgo...",
    "video": "http://www.youtube.com/ajigliech"
  },
  "BAR_231": "images/image_bar.jpg"
}

In ARB, localizable resources are encoded as a JSON object. Each resource has a resource entry identified by a resource key, and an optional resource attribute entry with a resource attribute key.

Please note that as long as Flutter is used to create cross-platform apps, your translation keys imported from the ARB file will be assigned with the Other platform.

ARB file structure and using ARB on Lokalise

Supported project types

Please note that ARB files can be uploaded only to Web and mobile projects.

Resource ID and Resource Value

The resource ID is a resource identifier inside the given namespace. Resource values in ARB files are always strings:

{"title_bar": "My Sample"}

Make sure you name your resource IDs properly:

ID cannot start with an underscore or a number
It should contain only alphanumeric symbols
It must start with a lowercase character

Placeholders

Placeholders are wrapped with curly brackets, and can contain either position or variable name:

{
  "hello": "Hello {0}",
  "hello": "Hello {name}"
}

On Lokalise:

Note that you can convert these placeholders into the universal ones while importing to Lokalise.

A special placeholder syntax (with @ directly after the opening curly bracket) is used to guard certain content from being modified by translators:

{
  "hello_with_markup": "Hello {@<b>}World{@</b>}"
}

On Lokalise:

Plural and gender support

The ICU syntax is used to support plurals and genders. Please note however that plural and gender support in ARB is experimental.

{
  "pageHomeBirthday": "{sex, select,
    male{His birthday}
    female{Her birthday}
    other{Their birthday}}",

  "pageHomeInboxCount": "{count, plural,
    zero{You have no new messages}
    one{You have 1 new message}
    other{You have {count} new messages}}"
}

On Lokalise (gender support):

Please note that if your ARB file contains plurals, you can enable Detect ICU plurals option during the import process:

In this case your key will be recognized as plural:

Resource attributes

A resource can also have a set of additional attributes. These attributes are embedded into an attribute item keyed by original resource ID plus @ prefix. The value part of an attribute item is a map object that contains a list of attributes as name/value pairs.

type (string). Possible values: text | image | css. type will be saved as a custom attribute. Custom attributes are added to the export bundle by default.
context (string). Describes the context in which this resource applies. Context is organized hierarchically, and different levels are separated with : (colon). context will be saved to the "context" field of the translation key inside Lokalise. Context is added to the export bundle by default.
description (string). Describes the resource. Saved to the "description" field of the translation key. If you would like to add keys description to the downloaded translation bundle, enable the Include description option during the export.
screenshot (string). A URL to the image location or base-64 encoded image data. Saved as a screenshot (for base-64 encoded image data) or as a custom attribute (for URLs). Custom attributes are added to the export bundle by default. Please note that by default the exported URL will have forward slashes escaped meaning that http://www.example.com/sample turns to http:\/\/www.example.com\/sample. If you don't want this to happen, enable the Unescape forward slashes option during the export process.
video (string). A video URL of the app/resource/widget in action. Saved as a custom attribute. Custom attributes are added to the export bundle by default. Please note that by default the exported URL will have forward slashes escaped meaning that http://www.youtube.com/sample turns to http:\/\/www.youtube.com\/sample. If you don't want this to happen, enable the Unescape forward slashes option during the export process.
source_text (string). The source text for the translation. Currently ignored by Lokalise.
placeholders (object). Saved as a placeholder in Lokalise, while all additional data is saved as custom attributes. Skipped if the placeholder is treated as literal.

There are two important rules considering placeholders:

All placeholders in valid syntax are interpreted as placeholders if there is no placeholders property inside the attributes.
A placeholder in valid syntax is treated as literal if messages don't have the placeholders property, but the placeholder has no corresponding entry inside the placeholders map. In other words, if the placeholders property is present, it must be complete.

Customized attributes

While it is possible to create customized attributes prefixed with x-, Lokalise currently ignores these as they are tool-specific.

Global attributes

On top level there can be a set of global attributes that apply to the resource bundle as a whole. Global attribute names are prefixed with @@.

@@locale. The locale of the translation file that is used to perform language detection. Saved as a file language during the import process.
@@context. Describes context for all resources. Currently ignored by Lokalise.
@@last_modified. The last modification datetime of the ARB file. Should be provided in ISO8601 format, for example: 2020-09-08T09:42-07:00. Currently ignored on import, but during the export uses the most recent modification date among all keys included in the export bundle.
@@author. Author of the translation file. Currently ignored by Lokalise.

Known limitations

Placeholder Handling: Ensure all placeholders are properly defined to avoid misinterpretation.
Plural and Gender Support: Experimental and might not cover all use cases.
Customized Attributes: Tool-specific attributes prefixed with x- are ignored by Lokalise.

Additional reading

Android Resources (.xml)

Apple Stringsdict (.stringsdict)

Gettext (.po, .pot)

Qt Linguist (.ts)

XLIFF (.xlf, .xliff)