@better-intl/compiler 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,115 @@
+# @better-intl/compiler
+
+AST extractor and Babel/SWC transform for **better-intl**.
+
+Extracts translatable text from JSX at build time and transforms it into optimized `t()` calls — or inlines translations for zero-runtime cost.
+
+## Install
+
+```bash
+npm install @better-intl/compiler
+```
+
+## Usage
+
+### Extract messages from source
+
+```ts
+import { extract } from "@better-intl/compiler";
+
+const messages = extract(
+  `export function Hero() {
+    return <h1>Hello world</h1>;
+  }`,
+  { filePath: "src/Hero.tsx" }
+);
+
+// [{ id: "0rr2b7c", defaultMessage: "Hello world", filePath: "src/Hero.tsx", ... }]
+```
+
+### Transform JSX
+
+```ts
+import { transform } from "@better-intl/compiler";
+
+// Runtime mode — replaces text with t() calls
+const result = transform(source, {
+  filePath: "src/Hero.tsx",
+  mode: "auto",
+});
+
+// Zero-runtime mode — inlines translated text
+const result = transform(source, {
+  filePath: "src/Hero.tsx",
+  locale: "pt-BR",
+  messages: { "0rr2b7c": "Olá mundo" },
+});
+```
+
+### Catalog utilities
+
+```ts
+import {
+  generateDefaultCatalog,
+  mergeCatalog,
+  findMissingKeys,
+  findDeadKeys,
+} from "@better-intl/compiler";
+
+// Generate default locale catalog from extracted messages
+const catalog = generateDefaultCatalog(messages);
+
+// Merge new messages into existing catalog (preserves translations)
+const { messages, added, removed } = mergeCatalog(existing, extracted);
+
+// Find missing translations
+const missing = findMissingKeys(enCatalog, ptBrCatalog);
+
+// Find unused keys
+const dead = findDeadKeys(catalog, extracted);
+```
+
+### Babel plugin
+
+```js
+// babel.config.js
+module.exports = {
+  plugins: [
+    ["@better-intl/compiler/babel", {
+      locale: "pt-BR",
+      messages: require("./locales/pt-BR.json"),
+    }],
+  ],
+};
+```
+
+### Webpack loader
+
+```js
+// webpack.config.js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.[jt]sx$/,
+        use: ["@better-intl/compiler/webpack-loader"],
+      },
+    ],
+  },
+};
+```
+
+## API
+
+| Export | Description |
+|--------|-------------|
+| `extract(source, options)` | Extract translatable messages from JSX |
+| `transform(source, options)` | Transform JSX text into `t()` calls or inline translations |
+| `generateDefaultCatalog(messages)` | Generate catalog for default locale |
+| `mergeCatalog(existing, extracted)` | Merge new messages preserving existing translations |
+| `findMissingKeys(default, target)` | Find keys missing in target locale |
+| `findDeadKeys(catalog, extracted)` | Find unused keys in catalog |
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-intl/compiler",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "AST extractor and Babel/SWC transform for better-intl",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -24,10 +24,11 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "dependencies": {
-    "@better-intl/core": "0.1.0"
+    "@better-intl/core": "0.1.1"
   },
   "devDependencies": {
     "@babel/core": "^7.26.0",