ARB Glue #

ARB Glue is a tool that merges multiple files into one single ARB format file, facilitating the management of internationalization resources.

Features:

• YAML, which allows comment and multiple lines string;
• Multiple files merge into one;
• Set prefix on each file;
• Nested structure;
• Map structure on select and plural;
• Placeholders are only needed in the base language.

Installation #

Using pub.flutter-io.cn to manage the package:s

flutter pub add dev:arb_glue

Or add dependencies to pubspec.yaml:

dev_dependencies:
  arb_glue: *

Usage #

Original Structure:

.
└── lib/
    └── l10n/
        ├── en/
        │   ├── global.yaml
        │   └── feature-1.yaml
        └── zh/
            ├── global.yaml
            └── feature-1.yaml

Execution:

dart run arb_glue
# or
flutter pub run arb_glue

Resulting structure:

.
└── lib/
    └── l10n/
        ├── en/
        │   ├── global.yaml
        │   └── feature-1.yaml
        ├── zh/
        │   ├── global.yaml
        │   └── feature-1.yaml
        ├── en.arb
        └── zh.arb

Supported formats #

Currently, ARB Glue supports JSON and YAML encoded files.

In addition to ARB format, it allows writing descriptions directly into one key:

{
  "myButton": "My Button {type}",
  "@myButton": {
    "description": "My custom button label",
    "placeholders": {
      "type": {"type": "String"}
    }
  }
}

This is equivalent to:

myButton: My Button
"@myButton":
  description: My custom button label
  placeholders:
    type: {type: String}

And equal to:

myButton:
- My Button
# description and placeholders can switch position
- My custom button label
- type: {type: String}

Prefix #

Each file can have its own prefix by setting $prefix:

$prefix: myFeature
button: My Feature Button

This will render as:

{
  "myFeatureButton": "My Feature Button"
}

Nested Structure #

arb_glue allow nested structure:

$prefix: myFeature
subModule: # this key is the default prefix value
  $prefix: awesome # it can be customize by `$prefix`
  button: My Awesome Button

This will render as:

{
  "myFeatureAwesomeButton": "My Awesome Button"
}

Select and plural #

arb_glue can let you use map on select or plural text:

title:
- car: Car
  bicycle: Bicycle
  scooter: Scooter
  other: UNKNOWN
- {tool: {type: String, mode: select}} # type and mode is not required, since they are using default values
                                       # strictly equal to: `- {tool: {}}`
counter:
- =0: Empty
  =1: One Item
  other: '{count} Items'
- {count: {type: int, mode: plural}} # type and mode is required in this case

This will render as:

{
  "title": "{tool, select, car{Car} bicycle{Bicycle} scooter{Scooter} other{UNKNOWN}}",
  "@title": {
    "placeholders": {
      "tool": { "type": "String" }
    }
  },
  "counter": "{count, plural, =0{Empty} =1{One Item} other{{count} Item}}",
  "@counter": {
    "placeholders": {
      "count": { "type": "int" }
    }
  }
}

Configuration #

There are two methods to configure the process: via pubspec.yaml or through command-line arguments.

pubspec.yaml:

# pubspec.yaml
name: MyApp
arb_glue:
  source: lib/l10n

Command line:

dart run arb_glue --source lib/l10n

Full configuration options:

arb_glue:
  # The source folder contains the files.
  # Type: String
  source: lib/l10n
  # The destination folder where the files will be generated.
  # Type: String
  destination: lib/l10n
  # Blacklisted folders inside the [source].
  # Type: List<String>
  exclude:
  # The author of the arb file.
  # Type: String
  author:
  # The context of the arb file.
  # Type: String
  context:
  # The base locale of the arb file.
  # If not provided, the base locale will be the first locale found in the
  # source folder.
  # `base` locale can fallback placeholder to other locales.
  # Type: String
  base:
  # The file template for the output arb file.
  fileTemplate: '{lang}.arb'
  # Whether to print verbose output.
  # Type: bool
  verbose: false