Learn about Flutter internationalization in our blog post.

You might be also interested in learning about our Flutter SDK with over-the-air support

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.

Introduction

While both JSON and ARB files can be utilized in Flutter, the latter format is preferred. ARB format is similar to JSON but it isn't just as simple as a key-value format. An ARB file can store string resources that have additional features like placeholders, plural and gender support etc.

Here's an example:

{
  "@@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.

File structure

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. Saved as a key language during the import process.
@@context. Describes context for all resources. Currently ignored.
@@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.

You can find the full ARB specification on GitHub.

Lokalise universal placeholders

Android Resources (.xml)

Apple Stringsdict (.stringsdict)

XLIFF (.xlf, .xliff)

Apple XLIFF (.xliff)