POEditor Downloader

A CLI tool for downloading and converting translations from POEditor to Flutter ARB (Application Resource Bundle) files for Flutter localization.

Features

📥 Downloads translations from POEditor projects
🔄 Converts POEditor exports to Flutter ARB format
🏷️ Supports filtering by tags and translation status
🔑 Converts translation keys to camelCase automatically
📊 Optional metadata inclusion (locale, language, percentage, last updated)
🎯 Generates separate ARB files per language (e.g., app_en.arb, app_es.arb)

Prerequisites

Dart SDK ^3.4.0 or higher
A POEditor account with an active project
POEditor API token (get it from Account Settings → API Access)

Installation

flutter pub add dev:po_editor_downloader

Configuration

POEditor Downloader supports multiple configuration methods with a clear priority order:

Command-line arguments (highest priority)
Environment variables (for API token)
YAML configuration in pubspec.yaml (for project settings)

YAML Configuration (Recommended)

Add a po_editor section to your pubspec.yaml:

po_editor:
  # IMPORTANT: Do NOT store api_token here for security reasons!
  project_id: "your_project_id"
  tags: "mobile"
  filters: "translated"
  files_path: "lib/l10n/"
  filename_pattern: "app_{locale}.arb"
  add_metadata: true

Security Note: Never commit your API token to version control. Use environment variables or command-line arguments instead.

Environment Variable (Recommended for API Token)

Set your API token as an environment variable:

export PO_EDITOR_API_TOKEN="your_api_token"

Or add it to your shell profile (~/.zshrc, ~/.bashrc, etc.):

echo 'export PO_EDITOR_API_TOKEN="your_api_token"' >> ~/.zshrc

Usage

With YAML + Environment Variable (Recommended)

Configure your pubspec.yaml with project settings (shown above)
Set PO_EDITOR_API_TOKEN environment variable
Run:

dart run po_editor_downloader

Command-Line Only

dart run po_editor_downloader --api_token=your_api_token --project_id=your_project_id

Override YAML Settings

Use command-line arguments to override YAML configuration:

# Override tags for a specific build
dart run po_editor_downloader --tags=web

# Override filters
dart run po_editor_downloader --filters=proofread

# Override multiple settings
dart run po_editor_downloader --tags=mobile,ios --filters=translated --files_path=assets/l10n/

Custom Configuration File

Use a custom YAML configuration file:

dart run po_editor_downloader --config=po_editor_config.yaml

Additional Examples

# Custom file path
dart run po_editor_downloader --files_path=assets/translations/

# Filter by tags (single tag)
dart run po_editor_downloader --tags=mobile

# Filter by multiple tags (comma-separated)
dart run po_editor_downloader --tags=mobile,web

# Filter by status
dart run po_editor_downloader --filters=translated

# Include metadata in ARB files
dart run po_editor_downloader --add_metadata=true

Parameters

Required

Parameter	Source	Description
`api_token`	ENV var or CLI	POEditor API token. Never store in YAML!
`project_id`	YAML or CLI	POEditor project ID

Optional

Parameter	Source	Description	Default
`tags`	YAML or CLI	Filter by tags (single tag or comma-separated list)	-
`filters`	YAML or CLI	Filter by status: `translated`, `untranslated`, `fuzzy`, `not_fuzzy`, `automatic`, `not_automatic`, `proofread`, `not_proofread`	-
`files_path`	YAML or CLI	Output directory path	`lib/l10n/`
`filename_pattern`	YAML or CLI	Filename pattern for ARB files. Use `{locale}` as placeholder (e.g., `{locale}.arb`, `intl_{locale}.arb`)	`app_{locale}.arb`
`add_metadata`	YAML or CLI	Include metadata (locale, language name, percentage, last updated) in ARB files	`false`
`config`	CLI only	Path to custom YAML configuration file	`pubspec.yaml`
`--quiet`, `-q`	CLI only	Quiet mode - show only errors (useful for CI/CD)	-
`--verbose`, `-v`	CLI only	Verbose mode - show debug information (useful for troubleshooting)	-

