ARB for Flutter
Translation File Format

ARB file format

ARB (Application Resource Bundle) is a simple text-based file format used to store key-value pairs of translations. It's essentially a single-language JSON file used for translations, following a specific structure commonly used in Flutter applications. Each ARB file should contain a @@locale field, which specifies the language or locale of the translations in the file. Like JSON, the format uses translation keys, created by the developer, with the translations as their corresponding values.

{
  "@@locale": "en",
  "home.interface.signup": "Signup",
  "@home.interface.signup": {
    "description": "The text on the signup button"
  },
  "home.interface.email": "Email",
  "home.interface.password": "Password",
  "@home.interface.password": {
    "description": "The text on the password input field"
  },
  "notifications_zero": "No notifications",
  "notifications_one": "You have one notification",
  "notifications_other": "You have {count} notifications",
  "@notifications_other": {
    "description": "The text that shows the number of notifications"
  }
}

The format by convention supports additional metadata like descriptions, placeholders, and plural forms. Metadata for translation keys are created by adding a key that starts with the @ symbol. They are used to provide context and additional information about the key, but they are not required or used by the Flutter framework itself. You can put any metadata you want in the ARB file, but it's a good practice to include descriptions for each key to make it easier for other developers to understand the purpose of the translation.

{
  "@@locale": "pl",
  "home.interface.signup": "Zarejestruj się",
  "@home.interface.signup": {
    "description": "The text on the signup button"
  },
  "home.interface.email": "Adres email",
  "home.interface.password": "Hasło",
  "@home.interface.password": {
    "description": "The text on the password input field"
  },
  "notifications_zero": "Brak powiadomień",
  "notifications_one": "Masz jedno powiadomienie",
  "notifications_other": "Masz {count} powiadomienia",
  "@notifications_other": {
    "description": "The text that shows the number of notifications"
  }
}

In most cases, one file contains translations for a single language. For example, you can have a file with translations for English (app_en.arb) and another file with translations for Polish (app_pl.arb).

@ symbol in ARB files

ARB files support metadata, placeholders, and plural forms by convention. That means it's basically a JSON format with assumption that keys that start with the @ symbol are metadata objects. You can use metadata to provide additional information about the translation keys, such as descriptions, placeholders, and plural forms. Metadata is not required by the Flutter framework. The most popular metadata key is description, which is used to provide a description of the translation key.placeholders are used to define placeholders in the translation value, and plural is used to define plural forms of the translation value.

File naming conventions

Even though ARB files are basically valid JSON files, they are typically named using the *.arb extension. The name of the file should reflect the purpose of the content, which is usually translations for a specific language. It is a good practice to include the language code in the file name. For example:

• messages_en.arb - English translations
• messages_pl.arb - Polish translations
• messages_de.arb - German translations

Content of ARB files can be very large, especially in complex mobile applications with many screens and features. Splitting translations into multiple files is rarely needed, since *.arb files are loaded on application startup.

Why we use ARB and not JSON?

Both ARB and JSON are text-based file formats that are used to store key-value pairs of translations. The main difference between the two formats is that ARB files support metadata, such as descriptions, placeholders, and plural forms, which are not supported by JSON. This makes ARB a better choice for managing translations in Flutter applications, where metadata is often used to provide context and additional information about the translations. The support comes from the convention of using keys that start with the @ symbol. In a regular JSON file, you would have to manage metadata separately.

What is Flutter?

Flutter is an open-source framework designed for building cross-platform applications and created by Google. It's mostly used to build mobile applications for Android and iOS, but it can also be used to build web. A huge advantage of Flutter is that it uses a single codebase for all platforms, which means that you can write your application once and run it on multiple platforms. Flutter uses the Dart programming language and provides a rich set of pre-built widgets and tools for building beautiful, responsive user interfaces.

Intl package for Flutter

The intl package is a popular choice for managing translations in Flutter applications. It provides a set of tools and utilities for formatting dates, numbers, and currencies, as well as managing translations and localization. The intl package supports the ARB file format, making it easy to load and use translations in your Flutter application.

How to use ARB files in Flutter?

Configuring i18n in Flutter with ARB is a multistep process that involves setting up the intl package, loading translations from ARB files, and using them in your application.

Are there other translation file formats for Flutter?

Yes, you can also use JSON (single language) that has a similar structure to ARB, it doesn't support metadata like ARB does, so you won't be able to add descriptions or placeholders to your translations during import. You can choose JSON (single language) format for exporting translations from SimpleLocalize, as metadata is not required for the Flutter framework to work. Please remember that the translations format used in Flutter depends mostly on the libraries and tools you are using in your project.

How to keep ARB files in sync?

Keeping translations in sync with your application code can be challenging, especially when you have to manage a few languages. Adding, editing or deleting one translation key in your application requires updating all translation files. This process can be time-consuming and error-prone, leading to inconsistencies or missing translations. To make this process easier, you can use SimpleLocalize and its translation editor to manage your translations in one place. You can upload your ARB files to our platform, edit translations, and download updated files with a single click. With features like auto-translation, AI actions, bulk actions, and CLI integration, you can keep your translations up-to-date and ensure that your application is localized for all your users.