next-intl-codemod 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 seob717
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# next-intl-codemod
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Migrates a Next.js app from `useTranslations` / `getTranslations` with hand-written keys to
+[`useExtracted` / `getExtracted`](https://next-intl.dev/docs/usage/extraction) with inline messages,
+and carries the existing translations over so nothing has to be translated again.
+
+```sh
+npx next-intl-codemod --messages 'messages/{locale}.json' --source-locale en
+```
+
+## What it does
+
+For every `t` that is bound to one of the old hooks and only ever called with static keys:
+
+```tsx
+// before
+import {useTranslations} from 'next-intl';
+const t = useTranslations('Checkout');
+t('title');
+t.rich('terms', {link: (chunks) => <a>{chunks}</a>});
+
+// after
+import {useExtracted} from 'next-intl';
+const t = useExtracted();
+t('Checkout');
+t.rich('Please accept the <link>terms</link>.', {link: (chunks) => <a>{chunks}</a>});
+```
+
+1. The key is replaced by the source-locale text from your catalogs. Ids are generated exactly like
+   the extractor does (SHA-512, base64url, 6 chars), so a later `next dev` / `next build` leaves the
+   catalogs untouched.
+2. Catalogs for all locales are written in the extraction format (`po` or `json`) with the old
+   translations filled in. An existing extraction catalog is merged, never overwritten. A `.po`
+   catalog in the previous next-intl layout (keys in `msgid`) stops the run before anything changes.
+3. If one source text was translated differently under different keys, each distinct translation set
+   keeps its own message with an explicit id (the old key), so no translation is lost:
+   ```tsx
+   t({id: 'pricing.enterprise.seats', message: 'Unlimited'});
+   ```
+4. Everything the extractor cannot handle is left untouched and listed in the report: dynamic keys
+   (`t(key)`, `t(\`a.${b}\`)`), dynamic namespaces, `t.raw`, `t.has`, `t` passed to another function
+   or returned, keys missing from the catalogs. The old hook import stays as long as one binding in the
+   file still needs it.
+
+## Options
+
+| Option | Default | |
+| --- | --- | --- |
+| `--messages <pattern>` | required | Old catalogs. `{locale}` is required, `*` matches several files per locale that are merged: `messages/{locale}.json`, `locales/{locale}/*.json` |
+| `--source-locale <locale>` | required | Locale whose texts become the inline messages |
+| `--src <dir>` | `src` | Source directory, repeatable |
+| `--out <dir>` | `messages` | Where the extraction catalogs are written (`<locale>.po` / `.json`) |
+| `--format po\|json` | `po` | |
+| `--namespace none\|first-segment\|keep` | `none` | `first-segment` uses the first segment of the old key (`Checkout.title` → `useExtracted('Checkout')`), `keep` the namespace the old hook was called with |
+| `--project-root <dir>` | cwd | Base for the `#:` references |
+| `--dry-run` | | Report only |
+| `--report <file>` | | JSON report: skipped bindings with reasons, conflicts, old keys never referenced, and `keyMap` (old key → new id) |
+
+## Choosing the source locale
+
+Inline messages are written in one locale and that locale must be the `messages.sourceLocale` of
+your next-intl config. Pick the language your developers write copy in; it does not have to be
+English. Texts are normalized to NFC before they are written, because ids hash the bytes as written
+and editors save NFC: a decomposed catalog text would otherwise get a new id on its first save.
+Keys whose text was normalized are listed under `normalizedKeys` in the report.
+
+Run the codemod against the most complete catalog you have: keys missing from the source-locale
+catalog cannot be inlined and are reported as `missing-key`.
+
+## After running
+
+- Review the report. Dynamic keys usually become a `switch` or an object literal of `t('…')` calls
+  inside the component, as described in [static analysis](https://next-intl.dev/docs/usage/extraction#static-analysis).
+- Old catalogs are not modified. Delete the migrated keys (or the files) once no binding reads them;
+  `unreferencedKeys` in the report lists keys that no static call references.
+- Run `tsc`. `useExtracted` types `values` from the inline message, which is stricter than
+  catalog-based types, so two kinds of pre-existing looseness surface as errors:
+  - Values or tag handlers the source text does not declare but a translation uses (e.g. a `<br>`
+    only the English text has), and tag handlers passed to a plain `t()` call. These calls are
+    listed under `valuesNotInMessage` in the report. Add the tag or argument to the source text, or
+    switch to `t.rich`; removing the value would break the translation.
+  - Numbers passed to a plain `{arg}`, which is typed as `string`. Use `{arg, number}` in the
+    message (which also formats the number) or pass a string.
+- Run the app once: the extractor rewrites nothing if the migration is consistent.
+
+## Verification
+
+The codemod was validated on a production app:
+
+- running next-intl's extractor over the converted sources reproduces the written catalogs byte for byte;
+- every migrated key resolves to a catalog entry whose translations equal the old ones, in every locale;
+- fixtures in `test/` cover the rewrite rules, conflicts, skipping and import handling.

package/dist/apply.js

@@ -0,0 +1,93 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import createJsonCodec from '@eloqnt/format-json';
+import createPoCodec from '@eloqnt/format-po';
+/**
+ * `textByFile` holds the text the offsets were computed on (TypeScript strips a BOM when reading),
+ * so edits never land one character off; a BOM on disk is put back.
+ */
+export function applyEdits(edits, textByFile) {
+    const byFile = new Map();
+    for (const edit of edits) {
+        const list = byFile.get(edit.file) ?? [];
+        list.push(edit);
+        byFile.set(edit.file, list);
+    }
+    for (const [file, list] of byFile) {
+        const onDisk = fs.readFileSync(file, 'utf8');
+        let text = textByFile.get(file) ?? onDisk;
+        // Apply from the end so earlier offsets stay valid.
+        for (const edit of list.sort((a, b) => b.start - a.start || b.end - a.end)) {
+            text = text.slice(0, edit.start) + edit.text + text.slice(edit.end);
+        }
+        const bom = onDisk.startsWith('') && !text.startsWith('') ? '' : '';
+        fs.writeFileSync(file, bom + text);
+    }
+}
+/** Merging into the previous layout would write a catalog next-intl refuses to read. */
+export function assertCatalogsSupported(options) {
+    if (options.format !== 'po')
+        return;
+    for (const locale of options.locales) {
+        const file = path.join(options.outDir, `${locale}.po`);
+        if (fs.existsSync(file) && fs.readFileSync(file, 'utf8').includes('X-Crowdin-SourceKey: msgstr')) {
+            throw new Error(`${file} uses the previous PO layout of next-intl, which current versions refuse to read. ` +
+                'Migrate it (https://github.com/amannn/next-intl/pull/2393), or delete it if it has no entries, ' +
+                'then run the codemod again. Nothing was changed.');
+        }
+    }
+}
+export function writeCatalogs(messages, options) {
+    if (messages.length === 0)
+        return;
+    const codec = options.format === 'po' ? createPoCodec() : createJsonCodec();
+    const extension = `.${options.format}`;
+    fs.mkdirSync(options.outDir, { recursive: true });
+    // Like the extractor, every locale is encoded against the source catalog: it provides the
+    // source text (`msgid`) and decides which entries exist. Target entries without a source are orphans.
+    const sourceMessagesById = new Map();
+    const localeList = [options.sourceLocale, ...options.locales.filter((locale) => locale !== options.sourceLocale)];
+    for (const locale of localeList) {
+        const file = path.join(options.outDir, `${locale}${extension}`);
+        const isSource = locale === options.sourceLocale;
+        const existing = new Map();
+        if (fs.existsSync(file)) {
+            for (const message of codec.decode(fs.readFileSync(file, 'utf8'), { locale, sourceLocale: options.sourceLocale })) {
+                existing.set(message.id, message);
+            }
+        }
+        const merged = new Map();
+        if (isSource) {
+            for (const [id, message] of existing)
+                merged.set(id, message);
+        }
+        else {
+            for (const [id, message] of existing)
+                if (sourceMessagesById.has(id))
+                    merged.set(id, message);
+        }
+        for (const message of messages) {
+            const text = isSource ? message.message : (message.translations[locale] ?? '');
+            const previous = merged.get(message.id);
+            if (!previous) {
+                merged.set(message.id, { id: message.id, message: text, description: [], references: message.references });
+                continue;
+            }
+            // A translation already on disk wins over the carried-over one; references are unioned.
+            const seen = new Set(previous.references.map((ref) => `${ref.path}:${ref.line ?? ''}`));
+            merged.set(message.id, {
+                ...previous,
+                message: isSource ? text : previous.message || text,
+                references: [
+                    ...previous.references,
+                    ...message.references.filter((ref) => !seen.has(`${ref.path}:${ref.line}`))
+                ]
+            });
+        }
+        if (isSource) {
+            for (const [id, message] of merged)
+                sourceMessagesById.set(id, message);
+        }
+        fs.writeFileSync(file, codec.encode([...merged.values()], { locale, sourceMessagesById }));
+    }
+}

package/dist/catalog.js

@@ -0,0 +1,107 @@
+import fs from 'node:fs';
+import path from 'node:path';
+function segmentToRegExp(segment) {
+    const source = segment
+        .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+        .replace(/\\\{locale\\\}/g, '(?<locale>[A-Za-z0-9_-]+)')
+        .replace(/\*/g, '[^/]*');
+    return new RegExp(`^${source}$`);
+}
+/**
+ * Expands a catalog path pattern such as `messages/{locale}.json` or
+ * `locales/{locale}/*.json` into the files that exist on disk, grouped by locale.
+ */
+export function resolveCatalogFiles(pattern, projectRoot) {
+    const segments = pattern.split('/').filter(Boolean);
+    const result = new Map();
+    function walk(dir, index, locale) {
+        const segment = segments[index];
+        const isLast = index === segments.length - 1;
+        const isStatic = !/[{*]/.test(segment);
+        if (isStatic) {
+            const next = path.join(dir, segment);
+            if (!fs.existsSync(next))
+                return;
+            if (isLast)
+                addFile(next, locale);
+            else
+                walk(next, index + 1, locale);
+            return;
+        }
+        const regExp = segmentToRegExp(segment);
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const match = regExp.exec(entry.name);
+            if (!match)
+                continue;
+            const nextLocale = match.groups?.locale ?? locale;
+            const next = path.join(dir, entry.name);
+            if (isLast) {
+                if (entry.isFile())
+                    addFile(next, nextLocale);
+            }
+            else if (entry.isDirectory()) {
+                walk(next, index + 1, nextLocale);
+            }
+        }
+    }
+    function addFile(file, locale) {
+        if (!locale)
+            throw new Error(`Pattern "${pattern}" must contain {locale}.`);
+        const list = result.get(locale) ?? [];
+        list.push(file);
+        result.set(locale, list);
+    }
+    walk(projectRoot, 0, undefined);
+    for (const list of result.values())
+        list.sort();
+    return result;
+}
+function flatten(value, prefix, strings, others) {
+    if (typeof value === 'string') {
+        strings.set(prefix, value);
+    }
+    else if (value && typeof value === 'object' && !Array.isArray(value)) {
+        for (const [key, child] of Object.entries(value)) {
+            flatten(child, prefix ? `${prefix}.${key}` : key, strings, others);
+        }
+    }
+    else {
+        others.set(prefix, value);
+    }
+}
+export function loadCatalogs(pattern, projectRoot, sourceLocale) {
+    const filesByLocale = resolveCatalogFiles(pattern, projectRoot);
+    if (!filesByLocale.has(sourceLocale)) {
+        throw new Error(`No catalog found for source locale "${sourceLocale}" with pattern "${pattern}".`);
+    }
+    const byLocale = new Map();
+    const nonString = new Map();
+    const collisions = [];
+    for (const [locale, files] of filesByLocale) {
+        const merged = new Map();
+        const fileByKey = new Map();
+        for (const file of files) {
+            const strings = new Map();
+            const others = new Map();
+            flatten(JSON.parse(fs.readFileSync(file, 'utf8')), '', strings, others);
+            for (const [key, value] of strings) {
+                const previous = merged.get(key);
+                if (previous !== undefined && previous !== value) {
+                    collisions.push({ locale, key, files: [fileByKey.get(key), file] });
+                }
+                merged.set(key, value);
+                fileByKey.set(key, file);
+            }
+            if (locale === sourceLocale) {
+                for (const [key, value] of others)
+                    nonString.set(key, value);
+            }
+        }
+        byLocale.set(locale, merged);
+    }
+    const locales = [
+        sourceLocale,
+        ...[...filesByLocale.keys()].filter((locale) => locale !== sourceLocale).sort()
+    ];
+    return { locales, byLocale, nonString, collisions, filesByLocale };
+}

package/dist/cli.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { applyEdits, assertCatalogsSupported, writeCatalogs } from './apply.js';
+import { loadCatalogs } from './catalog.js';
+import { collectSourceFiles } from './files.js';
+import { buildPlan } from './plan.js';
+import { scanFiles } from './scan.js';
+const { values } = parseArgs({
+    options: {
+        src: { type: 'string', multiple: true, default: ['src'] },
+        messages: { type: 'string' },
+        'source-locale': { type: 'string' },
+        out: { type: 'string', default: 'messages' },
+        format: { type: 'string', default: 'po' },
+        namespace: { type: 'string', default: 'none' },
+        'project-root': { type: 'string', default: process.cwd() },
+        'dry-run': { type: 'boolean', default: false },
+        report: { type: 'string' },
+        help: { type: 'boolean', default: false }
+    }
+});
+if (values.help || !values.messages || !values['source-locale']) {
+    console.log(`Usage: next-intl-codemod --messages <pattern> --source-locale <locale> [options]
+
+Rewrites useTranslations/getTranslations calls with static keys to useExtracted/getExtracted
+inline messages and carries the existing translations over to extraction catalogs.
+
+  --messages <pattern>     Old catalogs, e.g. "messages/{locale}.json" or "locales/{locale}/*.json"
+  --source-locale <locale> Locale whose texts become the inline messages
+  --src <dir>              Source directory (repeatable, default: src)
+  --out <dir>              Where to write the extraction catalogs (default: messages)
+  --format po|json         Catalog format (default: po)
+  --namespace none|first-segment|keep
+                           none: useExtracted(); first-segment: first key segment;
+                           keep: the namespace the old hook used (default: none)
+  --project-root <dir>     Base for file references (default: cwd)
+  --dry-run                Plan and report only
+  --report <file>          Write the JSON report here`);
+    process.exit(values.help ? 0 : 1);
+}
+const projectRoot = path.resolve(values['project-root']);
+const format = values.format;
+const namespace = values.namespace;
+if (!['po', 'json'].includes(format))
+    throw new Error(`Unknown format: ${format}`);
+if (!['none', 'first-segment', 'keep'].includes(namespace))
+    throw new Error(`Unknown namespace strategy: ${namespace}`);
+const catalogs = loadCatalogs(values.messages, projectRoot, values['source-locale']);
+assertCatalogsSupported({ outDir: path.resolve(projectRoot, values.out), format, locales: catalogs.locales });
+const files = [];
+for (const dir of values.src)
+    collectSourceFiles(path.resolve(projectRoot, dir), files);
+const scanned = scanFiles(files);
+const plan = buildPlan(scanned, catalogs, { projectRoot, sourceLocale: values['source-locale'], namespace });
+const { report } = plan;
+console.log([
+    `files: ${report.files.changed}/${report.files.scanned} changed`,
+    `bindings: ${report.bindings.converted} converted, ${report.bindings.skipped} skipped`,
+    `calls: ${report.calls.converted} converted`,
+    `messages: ${report.messages.total} (${report.messages.explicitIds} with explicit ids from ${report.conflicts.length} conflicting texts)`,
+    `old keys never referenced statically: ${report.unreferencedKeys.length}`
+].join('\n'));
+const reasons = new Map();
+for (const binding of report.skipped) {
+    for (const problem of binding.problems) {
+        const reason = problem.reason.split(':')[0];
+        reasons.set(reason, (reasons.get(reason) ?? 0) + 1);
+    }
+}
+if (reasons.size > 0) {
+    console.log('skipped because:');
+    for (const [reason, count] of [...reasons].sort((a, b) => b[1] - a[1]))
+        console.log(`  ${count}× ${reason}`);
+}
+if (values.report) {
+    fs.writeFileSync(values.report, JSON.stringify(report, null, 2));
+    console.log(`report: ${values.report}`);
+}
+if (report.valuesNotInMessage.length > 0) {
+    console.log(`calls passing values the source text does not declare (expect tsc errors, see report): ${report.valuesNotInMessage.length}`);
+}
+if (report.files.withoutNextIntlImport.length > 0) {
+    console.log(`files mentioning the hooks without a next-intl import (left untouched): ${report.files.withoutNextIntlImport.length}`);
+}
+if (!values['dry-run']) {
+    applyEdits(plan.edits, new Map(scanned.map((scannedFile) => [scannedFile.file, scannedFile.text])));
+    writeCatalogs(plan.messages, {
+        outDir: path.resolve(projectRoot, values.out),
+        format,
+        sourceLocale: values['source-locale'],
+        locales: catalogs.locales
+    });
+    console.log(`wrote ${catalogs.locales.length} catalogs to ${values.out}`);
+}

package/dist/files.js

@@ -0,0 +1,20 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mts', '.mjs']);
+const IGNORED_DIRS = new Set(['node_modules', '.next', '.git', 'dist', 'build', 'out']);
+/** Source files that mention one of the old hooks; everything else cannot change. */
+export function collectSourceFiles(dir, out = []) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+            if (!IGNORED_DIRS.has(entry.name))
+                collectSourceFiles(path.join(dir, entry.name), out);
+        }
+        else if (SOURCE_EXTENSIONS.has(path.extname(entry.name)) && !entry.name.endsWith('.d.ts')) {
+            const file = path.join(dir, entry.name);
+            const text = fs.readFileSync(file, 'utf8');
+            if (text.includes('useTranslations') || text.includes('getTranslations'))
+                out.push(file);
+        }
+    }
+    return out;
+}