Configuration Priority

When the same parameter is provided from multiple sources:

For API Token (Security Sensitive):

--api_token CLI argument (highest priority)
PO_EDITOR_API_TOKEN environment variable
❌ Never from YAML (will show warning)

For Other Parameters:

Command-line arguments (highest priority)
Custom config file (if --config specified)
pubspec.yaml po_editor section
Default values (lowest priority)

Getting Started

Get API Token: Go to POEditor Account Settings → API Access
Get Project ID: Found in your POEditor project URL or project settings page
Run the tool with your credentials
Configure Flutter localization in your pubspec.yaml:
```
flutter:
  generate: true
```

Create l10n.yaml in your project root:

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart

Run flutter gen-l10n to generate localization classes

Output Format

The tool generates ARB files for each language in your POEditor project:

lib/l10n/
  ├── app_en.arb
  ├── app_es.arb
  ├── app_fr.arb
  └── ...

Example ARB file (app_en.arb):

{
    "@@locale": "en",
    "@@updated": "2025-11-06 12:30:00",
    "@@language": "English",
    "@@percentage": "95.5",
    "welcomeMessage": "Welcome to our app",
    "loginButton": "Login",
    "errorMessage": "Something went wrong"
}

Note: Translation keys are automatically converted to camelCase for consistency with Dart naming conventions.

Key Features Explained

Tag Filtering

Filter translations by POEditor tags to manage different contexts or platforms:

dart run po_editor_downloader --api_token=token --project_id=id --tags=mobile,ios

Status Filtering

Download only translations with specific statuses:

translated - Only translated terms
untranslated - Only untranslated terms
fuzzy - Terms marked as fuzzy
not_fuzzy - Terms not marked as fuzzy
automatic - Automatically translated terms
proofread - Proofread terms

Metadata

Include additional information in ARB files for tracking and debugging:

dart run po_editor_downloader --api_token=token --project_id=id --add_metadata=true

This adds:

@@locale - Language code
@@language - Language name
@@percentage - Translation completion percentage
@@updated - Last update timestamp

Verbosity Control

Control the amount of output:

# Quiet mode - only show errors (useful for CI/CD)
dart run po_editor_downloader --quiet

# Verbose mode - show debug information (useful for troubleshooting)
dart run po_editor_downloader --verbose

# Normal mode (default) - show progress and success messages
dart run po_editor_downloader

Custom Filename Patterns

Customize how ARB files are named using the filename_pattern option with {locale} as a placeholder:

# Use simple locale names: en.arb, es.arb
dart run po_editor_downloader --filename_pattern="{locale}.arb"

# Use intl prefix: intl_en.arb, intl_es.arb
dart run po_editor_downloader --filename_pattern="intl_{locale}.arb"

# Use translations prefix: translations_en.arb, translations_es.arb
dart run po_editor_downloader --filename_pattern="translations_{locale}.arb"

Or configure in pubspec.yaml:

po_editor:
  project_id: "12345"
  filename_pattern: "{locale}.arb"  # Generates: en.arb, es.arb, etc.

Common patterns:

app_{locale}.arb (default) → app_en.arb, app_es.arb
{locale}.arb → en.arb, es.arb
intl_{locale}.arb → intl_en.arb, intl_es.arb
l10n_{locale}.arb → l10n_en.arb, l10n_es.arb

Troubleshooting

Common Issues

"Failed to load languages"

Verify your API token is correct
Check that the project ID exists and you have access to it
Ensure your POEditor account has API access enabled

"No files generated"

Check that your POEditor project has languages added
Verify the output directory exists or can be created
Ensure there are translations available for the filtered criteria

"Permission denied" when writing files

Verify write permissions for the output directory
Try running with elevated permissions if needed

Empty ARB files

Check if your filters are too restrictive
Verify that translations exist in POEditor for the specified tags/filters