{"_id":"@apappas1129/ngx-fluent-extract","name":"@apappas1129/ngx-fluent-extract","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@apappas1129/ngx-fluent-extract","version":"0.1.0","description":"Extraction report CLI for ngx-fluent: diffs translation keys used in an Angular app's code against each locale's .ftl file.","license":"MIT","type":"module","bin":{"ngx-fluent-extract":"dist/cli.js"},"main":"./dist/index.js","types":"./dist/index.d.ts","publishConfig":{"access":"public"},"engines":{"node":">=20"},"scripts":{"build":"tsc && node -e \"require('node:fs').chmodSync('dist/cli.js', 0o755)\"","test":"vitest run"},"dependencies":{"@fluent/syntax":"^0.19.0"},"peerDependencies":{"typescript":">=5.0.0"},"repository":{"type":"git","url":"git+https://github.com/apappas1129/ngx-fluent.git","directory":"ngx-fluent-extract"},"keywords":["i18n","l10n","localization","ftl","fluent","angular","cli"],"gitHead":"2e57f321df71a424d17f8d8a34f6a7e36869c219","_id":"@apappas1129/ngx-fluent-extract@0.1.0","bugs":{"url":"https://github.com/apappas1129/ngx-fluent/issues"},"homepage":"https://github.com/apappas1129/ngx-fluent#readme","_nodeVersion":"24.16.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-jJaJLTox74KWtXAjpRYtqMAVXS8x3ZzYIa/Ab2dy+HgI6V1fupNXM5+W3ZyySQq2MoxwaOFXGSrV9b1/UQKm6Q==","shasum":"0ae11aa3e78d879fc27a3a81d42522f5414397c6","tarball":"https://registry.npmjs.org/@apappas1129/ngx-fluent-extract/-/ngx-fluent-extract-0.1.0.tgz","fileCount":18,"unpackedSize":24032,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICzJ7ZqvkblL+ulXDLltV1HsfTesQa/DMB6wiVDnNOG5AiBncZcaeu5yQU/n+baB9g8AJI8MzkOmkrVDZx+U3OhK8Q=="}]},"_npmUser":{"name":"apappas1129","email":"apappas1129@gmail.com"},"directories":{},"maintainers":[{"name":"apappas1129","email":"apappas1129@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ngx-fluent-extract_0.1.0_1783405380894_0.4680604367395891"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-07T06:23:00.742Z","0.1.0":"2026-07-07T06:23:01.031Z","modified":"2026-07-07T06:23:01.253Z"},"maintainers":[{"name":"apappas1129","email":"apappas1129@gmail.com"}],"description":"Extraction report CLI for ngx-fluent: diffs translation keys used in an Angular app's code against each locale's .ftl file.","homepage":"https://github.com/apappas1129/ngx-fluent#readme","keywords":["i18n","l10n","localization","ftl","fluent","angular","cli"],"repository":{"type":"git","url":"git+https://github.com/apappas1129/ngx-fluent.git","directory":"ngx-fluent-extract"},"bugs":{"url":"https://github.com/apappas1129/ngx-fluent/issues"},"license":"MIT","readme":"# @apappas1129/ngx-fluent-extract\n\nA report-only extraction CLI for [ngx-fluent](https://github.com/apappas1129/ngx-fluent). It diffs the translation keys used in your Angular app's code against each locale's `.ftl` file, and tells you what's **missing** (used in code, not defined) and **orphaned** (defined, never used).\n\nIt never writes to `.ftl` files. Fluent messages can carry variants, attributes, and term references that a generated stub can't meaningfully guess — so this tool only reports, it doesn't scaffold.\n\n## When you'd need this\n\nNothing in ngx-fluent stops your app from compiling or running if a translation key is missing — the `fluent` pipe just falls back to showing the raw key string (`'welcome-user'` instead of \"Welcome!\"). That's silent in dev and in code review; the first anyone notices is usually a user seeing a raw key in production, or a translator asking why a locale looks half-finished. Reach for this CLI when:\n\n- **You're about to add a new locale.** Point the config at the new `.ftl` file and see exactly which keys it's missing before you ship it, instead of finding out from a user.\n- **You just refactored or deleted a component.** The `.ftl` entries it used don't get cleaned up automatically — `orphaned` tells you what's now dead weight in your translation files.\n- **You want a CI check on PRs that touch templates or translations.** A key typo'd in a template, or added in code but never given a translation, exits non-zero — catch it before merge instead of after a user reports it.\n- **A `.ftl` file came back from a translator or survived a merge conflict.** Malformed Fluent syntax fails silently at runtime (the bundle just drops the broken entry); this CLI's `parseError` surfaces it as a build-breaking problem, not a runtime mystery.\n\nIf none of that applies — small app, one locale, translations always land alongside the code that uses them — you probably don't need this yet.\n\n## Install\n\n```bash\nnpm install --save-dev @apappas1129/ngx-fluent-extract\n```\n\nRequires TypeScript as a peer dependency (already present in any Angular project).\n\n## Usage\n\n```bash\nnpx ngx-fluent-extract [scanRoot] [options]\n```\n\n- `scanRoot` — directory to scan from. Defaults to the current directory (like `code .` / `code <path>`).\n- `--config <path>` — path to the extraction config. Defaults to `<scanRoot>/ngx-fluent-extract.config.json`.\n- `--project <path>` — path to a `tsconfig.json`. Defaults to auto-discovery from `scanRoot` (following `references` one level).\n- `--json` — print the report as JSON instead of human-readable text.\n- `--help` — show usage.\n\nExit code is non-zero only when a locale has **missing** keys or a **parse error**. Orphaned keys alone don't fail the run — they're hygiene, not a defect users will see.\n\n## Config\n\n`ngx-fluent-extract.config.json`, at the scan root:\n\n```json\n{\n  \"locales\": {\n    \"en\": \"public/i18n/en.ftl\",\n    \"sv\": \"public/i18n/sv.ftl\"\n  }\n}\n```\n\nPaths are resolved relative to the config file's own directory. There's no source-glob field — source files are discovered from the resolved `tsconfig.json`'s file list plus each `@Component`'s `templateUrl`/inline `template`, not by pattern matching.\n\n## What it detects\n\n- `'key' | fluent` pipe usage in templates (inline or external, via `templateUrl`)\n- `NgxFluentService.translate('key', ...)` calls in TypeScript, matched type-aware (via the TypeScript Compiler API) rather than by name alone, so an unrelated `.translate()` method on another class isn't mistaken for this library's\n\nA key that isn't a string literal (a variable, a function call) can't be resolved statically. Those surface as **dynamic key warnings** — file and line — rather than being silently dropped, so they don't corrupt the missing/orphaned counts.\n\n## Out of scope for v1\n\n- **Message attributes** (`login-button.title`) — `NgxFluentService.translate()` doesn't expose attribute lookup at all yet, so there's nothing in code for an attribute-aware report to check against.\n- **Fluent terms** (`-brand-name`) — terms are only referenced from within other messages, never from code. Checking whether a term is used anywhere in a `.ftl` file is a different job (dead-code-within-`.ftl`) from this tool's code-vs-translation-file diff.\n\n## Why a standalone CLI, not an `ng` builder\n\nAn Angular builder (`ng run ... :extract-i18n`-style) would need `@angular-devkit/architect` and an `angular.json` target for what's fundamentally a diagnostic side-channel, not a build step. A plain CLI runs anywhere — this repo's own example apps, any CI pipeline — without that coupling. It ships as its own package rather than bundled into `@apappas1129/ngx-fluent` because that library is built with `ng-packagr` for Angular consumption, which can't produce a runnable `bin` script.\n\nA thin Angular builder that wraps this same CLI is a good scope for a community PR if there's demand — issues and PRs welcome.\n","readmeFilename":"README.md","_rev":"1-2d6edd0047442766742336fdf5819a59"}