ui-strings 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +105 -0
- package/dist/cli.js +1244 -0
- package/package.json +50 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 junseinagao
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
<img src="https://raw.githubusercontent.com/junseinagao/ui-strings-scanner/main/assets/hero.png" width="1200" alt="UI Strings Scanner" />
|
|
3
|
+
</div>
|
|
4
|
+
|
|
5
|
+
<hr />
|
|
6
|
+
|
|
7
|
+
<div align="center">
|
|
8
|
+
|
|
9
|
+
[](https://www.npmjs.com/package/ui-strings)
|
|
10
|
+
[](https://www.npmjs.com/package/ui-strings)
|
|
11
|
+
[](https://www.npmjs.com/package/ui-strings)
|
|
12
|
+
[](LICENSE)
|
|
13
|
+
|
|
14
|
+
</div>
|
|
15
|
+
|
|
16
|
+
# UI Strings Scanner
|
|
17
|
+
|
|
18
|
+
UI Strings Scanner lists every string that could reach the user in a React (JSX/TSX) codebase, without running the code. It parses the AST with [ts-morph](https://ts-morph.com/), so it works on any React project with one command: no build, no mocks, no runtime. Detection is built on JSX semantics, so it is React-only.
|
|
19
|
+
|
|
20
|
+
Use it to audit hardcoded copy, review tone and wording, catch untranslated strings, or take stock before adopting i18n. It inventories strings; translation-key management is out of scope.
|
|
21
|
+
|
|
22
|
+
## Quick Start
|
|
23
|
+
|
|
24
|
+
Run it at the root of your React project:
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
npx ui-strings scan
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
```
|
|
31
|
+
Scanning: /path/to/my-app/src/**/*.{ts,tsx,js,jsx}
|
|
32
|
+
|
|
33
|
+
214 strings (+18 internal) / 52 files scanned
|
|
34
|
+
visible 163
|
|
35
|
+
interactive 31
|
|
36
|
+
internal 18
|
|
37
|
+
a11y 14
|
|
38
|
+
meta 6
|
|
39
|
+
|
|
40
|
+
→ /path/to/my-app/ui-strings-report/ui-strings.json
|
|
41
|
+
→ /path/to/my-app/ui-strings-report/ui-strings.md
|
|
42
|
+
→ /path/to/my-app/ui-strings-report/ui-strings.html
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Features
|
|
46
|
+
|
|
47
|
+
- **Sentence-level extraction** - `<p>Hello <b>world</b>,<br />welcome</p>` comes out as one string. Embedded expressions become `{count}` placeholders.
|
|
48
|
+
- **Condition tracking** - Strings inside `cond ? A : B` or `cond && X` carry their condition, so you know when they show.
|
|
49
|
+
- **Symbol resolution** - An option array rendered with `.map()` links back to its declaration, across import chains and `@/` aliases.
|
|
50
|
+
- **Surface classification** - Every string is tagged by how it reaches the user: `visible`, `interactive`, `a11y`, `meta`, or `internal`.
|
|
51
|
+
- **Noise filtering** - Class names, import paths, and directives never make the list. Structural rules combine with lexical shape, and non-Latin text always counts as copy, so mixed-language projects work.
|
|
52
|
+
- **Next.js aware** - Entries group by App Router route, and `metadata` is classified as `meta`.
|
|
53
|
+
- **Fix prompts** - Edit strings in the HTML viewer, then copy all edits as a ready-to-run prompt for an AI coding agent.
|
|
54
|
+
|
|
55
|
+
## Usage
|
|
56
|
+
|
|
57
|
+
```sh
|
|
58
|
+
npx ui-strings scan [projectDir] [options]
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`projectDir` defaults to the current directory.
|
|
62
|
+
|
|
63
|
+
| Option | Default | Description |
|
|
64
|
+
| -------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------- |
|
|
65
|
+
| `--src <glob>` | `src/**/*.{ts,tsx,js,jsx}` | files to scan (relative to projectDir) |
|
|
66
|
+
| `--exclude <globs>` | none | extra exclude globs, comma-separated (`*.test.*` / `*.spec.*` / `__tests__` / `__mocks__` are always excluded) |
|
|
67
|
+
| `--out <dir>` | `./ui-strings-report` | output directory |
|
|
68
|
+
| `--format <list>` | `json,md,html` | output formats |
|
|
69
|
+
| `--include-internal` | off | include console/throw strings in the Markdown listing |
|
|
70
|
+
| `--open` | off | open the HTML report in a browser |
|
|
71
|
+
|
|
72
|
+
The scanner reads the target project's `tsconfig.json` when present and resolves path aliases such as `@/*` through it.
|
|
73
|
+
|
|
74
|
+
## Output
|
|
75
|
+
|
|
76
|
+
- `ui-strings.json` - every entry with `text`, `file`, `line`, `kind`, `surface`, and `condition`
|
|
77
|
+
- `ui-strings.md` - counts by surface, kind, and group, plus the full listing
|
|
78
|
+
- `ui-strings.html` - single-file viewer with search, filters, TSV row copy, and inline editing
|
|
79
|
+
|
|
80
|
+
## Limitations
|
|
81
|
+
|
|
82
|
+
Static analysis has limits. Strings built at runtime, such as API responses and computed values, stay invisible. Copy passed across components is captured at its declaration, and only the array `.map()` pattern resolves to a render site. Unknown copy attributes fall back to lexical detection.
|
|
83
|
+
|
|
84
|
+
## Development
|
|
85
|
+
|
|
86
|
+
The published CLI runs on Node. Development uses [Bun](https://bun.sh).
|
|
87
|
+
|
|
88
|
+
```sh
|
|
89
|
+
bun install
|
|
90
|
+
bun test
|
|
91
|
+
bun run typecheck
|
|
92
|
+
bun run build # bundle dist/cli.js
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Contributing
|
|
96
|
+
|
|
97
|
+
Issues and pull requests are welcome.
|
|
98
|
+
|
|
99
|
+
## License
|
|
100
|
+
|
|
101
|
+
[MIT](LICENSE)
|
|
102
|
+
|
|
103
|
+
## Author
|
|
104
|
+
|
|
105
|
+
Junsei Nagao <https://github.com/junseinagao>
|