i18next-cli 1.62.0 → 1.63.0

package/README.md

@@ -118,6 +118,13 @@ npx i18next-cli init
   also auto-detects `CI=true` and falls back to printing the URL on headless
   Linux (no `DISPLAY`/`WAYLAND_DISPLAY`), so this flag is rarely needed
   explicitly.
+- `--inlang`: Also scaffold an [inlang](https://inlang.com) project
+  (`project.inlang/settings.json`) so inlang tooling — the
+  [Sherlock](https://inlang.com/m/r7kp499g/app-inlang-ideExtension) VS Code
+  extension, the [Fink](https://fink.inlang.com) web editor for translators,
+  and the [Paraglide](https://inlang.com/m/gerre34r/library-inlang-paraglideJs)
+  compiler — works directly on your translation files. Skips the
+  corresponding wizard question.
 
 The wizard asks for the config file type, locales, source-file glob, output
 path, and finally **"Translation backend?"** with three options:
@@ -131,6 +138,28 @@ path, and finally **"Translation backend?"** with three options:
   mode); add it later via a `LOCIZE_API_KEY` environment variable.
 - **Other / skip** — same as "Local files only" for the wizard's purposes.
 
+The wizard then offers to **set up inlang tooling** (default: no — or pass
+`--inlang` to skip the question). If accepted, it scaffolds a
+`project.inlang/settings.json` that points the
+[inlang i18next plugin](https://inlang.com/m/3i8bor92/plugin-inlang-i18next)
+at your existing translation files: `baseLocale`/`locales` come from your
+config, and `pathPattern` is derived from `extract.output` (the namespaced
+object form when your layout uses `{{namespace}}`, with namespaces discovered
+from the primary language's files; a plain pattern otherwise). It also adds
+the Sherlock extension to `.vscode/extensions.json` recommendations (merging
+comment-aware, never clobbering existing entries). Your i18next JSON files
+remain the single source of truth — inlang tools read and write them in
+place, so there is no second catalog to drift. An existing
+`project.inlang/settings.json` is never overwritten; re-running `init` is
+safe. Requires JSON resource files. The plugin is pinned to an exact verified
+version (`@inlang/plugin-i18next@6.2.0`) — bump the `modules` URL in
+`settings.json` to pick up newer plugin releases. Only `settings.json` is
+scaffolded by design: `project.inlang/` is the
+[unpacked (git-friendly)](https://inlang.com/docs/unpacked-project) project
+form, and inlang tools generate and manage its remaining files (`.gitignore`,
+`README.md`, `cache/`) on first use — so expect a few new files there after
+opening the project with Sherlock or Paraglide.
+
 ### `extract`
 Parses source files, extracts keys, and updates your JSON translation files.
 

package/dist/cjs/cli.js

@@ -37,7 +37,7 @@ const program = new commander.Command();
 program
     .name('i18next-cli')
     .description('A unified, high-performance i18next CLI.')
-    .version('1.62.0'); // This string is replaced with the actual version at build time by rollup
+    .version('1.63.0'); // This string is replaced with the actual version at build time by rollup
 // new: global config override option
 program.option('-c, --config <path>', 'Path to i18next-cli config file (overrides detection)');
 program
@@ -197,7 +197,8 @@ program
     .command('init')
     .description('Create a new i18next.config.ts/js file with an interactive setup wizard.')
     .option('--ci', 'Skip the browser launch when a backend (e.g. Locize) is selected. The signup URL is printed instead.')
-    .action((options) => init.runInit({ ci: !!options.ci }));
+    .option('--inlang', 'Also scaffold an inlang project (project.inlang/settings.json) so inlang tooling (Sherlock, Fink, Paraglide) works on the translation files. Skips the corresponding wizard question.')
+    .action((options) => init.runInit({ ci: !!options.ci, inlang: !!options.inlang }));
 program
     .command('lint')
     .description('Find potential issues like hardcoded strings in your codebase.')

package/dist/cjs/init.js

@@ -5,6 +5,7 @@ var promises = require('node:fs/promises');
 var node_path = require('node:path');
 var heuristicConfig = require('./heuristic-config.js');
 var locizeOnboarding = require('./utils/locize-onboarding.js');
+var inlangScaffold = require('./utils/inlang-scaffold.js');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -160,6 +161,14 @@ async function runInit(options = {}) {
             ],
             default: 'local',
         },
+        {
+            type: 'confirm',
+            name: 'inlang',
+            message: 'Also set up inlang tooling (Sherlock VS Code extension, Fink editor, Paraglide) on these translation files?',
+            default: false,
+            // Skip the question when already requested via the --inlang flag.
+            when: () => !options.inlang,
+        },
     ]);
     let locizeConfig;
     if (answers.backend === 'locize') {
@@ -253,6 +262,13 @@ module.exports = ${toJs(configObject)}`;
     const outputPath = node_path.resolve(process.cwd(), fileName);
     await promises.writeFile(outputPath, fileContent.trim());
     console.log(`✅ Configuration file created at: ${outputPath}`);
+    if (options.inlang || answers.inlang) {
+        await inlangScaffold.scaffoldInlangProject({
+            locales: answers.locales,
+            primaryLanguage: answers.locales[0],
+            output: answers.output,
+        });
+    }
     if (locizeConfig) {
         console.log('\nNext steps for Locize:');
         console.log('  1. Push your local translations to Locize:');

package/dist/cjs/instrumenter/core/instrumenter.js

@@ -1470,7 +1470,8 @@ const I18N_INIT_FILE_NAMES = [
  * Searches the common locations (`src/` and the project root) for an existing
  * i18n initialization file.
  *
- * @returns The path of the first init file found (relative to cwd), or null.
+ * @returns The path of the first init file found (relative to cwd, native
+ *          platform separators), or null.
  */
 async function findExistingI18nInitFile() {
     const cwd = process.cwd();

package/dist/cjs/utils/inlang-scaffold.js

@@ -0,0 +1,184 @@
+'use strict';
+
+var promises = require('node:fs/promises');
+var node_path = require('node:path');
+var jsoncParser = require('jsonc-parser');
+
+/**
+ * The plugin that teaches inlang tools (Sherlock, Fink, Paraglide) to read and
+ * write i18next JSON resource files directly.
+ *
+ * Pinned to an exact version on purpose: 6.2.0 is the first release with
+ * verified round-trip support for plurals, context, `_zero` and ordinal keys,
+ * and jsDelivr serves floating range URLs (`@6`) from edge caches that can
+ * lag releases by days. Bump deliberately when newer verified versions ship.
+ */
+const INLANG_PLUGIN_MODULE = 'https://cdn.jsdelivr.net/npm/@inlang/plugin-i18next@6.2.0/dist/index.js';
+/** VS Code marketplace id of the inlang Sherlock extension. */
+const SHERLOCK_EXTENSION_ID = 'inlang.vs-code-extension';
+/**
+ * Scaffolds an inlang project (`project.inlang/settings.json`) next to the
+ * i18next configuration so that inlang tooling (Sherlock VS Code extension,
+ * Fink editor, Paraglide compiler) operates on the EXISTING i18next JSON
+ * files. The i18next files remain the single source of truth — the scaffold
+ * is just the adapter.
+ *
+ * Behavior:
+ * - Derives `plugin.inlang.i18next.pathPattern` from the `extract.output`
+ *   template: the namespaced object form when the template contains a
+ *   `{{namespace}}` placeholder (namespaces are discovered from the files of
+ *   the primary language), the plain string form otherwise.
+ * - Never overwrites an existing `project.inlang/settings.json`.
+ * - Adds the Sherlock extension to `.vscode/extensions.json` recommendations
+ *   (creating or comment-preservingly merging the file).
+ */
+async function scaffoldInlangProject(options) {
+    const { locales, output } = options;
+    const baseLocale = options.primaryLanguage || locales[0] || 'en';
+    if (typeof output !== 'string') {
+        console.log('⚠️  Skipping inlang setup: extract.output is a function, so the file layout cannot be derived automatically. Create project.inlang/settings.json manually (see https://inlang.com/m/3i8bor92/plugin-inlang-i18next).');
+        return;
+    }
+    // Normalize Windows separators (heuristic-detected templates may be built
+    // with path.join) — settings.json patterns must be POSIX for portability.
+    // {{lng}} is a supported alias for {{language}}.
+    const template = output.replace(/\\/g, '/').replace(/\{\{lng\}\}/g, '{{language}}');
+    if (!template.endsWith('.json')) {
+        console.log('⚠️  Skipping inlang setup: the inlang i18next plugin supports JSON resource files only, but extract.output points to non-JSON files.');
+        return;
+    }
+    const settingsDir = node_path.resolve(process.cwd(), 'project.inlang');
+    const settingsPath = node_path.resolve(settingsDir, 'settings.json');
+    if (await fileExists(settingsPath)) {
+        console.log('ℹ️  project.inlang/settings.json already exists — leaving it untouched.');
+    }
+    else {
+        const pathPattern = template.includes('{{namespace}}')
+            ? await deriveNamespacedPathPattern(template, baseLocale, options.defaultNS)
+            : toInlangPattern(template);
+        const settings = {
+            $schema: 'https://inlang.com/schema/project-settings',
+            baseLocale,
+            locales,
+            modules: [INLANG_PLUGIN_MODULE],
+            'plugin.inlang.i18next': { pathPattern },
+        };
+        await promises.mkdir(settingsDir, { recursive: true });
+        await promises.writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+        console.log(`✅ inlang project created at: ${settingsPath}`);
+        console.log('   Your i18next JSON files stay the single source of truth — inlang tools read and write them directly.');
+        console.log(`   • Sherlock (VS Code): install the recommended "${SHERLOCK_EXTENSION_ID}" extension`);
+        console.log('   • Fink (web editor for translators): https://fink.inlang.com');
+        console.log('   • Paraglide (compiled i18n): npx @inlang/paraglide-js compile --project ./project.inlang');
+    }
+    await recommendSherlockExtension();
+}
+/**
+ * Converts an i18next-cli output template into an inlang `pathPattern`:
+ * `{{language}}` becomes `{locale}`, and relative paths are prefixed with
+ * `./` as required by the plugin's settings schema (which also permits
+ * `../`-relative and absolute paths, so those pass through unchanged).
+ */
+function toInlangPattern(template) {
+    const pattern = template.replace(/\{\{language\}\}/g, '{locale}');
+    if (pattern.startsWith('./') || pattern.startsWith('../') || pattern.startsWith('/')) {
+        return pattern;
+    }
+    return `./${pattern}`;
+}
+/**
+ * Builds the namespaced (object) form of `pathPattern` by discovering the
+ * project's namespaces from the existing resource files of the primary
+ * language. Falls back to the default namespace when no files exist yet
+ * (e.g. `init` ran before the first `extract`).
+ */
+async function deriveNamespacedPathPattern(template, baseLocale, defaultNS) {
+    const namespaces = await discoverNamespaces(template, baseLocale);
+    if (namespaces.length === 0) {
+        namespaces.push(typeof defaultNS === 'string' ? defaultNS : 'translation');
+    }
+    const pathPattern = {};
+    for (const ns of namespaces.sort()) {
+        pathPattern[ns] = toInlangPattern(template.replace(/\{\{namespace\}\}/g, ns));
+    }
+    return pathPattern;
+}
+/**
+ * Discovers namespace names by listing the directory entries that match the
+ * `{{namespace}}` segment of the output template, resolved for the primary
+ * language. Works for namespaces in the file name
+ * (`locales/en/{{namespace}}.json`) as well as in a directory segment
+ * (`locales/{{namespace}}/en.json`).
+ */
+async function discoverNamespaces(template, baseLocale) {
+    const resolved = template.replace(/\{\{language\}\}/g, baseLocale);
+    const segments = resolved.split('/');
+    const nsIndex = segments.findIndex(segment => segment.includes('{{namespace}}'));
+    if (nsIndex === -1)
+        return [];
+    const baseDir = node_path.resolve(process.cwd(), segments.slice(0, nsIndex).join('/'));
+    const [prefix, suffix = ''] = segments[nsIndex].split('{{namespace}}');
+    try {
+        const entries = await promises.readdir(baseDir);
+        return entries
+            .filter(entry => entry.startsWith(prefix) &&
+            entry.endsWith(suffix) &&
+            entry.length > prefix.length + suffix.length)
+            .map(entry => entry.slice(prefix.length, entry.length - suffix.length));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Adds the Sherlock VS Code extension to `.vscode/extensions.json`
+ * recommendations. Creates the file when missing; otherwise merges into the
+ * existing one while preserving comments and formatting (JSONC-aware). Bails
+ * gracefully — with a notice, never an error — when the existing file cannot
+ * be parsed.
+ */
+async function recommendSherlockExtension() {
+    const extensionsPath = node_path.resolve(process.cwd(), '.vscode', 'extensions.json');
+    let text;
+    try {
+        text = await promises.readFile(extensionsPath, 'utf-8');
+    }
+    catch {
+        // File doesn't exist yet — create it.
+    }
+    if (text === undefined || text.trim() === '') {
+        await promises.mkdir(node_path.dirname(extensionsPath), { recursive: true });
+        await promises.writeFile(extensionsPath, JSON.stringify({ recommendations: [SHERLOCK_EXTENSION_ID] }, null, 2) + '\n');
+        console.log('✅ Added the Sherlock extension to .vscode/extensions.json recommendations.');
+        return;
+    }
+    const errors = [];
+    const current = jsoncParser.parse(text, errors, { allowTrailingComma: true });
+    if (errors.length > 0 || typeof current !== 'object' || current === null || Array.isArray(current)) {
+        console.log('⚠️  Could not parse .vscode/extensions.json — please add "inlang.vs-code-extension" to its recommendations manually.');
+        return;
+    }
+    const recommendations = Array.isArray(current.recommendations) ? current.recommendations : [];
+    const alreadyRecommended = recommendations.some(entry => typeof entry === 'string' && entry.toLowerCase() === SHERLOCK_EXTENSION_ID);
+    if (alreadyRecommended)
+        return;
+    const formattingOptions = { insertSpaces: true, tabSize: 2, eol: '\n' };
+    const edits = Array.isArray(current.recommendations)
+        // Append to the existing array (preserves comments and formatting).
+        ? jsoncParser.modify(text, ['recommendations', recommendations.length], SHERLOCK_EXTENSION_ID, { isArrayInsertion: true, formattingOptions })
+        // No recommendations key yet — add one.
+        : jsoncParser.modify(text, ['recommendations'], [SHERLOCK_EXTENSION_ID], { formattingOptions });
+    await promises.writeFile(extensionsPath, jsoncParser.applyEdits(text, edits));
+    console.log('✅ Added the Sherlock extension to .vscode/extensions.json recommendations.');
+}
+async function fileExists(path) {
+    try {
+        await promises.readFile(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+
+exports.scaffoldInlangProject = scaffoldInlangProject;

package/dist/esm/cli.js

@@ -31,7 +31,7 @@ const program = new Command();
 program
     .name('i18next-cli')
     .description('A unified, high-performance i18next CLI.')
-    .version('1.62.0'); // This string is replaced with the actual version at build time by rollup
+    .version('1.63.0'); // This string is replaced with the actual version at build time by rollup
 // new: global config override option
 program.option('-c, --config <path>', 'Path to i18next-cli config file (overrides detection)');
 program
@@ -191,7 +191,8 @@ program
     .command('init')
     .description('Create a new i18next.config.ts/js file with an interactive setup wizard.')
     .option('--ci', 'Skip the browser launch when a backend (e.g. Locize) is selected. The signup URL is printed instead.')
-    .action((options) => runInit({ ci: !!options.ci }));
+    .option('--inlang', 'Also scaffold an inlang project (project.inlang/settings.json) so inlang tooling (Sherlock, Fink, Paraglide) works on the translation files. Skips the corresponding wizard question.')
+    .action((options) => runInit({ ci: !!options.ci, inlang: !!options.inlang }));
 program
     .command('lint')
     .description('Find potential issues like hardcoded strings in your codebase.')

package/dist/esm/init.js

@@ -3,6 +3,7 @@ import { writeFile, readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { detectConfig } from './heuristic-config.js';
 import { openBrowser, promptLocizeCredentials } from './utils/locize-onboarding.js';
+import { scaffoldInlangProject } from './utils/inlang-scaffold.js';
 
 const LOCIZE_SIGNUP_URL = 'https://www.locize.app/register?from=i18next_cli__init-wizard';
 /**
@@ -154,6 +155,14 @@ async function runInit(options = {}) {
             ],
             default: 'local',
         },
+        {
+            type: 'confirm',
+            name: 'inlang',
+            message: 'Also set up inlang tooling (Sherlock VS Code extension, Fink editor, Paraglide) on these translation files?',
+            default: false,
+            // Skip the question when already requested via the --inlang flag.
+            when: () => !options.inlang,
+        },
     ]);
     let locizeConfig;
     if (answers.backend === 'locize') {
@@ -247,6 +256,13 @@ module.exports = ${toJs(configObject)}`;
     const outputPath = resolve(process.cwd(), fileName);
     await writeFile(outputPath, fileContent.trim());
     console.log(`✅ Configuration file created at: ${outputPath}`);
+    if (options.inlang || answers.inlang) {
+        await scaffoldInlangProject({
+            locales: answers.locales,
+            primaryLanguage: answers.locales[0],
+            output: answers.output,
+        });
+    }
     if (locizeConfig) {
         console.log('\nNext steps for Locize:');
         console.log('  1. Push your local translations to Locize:');

package/dist/esm/instrumenter/core/instrumenter.js

@@ -1464,7 +1464,8 @@ const I18N_INIT_FILE_NAMES = [
  * Searches the common locations (`src/` and the project root) for an existing
  * i18n initialization file.
  *
- * @returns The path of the first init file found (relative to cwd), or null.
+ * @returns The path of the first init file found (relative to cwd, native
+ *          platform separators), or null.
  */
 async function findExistingI18nInitFile() {
     const cwd = process.cwd();

package/dist/esm/utils/inlang-scaffold.js

@@ -0,0 +1,182 @@
+import { mkdir, writeFile, readFile, readdir } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { parse, modify, applyEdits } from 'jsonc-parser';
+
+/**
+ * The plugin that teaches inlang tools (Sherlock, Fink, Paraglide) to read and
+ * write i18next JSON resource files directly.
+ *
+ * Pinned to an exact version on purpose: 6.2.0 is the first release with
+ * verified round-trip support for plurals, context, `_zero` and ordinal keys,
+ * and jsDelivr serves floating range URLs (`@6`) from edge caches that can
+ * lag releases by days. Bump deliberately when newer verified versions ship.
+ */
+const INLANG_PLUGIN_MODULE = 'https://cdn.jsdelivr.net/npm/@inlang/plugin-i18next@6.2.0/dist/index.js';
+/** VS Code marketplace id of the inlang Sherlock extension. */
+const SHERLOCK_EXTENSION_ID = 'inlang.vs-code-extension';
+/**
+ * Scaffolds an inlang project (`project.inlang/settings.json`) next to the
+ * i18next configuration so that inlang tooling (Sherlock VS Code extension,
+ * Fink editor, Paraglide compiler) operates on the EXISTING i18next JSON
+ * files. The i18next files remain the single source of truth — the scaffold
+ * is just the adapter.
+ *
+ * Behavior:
+ * - Derives `plugin.inlang.i18next.pathPattern` from the `extract.output`
+ *   template: the namespaced object form when the template contains a
+ *   `{{namespace}}` placeholder (namespaces are discovered from the files of
+ *   the primary language), the plain string form otherwise.
+ * - Never overwrites an existing `project.inlang/settings.json`.
+ * - Adds the Sherlock extension to `.vscode/extensions.json` recommendations
+ *   (creating or comment-preservingly merging the file).
+ */
+async function scaffoldInlangProject(options) {
+    const { locales, output } = options;
+    const baseLocale = options.primaryLanguage || locales[0] || 'en';
+    if (typeof output !== 'string') {
+        console.log('⚠️  Skipping inlang setup: extract.output is a function, so the file layout cannot be derived automatically. Create project.inlang/settings.json manually (see https://inlang.com/m/3i8bor92/plugin-inlang-i18next).');
+        return;
+    }
+    // Normalize Windows separators (heuristic-detected templates may be built
+    // with path.join) — settings.json patterns must be POSIX for portability.
+    // {{lng}} is a supported alias for {{language}}.
+    const template = output.replace(/\\/g, '/').replace(/\{\{lng\}\}/g, '{{language}}');
+    if (!template.endsWith('.json')) {
+        console.log('⚠️  Skipping inlang setup: the inlang i18next plugin supports JSON resource files only, but extract.output points to non-JSON files.');
+        return;
+    }
+    const settingsDir = resolve(process.cwd(), 'project.inlang');
+    const settingsPath = resolve(settingsDir, 'settings.json');
+    if (await fileExists(settingsPath)) {
+        console.log('ℹ️  project.inlang/settings.json already exists — leaving it untouched.');
+    }
+    else {
+        const pathPattern = template.includes('{{namespace}}')
+            ? await deriveNamespacedPathPattern(template, baseLocale, options.defaultNS)
+            : toInlangPattern(template);
+        const settings = {
+            $schema: 'https://inlang.com/schema/project-settings',
+            baseLocale,
+            locales,
+            modules: [INLANG_PLUGIN_MODULE],
+            'plugin.inlang.i18next': { pathPattern },
+        };
+        await mkdir(settingsDir, { recursive: true });
+        await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+        console.log(`✅ inlang project created at: ${settingsPath}`);
+        console.log('   Your i18next JSON files stay the single source of truth — inlang tools read and write them directly.');
+        console.log(`   • Sherlock (VS Code): install the recommended "${SHERLOCK_EXTENSION_ID}" extension`);
+        console.log('   • Fink (web editor for translators): https://fink.inlang.com');
+        console.log('   • Paraglide (compiled i18n): npx @inlang/paraglide-js compile --project ./project.inlang');
+    }
+    await recommendSherlockExtension();
+}
+/**
+ * Converts an i18next-cli output template into an inlang `pathPattern`:
+ * `{{language}}` becomes `{locale}`, and relative paths are prefixed with
+ * `./` as required by the plugin's settings schema (which also permits
+ * `../`-relative and absolute paths, so those pass through unchanged).
+ */
+function toInlangPattern(template) {
+    const pattern = template.replace(/\{\{language\}\}/g, '{locale}');
+    if (pattern.startsWith('./') || pattern.startsWith('../') || pattern.startsWith('/')) {
+        return pattern;
+    }
+    return `./${pattern}`;
+}
+/**
+ * Builds the namespaced (object) form of `pathPattern` by discovering the
+ * project's namespaces from the existing resource files of the primary
+ * language. Falls back to the default namespace when no files exist yet
+ * (e.g. `init` ran before the first `extract`).
+ */
+async function deriveNamespacedPathPattern(template, baseLocale, defaultNS) {
+    const namespaces = await discoverNamespaces(template, baseLocale);
+    if (namespaces.length === 0) {
+        namespaces.push(typeof defaultNS === 'string' ? defaultNS : 'translation');
+    }
+    const pathPattern = {};
+    for (const ns of namespaces.sort()) {
+        pathPattern[ns] = toInlangPattern(template.replace(/\{\{namespace\}\}/g, ns));
+    }
+    return pathPattern;
+}
+/**
+ * Discovers namespace names by listing the directory entries that match the
+ * `{{namespace}}` segment of the output template, resolved for the primary
+ * language. Works for namespaces in the file name
+ * (`locales/en/{{namespace}}.json`) as well as in a directory segment
+ * (`locales/{{namespace}}/en.json`).
+ */
+async function discoverNamespaces(template, baseLocale) {
+    const resolved = template.replace(/\{\{language\}\}/g, baseLocale);
+    const segments = resolved.split('/');
+    const nsIndex = segments.findIndex(segment => segment.includes('{{namespace}}'));
+    if (nsIndex === -1)
+        return [];
+    const baseDir = resolve(process.cwd(), segments.slice(0, nsIndex).join('/'));
+    const [prefix, suffix = ''] = segments[nsIndex].split('{{namespace}}');
+    try {
+        const entries = await readdir(baseDir);
+        return entries
+            .filter(entry => entry.startsWith(prefix) &&
+            entry.endsWith(suffix) &&
+            entry.length > prefix.length + suffix.length)
+            .map(entry => entry.slice(prefix.length, entry.length - suffix.length));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Adds the Sherlock VS Code extension to `.vscode/extensions.json`
+ * recommendations. Creates the file when missing; otherwise merges into the
+ * existing one while preserving comments and formatting (JSONC-aware). Bails
+ * gracefully — with a notice, never an error — when the existing file cannot
+ * be parsed.
+ */
+async function recommendSherlockExtension() {
+    const extensionsPath = resolve(process.cwd(), '.vscode', 'extensions.json');
+    let text;
+    try {
+        text = await readFile(extensionsPath, 'utf-8');
+    }
+    catch {
+        // File doesn't exist yet — create it.
+    }
+    if (text === undefined || text.trim() === '') {
+        await mkdir(dirname(extensionsPath), { recursive: true });
+        await writeFile(extensionsPath, JSON.stringify({ recommendations: [SHERLOCK_EXTENSION_ID] }, null, 2) + '\n');
+        console.log('✅ Added the Sherlock extension to .vscode/extensions.json recommendations.');
+        return;
+    }
+    const errors = [];
+    const current = parse(text, errors, { allowTrailingComma: true });
+    if (errors.length > 0 || typeof current !== 'object' || current === null || Array.isArray(current)) {
+        console.log('⚠️  Could not parse .vscode/extensions.json — please add "inlang.vs-code-extension" to its recommendations manually.');
+        return;
+    }
+    const recommendations = Array.isArray(current.recommendations) ? current.recommendations : [];
+    const alreadyRecommended = recommendations.some(entry => typeof entry === 'string' && entry.toLowerCase() === SHERLOCK_EXTENSION_ID);
+    if (alreadyRecommended)
+        return;
+    const formattingOptions = { insertSpaces: true, tabSize: 2, eol: '\n' };
+    const edits = Array.isArray(current.recommendations)
+        // Append to the existing array (preserves comments and formatting).
+        ? modify(text, ['recommendations', recommendations.length], SHERLOCK_EXTENSION_ID, { isArrayInsertion: true, formattingOptions })
+        // No recommendations key yet — add one.
+        : modify(text, ['recommendations'], [SHERLOCK_EXTENSION_ID], { formattingOptions });
+    await writeFile(extensionsPath, applyEdits(text, edits));
+    console.log('✅ Added the Sherlock extension to .vscode/extensions.json recommendations.');
+}
+async function fileExists(path) {
+    try {
+        await readFile(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+
+export { scaffoldInlangProject };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18next-cli",
-  "version": "1.62.0",
+  "version": "1.63.0",
   "description": "A unified, high-performance i18next CLI.",
   "type": "module",
   "bin": {

package/types/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAqBnC,QAAA,MAAM,OAAO,SAAgB,CAAA;AA2c7B,OAAO,EAAE,OAAO,EAAE,CAAA"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAqBnC,QAAA,MAAM,OAAO,SAAgB,CAAA;AA4c7B,OAAO,EAAE,OAAO,EAAE,CAAA"}

package/types/init.d.ts

@@ -27,5 +27,6 @@
  */
 export declare function runInit(options?: {
     ci?: boolean;
+    inlang?: boolean;
 }): Promise<void>;
 //# sourceMappingURL=init.d.ts.map

package/types/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAoEA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,OAAO,CAAE,OAAO,GAAE;IAAE,EAAE,CAAC,EAAE,OAAO,CAAA;CAAO,iBAsL5D"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAqEA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,OAAO,CAAE,OAAO,GAAE;IAAE,EAAE,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,iBAsM9E"}

package/types/instrumenter/core/instrumenter.d.ts

@@ -33,7 +33,8 @@ export declare function isProjectUsingTypeScript(): Promise<boolean>;
  * Searches the common locations (`src/` and the project root) for an existing
  * i18n initialization file.
  *
- * @returns The path of the first init file found (relative to cwd), or null.
+ * @returns The path of the first init file found (relative to cwd, native
+ *          platform separators), or null.
  */
 export declare function findExistingI18nInitFile(): Promise<string | null>;
 /**

package/types/instrumenter/core/instrumenter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instrumenter.d.ts","sourceRoot":"","sources":["../../../src/instrumenter/core/instrumenter.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,eAAe,EAA6B,sBAAsB,EAAiE,MAAM,gBAAgB,CAAA;AAU1N;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,mBAAmB,EAC5B,MAAM,GAAE,MAA4B,GACnC,OAAO,CAAC,sBAAsB,CAAC,CAoNjC;AAivCD;;GAEG;AACH,wBAAsB,mBAAmB,IAAK,OAAO,CAAC,OAAO,CAAC,CAU7D;AAID,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,aAAa,GAAG,MAAM,GAAG,SAAS,CAAA;AA6B/E;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,IAAK,OAAO,CAAC,kBAAkB,CAAC,CA8B7E;AAED;;GAEG;AACH,wBAAsB,wBAAwB,IAAK,OAAO,CAAC,OAAO,CAAC,CAOlE;AAwBD;;;;;GAKG;AACH,wBAAsB,wBAAwB,IAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWxE;AAmYD;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,eAAe,EAAE,EAC7B,MAAM,EAAE,oBAAoB,EAC5B,SAAS,CAAC,EAAE,MAAM,EAClB,MAAM,GAAE,MAA4B,GACnC,OAAO,CAAC,IAAI,CAAC,CAoDf"}
+{"version":3,"file":"instrumenter.d.ts","sourceRoot":"","sources":["../../../src/instrumenter/core/instrumenter.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,eAAe,EAA6B,sBAAsB,EAAiE,MAAM,gBAAgB,CAAA;AAU1N;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,mBAAmB,EAC5B,MAAM,GAAE,MAA4B,GACnC,OAAO,CAAC,sBAAsB,CAAC,CAoNjC;AAivCD;;GAEG;AACH,wBAAsB,mBAAmB,IAAK,OAAO,CAAC,OAAO,CAAC,CAU7D;AAID,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,aAAa,GAAG,MAAM,GAAG,SAAS,CAAA;AA6B/E;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,IAAK,OAAO,CAAC,kBAAkB,CAAC,CA8B7E;AAED;;GAEG;AACH,wBAAsB,wBAAwB,IAAK,OAAO,CAAC,OAAO,CAAC,CAOlE;AAwBD;;;;;;GAMG;AACH,wBAAsB,wBAAwB,IAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWxE;AAmYD;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,eAAe,EAAE,EAC7B,MAAM,EAAE,oBAAoB,EAC5B,SAAS,CAAC,EAAE,MAAM,EAClB,MAAM,GAAE,MAA4B,GACnC,OAAO,CAAC,IAAI,CAAC,CAoDf"}

package/types/utils/inlang-scaffold.d.ts

@@ -0,0 +1,28 @@
+export interface InlangScaffoldOptions {
+    /** All project locales (the first one is used as `baseLocale` unless `primaryLanguage` is set). */
+    locales: string[];
+    /** The base/source locale. Defaults to the first entry of `locales`. */
+    primaryLanguage?: string;
+    /** The `extract.output` template, e.g. `public/locales/{{language}}/{{namespace}}.json`. */
+    output: string | ((language: string, namespace?: string) => string);
+    /** Default namespace used as fallback when no resource files exist yet (default: 'translation'). */
+    defaultNS?: string | false;
+}
+/**
+ * Scaffolds an inlang project (`project.inlang/settings.json`) next to the
+ * i18next configuration so that inlang tooling (Sherlock VS Code extension,
+ * Fink editor, Paraglide compiler) operates on the EXISTING i18next JSON
+ * files. The i18next files remain the single source of truth — the scaffold
+ * is just the adapter.
+ *
+ * Behavior:
+ * - Derives `plugin.inlang.i18next.pathPattern` from the `extract.output`
+ *   template: the namespaced object form when the template contains a
+ *   `{{namespace}}` placeholder (namespaces are discovered from the files of
+ *   the primary language), the plain string form otherwise.
+ * - Never overwrites an existing `project.inlang/settings.json`.
+ * - Adds the Sherlock extension to `.vscode/extensions.json` recommendations
+ *   (creating or comment-preservingly merging the file).
+ */
+export declare function scaffoldInlangProject(options: InlangScaffoldOptions): Promise<void>;
+//# sourceMappingURL=inlang-scaffold.d.ts.map

package/types/utils/inlang-scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inlang-scaffold.d.ts","sourceRoot":"","sources":["../../src/utils/inlang-scaffold.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,qBAAqB;IACpC,mGAAmG;IACnG,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,4FAA4F;IAC5F,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC,CAAA;IACnE,oGAAoG;IACpG,SAAS,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;CAC3B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgD1F"}