Getting Started

How globalize.now works — overview

globalize.now makes your app multilingual in four steps. Already have i18n set up? If your codebase already has locale files and an i18n library configured, skip steps 1–3 and jump straight to Step 4. Run npx globalize-skills then "Set up globalize for this project" to connect your existing setup to auto-translate on push. Free to start. Setup (steps 1–3) is free. You get a €5 translation credit when you sign up — enough to translate a small-to-medium app across multiple languages before you need to add billing. Step 1 — Install skills Run one command in your terminal from your project root: npx globalize-skills This installs skill files into your AI coding agent (Claude Code, Cursor, or VS Code Copilot/Codex). The agent now knows how to handle i18n. Nothing in your codebase changes yet. Step 2 — Set up localization Use Claude Opus for this step and Step 3. It handles messy, vibe-coded codebases reliably. Smaller models tend to miss strings or generate inconsistent key names. Open your AI coding agent and type: Set up localization for my project The agent scans your repo, detects your framework, installs the right i18n library, and creates the locale file structure. Takes 3–8 minutes for a small app. Step 3 — Convert your app Type in your agent: Convert my app The agent rewrites your components to replace hardcoded strings with translation keys, and generates locale files for every language you selected. Roughly 30 minutes for a small-to-medium app — don't cancel the session mid-way. Which mode? When prompted, choose unguided — it makes sensible decisions automatically. Use guided only if you have strong opinions about key naming or want to watch every step. Step 4 — Connect your repo Log in to globalize.now, connect your GitHub or GitLab repo, and enable auto-translate. From this point on, every time you push new code, globalize.now detects new strings, translates them, and opens a pull request with updated locale files. You review and merge — no other manual steps, ever. What you get at the end - All UI strings extracted and translated into your chosen languages - Locale files committed to your repo (you own the files — no vendor lock-in) - A language switcher in your app - Automatic sync on every future push Verify it worked After setup, confirm the output looks right before you call it done. See the verify setup article. Where to go next - Before you start — what to expect - What does globalize.now actually do to your code? - What project types and frameworks are supported?

Before you start: what to expect

Three things to know before you run the first command: what it will do to your code, how long it takes, and how to set up your repo. Create a branch first Always start on a fresh branch. Setup and conversion make significant changes to your codebase — rewrites component files, adds library config, creates locale files, may touch your root layout. You want all of this isolated from main so you can review the diff and merge when you're satisfied. git checkout -b feat/i18n-setup git push -u origin feat/i18n-setup Then push your latest changes so globalize.now can read them: git status # confirm nothing uncommitted git push # push any local commits Connect globalize.now to this branch. If you run setup directly on main, all agent changes go straight to your main branch with no staging area. How long it takes | Step | Typical time | | ------------------------------------ | ------------- | | npx globalize-skills install | < 1 minute | | Set up localization for my project | 3–8 minutes | | Convert my app | 15–45 minutes | | Connect repo in globalize.now | 2–5 minutes | | First translation job | 2–10 minutes | Total: roughly 30 minutes for a small-to-medium app. Large codebases (100+ components) take longer. Don't cancel mid-conversion The Convert my app step can take 30–45 minutes on a large codebase. This is normal. Do not cancel the session mid-way — interrupting it leaves your codebase in a partial state. Check your editor's source control panel to confirm files are still being modified if you're unsure it's working. If you need to scope the conversion, tell the agent upfront: Convert only the /src/components directory first After setup is complete Review the diff, test your app locally, then open a pull request from your branch to main. Merge when you're happy with the output. Future runs (adding new strings) are much faster — the agent only processes what's changed.

What does globalize.now actually do to your code?

Two questions most users have before starting: what does the install command do, and will it break anything? What npx globalize-skills does It installs skill files into your AI coding agent. That's it — nothing in your codebase changes. The command downloads markdown files into your project's .claude/skills/ directory. These are plain text instructions that tell the agent how to handle i18n: which library to use, how to extract strings, how to name keys, how to structure locale files. When prompted, pick the preset — it selects the right combination for your stack automatically. After the install, the globalize.now website shows you three prompts to copy into your agent: Set up localization for my project Convert my app Set up globalize for this project These are things you type into your agent — not output the agent generates. Will it change your code permanently? No. Every change goes into the branch you created before starting — not directly to main. When you run Set up localization for my project and Convert my app, the agent modifies files in your local branch. It rewrites components to use translation keys instead of hardcoded strings, adds locale files, and updates configuration. All of this happens in a branch. At the end, you review a diff like any other pull request. You can inspect every change, test locally, and only merge when satisfied. What if something looks wrong? - Don't merge. Close the branch and nothing reaches main. - Revert the branch. git checkout main && git branch -D feat/i18n-setup. Main is untouched. - Fix specific files. Edit them in the branch before merging. The agent doesn't force-push to main — that's an explicit design constraint. What about auto-translate? When globalize.now translates your strings on every push, it creates a pull request with updated locale files. Same model — you review it, you merge it. The app never commits directly to main. Where do the skill files go? Skills install locally to .claude/skills/ in your project. Project-scoped — one repo doesn't affect another. They're plain text files you can read in any editor. If you want to review them before installing, clone the skills repo from GitHub and copy the files manually.

You're set up! here's how to verify it worked

The setup is done. Here's what success looks like and how to confirm everything is working before you call it done. What your repo should look like now After Convert my app completes, your repo should contain: New files added: /messages (or /locales — depends on your i18n library) en.json ← your source strings, all extracted es.json ← placeholder file, empty until translated de.json fr.json Modified files: - Your component files — hardcoded strings replaced with t("checkout.submit") calls - Root layout or app entry point — i18n provider wrapped - i18n library config file — new, auto-generated If you don't see locale files in your repo, the conversion step didn't complete. See the setup stalled troubleshooting article and re-run. Check that the conversion looks right Open a few component files and confirm the strings were extracted. Look for: - t("some.key") calls replacing what used to be inline text - Consistent key naming (e.g. checkout.submit_button, not a mix of styles) - The en.json file contains real readable strings, not garbled output If you see hardcoded strings still in the file, the agent missed them. Run Convert my app again — it will pick up what was missed without duplicating work. Test the language switcher locally 1. Run your dev server: npm run dev (or your usual command) 2. Open the app in your browser 3. Switch languages using the switcher 4. Confirm UI text changes — it won't be translated yet (just the keys), but switching shouldn't break the app If the switcher isn't visible, ask your agent: Add a simple language switcher to my app If switching languages crashes the app, chat with us at globalize.now — it usually means the i18n provider wasn't wrapped correctly during setup. Trigger your first translation push git add . git commit -m "test: trigger first globalize.now translation" git push Within 2–5 minutes you should see a new pull request from globalize.now with translated locale files. Open the PR and check that the locale files contain actual translated text and the languages you selected are all present. If no PR appears after 10 minutes, check your globalize.now dashboard for the job status. Merge and you're done Review the translation PR, merge it, and your app is now serving real translated content. From this point on, every push you make automatically triggers the translation pipeline. No further manual steps.