CLI to find unused/missing translations

[simonlovesyou]

Hey!

At my previous engagement we developed a CLI to find unused or missing translations with static code analysis. It was closed source unfortunately, but would there be any interest in integrating it to next-intl if I were to rebuild it, but open source? :) If so, any thoughts on what the features set should be? There are also some different choices we can make in terms of user configuration, preferred libraries to use etc.

This is relevant to Linting unused strings · amannn/next-intl · Discussion #398

EDIT: On second thought it could even be integrated as an eslint rule instead of a separate CLI if we would prefer that.

[amannn]

Hey @simonlovesyou, thank you so much for starting this discussion! There's no CLI or ESLint plugin planned at this point, but I'm absolutely open to discussing this!

Would you like to implement and provide this under your own GitHub user or in this repo? Both is totally fine IMO, we can link to it from the workflows & integrations page in the docs.

I like your idea about having an ESLint plugin, mostly because many developers already use ESLint and therefore it's easy to integrate with their toolchain. In regard to other rules, a no-deprecated rule could be interesting to help users migrate when APIs need to be changed—this is something I already considered. In regard to messages handling I could also imagine a sort-keys rule that is autofixable and makes sure that messages files are consistently structured. I personally use the i18n Ally VSCode extension that does the sorting, not sure if it's worth implementing this ourselves.

But starting with an ESLint plugin with a single rule could still be useful IMO.

Do you have experience with building something like this? I'm wondering how this would impact editor performance or, more generally, ESLint runtime performance. When are messages files checked? Are there parts of the linting process that can be cached?

