Using globalize.now

How does globalize.now fits into your stack

Two questions in one: what's the difference between globalize.now and your coding agent, and do you need both globalize.now and an i18n library? globalize.now vs your coding agent They work together. Your agent does the coding work. globalize.now gives it the instructions and handles the infrastructure. This works the same whether you're using Claude Code, Cursor, or Codex. Your AI coding agent reads your files, rewrites your components, generates locale files, and makes changes to your repo. Without globalize.now's skills, it improvises, and produces inconsistent key names, misses strings, or builds an architecture that breaks when you add new features. globalize.now does two things: 1. Installs skill files into your agent, the playbook it follows (which i18n library, how to name keys, how to handle RTL, plurals, and dynamic strings, how to structure locale files) 2. Runs translation infrastructure, the server-side jobs that translate your strings on every push and open PRs with updated locale files | Step | Who does it | | --- | --- | | npx skills add --all globalize-now/globalize-skills | globalize.now installs the skills | | Set up i18n for my project | the globalize-guide skill inspects your stack, plans, installs the library, wraps strings, generates locale files | | Connect globalize.now to my repo | the globalize-now-cli-setup skill connects your GitHub or GitLab repo | | Auto-translate on push | globalize.now's cloud infrastructure | | PR with updated locale files | globalize.now opens it, you review and merge | Do you need both globalize.now and an i18n library? Yes. They do different jobs. globalize.now handles infrastructure: scans your repo, generates translation keys and locale files, syncs on every Git push, keeps your locale files current. An i18n runtime library (next-intl, Lingui, react-i18next, i18next) handles the runtime: loads the right locale file for the current user, renders translated strings in the browser or server, handles pluralization and ICU message formatting, manages locale switching. globalize.now produces the locale files. The i18n library consumes them. Neither replaces the other. The setup step auto-detects your framework and installs the right library, you don't need to choose or configure it manually. | Framework | Library installed | | --- | --- | | Next.js (App Router) | next-intl | | Next.js (Pages Router) | i18next / react-i18next | | React + Vite / CRA | Lingui |

What project types and frameworks are supported?

