next-intl-scanner
Advanced tools
A tool to extract and manage translations from Next.js projects using next-intl
A powerful tool to extract and manage internationalization messages from Next.js projects using the next-intl package. This tool helps automate the process of managing translations in your Next.js applications, making it easier to maintain multilingual projects.
npm install next-intl-scanner --save-dev
# or
yarn add next-intl-scanner --dev
This package is designed to be used as a CLI tool for extracting translations during build time or development.
next-intl-scanner extract
The simplest way to use Next Intl Scanner is to run the extract command:
npx next-intl-scanner extract
This will scan your project for translations using the default configuration.
the problem with using strings as keys is that there are some characters that are not allowed in jsonKeys like . and :, so we need to use a custom hook to scan the jsonKeys and return the clean keys.
To solve this, you can use a custom hook for translations, so that our custom scanner function will work with the clean keys.
// hooks/useTranslation.ts
import { useTranslations } from "next-intl";
export function useCustomTranslation(namespace: string) {
const t = useTranslations(namespace);
return {
t: (key: string, params?: Record<string, any>, message?: string) => {
try {
return t(key, params);
} catch (error) {
// Fallback to message or key if translation is missing
return message || key;
}
},
};
}
// Usage in components:
import { useCustomTranslation } from "@/hooks/useTranslation";
function MyComponent() {
const { t } = useCustomTranslation("namespace");
return <div>{t("key", {}, "fallback message")}</div>;
}
This approach:
you can define a custom jsx element to be used in your project, and the scanner will extract the translations from it.
// components/FormattedMessage.tsx
"use client";
import { useTranslations } from "@/hooks/useTranslations";
interface FormattedMessageProps {
string: string;
namespace?: string;
messageKey?: string;
params?: Record<string, any>;
}
const FormattedMessage = (props: FormattedMessageProps) => {
const { string, namespace, messageKey, params } = props;
const t = useTranslations(namespace || "");
const finalKey = messageKey || string;
return <>{t(finalKey, params || {}, string)}</>;
};
export default FormattedMessage;
Then use the custom element like this :
<FormattedMessage
string="Hello, {name}!"
namespace="customNamespace"
params={{ name: "John" }}
messageKey="hello"
/>
This way you can use the custom jsx element in your project, and the scanner will extract the translations from it.
npx next-intl-scanner extract --auto-translate
npx next-intl-scanner extract --config ./custom.config.js
npx next-intl-scanner extract --overwrite
Run the scanner in watch mode to automatically re-extract translations when files change:
npx next-intl-scanner extract --watch
You can also combine watch mode with other options:
npx next-intl-scanner extract --watch --overwrite
npx next-intl-scanner extract --watch --auto-translate
The watch mode will:
--config <path>: Path to configuration file (default: ./next-intl-scanner.config.js)--auto-translate: Enable auto-translation of extracted strings--overwrite: Overwrite existing translations (use with caution)--watch: Watch for file changes and automatically re-extract translations--version: Display version information--help: Display help informationCreate a next-intl-scanner.config.js file in your project root. Here's a detailed example:
module.exports = {
// Source files to scan (supports glob patterns)
input: [
"src/**/*.{js,jsx,ts,tsx}",
"!src/**/*.test.{js,jsx,ts,tsx}", // Exclude test files
"!src/**/*.spec.{js,jsx,ts,tsx}", // Exclude spec files
],
// Output directory for translation files
output: "src/locales",
// Supported locales
locales: ["en", "ar", "fr", "es"],
// Default locale
defaultLocale: "en",
// Note: Currently only Google Translate API v2 is supported , make sure that you have set the GOOGLE_TRANSLATE_API_KEY environment variable
// If you need support for other translation services, please create an issue on GitHub
};
To enable auto-translation, you need to set the GOOGLE_TRANSLATE_API_KEY environment variable and use the --auto-translate flag.
export GOOGLE_TRANSLATE_API_KEY=<your-api-key>
Add the scanner to your build process by updating your package.json:
{
"scripts": {
"extract-translations": "next-intl-scanner extract",
"extract-translations:watch": "next-intl-scanner extract --watch",
"build": "next-intl-scanner extract && next build"
}
}
--overwrite optionMissing Translations
input patternsAuto-translation Not Working
Configuration Errors
If you encounter any issues or have questions:
MIT
FAQs
A tool to extract and manage translations from Next.js projects using next-intl
We found that next-intl-scanner demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Company News
Socket won two 2026 Reppy Awards from RepVue, ranking in the top 5% of all sales orgs. AE Alexandra Lister shares what it's like to grow a sales career here.
Security News
NIST will stop enriching most CVEs under a new risk-based model, narrowing the NVD's scope as vulnerability submissions continue to surge.
Company News
/Security News
Socket is an initial recipient of OpenAI's Cybersecurity Grant Program, which commits $10M in API credits to defenders securing open source software.