A CLI might be less performance-sensitive since a user would explicitly call the CLI e.g. on CI (see also #398 (comment)).

What's your opinion?

/cc @kieranm

[kieranm]

I tried to write an ESlint rule for this and failed miserably. ESLint seems to analyse files independently and so there doesn't appear to be a way of determining whether something is used or unused globally across the whole codebase. I could be missing something big though as my ESLint knowledge is very limited

[amannn]

I just noticed i18n Ally has a usage report, this could be helpful in this context:

It currently reports a few false positives for me though, due to pending support for getTranslations (useTranslations seems to work fine).

[amannn]

i18n-check is exploring detecting unused messages: Validating messages

[ohmycode]

Late to the party, but in case somebody still needs it, with the help of some LLM magic I've created this node script that works for my needs:

const fs = require('fs');
const path = require('path');
const { Project, SyntaxKind } = require('ts-morph');

// === CLI ARGUMENTS ===
const locale = process.argv[2] || 'en';
const messagesDir = process.argv[3] || '../messages';

const RELATIVE_LOCALE_PATH = `${messagesDir}/${locale}.json`;
const LOCALE_FILE = path.join(__dirname, RELATIVE_LOCALE_PATH);
const SRC_DIR = path.join(__dirname, '../src'); // Adjust if needed

console.log(`🔍 Checking missing messages in path: ${RELATIVE_LOCALE_PATH}`);

// === STEP 1: LOAD EXISTING TRANSLATIONS ===
let existingMessages = {};
try {
  existingMessages = JSON.parse(fs.readFileSync(LOCALE_FILE, 'utf8'));
} catch (err) {
  console.error(`❌ Failed to load locale file: ${RELATIVE_LOCALE_PATH}`);
  console.error(err.message);
  process.exit(1);
}

const existingKeys = new Set();

function flatten(obj, prefix = '') {
  for (const key in obj) {
    const val = obj[key];
    const fullKey = prefix ? `${prefix}.${key}` : key;
    if (typeof val === 'object' && val !== null) {
      flatten(val, fullKey);
    } else {
      existingKeys.add(fullKey);
    }
  }
}
flatten(existingMessages);

// === STEP 2: PARSE FILES WITH ts-morph ===
const project = new Project({
  tsConfigFilePath: path.join(__dirname, '../tsconfig.json'),
});
project.addSourceFilesAtPaths(`${SRC_DIR}/**/*.{ts,tsx,js,jsx}`);

const usedKeys = new Set();

project.getSourceFiles().forEach((file) => {
  const namespaceMap = new Map(); // e.g. t -> "general"

  // Track: const t = useTranslations('namespace')
  file.forEachDescendant((node) => {
    if (node.getKind() === SyntaxKind.VariableDeclaration) {
      const init = node.getInitializer();
      if (!init || init.getKind() !== SyntaxKind.CallExpression) return;

      const call = init;
      const expr = call.getExpression().getText();
      if (expr === 'useTranslations') {
        const args = call.getArguments();
        if (args.length > 0 && args[0].getKind() === SyntaxKind.StringLiteral) {
          const ns = args[0].getText().slice(1, -1); // remove quotes
          const varName = node.getName();
          namespaceMap.set(varName, ns);
        }
      }
    }
  });

  // Match calls like t("title") where t is a known namespace-bound function
  file.forEachDescendant((node) => {
    if (node.getKind() === SyntaxKind.CallExpression) {
      const call = node;
      const expr = call.getExpression().getText();
      const arg = call.getArguments()[0];

      if (namespaceMap.has(expr) && arg && arg.getKind() === SyntaxKind.StringLiteral) {
        const key = arg.getText().slice(1, -1); // remove quotes
        const fullKey = `${namespaceMap.get(expr)}.${key}`;
        usedKeys.add(fullKey);
      }
    }
  });
});

// === STEP 3: COMPARE USED VS EXISTING ===
const missing = [...usedKeys].filter((key) => !existingKeys.has(key));

if (missing.length === 0) {
  console.log('✅ No missing translation keys found!');
} else {
  console.log(`🚨 Found ${missing.length} missing translation key(s):\n`);
  missing.forEach((key) => console.log(`- ${key}`));
}

Usage example:
node scripts/find-missing-translations.js' [locale] [relative path to folder containing messages]

Required npm package:

• ts-morph

[serjdrn]

@amannn I have a created cli tool in go for exactly this purpose and it tests out pretty good. Would you be interested in checking it out?

[amannn]

Sure, you can definitely share a link to it here for people to check it out!

I've also shared one above that I recently found: #503 (comment)

[serjdrn]

@amannn https://github.com/serjdrn/next-intl-analyzer here's the project. I've identified some edge cases and false positives but mostly does the job I need it to do.

[amannn]

That's a really interesting one!

The go dependency for install seems a bit heavy, but I guess it could easily be removed for distributing on npm, if desired.

Your heuristics for detecting hardcoded strings are very interesting, it's quite a tricky problem to solve (esp. for props).

Will definitely keep an eye on this!

[r1si]

Hi @amannn 👋
First of all, thanks a lot for your great work on next-intl — it’s an excellent and very well-designed library!

Recently, in one of my Next.js projects using next-intl, I wrote a few Node.js scripts that:

• detect all unused keys in the translation JSON files,

• list all calls to t() or useTranslations in the codebase that don’t have a corresponding translation key,

• and verify that all message files across different locales contain the same set of keys.

After the introduction of useExtractor, I was wondering if you’re still interested in integrating such features — possibly as CLI commands like npx next-intl check-unused or npx next-intl verify-keys.

If so, what would be the best way to proceed?
Should I share the individual scripts first so you can review them, or would you prefer that I open a pull request directly?

Thanks again for your amazing work and for maintaining this project!

[amannn]

Great to hear that you like it, thanks! Sounds pretty cool what you've set up there!

There are currently some useful community tools like i18n-check and next-intl-analyzer which do a pretty decent job here I think.

As for useExtracted: A benefit is that you can never have either unused keys or calls to t which are not backed up with translations. On top of this, I think e.g. i18n-check is very helpful here to validate that you don't have missing messages in target locales or you're using ICU features inconsistently.

So as far as I'm concerned, it seems like everything is already there. It could surely be considered to offer similar features like i18n-check in the future, but I currently don't really see the immediate need for it since this tool works very well.

What do you think?

[r1si]

Thanks a lot for the clarification!

I already knew about next-intl-analyzer, but I was actually hoping for a solution that doesn’t rely on Go — mainly to simplify setup and keep everything within the same JS tooling ecosystem.
I hadn’t tried i18n-check before though, so I’m going to test it right away to see how it compares, and whether my scripts cover anything that it doesn’t.

I completely understand your point of view: if i18n-check works well, there’s probably no urgent need for additional built-in tools. Still, I think it would be really nice if, in the long run, the main next-intl package offered an integrated way to analyze message usage — something in the spirit of npx prisma studio, but for i18n.

Thanks again for taking the time to reply, and for maintaining such a solid library! 💯