Supported frameworks globalize.now works with React-based web apps. Current first-class support: | Framework | Status | |---|---| | Next.js (App Router) | ✅ Fully supported | | Next.js (Pages Router) | ✅ Fully supported | | React + Vite | ✅ Fully supported | | React + Create React App | ✅ Supported | | TanStack Router / Start | ✅ Supported | Note on Lovable: Lovable projects now use TanStack Router by default. This is fully supported. What's not in scope yet | Project type | Status | |---|---| | Blog and long-form content | ❌ Not supported — use a CMS or translate separately | | Chrome extensions | ❌ Not supported | | Vue / Svelte / Angular | ❌ Not supported yet | | Android / iOS native apps | ❌ Not supported | | WordPress / HubSpot CMS | ❌ Out of scope | | MCP server code | ❌ Not applicable | | Non-UI backend files | ❌ Skipped automatically | Blog content: globalize.now extracts UI strings from your app — buttons, labels, headings, form fields. It doesn't translate blog posts, documentation, or long-form content. If your project has both a web app and a blog, the tool handles the app and skips the blog. If your project includes components outside the supported scope, the agent focuses on the React web app and skips unsupported parts. It won't fail — it just won't touch those files. Corporate VPN and enterprise environments globalize.now does not work on corporate VPN or in enterprise environments that restrict external connections. The npx skills install step and the GitHub connection both require external network access. Workaround: Use a personal machine or a personal GitHub account. Monorepos globalize.now works on monorepos. The agent focuses on the React/Next.js parts and ignores non-web code. To scope the conversion: Convert only the /apps/web directory Partially internationalized codebases (L1 state) If your app already has an i18n library wired up — next-intl, react-i18next, i18next, or @lingui/* — globalize.now detects that on first run and skips the setup scaffold. No language switcher gets injected. Your existing locale file structure is preserved. The agent moves straight to sync mode. What we detect On first run, the agent reads your repo for any of: - package.json dependencies: next-intl, react-i18next, i18next, @lingui/core, @lingui/react, @lingui/macro, or any i18next-* plugin. - Locale folders: messages/ or locales/ at the repo root, or src/i18n/ with locale subfolders. - Existing locale files: en.json, en.po, en.yml, en.yaml, or whichever default-locale file your library expects. - Framework config: i18n.config.ts, next-intl middleware, lingui.config.js, or equivalents. If at least two of these are present, the project is treated as L1. What we skip in L1 mode - No string-extraction pass across your components - No new translation keys or restructuring of your existing key tree - No locale files scaffolded for languages you haven't already set up - No language-switcher component injected into your UI - No changes to your routing, middleware, or framework config What we do L1 mode is sync-only. Connect your GitHub repo, the agent reads your existing locale files to learn your key structure and source language, and on every push to main we diff the source-language file against the other locales. Missing translations get translated. A PR lands with the updated locale files. You review and merge. Mixed L1 (some keys, some hardcoded strings) Some apps are halfway through their i18n migration — t() calls on the new components, hardcoded strings on the old ones. The agent detects what's already wrapped and only extracts what isn't. Existing keys are preserved. Non-English source languages globalize.now uses whatever language your app is currently written in as the source. The agent auto-detects it. Detection edge case: If your site contains mixed-language content, the agent may occasionally mis-detect the primary source language. Correct it in your globalize.now project settings before translating. File formats globalize.now generates locale files in the format your i18n library expects: | Library | Output format | |---|---| | next-intl | JSON under /messages/ | | i18next | JSON under /public/locales/ | | LinguiJS | .po or JSON via Lingui CLI | You don't need to choose — the agent detects your library and generates the right format.

Where do my translations live?

In your repo. globalize.now generates locale files and commits them to your GitHub or GitLab branch — just like any other code change. You own the files. What the output looks like After setup, your repo will contain a locale directory with one JSON file per language: /locales en.json es.json de.json fr.json Or, if you're using next-intl: /messages en.json es.json The exact location and format depends on your i18n library. The agent sets this up correctly for your framework automatically. How updates work When you push new code with new UI strings, globalize.now detects the diff, translates only the new or changed strings, and opens a pull request with the updated locale files. The PR is just like any other — you can review, merge, or request changes. What if I merge a PR before translations are complete? Not a breaking change. If you merge your code PR while the translation PR is still open, your app won't break. globalize.now also monitors your main branch — it will detect the missing translation keys and open a new PR with just the missing translations. That said, the cleanest workflow is to wait for the translation PR, review it, and merge them together. This keeps your main branch fully translated at all times. Can I review or edit translations in the globalize.now app? Yes. The globalize.now app shows your translation output side-by-side with the source strings. You can review what was generated, edit specific translations that don't look right, and filter strings by language. Changes you make in the app are committed back to your locale files on the next sync. If you prefer editing directly in your repo, that works too — your locale files are plain JSON and any editor will open them. No vendor lock-in Your locale files are standard JSON. If you stop using globalize.now, your translations stay in your repo and keep working exactly as they do today. You can switch to any other translation tool or manage the files manually — nothing is locked to our platform. Do globalize.now servers store my translations? The translation process runs on our infrastructure, but the output is committed directly to your repo. We don't maintain a separate database of your translations. Your locale files are the source of truth, and they live in your codebase. Can I edit translations manually? Yes. Your locale files are plain JSON — you can edit them directly or use any translation editor. On the next push, globalize.now only touches strings it generated. Manual edits to existing keys are preserved.

How do I add more languages later?

You don't need to re-run the full setup. Adding a new language is a two-step process: add it to your globalize.now project settings, then trigger a push. Step 1 — Add the language in globalize.now 1. Log in to globalize.now 2. Go to your project settings → Languages 3. Click Add language and select the target language 4. Save Step 2 — Trigger a translation run Make a small push to your connected branch — even a one-line change is enough. globalize.now will detect that a new target language has been added and run a full translation of all existing strings in that language, opening a PR with the new locale file. git add . git commit -m "chore: add [language] to globalize.now" git push Within 2–10 minutes, a new PR will appear with the translated locale file for the added language. What about languages I want to remove? Go to project settings → Languages, remove the language, and save. The existing locale file stays in your repo — we don't delete files from your codebase. You can delete the locale file manually if you want to remove it, or leave it in place. How many languages can I have? No hard limit. Each language adds to your monthly translated-character count when new strings are pushed. Adding a new language to an existing app with many strings will use a larger character batch on the first run (translating the full back-catalogue). See the billing guide for how characters are counted.

Connect an AI agent with the Globalize MCP server

The Globalize MCP server lets an AI agent — Claude, Claude Code, Cursor, or any MCP-compatible client — work with your localization directly: create projects, add languages, translate files, and connect a GitHub repo, all from inside the tool you already use. A connected agent acts on your behalf, with your own permissions. The server endpoint is: https://api.globalize.now/mcp Pick your setup Claude.ai, ChatGPT, or any client with OAuth 1. Add Globalize as a custom connector using the URL above. 2. Sign in with your Globalize account when the client prompts you. No API key needed. 3. Tool calls run as you, in the organisation you last used in the dashboard. Claude Code Run this in your terminal, then run /mcp inside Claude Code and sign in through your browser: claude mcp add --transport http globalize https://api.globalize.now/mcp Cursor Add this to ~/.cursor/mcp.json. Cursor prompts you to sign in on first use: { "mcpServers": { "globalize": { "url": "https://api.globalize.now/mcp" } } } Any other MCP client Generate an API key on the MCP page in your dashboard (it's shown once), then configure a Streamable HTTP transport pointed at the endpoint with the header Authorization: Bearer <your key>. What the agent can do once connected - Set up projects — create a project, add or remove target languages, set project-wide context. - Connect your repository — link a GitHub repo, detect its framework and locale file patterns, and keep translations in sync on every push. - Translate files — hand the agent a locale file (JSON, ARB, PO, XLIFF, YAML, Android XML, or iOS .xcstrings) and get the translated versions back. - Keep quality consistent — manage a glossary and per-language style guides. What it does not do The MCP server does not internationalize your source code. It works on locale files, not your components. To turn hardcoded strings into translation keys, use the Globalize skills in your coding agent. If your agent is connected to the MCP, install them in one step by running the install-skills prompt (a slash command) instead of running npx skills add globalize-now/globalize-skills yourself. See "MCP, CLI, or skills — which one do I need?" Revoking access Remove the connector in your client, and revoke any API key from Settings → Manage keys in the dashboard.

Connect a GitHub repo and sync translations on every push

Once your locale files live in a GitHub repo, Globalize can keep them translated automatically. When you push new source text, Globalize opens a pull request with the translations already filled in. You review and merge — nothing is pushed to your main branch directly. This guide covers connecting a repo through an AI agent using the MCP server. Before you start - Install the Globalize GitHub App on the account or organisation that owns the repo. If it isn't installed yet, the agent can start the install and hand you a link to approve in your browser. - Push your latest code first. Globalize reads the repository from GitHub, so any locale files that only exist locally won't be seen. Steps 1. Find your installation. The agent lists your GitHub App installations and picks the one that owns your repo. 2. Detect the repo. The agent scans it and reports what it found — your framework, the locale file pattern (for example messages/{locale}.json), the file format, and your source and target languages. This confirms Globalize will read the right files. 3. Connect it. The agent links the repo to your project and registers a webhook. Your existing translations can be imported as final so they aren't re-translated. 4. Push new text. Add a new string to your source locale file and push to your connected branch. 5. Review the PR. Within about a minute, Globalize opens a branch like globalize/translations-main with a pull request adding the new keys to each target language. Merge when you're happy. Good to know - The pull request is scoped to what changed. New keys get translated; your reviewed translations are left alone. - Locale files always live in your repo. You own them, and every change goes through a PR you approve. - If a translation reads too formal or too casual for your brand, set a per-language style guide (for example, "use informal address") so future translations match your voice.