auto_localize_cli 1.0.6
auto_localize_cli: ^1.0.6 copied to clipboard
AST-powered Flutter CLI that extracts hardcoded strings into .arb files, removes ancestor consts, and rewrites code to use context-less l10n getters.
Changelog #
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
1.0.6 #
Architecture & Scaffolding Isolation #
- Dedicated Subfolder Isolation (
lib/core/localization/):- Scaffolds
localization_helper.dartandapp_strings.dartinside a dedicated subfolder:lib/core/localization/instead of directly at the root oflib/core/. - Ensures clean separation and zero directory pollution for enterprise apps with existing
lib/core/architectures (e.g.core/network/,core/constants/,core/theme/). - Updated AST code rewriter, directory crawler, and test suites to automatically inject and respect
lib/core/localization/localization_helper.dart.
- Scaffolds
- Comprehensive
init&extractEngine Logic Documentation:- Added detailed under-the-hood engine breakdowns for both
dart run auto_localize_cli:initanddart run auto_localize_cli:extractdirectly into the Quick Start and Installation guides inREADME.mdandlib/auto_localize_cli.dart. - Documented AST parsing stages, dual-mode whitelisting, ancestor
conststripping, and 0 KB release bundle footprint.
- Added detailed under-the-hood engine breakdowns for both
- Example App Updates:
- Updated
example/structure and imports tolib/core/localization/.
- Updated
1.0.5 #
Example & Documentation Overhaul #
- Production-Grade Flutter Example Application:
- Overhauled
example/into a complete, standalone, runnable Flutter UI application. - Implemented real-world demonstrations of context-less
l10n.<key>, dynamic runtime language switching (changeAppLocale), parameterized translations (welcomeBackUser), and non-UI usage in repositories (AuthRepository). - Added standalone
example/pubspec.yaml,example/l10n.yaml, and generated localization delegates achieving 0 issues onflutter analyze.
- Overhauled
- Top-of-README Quick Start Guide:
- Moved the streamlined "⚡ Quick Start: From Zero to Multilingual in 4 Steps" directly to the top of
README.md, clarifying installation, one-timeMaterialAppconnection, AST extraction, and AI-assisted multilingual translation.
- Moved the streamlined "⚡ Quick Start: From Zero to Multilingual in 4 Steps" directly to the top of
- Version Updates:
- Bumped package dependency examples and documentation to
^1.0.5.
- Bumped package dependency examples and documentation to
1.0.4 #
Documentation #
- Added high-priority "Why auto_localize_cli? (The Core Problem & Solution)" architectural overview to the very top of
README.md. - Documented the complete 2-step AST extraction and AI-assisted multilingual translation workflow.
- Updated installation instructions across documentation to
^1.0.4.
1.0.3 #
Documentation & Polishing #
- Updated installation instructions across
README.mdandexample/README.mdwith modern CLI commands (flutter pub add dev:auto_localize_cli). - Polished dependency constraints and release packaging.
1.0.2 #
Fixed #
- Analyzer 14.x Compatibility for 160/160 pub points:
- Expanded
analyzerdependency constraint to'>=6.4.0 <15.0.0', supporting the newest stableanalyzer 14.xreleases while maintaining 100% backward compatibility down to6.4.0. - Adapted AST visitor for Dart 3.13 /
analyzer 14.xAST changes:- Handled
NamedArgumentin addition to legacyNamedExpression. - Handled
BlockClassBodyhierarchy andClassNameParttype name extraction. - Handled
NamedType.namealongsideNamedType.name2. - Handled
FormalParameterandFormalParameterDefaultClauseparameter validation. - Simplified
PartOfDirective.libraryNameresolution with.toSource().
- Handled
- Expanded
1.0.1 #
Fixed #
- Expanded
analyzerdependency constraint to support both6.xand7.x(>=6.4.0 <8.0.0) for maximumpub.devscore. - Escaped angle brackets in documentation comments to comply with
dartdocHTML lint rules.
1.0.0 #
Added #
-
Phase 1 Scaffolding (
auto_localize_cli:init):- Automatically configures
flutter_localizationsandintlinpubspec.yamlwithgenerate: true. - Creates
l10n.yamlwith standard Flutter localization configuration. - Generates template ARB catalog (
lib/l10n/app_en.arbor custom base locale via--locale/-l). - Scaffolds context-less global getter
l10n(lib/core/localization_helper.dart) with pre-mount safe fallback (lookupAppLocalizations) and seamless existingrootNavigatorKeyintegration viasetGlobalNavigatorKey. - Provides reactive runtime language switching through
localeNotifierandchangeAppLocale(...). - Creates core error and string catalog (
lib/core/app_strings.dart).
- Automatically configures
-
Hyper-Scale Architecture for Enterprise Monorepos (100K to 50M+ Files):
- Zero-List Streaming Directory Traversal ($O(1)$ RAM): Lazily streams Dart files with directory-level early pruning of hidden (
.git,.dart_tool) and build/platform folders (build,android,ios,web,macos,linux,windows), preventing OutOfMemoryError. - Bounded Backpressure Chunking: Restricts concurrent open files to batches of 64, completely eliminating OS file descriptor limits (
EMFILE). - Pre-AST Lexical Fast-Reject Filter: Fast $<0.01\text{ms}$ check bypasses 90%+ of non-UI files (models, DTOs, services, repositories) before invoking the Dart analyzer AST parser.
- Sharded Incremental File-Stat Cache: Partitions file modification timestamps across 256 lightweight JSON shards in
.dart_tool/auto_localize_cli/cache/. Second runs on 1,000 files complete in $<150\text{ms}$ with 0 files parsed. - Multi-Core Isolate Worker Pool: Parallelizes AST parsing across CPU cores (
--workers) with deterministic sequential main-thread ARB key resolution. - $O(k)$ Git-Diff Mode (
--git-diff/-g): Extracts only from uncommitted and untracked Git files, achieving sub-second extraction in multi-million-file repositories.
- Zero-List Streaming Directory Traversal ($O(1)$ RAM): Lazily streams Dart files with directory-level early pruning of hidden (
-
Phase 2 Extraction (
auto_localize_cli:extract):- Compiler-grade AST parsing using
package:analyzer. - Automatically locates hardcoded UI strings in widgets (
Text,SelectableText,Tooltip,InputDecoration,Semantics, etc.) and core string classes. - Automatically walks up the AST hierarchy to remove ancestor
constkeywords on widgets and literal lists/maps, preventing compile-time errors. - Bottom-to-top source code rewriting preserving exact source code formatting and indentation.
- Idempotent extraction (running multiple times results in 0 modifications).
- Automatically triggers
flutter gen-l10nafter extraction.
- Compiler-grade AST parsing using
-
String Interpolation & Parameterization:
- Extracts interpolated strings (
"Hello $userName","Total: ₹${order.totalAmount}"). - Generates parameterized ARB entries with
@keyand{placeholder}ICU metadata. - Replaces string interpolations with parameterized method calls (
l10n.helloUserName(userName)). - Automatically deduplicates repeated expressions in the same string (
"Hi $name, welcome back $name!"passesnameonly once).
- Extracts interpolated strings (
-
7-Step Smart
camelCaseKey Generation Algorithm:- Step 1: Validation and filtering (ignores paths, URLs, emails, dates, pure numbers).
- Step 2: CamelCase splitting and tokenization with contraction normalization (
It's->Its). - Step 3: Leading numbers repositioning (
"24 7 Customer Support Available"->customer247Available). - Step 4: Stopword and noise word pruning.
- Step 5: Candidate key building (first 3 words + meaningful tail word) with 2nd/3rd-last word fallback for collisions.
- Step 6: Reserved Dart keyword disambiguation (
"Continue"->continueText,"Return"->returnText). - Step 7: Deterministic collision fallback with numeric suffixes if required.
- Multilingual & Cyrillic transliteration support (Russian, Ukrainian, Belarusian, Bulgarian $\rightarrow$ Latin
camelCase).
-
Compiler-Grade Architectural Safety:
part/part ofsupport: Never injects imports intopart offiles; safely resolves and injects imports into the parent library file.AdjacentStringsmerging: Automatically merges multi-line concatenated string literals into a single localization key.AppStringsfield conversion: Automatically convertsstatic const Stringfields intostatic String getgetters to allow dynamic localization lookup.- Smart Ignore: Preserves compile-time constants like numbers (
"2026"), symbols ("100%","+91-9876543210"), default parameter values (this.title = "Default"), andassertstatements.