package/dist/id.js

@@ -0,0 +1,5 @@
+import { createHash } from 'node:crypto';
+/** Mirrors `packages/swc-plugin-extractor/src/key_generator.rs`. */
+export function generateId(message) {
+    return createHash('sha512').update(message, 'utf8').digest('base64url').slice(0, 6);
+}

package/dist/plan.js

@@ -0,0 +1,272 @@
+import path from 'node:path';
+import { generateId } from './id.js';
+import { EXTRACTED_BY_HOOK, MODULE_BY_HOOK } from './scan.js';
+export function toStringLiteral(text) {
+    const escaped = text
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t')
+        .replace(/\u2028/g, '\\u2028')
+        .replace(/\u2029/g, '\\u2029')
+        .replace(/[\u0000-\u001f\u007f]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`);
+    return `'${escaped}'`;
+}
+function resolveBinding(binding, catalogs, sourceLocale) {
+    const source = catalogs.byLocale.get(sourceLocale);
+    const problems = [...binding.problems];
+    const resolved = [];
+    // Without a static namespace no key can be looked up; reporting each call would only repeat the cause.
+    if (problems.some((problem) => problem.reason === 'dynamic-namespace'))
+        return { resolved, problems };
+    for (const call of binding.calls) {
+        const fullKey = binding.namespace ? `${binding.namespace}.${call.key}` : call.key;
+        const raw = source.get(fullKey);
+        // Ids hash the bytes as written. Editors save NFC, so a decomposed catalog text would get a new
+        // id (and lose its translations) on the first save; normalize up front instead.
+        const text = raw?.normalize('NFC');
+        if (text !== undefined && text.trim() === '') {
+            problems.push({ reason: `empty-message: ${fullKey}`, line: call.line, column: call.column });
+            continue;
+        }
+        if (text === undefined) {
+            const reason = catalogs.nonString.has(fullKey)
+                ? 'non-string-message'
+                : [...source.keys()].some((key) => key.startsWith(`${fullKey}.`))
+                    ? 'key-refers-to-namespace-object'
+                    : 'missing-key';
+            problems.push({ reason: `${reason}: ${fullKey}`, line: call.line, column: call.column });
+            continue;
+        }
+        resolved.push({ call, fullKey, text, normalized: raw !== text });
+    }
+    return { resolved, problems };
+}
+function pickNamespace(binding, resolved, strategy) {
+    if (strategy === 'none')
+        return undefined;
+    if (strategy === 'keep')
+        return binding.namespace;
+    // A single-segment key has no namespace to take; mixing it with namespaced keys yields none either.
+    const firstSegments = new Set(resolved.map(({ fullKey }) => (fullKey.includes('.') ? fullKey.split('.')[0] : undefined)));
+    return firstSegments.size === 1 ? [...firstSegments][0] : undefined;
+}
+export function buildPlan(scanned, catalogs, options) {
+    const targetLocales = catalogs.locales.filter((locale) => locale !== options.sourceLocale);
+    const edits = [];
+    const skipped = [];
+    const referencedKeys = new Set();
+    const groups = new Map();
+    // Call-site edits are emitted once ids are known, so remember where each call goes.
+    const pendingCalls = [];
+    let convertedBindings = 0;
+    let convertedCalls = 0;
+    const changedFiles = new Set();
+    const normalizedKeys = new Set();
+    const valuesNotInMessage = [];
+    for (const scannedFile of scanned) {
+        const { file, text } = scannedFile;
+        // Per hook kind: which bindings stay on the old hook decides whether the
+        // import is renamed or extended.
+        const kept = new Set();
+        const converted = new Set();
+        const hookEdits = [];
+        for (const binding of scannedFile.bindings) {
+            const { resolved, problems } = resolveBinding(binding, catalogs, options.sourceLocale);
+            for (const { fullKey } of resolved)
+                referencedKeys.add(fullKey);
+            if (problems.length > 0) {
+                kept.add(binding.hook);
+                const { line, column } = positionFromOffset(text, binding.hookCallRange.start);
+                skipped.push({ file: relative(options.projectRoot, file), name: binding.name, hook: binding.hook, line, column, problems });
+                continue;
+            }
+            converted.add(binding.hook);
+            convertedBindings++;
+            const namespace = pickNamespace(binding, resolved, options.namespace);
+            hookEdits.push({ binding, namespace });
+            for (const { call, fullKey, text: messageText, normalized } of resolved) {
+                convertedCalls++;
+                if (normalized)
+                    normalizedKeys.add(fullKey);
+                if (call.valueKeys) {
+                    const { args, tags } = icuNames(messageText);
+                    // Tag handlers only exist on t.rich / t.markup; a plain t() call cannot take them.
+                    const declared = call.method === 'call' ? args : new Set([...args, ...tags]);
+                    const extra = call.valueKeys.filter((name) => !declared.has(name));
+                    if (extra.length > 0) {
+                        valuesNotInMessage.push({ file: relative(options.projectRoot, file), line: call.line, column: call.column, key: fullKey, values: extra });
+                    }
+                }
+                const groupKey = `${namespace ?? ''}\u0000${messageText}`;
+                let group = groups.get(groupKey);
+                if (!group) {
+                    group = { namespace, text: messageText, entries: new Map() };
+                    groups.set(groupKey, group);
+                }
+                let entry = group.entries.get(fullKey);
+                if (!entry) {
+                    const translations = {};
+                    for (const locale of targetLocales) {
+                        translations[locale] = catalogs.byLocale.get(locale)?.get(fullKey) ?? '';
+                    }
+                    entry = { fullKey, translations, sites: [] };
+                    group.entries.set(fullKey, entry);
+                }
+                entry.sites.push({ file, call });
+                pendingCalls.push({ file, call, groupKey, fullKey });
+            }
+        }
+        if (hookEdits.length === 0)
+            continue;
+        changedFiles.add(file);
+        for (const hook of converted) {
+            const extractedName = EXTRACTED_BY_HOOK[hook];
+            const oldName = hook === 'use' ? 'useTranslations' : 'getTranslations';
+            const moduleImports = scannedFile.imports.filter((info) => info.module === MODULE_BY_HOOK[hook]);
+            const importInfo = moduleImports.find((info) => info.specifiers.some((spec) => spec.imported === oldName)) ?? moduleImports[0];
+            const existing = moduleImports.flatMap((info) => info.specifiers).find((spec) => spec.imported === extractedName);
+            const hookSpecifier = importInfo?.specifiers.find((spec) => spec.imported === oldName);
+            // The old specifier can go only when no binding and no other reference still needs it.
+            const oldSpecifierUnused = hookSpecifier !== undefined && !kept.has(hook) && hookSpecifier.otherUses === 0;
+            let localName = extractedName;
+            if (existing) {
+                localName = existing.local;
+                if (oldSpecifierUnused) {
+                    // The old hook is no longer used: drop its specifier together with one separating comma.
+                    const specifiers = importInfo.specifiers;
+                    const index = specifiers.indexOf(hookSpecifier);
+                    const start = index > 0 ? specifiers[index - 1].elementRange.end : hookSpecifier.elementRange.start;
+                    const end = index > 0 ? hookSpecifier.elementRange.end : specifiers[index + 1].elementRange.start;
+                    edits.push({ file, start, end, text: '' });
+                }
+            }
+            else if (oldSpecifierUnused) {
+                // Every binding of this hook is converted: rename the specifier in place.
+                edits.push({ file, ...hookSpecifier.importedRange, text: extractedName });
+                if (hookSpecifier.local !== hookSpecifier.imported)
+                    localName = hookSpecifier.local;
+            }
+            else if (importInfo) {
+                edits.push({ file, start: importInfo.appendPosition, end: importInfo.appendPosition, text: `, ${extractedName}` });
+            }
+            for (const { binding, namespace } of hookEdits) {
+                if (binding.hook !== hook)
+                    continue;
+                let args = '';
+                if (binding.otherHookProps) {
+                    const props = [...binding.otherHookProps];
+                    if (namespace !== undefined)
+                        props.push(`namespace: ${toStringLiteral(namespace)}`);
+                    args = props.length > 0 ? `{${props.join(', ')}}` : '';
+                }
+                else if (namespace !== undefined) {
+                    args = toStringLiteral(namespace);
+                }
+                edits.push({ file, ...binding.hookCallRange, text: `${localName}(${args})` });
+            }
+        }
+    }
+    // Resolve ids: one message per (namespace, text) unless the old translations
+    // disagree, in which case each distinct translation set keeps an explicit id.
+    const messages = [];
+    const conflicts = [];
+    const idByFullKey = new Map();
+    const usedIds = new Set();
+    for (const group of groups.values()) {
+        const clusters = new Map();
+        for (const entry of group.entries.values()) {
+            const signature = JSON.stringify(targetLocales.map((locale) => entry.translations[locale]));
+            const list = clusters.get(signature) ?? [];
+            list.push(entry);
+            clusters.set(signature, list);
+        }
+        const isConflict = clusters.size > 1;
+        const conflict = { namespace: group.namespace, message: group.text, clusters: [] };
+        const prefix = group.namespace ? `${group.namespace}.` : '';
+        for (const entries of clusters.values()) {
+            entries.sort((a, b) => a.fullKey.localeCompare(b.fullKey, 'en'));
+            let localId = generateId(group.text);
+            if (isConflict) {
+                const first = entries[0].fullKey;
+                localId = first.startsWith(prefix) ? first.slice(prefix.length) : first;
+            }
+            const id = `${prefix}${localId}`;
+            if (usedIds.has(id))
+                throw new Error(`Generated id collision: ${id}`);
+            usedIds.add(id);
+            const references = [];
+            for (const entry of entries) {
+                idByFullKey.set(entry.fullKey, { localId, explicit: isConflict });
+                for (const { file, call } of entry.sites) {
+                    references.push({ path: relative(options.projectRoot, file), line: call.line, column: call.column });
+                }
+            }
+            messages.push({
+                id,
+                message: group.text,
+                references: references.sort(compareReferences),
+                translations: entries[0].translations,
+                explicitId: isConflict,
+                oldKeys: entries.map((entry) => entry.fullKey)
+            });
+            conflict.clusters.push({ id, oldKeys: entries.map((entry) => entry.fullKey), translations: entries[0].translations });
+        }
+        if (isConflict)
+            conflicts.push(conflict);
+    }
+    for (const { file, call, fullKey, groupKey } of pendingCalls) {
+        const { localId, explicit } = idByFullKey.get(fullKey);
+        const text = groups.get(groupKey).text;
+        const replacement = explicit
+            ? `{id: ${toStringLiteral(localId)}, message: ${toStringLiteral(text)}}`
+            : toStringLiteral(text);
+        edits.push({ file, ...call.argRange, text: replacement });
+    }
+    const source = catalogs.byLocale.get(options.sourceLocale);
+    const report = {
+        files: {
+            scanned: scanned.length,
+            changed: changedFiles.size,
+            withoutNextIntlImport: scanned
+                .filter((scannedFile) => scannedFile.imports.length === 0 && scannedFile.hookIdentifiers > 0)
+                .map((scannedFile) => relative(options.projectRoot, scannedFile.file))
+        },
+        bindings: { converted: convertedBindings, skipped: skipped.length },
+        calls: { converted: convertedCalls },
+        messages: { total: messages.length, explicitIds: messages.filter((m) => m.explicitId).length },
+        normalizedKeys: [...normalizedKeys],
+        valuesNotInMessage,
+        skipped,
+        conflicts,
+        nonStringKeys: [...catalogs.nonString.keys()],
+        catalogCollisions: catalogs.collisions,
+        unreferencedKeys: [...source.keys()].filter((key) => !referencedKeys.has(key)),
+        keyMap: Object.fromEntries(messages.flatMap((m) => m.oldKeys.map((key) => [key, m.id])))
+    };
+    return { edits, messages, report };
+}
+/** Argument and tag names an ICU message declares: `{count, plural, …}`, `<link>…</link>`. */
+function icuNames(message) {
+    const args = new Set();
+    const tags = new Set();
+    for (const match of message.matchAll(/\{\s*([A-Za-z0-9_]+)/g))
+        args.add(match[1]);
+    for (const match of message.matchAll(/<([A-Za-z0-9_]+)[\s/>]/g))
+        tags.add(match[1]);
+    return { args, tags };
+}
+/** Same order as the extractor (`compareReferences` in next-intl), so a later extraction run rewrites nothing. */
+function compareReferences(a, b) {
+    return a.path.localeCompare(b.path, 'en') || a.line - b.line || a.column - b.column;
+}
+function relative(projectRoot, file) {
+    return path.relative(projectRoot, file).split(path.sep).join('/');
+}
+function positionFromOffset(text, offset) {
+    const before = text.slice(0, offset);
+    const line = before.split('\n').length;
+    const column = offset - (before.lastIndexOf('\n') + 1);
+    return { line, column };
+}

package/dist/scan.js

@@ -0,0 +1,280 @@
+import ts from 'typescript';
+const HOOK_BY_IMPORT = {
+    useTranslations: 'use',
+    getTranslations: 'get'
+};
+const EXTRACTED_BY_HOOK = {
+    use: 'useExtracted',
+    get: 'getExtracted'
+};
+const MODULE_BY_HOOK = {
+    use: 'next-intl',
+    get: 'next-intl/server'
+};
+export { EXTRACTED_BY_HOOK, MODULE_BY_HOOK };
+function staticString(node) {
+    if (!node)
+        return undefined;
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+        return node.text;
+    }
+    return undefined;
+}
+function rangeOf(node, sourceFile) {
+    return { start: node.getStart(sourceFile), end: node.getEnd() };
+}
+function positionOf(node, sourceFile) {
+    const start = node.getStart(sourceFile);
+    const { line } = sourceFile.getLineAndCharacterOfPosition(start);
+    // The SWC extractor counts columns in code points, TypeScript in UTF-16 units.
+    const lineStart = sourceFile.getPositionOfLineAndCharacter(line, 0);
+    const column = [...sourceFile.text.slice(lineStart, start)].length;
+    return { line: line + 1, column };
+}
+/**
+ * Finds the variable the hook result is bound to:
+ * `const t = useTranslations()`, `const t = await getTranslations()` or
+ * `const [a, b] = await Promise.all([getTranslations('a'), getTranslations('b')])`.
+ */
+function findBindingName(call) {
+    let node = call;
+    if (ts.isAwaitExpression(node.parent))
+        node = node.parent;
+    if (ts.isVariableDeclaration(node.parent) && ts.isIdentifier(node.parent.name)) {
+        return node.parent.name;
+    }
+    if (ts.isArrayLiteralExpression(node.parent)) {
+        const index = node.parent.elements.indexOf(node);
+        let declaration = node.parent.parent;
+        if (!ts.isCallExpression(declaration))
+            return undefined;
+        declaration = declaration.parent;
+        if (ts.isAwaitExpression(declaration))
+            declaration = declaration.parent;
+        if (ts.isVariableDeclaration(declaration) &&
+            ts.isArrayBindingPattern(declaration.name)) {
+            const element = declaration.name.elements[index];
+            if (element && ts.isBindingElement(element) && ts.isIdentifier(element.name)) {
+                return element.name;
+            }
+        }
+    }
+    return undefined;
+}
+function staticPropertyNames(node) {
+    if (!node || !ts.isObjectLiteralExpression(node))
+        return undefined;
+    const names = [];
+    for (const property of node.properties) {
+        const name = property.name;
+        if (!name || !(ts.isIdentifier(name) || ts.isStringLiteral(name)))
+            return undefined;
+        names.push(name.text);
+    }
+    return names;
+}
+/** True for an identifier inside the trailing array argument of a `useXxx(...)` call. */
+function isHookDependency(reference) {
+    const array = reference.parent;
+    if (!ts.isArrayLiteralExpression(array) || !ts.isCallExpression(array.parent))
+        return false;
+    const call = array.parent;
+    if (call.arguments[call.arguments.length - 1] !== array)
+        return false;
+    const callee = call.expression;
+    const name = ts.isIdentifier(callee)
+        ? callee.text
+        : ts.isPropertyAccessExpression(callee)
+            ? callee.name.text
+            : '';
+    return /^use[A-Z]/.test(name);
+}
+export function scanFiles(files) {
+    const program = ts.createProgram(files, {
+        allowJs: true,
+        jsx: ts.JsxEmit.Preserve,
+        noResolve: true,
+        noLib: true,
+        target: ts.ScriptTarget.ESNext,
+        module: ts.ModuleKind.ESNext
+    });
+    const checker = program.getTypeChecker();
+    const result = [];
+    for (const file of files) {
+        const sourceFile = program.getSourceFile(file);
+        if (!sourceFile)
+            continue;
+        result.push(scanSourceFile(sourceFile, checker));
+    }
+    return result;
+}
+function scanSourceFile(sourceFile, checker) {
+    const imports = [];
+    const hookByImportSymbol = new Map();
+    const hookSpecifiers = [];
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement))
+            continue;
+        const moduleName = staticString(statement.moduleSpecifier);
+        if (moduleName !== 'next-intl' && moduleName !== 'next-intl/server')
+            continue;
+        const named = statement.importClause?.namedBindings;
+        if (!named || !ts.isNamedImports(named))
+            continue;
+        const info = {
+            module: moduleName,
+            specifiers: [],
+            appendPosition: named.elements[named.elements.length - 1]?.getEnd() ?? named.getEnd() - 1
+        };
+        for (const element of named.elements) {
+            const importedNode = element.propertyName ?? element.name;
+            const imported = importedNode.text;
+            const specifier = {
+                imported,
+                local: element.name.text,
+                importedRange: rangeOf(importedNode, sourceFile),
+                elementRange: rangeOf(element, sourceFile),
+                otherUses: 0
+            };
+            info.specifiers.push(specifier);
+            const hook = HOOK_BY_IMPORT[imported];
+            if (hook && MODULE_BY_HOOK[hook] === moduleName) {
+                const symbol = checker.getSymbolAtLocation(element.name);
+                if (symbol) {
+                    hookByImportSymbol.set(symbol, hook);
+                    hookSpecifiers.push({ specifier, symbol, nameNode: element.name });
+                }
+            }
+        }
+        imports.push(info);
+    }
+    const bindings = [];
+    let hookIdentifiers = 0;
+    const countHookIdentifiers = (node) => {
+        if (ts.isIdentifier(node) && node.text in HOOK_BY_IMPORT)
+            hookIdentifiers++;
+        ts.forEachChild(node, countHookIdentifiers);
+    };
+    countHookIdentifiers(sourceFile);
+    const result = { file: sourceFile.fileName, text: sourceFile.text, imports, bindings, hookIdentifiers };
+    if (hookByImportSymbol.size === 0)
+        return result;
+    // One pass collects every identifier by symbol, so references of a binding
+    // are a lookup instead of a traversal per binding.
+    const identifiersBySymbol = new Map();
+    const hookCalls = [];
+    const visit = (node) => {
+        if (ts.isIdentifier(node)) {
+            const symbol = ts.isShorthandPropertyAssignment(node.parent)
+                ? checker.getShorthandAssignmentValueSymbol(node.parent)
+                : checker.getSymbolAtLocation(node);
+            if (symbol) {
+                const list = identifiersBySymbol.get(symbol) ?? [];
+                list.push(node);
+                identifiersBySymbol.set(symbol, list);
+            }
+        }
+        if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+            const symbol = checker.getSymbolAtLocation(node.expression);
+            const hook = symbol && hookByImportSymbol.get(symbol);
+            if (hook)
+                hookCalls.push({ call: node, hook });
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    const hookCallees = new Set(hookCalls.map(({ call }) => call.expression));
+    for (const { specifier, symbol, nameNode } of hookSpecifiers) {
+        specifier.otherUses = (identifiersBySymbol.get(symbol) ?? []).filter((identifier) => identifier !== nameNode && !hookCallees.has(identifier)).length;
+    }
+    for (const { call, hook } of hookCalls) {
+        const binding = {
+            name: '',
+            hook,
+            hookCallRange: rangeOf(call, sourceFile),
+            calls: [],
+            problems: []
+        };
+        bindings.push(binding);
+        const position = positionOf(call, sourceFile);
+        const arg = call.arguments[0];
+        if (arg) {
+            if (ts.isObjectLiteralExpression(arg)) {
+                binding.otherHookProps = [];
+                for (const property of arg.properties) {
+                    const name = property.name && ts.isIdentifier(property.name) ? property.name.text : undefined;
+                    if (name === 'namespace' && ts.isPropertyAssignment(property)) {
+                        const namespace = staticString(property.initializer);
+                        if (namespace === undefined) {
+                            binding.problems.push({ reason: 'dynamic-namespace', ...position });
+                        }
+                        binding.namespace = namespace;
+                    }
+                    else {
+                        binding.otherHookProps.push(property.getText(sourceFile));
+                    }
+                }
+            }
+            else {
+                const namespace = staticString(arg);
+                if (namespace === undefined) {
+                    binding.problems.push({ reason: 'dynamic-namespace', ...position });
+                }
+                binding.namespace = namespace;
+            }
+        }
+        const nameNode = findBindingName(call);
+        if (!nameNode) {
+            binding.problems.push({ reason: 'hook-result-not-bound-to-variable', ...position });
+            continue;
+        }
+        binding.name = nameNode.text;
+        const symbol = checker.getSymbolAtLocation(nameNode);
+        const references = (symbol && identifiersBySymbol.get(symbol)) ?? [];
+        for (const reference of references) {
+            if (reference === nameNode)
+                continue;
+            const referencePosition = positionOf(reference, sourceFile);
+            let callExpression;
+            let method = 'call';
+            if (ts.isCallExpression(reference.parent) && reference.parent.expression === reference) {
+                callExpression = reference.parent;
+            }
+            else if (ts.isPropertyAccessExpression(reference.parent) &&
+                reference.parent.expression === reference &&
+                ts.isCallExpression(reference.parent.parent) &&
+                reference.parent.parent.expression === reference.parent) {
+                const property = reference.parent.name.text;
+                if (property === 'rich' || property === 'markup' || property === 'has' || property === 'raw') {
+                    method = property;
+                    callExpression = reference.parent.parent;
+                }
+            }
+            if (!callExpression) {
+                // `useCallback(() => t('x'), [t])`: the dependency list reads `t` but never calls it.
+                if (!isHookDependency(reference)) {
+                    binding.problems.push({ reason: 'translator-used-outside-call', ...referencePosition });
+                }
+                continue;
+            }
+            if (method === 'has' || method === 'raw') {
+                binding.problems.push({ reason: `t.${method}-not-supported-by-extraction`, ...referencePosition });
+                continue;
+            }
+            const keyNode = callExpression.arguments[0];
+            const key = staticString(keyNode);
+            if (key === undefined) {
+                binding.problems.push({ reason: 'dynamic-key', ...referencePosition });
+                continue;
+            }
+            binding.calls.push({
+                method,
+                argRange: rangeOf(keyNode, sourceFile),
+                key,
+                valueKeys: staticPropertyNames(callExpression.arguments[1]),
+                ...positionOf(callExpression, sourceFile)
+            });
+        }
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "next-intl-codemod",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "next-intl-codemod": "dist/cli.js"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "codemod": "tsx src/cli.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "pnpm test && pnpm build"
+  },
+  "dependencies": {
+    "@eloqnt/config": "^0.1.1",
+    "@eloqnt/format-json": "^0.1.0",
+    "@eloqnt/format-po": "^0.1.1",
+    "typescript": "^5.9.0"
+  },
+  "devDependencies": {
+    "@swc/core": "^1.16.0",
+    "@types/node": "^26.6.5",
+    "next-intl": "^4.14.9",
+    "next-intl-swc-plugin-extractor": "^4.14.9",
+    "tsx": "^4.20.0",
+    "vitest": "^3.2.0"
+  },
+  "license": "MIT",
+  "description": "Migrates next-intl useTranslations/getTranslations with static keys to useExtracted/getExtracted and carries existing translations over.",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seob717/next-intl-codemod.git"
+  }
+}