i18next-cli 1.61.1 → 1.63.0

package/dist/esm/index.js

@@ -11,3 +11,7 @@ export { runRenameKey } from './rename-key.js';
 export { runInstrumenter, writeExtractedKeys } from './instrumenter/core/instrumenter.js';
 import './utils/jsx-attributes.js';
 import 'magic-string';
+export { runLocalize } from './localize/localize.js';
+import 'node:fs/promises';
+import 'node:path';
+export { AGENT_PROMPT } from './localize/agent-prompt.js';

package/dist/esm/init.js

@@ -1,58 +1,11 @@
 import inquirer from 'inquirer';
 import { writeFile, readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
-import { execa } from 'execa';
 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';
-/** Rough 8-4-4-4-12 hex UUID shape — not strict (locize project IDs may evolve). */
-const UUID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-/**
- * Opens the given URL in the user's default browser using the platform-native command.
- * Returns true on success, false if there's nowhere to open one (CI, headless Linux)
- * or if spawning the command failed.
- */
-async function openBrowser(url, opts = {}) {
-    // Short-circuit: no point spawning a browser-opener in CI or headless Linux.
-    if (opts.ci || process.env.CI === 'true')
-        return false;
-    const isWSL = !!process.env.WSL_DISTRO_NAME;
-    if (process.platform === 'linux' && !isWSL &&
-        !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) {
-        return false;
-    }
-    try {
-        if (process.platform === 'darwin') {
-            await execa('open', [url], { stdio: 'ignore' });
-        }
-        else if (process.platform === 'win32') {
-            // `start` is a cmd.exe builtin; the empty "" is the window-title slot
-            await execa('cmd', ['/c', 'start', '""', url], { stdio: 'ignore' });
-        }
-        else if (isWSL) {
-            // WSL: try the wslu / wsl-open shims that bridge to the Windows side
-            // before falling back to xdg-open (which usually isn't installed there).
-            try {
-                await execa('wslview', [url], { stdio: 'ignore' });
-            }
-            catch {
-                try {
-                    await execa('wsl-open', [url], { stdio: 'ignore' });
-                }
-                catch {
-                    await execa('xdg-open', [url], { stdio: 'ignore' });
-                }
-            }
-        }
-        else {
-            await execa('xdg-open', [url], { stdio: 'ignore' });
-        }
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
+const LOCIZE_SIGNUP_URL = 'https://www.locize.app/register?from=i18next_cli__init-wizard';
 /**
  * Determines if the current project is configured as an ESM project.
  * Checks the package.json file for `"type": "module"`.
@@ -202,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') {
@@ -210,29 +171,7 @@ async function runInit(options = {}) {
         if (!opened) {
             console.log(`\n👉 Open this URL manually: ${LOCIZE_SIGNUP_URL}\n`);
         }
-        const credentials = await inquirer.prompt([
-            {
-                type: 'input',
-                name: 'projectId',
-                message: 'Locize Project ID (e.g. 4eeb5ce0-a7a7-453f-8eb3-078f6eeb56fe):',
-                validate: (input) => input.trim().length > 0 || 'Project ID cannot be empty.',
-                filter: (input) => input.trim(),
-            },
-            {
-                type: 'password',
-                name: 'apiKey',
-                message: 'Locize API key (needed for saveMissing / auto-publish / sync during development; leave empty to skip and add later via env var):',
-                filter: (input) => input.trim(),
-            },
-        ]);
-        if (!UUID_SHAPE.test(credentials.projectId)) {
-            console.log("⚠️  The Project ID doesn't look like a UUID (8-4-4-4-12 hex). It will still be written — double-check it in your Locize project settings.");
-        }
-        // API keys come in multiple shapes (UUID, `lz_pat_…`, `lz_api_…`, etc.) —
-        // treat them as opaque; no client-side format check.
-        locizeConfig = { projectId: credentials.projectId };
-        if (credentials.apiKey)
-            locizeConfig.apiKey = credentials.apiKey;
+        locizeConfig = await promptLocizeCredentials();
     }
     const isTypeScript = answers.fileType.includes('TypeScript');
     const isEsm = await isEsmProject();
@@ -317,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

@@ -1460,6 +1460,25 @@ const I18N_INIT_FILE_NAMES = [
     'i18n/index.ts', 'i18n/index.js', 'i18n/index.mjs',
     'i18next/index.ts', 'i18next/index.js'
 ];
+/**
+ * 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, native
+ *          platform separators), or null.
+ */
+async function findExistingI18nInitFile() {
+    const cwd = process.cwd();
+    const searchDirs = ['src', '.'];
+    for (const dir of searchDirs) {
+        for (const name of I18N_INIT_FILE_NAMES) {
+            if (await fileExists(join(cwd, dir, name))) {
+                return join(dir, name);
+            }
+        }
+    }
+    return null;
+}
 /**
  * Computes a POSIX-style relative path from the init-file directory to the
  * output template path (which still contains {{language}} / {{namespace}} placeholders).
@@ -1485,13 +1504,8 @@ function buildDynamicImportPath(outputTemplate, initDir) {
 async function ensureI18nInitFile(hasReact, hasTypeScript, config, logger, usesI18nextT) {
     const cwd = process.cwd();
     // Check for existing init files in common locations
-    const searchDirs = ['src', '.'];
-    for (const dir of searchDirs) {
-        for (const name of I18N_INIT_FILE_NAMES) {
-            if (await fileExists(join(cwd, dir, name))) {
-                return null; // Init file already exists
-            }
-        }
+    if (await findExistingI18nInitFile()) {
+        return null; // Init file already exists
     }
     // Check if i18next.init() is called anywhere in the source
     try {
@@ -1939,4 +1953,4 @@ async function runInstrumentOnResultPipeline(filePath, initialCandidates, plugin
     return candidates;
 }
 
-export { runInstrumenter, writeExtractedKeys };
+export { detectProjectEnvironment, findExistingI18nInitFile, isProjectUsingReact, isProjectUsingTypeScript, runInstrumenter, writeExtractedKeys };

package/dist/esm/localize/agent-prompt.js

@@ -0,0 +1,47 @@
+/**
+ * Copy-paste prompt for AI coding agents (Claude Code, Cursor, …) that walks
+ * an agent through the same steps the `localize` command orchestrates.
+ *
+ * This constant is the single source of truth — it is printed by
+ * `i18next-cli localize --print-agent-prompt` and mirrored in the README.
+ * A test guards that it mentions every orchestrated command, so flow changes
+ * that forget this prompt fail CI.
+ */
+const AGENT_PROMPT = `You are localizing this app with i18next + Locize. Execute these steps in order,
+verifying each before continuing. Use \`npx i18next-cli\` for all commands.
+
+1. Detect: confirm this is a React/Next.js project (check package.json).
+   - If Vue/Svelte: install a stack plugin (\`i18next-cli-vue\` /
+     \`i18next-cli-plugin-svelte\`) and add it to the \`plugins\` array of
+     i18next.config.ts, or write one via the plugin hooks
+     (instrumentOnLoad/onLoad) instead of wrapping strings manually.
+   - If the app uses inlang Paraglide (\`@inlang/paraglide-js\`), STOP —
+     instrumenting i18next calls would conflict; ask the user how to proceed.
+2. Config: if no i18next.config.{ts,js} exists, run \`npx i18next-cli init\`
+   and answer the prompts (pick Locize as backend if the user wants managed
+   translations and AI auto-translate).
+3. Instrument: run \`npx i18next-cli instrument --dry-run\` and review the
+   planned changes; then \`npx i18next-cli instrument\` to apply. Inspect the
+   git diff carefully: fix any t() wrapping inside Next.js *server components*
+   (add 'use client' or refactor to a server-side t() pattern). Commit.
+4. Extract: run \`npx i18next-cli extract\`. Verify the locale JSON files were
+   written (check the extract.output path in the config).
+5. Locize: ask the user for LOCIZE_PROJECTID and LOCIZE_API_KEY (they create
+   the project at https://www.locize.app/register?from=i18next_cli__agent-prompt
+   — any write-capable API key works; the target languages from
+   i18next.config.ts are created automatically on the first sync.
+   Auto-translation and quality estimation are enabled by default for new
+   projects; translations run once the project is subscribed or an AI/MT
+   provider is configured). Export both as environment variables.
+6. Translate & deliver:
+   \`npx i18next-cli locize-sync --auto-translate true\`
+   then \`npx i18next-cli locize-download\` to pull the AI translations, and
+   \`npx i18next-cli status\` — confirm all languages are (near) 100%.
+   AI translation is asynchronous; if targets are still empty, wait a minute
+   and re-run locize-download.
+7. Optionally switch runtime loading to i18next-locize-backend (CDN delivery,
+   so translation fixes go live without redeploying). NEVER put the API key
+   in client-side code — the CDN only needs the project ID.
+`;
+
+export { AGENT_PROMPT };

package/dist/esm/localize/detect.js

@@ -0,0 +1,85 @@
+import { readFile, access } from 'node:fs/promises';
+import { join } from 'node:path';
+
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readPackageDeps() {
+    try {
+        const content = await readFile(join(process.cwd(), 'package.json'), 'utf-8');
+        const packageJson = JSON.parse(content);
+        return { ...packageJson.dependencies, ...packageJson.devDependencies };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Detects the project stack relevant to the `localize` orchestrator:
+ * frontend framework, i18next presence, an existing i18n init file,
+ * Next.js App Router usage and inlang Paraglide usage.
+ *
+ * All checks are `process.cwd()`-relative (run from the package directory
+ * in monorepos).
+ *
+ * @param findInitFile - locator for an existing i18n init file
+ *                       (injected to reuse the instrumenter's implementation)
+ */
+async function detectStack(findInitFile) {
+    const deps = await readPackageDeps();
+    const has = (name) => !!deps[name];
+    let framework = 'unknown';
+    if (has('next'))
+        framework = 'next';
+    else if (has('react') || has('react-i18next'))
+        framework = 'react';
+    else if (has('vue') || has('nuxt'))
+        framework = 'vue';
+    else if (has('svelte') || has('@sveltejs/kit'))
+        framework = 'svelte';
+    else if (has('@angular/core'))
+        framework = 'angular';
+    const cwd = process.cwd();
+    const hasAppRouter = framework === 'next' &&
+        (await pathExists(join(cwd, 'app')) || await pathExists(join(cwd, 'src', 'app')));
+    const hasParaglide = has('@inlang/paraglide-js') || await pathExists(join(cwd, 'project.inlang'));
+    return {
+        framework,
+        hasI18next: has('i18next') || has('react-i18next'),
+        hasTypeScript: await pathExists(join(cwd, 'tsconfig.json')),
+        initFile: await findInitFile(),
+        hasAppRouter,
+        hasParaglide,
+    };
+}
+/** File extensions associated with frameworks the instrumenter cannot transform natively. */
+const STACK_EXTENSIONS = {
+    vue: ['.vue', 'vue'],
+    svelte: ['.svelte', 'svelte'],
+};
+/**
+ * Checks whether a configured plugin covers the detected stack's file
+ * extension via `instrumentExtensions` or `lintExtensions` — in which case
+ * the instrument/extract runners can process the stack's files through the
+ * plugin hooks and `localize` runs the full flow.
+ */
+function hasStackPlugin(config, framework) {
+    const extensions = STACK_EXTENSIONS[framework];
+    if (!extensions || !config.plugins?.length)
+        return false;
+    return config.plugins.some((plugin) => {
+        const declared = [
+            ...(plugin.instrumentExtensions || []),
+            ...(plugin.lintExtensions || []),
+        ];
+        return declared.some(ext => extensions.includes(ext));
+    });
+}
+
+export { detectStack, hasStackPlugin };