Troubleshooting

npx globalize-skills failed to install

npx globalize-skills runs partway through then crashes before installing. Two known causes: a Cursor legacy rules file conflict (any OS), and PowerShell execution policy on Windows. Cursor legacy rules file (any OS) If you see this error: EEXIST: file already exists, mkdir '/path/to/your-project/.cursor/rules' You're using Cursor's old single-file rules format, where .cursor/rules is a file. Cursor moved to a directory format (.cursor/rules/*.mdc), and our installer expects the directory layout. The mkdir call fails because a file already exists at that path. Fix — convert the file to a directory: mv .cursor/rules .cursor/rules.legacy.bak npx globalize-skills The installer creates .cursor/rules/ as a directory. Once the install completes, you can either delete .cursor/rules.legacy.bak or migrate its contents into a new .mdc file inside .cursor/rules/ per Cursor's docs. Alternative — let Cursor handle it. Open Cursor and prompt the agent: Run npx globalize-skills and figure out why it's blocked The agent can reason about the file vs directory mismatch and resolve it without you touching the filesystem. Windows / PowerShell npx globalize-skills can fail on Windows, particularly in PowerShell, due to execution policy restrictions or Node.js path issues. Workaround: manual install via zip 1. Go to globalize.now and download the skills zip from the setup page 2. Extract the zip 3. Copy the extracted folder into your project at .claude/skills/ Your project directory should look like: your-project/ .claude/ skills/ i18n-guide.md lingui.md next-intl.md ... src/ package.json 4. Continue with setup as normal — open Claude Code, prompt Set up localization for my project Why this happens: PowerShell's default execution policy blocks unsigned scripts, which affects how npx resolves and runs packages in some configurations. Known issue, fix in progress. Alternative — use CMD instead of PowerShell: Run npx globalize-skills in Windows Command Prompt (cmd.exe) rather than PowerShell. Works in most cases. Still not working? Open a chat with support and share: - Your Node.js version (node -v) - Your npm version (npm -v) - The exact error message you're seeing We'll help you get unstuck.

Setup stalled or producing unexpected output

If your agent is going off-script — writing long explanations instead of making changes, proposing the wrong i18n library, asking questions the skills should already know — it's likely lost the skills context. This is recoverable. How to recognize it - The agent writes long explanations instead of making code changes - It proposes a different i18n library than the one selected - It starts asking questions the skills should already know how to answer - Output looks inconsistent with earlier steps in the same session Recovery steps Step 1 — Refresh the skills npx globalize-skills Re-installs the skill files and resets the agent's localization context. Step 2 — Re-issue the setup prompt Set up localization for my project The agent rescans from the current state of the repo. It won't duplicate work already completed — it picks up where the code is. Step 3 — Re-issue the conversion prompt Convert my app New translation keys merge back into your locale files. Keys from the previous partial run are preserved. Step 4 — Verify Use the verification steps to confirm the output looks right before calling it done. The conversion step is just taking a long time If the conversion step seems to be running for 30–45 minutes without obvious activity, that's normal on a large codebase. Don't cancel the session. Check your editor's source control panel — if files are still being modified, it's working. Interrupting mid-conversion leaves your codebase in a partial state. Prevention - Run setup steps in order, don't skip ahead - Keep your session focused — avoid mixing i18n work with other code changes in the same agent context - On very large repos (100+ components), break conversion into batches: "Convert only the /src/components directory first"

Unexpected translation jobs, re-scan errors, and job failures

Need help fast? Chat with us at globalize.now — hit the chat icon on any page. Re-scan shows "no i18n files detected" If you trigger a re-scan and the globalize.now app shows "no i18n files detected", the job may already be running in the background — the UI is just not reflecting it yet. There's a timing gap between when a job starts and when the app's status updates. The message can appear briefly while the job is processing. It doesn't mean the scan failed. What to do: Wait a few minutes and refresh the page. Check your GitHub repo for a new pull request — that's the clearest sign the job ran successfully. If the issue persists after 10+ minutes, chat with us at globalize.now. Job shows "Completed" but contains an error If a translation job shows "Completed" status but you see a failed error when you click into it, the job likely partially succeeded — the strings were translated, but something went wrong at the commit or PR creation step. What to do: 1. Check your GitHub repo first. If a PR exists with the translated locale files, the translation itself worked. The error may be related to the repo connection, not the translation. 2. If no PR exists, start a chat at globalize.now with your repo name and job ID. Common cause: A GitHub authentication mismatch — for example, connecting globalize.now with one GitHub email while your repo is under a different account. Check that the GitHub account you connected has write access to the repo. Translation job started automatically without my approval If a translation job started without you explicitly triggering it, this is a known UX issue we're actively working on. Currently, connecting your repo to globalize.now and enabling auto-translate can trigger an immediate translation run. How to avoid this going forward: Connect your repo but don't enable auto-translate until you're ready to start using billable translations. If you're on the free setup phase only (no billing connected), no translation job will run — only string extraction and locale file generation happen. If a job ran and you weren't expecting it: Check your billing dashboard to see the character count used. If it's unexpectedly high, chat with us at globalize.now — we'll review the job and credit your account if appropriate. What's coming: We're adding an explicit consent step before any billable action runs.

My translation PR looks wrong: what do I do?

The PR from globalize.now is the first time you see real output. If something looks off, here’s how to diagnose and fix it. Need help? Chat with us at globalize.now — hit the chat icon on any page. The translations are empty or contain key names instead of text If your locale files contain "" or still show key names like "checkout.submit": "checkout.submit" instead of translated text, the translation job didn’t run or failed silently. What to check: 1. Go to your globalize.now dashboard and look at the job that triggered this PR 2. If it shows an error, see the troubleshooting guide for unexpected translation jobs 3. If no job ran at all, confirm auto-translate is enabled in your project settings The translations sound wrong or unnatural AI translation quality varies by language pair and domain. - Wrong tone (too formal, too casual, wrong register): We can adjust the translation style for your project’s language pair. Chat with us at globalize.now with examples. - Idioms translated literally: Known limitation for some language pairs. Chat with us with specific examples. - Brand terms or product names translated incorrectly: You need a glossary of protected terms. Chat with us at globalize.now to add one. The PR is missing strings from my app If some strings are translated but others are still hardcoded, the conversion step missed them during setup. Common reasons: Strings inside config objects (form labels, error messages, toast notifications); strings in files changed after setup ran; strings in deeply nested component patterns. Fix: In your coding agent, run: Convert my app The agent re-scans for any strings it missed and adds them to your locale files without duplicating existing keys. Then push again to trigger a new translation job. Wrong strings are being translated If URL slugs, database field names, or internal identifiers are showing up as translated strings, the agent extracted the wrong content. Open your en.json file and remove the keys that shouldn’t be there. Then tell your agent: Do not translate strings in [path/to/file.ts] The PR changes files I didn’t expect Check what was changed — it’s usually locale files the agent placed in a non-standard location during setup. Review the diff, merge what’s correct, and move any files to the right location. If something looks completely wrong, close the PR without merging. Your main branch is untouched. Chat with us at globalize.now with the PR link and we’ll review what happened.