How cbourgois/simonsays works
Project type and purpose
• This is an open-source CLI utility (an npm package) named “SimonSays.”
• Its purpose is to analyze JavaScript and HTML source code—in particular AngularJS code using angular-translate—to extract translation keys, verify their presence in translation files, search for them across projects, and rewrite translation files.
File structure
Top-level:
• bin/
– simonsays.js → the CLI entry point, runs commands (check, search, rewrite)
• src/
– angularjs/ → embedded AngularJS’s $interpolate and $parse implementations
– compiler/ → modules that generate or rewrite translation resource files
– finder/ → modules that scan ASTs for translation key usages
– parser/ → modules that parse JS (via @babel/parser) and HTML into AST, plus translation file parsers
– simonsays.js → orchestrates the high-level logic; ties CLI flags to core modules
• tests alongside source modules for validation
• configuration files: package.json, ava.config.js, ESLint, GitHub CI templates, etc.
README for additional insights
• The README describes three CLI commands (check, search, rewrite), the supported options (locale, module, output, merge, prefix), and the underlying approach (parsing JS/HTML ASTs, embedded AngularJS parsing code).
a. Main components
• CLI Layer (bin/simonsays.js)
• Core Orchestrator (src/simonsays.js)
• Parser Subsystem (src/parser/*)
• Finder Subsystem (src/finder/*)
• Compiler Subsystem (src/compiler/*)
• AngularJS Runtime Helpers (src/angularjs/*)
• File System (source code files, translation files: JSON/XML)
• External Dependency: @babel/parser
b. Relationships & data flow
1. User invokes CLI → CLI Layer
2. CLI Layer parses command + flags → invokes Core Orchestrator
3. Core reads input file paths from File System
4. Core calls Parser Subsystem → produces ASTs of .js/.html
5. Finder Subsystem scans ASTs → extracts translation key usages
6. Core optionally loads existing translation files from File System
7. Compiler Subsystem merges/checks/re-writes translation files
8. Core emits output (console report or rewritten files)
c. Architectural patterns & design principles
• Modular layering: CLI → orchestrator → pluggable subsystems
• Single Responsibility: parser only builds AST, finder only extracts keys, compiler only writes files
• Dependency injection of AngularJS helpers into parser/finder to handle AngularJS-specific AST constructs
• Extensibility: new parsers/finders could be added for other frameworks
d. Key technologies & libraries
• Node.js CLI (bin/)
• @babel/parser for JavaScript AST
• Custom HTML AST parser (src/parser/html.js)
• Embedded AngularJS code for $interpolate & $parse (src/angularjs)
• JSON/XML reading/writing for translation resources