poe2arb

README

poe2arb

poe2arb is a CLI tool that lets the POEditor work with Flutter's native localization solution (flutter gen-l10n).

Installation

You can download latest or historical binary straight from the GitHub releases artifacts or using Homebrew:

brew tap leancodepl/poe2arb
brew install poe2arb

Usage

poe2arb operates on POEditor's JSON (not JSON key-value) export file format.

Full POEditor integration

poe2arb poe command is your Swiss Army Knife enabling integrating POEditor into your Flutter workspace in one command:

1. Fetches all project languages from API.
2. Downloads JSON exports for all languages from API.
3. Converts JSON exports to ARB format.
4. Saves converted ARB files to the output directory.

Options

Flag	Description	Default
-p, --project-id	Required. POEditor project ID. It is visible in the URL of the project on POEditor website.	Defaults to poeditor-project-id from l10n.yaml file. If it's empty, then defaults to POEDITOR_PROJECT_ID env.
-t, --token	Required. POEditor API read-only access token. Available in Account settings > API access.	Defaults to POEDITOR_TOKEN env.
-o, --output-dir	ARB files output directory.	Defaults to arb-dir from l10n.yaml. If it's empty, then defaults to ..
--langs	Exported languages override.	Defaults to empty, no override.

Conversion

poe2arb convert command only converts the POE export to ARB format. Refer to Supported features section.

For conversion, you need to pass the translation file language in the --lang/-l flag.

By default, a template ARB file is generated. So no empty message is skipped and attributes are generated. If you want to skip that, pass --no-template flag.

Currently, only an stdin/stdout is supported for the poe2arb convert command.

poe2arb convert io --lang en < Hello_World_English.json > lib/l10n/app_en.arb

Syntax & supported features

Term name must be a valid Dart field name, additionaly, it must start with a lowercase letter (Flutter's constraint).

Placeholders

Placeholders can be as simple as a text between brackets, but they can also be well-defined with a type and format, to make use of date and number formatting.

By default, simple {placeholder} will have an Object type and will be toString()ed.

Each unique placeholder must be defined only once. I.e. for one {placeholder,String} you may have many {placeholder} (that use the same definition), but no other {placeholder,String} must be found in the term.

Placeholders with type DateTime must have a format specified. The valid values are the names of the DateFormat constructors, e.g. yMd, jms, or EEEEE.

Placeholders with type num, int, or double must also have a format specified. The valid values are the names of the NumberFormat constructors, e.g. decimalPattern, or percentPattern. In plurals, the count placeholder must be of int or num type. It can be left with no definition, or with just a num type, without the format, the number won't be formatted but simply to-stringed then. This is Flutter's behavior.

Only template files can define placeholders with their type and format. In non-template languages, placeholders' types and formats are ignored and no logical errors are reported.

Examples

Below are some examples of strings that make use of placeholders. Simple and well-defined.

Hello, {name}!

Hello, {name,String}!

You have {coins,int,decimalPattern} coins left in your {wallet,String} wallet.

last modified on {date,DateTime,yMMMEEEEd}

Placeholder syntax diagram

count placeholder syntax diagram

Plurals

POEditor plurals are also supported. Simply mark the the term as plural and give it any name (it's never used, but required by POEditor to enable plurals for the term).

In translations, a {count} placeholder can be used. You can use other placeholders too. Example:

one:    Andy has 1 kilogram of {fruit}.
other:  Andy has {count} kilograms of {fruit}.

You must provide at least other plural category for your translations, otherwise it won't be converted.

Contributing

Formatting

We use gofumpt, which is a superset of gofmt.

To make gopls in VS Code use gofumpt, add this to your settings:

"gopls": {
    "formatting.gofumpt": true
},

Linting

We use staticcheck with all checks enabled.

To make VS Code use staticcheck, add this to your settings:

"go.lintTool": "staticcheck",
"go.lintFlags": ["-checks=all"],

Building

All you need is Go 1.19.

go build .

Releasing

Create a lightweight git tag and push it. GitHub Actions with a GoReleaser workflow will take care of the rest.

git tag v0.1.1
git push origin v0.1.1