evan361425 / flutter-arb-glue

merges multiple files into one single ARB format file

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.

This package operates independently from the project POS System.

Explore that repository to witness firsthand how this package is utilized within the online product.

Table of Contents:

• Installation
• Usage
• Supported formats
  • Schema
  • Prefix
  • Nested Structure
  • Select and plural
• Configuration

Installation

Using pub.dev 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}

Schema

Flutter's localization (l10n) has several custom schemas, which are elaborated upon in arb.schema.json.

If you're utilizing VSCode, streamline the schema setup by incorporating the following configuration:

{
  "yaml.schemas": {
    ".vscode/arb.schema.json": ["/lib/l10n/**/*.yaml"]
  }
}

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 these messages.
  #
  # In the case of localized ARB files it can contain the names/details of the translator.
  # see: https://github.com/google/app-resource-bundle/wiki/ApplicationResourceBundleSpecification#global-attributes
  # Type: String
  author:

  # It describes (in text) the context in which all these resources apply.
  #
  # see: https://github.com/google/app-resource-bundle/wiki/ApplicationResourceBundleSpecification#global-attributes
  # Type: String
  context:

  # Whether to add the last modified time of the file.
  #
  # Type: bool
  lastModified: true

  # The fallback values of the arb file.
  #
  # If not provided, the base locale will be the first locale found in the
  # source folder.
  #
  # Based locale provide fallback placeholders to other locales.
  #
  # Type: String
  base:

  # The default value of other in select/plural mode.
  #
  # See example to get more detailed.
  #
  # Type: String
  defaultOtherValue: UNKNOWN

  # The file template for the output arb file.
  #
  # Type: String
  fileTemplate: '{lang}.arb'

  # Whether to print verbose output.
  #
  # Type: bool
  verbose: false