Troubleshooting

The skills install command isn't working

npx skills add --all globalize-now/globalize-skills is the install command. It uses the open skills CLI to copy the globalize.now skills into your AI coding agent. Here's what to check if it doesn't work. No agent detected If the CLI can't find a supported agent, it asks which one to install to. Pick yours from the list, or skip the prompt by naming the agent directly: npx skills add globalize-now/globalize-skills -a claude-code Swap claude-code for cursor, codex, or github-copilot as needed. Where the skills land The install location depends on your agent: - Claude Code: .claude/skills/ - Cursor, Codex, GitHub Copilot: .agents/skills/ After a successful install you'll see the globalize.now skill folders there: globalize-guide, globalize-now-cli-setup, globalize-now-cli-use, and css-i18n. Start a fresh agent conversation so it picks them up. Permission or symlink errors By default the CLI symlinks the skills into your agent's directory. If your environment blocks symlinks (some Windows setups, locked-down corporate machines), force plain copies instead: npx skills add globalize-now/globalize-skills --copy If you hit a write-permission error, make sure you have write access to the project directory, or install to your user directory with -g. Node.js The skills CLI runs through npx, which needs Node.js. If npx itself errors, confirm Node is installed with node -v. Node 18 or newer is recommended. Manual install You can always copy a skill in by hand. Browse globalize-now/globalize-skills on GitHub and copy the folder you need into your agent's skills directory, for example: cp -r skills/globalize-guide /path/to/your/project/.claude/skills/globalize-guide The skill is available the next time you start an agent conversation. Still stuck? Open a chat with support and share your Node.js version (node -v), your agent (Claude Code, Cursor, Codex), and the exact error. We'll get you unblocked.

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 skills add --all globalize-now/globalize-skills This re-installs the skill files and resets the agent's localization context. Step 2 — Re-ask for setup Set up i18n for my project The globalize-guide skill rescans from the current state of the repo and resumes the journey. It won't duplicate work already completed, it picks up where the code is. New translation keys merge back into your locale files, and keys from the previous partial run are preserved. Step 3 — 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"

Translation job errors and 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, ask it to finish wrapping the strings it missed: wrap the remaining hardcoded strings 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.

The setup plan looks bigger than expected

Before the globalize-guide skill changes anything, it shows you a plan: which library it will add, which files it will touch, whether it will add a language switcher. You approve that plan before any code changes. If the plan looks bigger than you expected, here's how to read it and rein it in. When the plan proposes a full setup on an app that already has i18n If your repo already uses next-intl, react-i18next, i18next, or @lingui/*, the agent should detect that and propose connect-only (sync) mode, not a fresh build. If the plan instead proposes installing a library, adding a language switcher, and rewriting many components, the detection missed your existing setup. Don't approve that plan. Tell the agent directly: This project already uses [your i18n library]. Connect it in sync mode instead of setting up i18n from scratch. The agent re-inspects, treats your project as already-internationalized, and switches to connecting your existing locale files for translation on push. Nothing gets rebuilt. If you already approved a plan that did too much It's recoverable. Discard the changes locally: git restore . git clean -fd If you committed but didn't push: git reset --hard HEAD~1 Then re-run setup and, when the plan appears, correct it as above before approving. What connect-only (sync) mode looks like For an app that already has i18n, the agent does not touch your code at setup time. It: 1. Reads your existing locale files 2. Connects your GitHub or GitLab repo 3. Watches for pushes to main 4. Opens a PR with translated locale files when new keys appear No language switcher. No file moves. No restructure. The first sign it's working is a PR on your next push. Tell us if detection keeps missing If the agent repeatedly fails to detect your existing setup, send us your package.json dependencies and your locale folder layout through the feedback widget (bottom-right on any globalize.now page). We use it to improve detection. Related - What project types and frameworks are supported — detection signals and what sync mode does - What globalize.now does to your code — the branch-safety model