intl_localizable

A command-line tool for Dart and Flutter that streamlines synchronizing, generating, and distributing localization files from the Localizable platform directly into your codebase.

---

Features

• 🚀 One-Command Sync: Fetch and unpack the latest localization exports with localizable update.
• 🔍 Automatic Project Detection: Automatically detects whether your project is Flutter or Pure Dart and exports the corresponding localization files.
• 📁 Smart Path Resolution: Intelligently places generated files into lib/src/ (if present) or lib/.
• 📦 Automated Dependency Management: Automatically checks your pubspec.yaml and adds or updates the intl dependency if needed.
• ⚡ gRPC-Powered: Fast and secure streaming export delivery via gRPC.

---

Installation

Activate the CLI globally using the Dart SDK:

dart pub global activate intl_localizable

---

Configuration

In the root of your Dart or Flutter project, Download the localizable_project.json configuration file by using the "Download CLI config" in the "Exports" section button of the localization-platform project:

{
  "id": "<YOUR_PROJECT_ID>",
  "jws": "<YOUR_JWS_AUTH_TOKEN>"
}

Field	Description
id	The unique identifier of your project in the Localizable platform.
jws	The JSON Web Signature (JWS) authentication token used to authorize export requests.

---

Usage

Run the tool from the root directory of your project:

localizable update

Commands

Command	Description
update	Request a new localization export from the server and extract it into your project.
init	Installs LOCALIZABLE.md in the project root with complete instructions for LLM agents.
project	Manage projects, configurations, and exports.
translation	Manage translation keys (snake_case).
localization	Manage localized texts for keys.
variable	Manage variables for translations (camelCase, plurals, genders, dates, numbers).
variable-localization	Manage localized values for variables.
tag	Manage tags and tag associations.
translate	Machine-translate text between locales.
issue	Inspect translation validation issues and warnings.
export	Download project export archives.
locale	List supported languages and locale details.
group	Manage workspace groups.
user	Manage current user account.

Global Options

Option	Shorthand	Status	Description	Default
--input-path	-i	Optional	Target project directory containing localizable_project.json and pubspec.yaml.	Current directory (.)
--output-path	-o	Optional	Output directory where extracted localization files will be saved.	Same as --input-path
--user-config	—	Optional	Path to localizable_user.json configuration file.	Auto-detected
--user-key	—	Optional	Direct user account JWS authentication key.	—
--project-config	—	Optional	Path to localizable_project.json configuration file.	Auto-detected
--project-key	—	Optional	Direct project JWS authentication key.	—
--project-id	—	Optional	Target project ID.	Inferred from localizable_project.json
--json	—	Optional	Output command results in structured JSON format (recommended for LLMs and scripts).	—
--debug	-d	Optional	Use localhost backend config for testing.	—
--version	-v	Optional	Display the current CLI tool version.	—
--help	-h	Optional	Display usage instructions and options.	—

---

Examples

Run in current directory

localizable update

Specify custom project directory

localizable update --input-path ~/workspace/my_flutter_app

Specify custom output location

localizable update -i ./ -o ./packages/core_ui

---

How It Works

1. Detects Project Type: Inspects pubspec.yaml to determine whether the target application is a Flutter app or a Pure Dart package.
2. Authenticates & Exports: Reads localizable_project.json and connects via gRPC to request an export archive for the given project ID.
3. Extracts Code: Extracts the relevant Dart/Flutter localization files directly into lib/ or lib/src/.
4. Validates Dependencies: Checks pubspec.yaml and ensures the required intl dependency is present.
5. Cleans Up: Deletes temporary export archives and finishes execution.

---

Troubleshooting

• Could not find pubspec.yaml in this directory: Make sure you run localizable update from your project root or provide --input-path.
• Unable to read/locate localizable_project.json config file: Ensure localizable_project.json is located in your project root or the specified --input-path.
• command not found: localizable: Verify that Dart's global bin path (~/.pub-cache/bin) is added to your environment's PATH.

---

License

This project is licensed under the terms described in the LICENSE file.