Documentation
localize.dev turns hardcoded copy into translation calls in React, Next.js, React Native, Vue, Nuxt, Svelte, Angular, Astro, Solid, Qwik, Lit, Ember, Flutter, Rails, Django, Laravel, Android, iOS and static HTML codebases, writes the locale dictionaries, sets up the i18n library if there isn't one, and can open the pull request for you. Translation runs on the hosted localize.dev model, so there's nothing to set up beyond an API key.
Quickstart
You need Node.js 22 or later. Your app doesn't need an i18n library yet; the first run sets one up. Create a free API key in the dashboard, then pick your framework:
React
Any UI rendered through a component that can call useTranslation(): React with Vite, Remix or Gatsby, Electron and Tauri renderers, and design systems or shared UI packages. Class components get t through withTranslation(), or <Translation> when they aren't the file's default export. Sentences around links stay whole with <Trans> (a link's own title included), copy in constants, toasts and zod messages is found, and dates, numbers and prices follow the app's language.
npm install --save-dev localize-dev
# Save your API key on this machine
npx localize-dev login
# See what would change, without writing anything
npx localize-dev run --dry-run -l es,fr
# Rewrite the code and write the locale files
npx localize-dev run -l es,fr
# Only if the run added packages to package.json
npm installReact guide: what changes, with a real before and after.
Next.js
App Router server components get const { t } = await getTranslation() and client components useTranslation(), both in the language the server picked; the Pages Router works like React. A generated proxy.ts gives every page a URL per language with hreflang links.
npm install --save-dev localize-dev
# Save your API key on this machine
npx localize-dev login
# See what would change, without writing anything
npx localize-dev run --dry-run -l es,fr
# Rewrite the code and write the locale files
npx localize-dev run -l es,fr
# Only if the run added packages to package.json
npm installNext.js guide: what changes, with a real before and after.
React Native and Expo
React Native and Expo. accessibilityLabel and accessibilityHint are translated too, and the i18n setup avoids browser-only APIs.
npm install --save-dev localize-dev
# Save your API key on this machine
npx localize-dev login
# See what would change, without writing anything
npx localize-dev run --dry-run -l es,fr
# Rewrite the code and write the locale files
npx localize-dev run -l es,fr
# Only if the run added packages to package.json
npm installReact Native and Expo guide: what changes, with a real before and after.
Vue
Text and {{ }} in <template> become {{ $t('key') }} and attributes become :placeholder="$t('key')", with vue-i18n set up in src/i18n.ts and installed in main.ts. Messages shown from <script setup> (alert, toasts, document.title) use t() from useI18n, and n === 1 ? … : … becomes a vue-i18n plural. An existing createI18n setup is left as it is. A sentence around a link or bold text stays one message through <i18n-t>, with the elements as slots. Constants in <script setup> shown by the template ({{ title }}, v-for="tab in tabs") become keys read through $t(). Templates written in Pug (<template lang="pug">) get the same: h1 {{ $t('key') }}, piped and block text, and input(:placeholder="$t('key')").
npm install --save-dev localize-dev
# Save your API key on this machine
npx localize-dev login
# See what would change, without writing anything
npx localize-dev run --dry-run -l es,fr
# Rewrite the code and write the locale files
npx localize-dev run -l es,fr
# Only if the run added packages to package.json
npm installVue guide: what changes, with a real before and after.
Nuxt
Pages and components are rewritten like any Vue component, and @nuxtjs/i18n is added to nuxt.config, with a URL per language (/es/about) and hreflang links from useLocaleHead().
npm install --save-dev localize-dev
# Save your API key on this machine
npx localize-dev login
# See what would change, without writing anything
npx localize-dev run --dry-run -l es,fr
# Rewrite the code and write the locale files
npx localize-dev run -l es,fr
# Only if the run added packages to package.json
npm installNuxt guide: what changes, with a real before and after.
Svelte and SvelteKit
Markup becomes {$_('key')} with svelte-i18n, initialized from src/lib/i18n and imported in +layout (or main.ts without SvelteKit). Attributes like title="Hello {name}" become one message. In SvelteKit, a generated hooks.server renders each page in the visitor's language (their saved choice, then Accept-Language), so there's no flash of the source language.
npm install --save-dev localize-dev
# Save your API key on this machine
npx localize-dev login
# See what would change, without writing anything
npx localize-dev run --dry-run -l es,fr
# Rewrite the code and write the locale files
npx localize-dev run -l es,fr
# Only if the run added packages to package.json
npm installSvelte and SvelteKit guide: what changes, with a real before and after.
Angular
Templates (.html and inline template:) become {{ 'key' | translate }} with ngx-translate, attributes [placeholder]="'key' | translate" ([attr.aria-label] for aria), and strings in bindings ('key' | translate). Control flow (@if, @for), *ngIf and inline templates are understood; elements marked with Angular's own i18n are left to it. The setup adds provideI18n() to app.config.ts (every locale bundled, no HTTP loader) and TranslatePipe to each standalone component that needs it.
npm install --save-dev localize-dev
# Save your API key on this machine
npx localize-dev login
# See what would change, without writing anything
npx localize-dev run --dry-run -l es,fr
# Rewrite the code and write the locale files
npx localize-dev run -l es,fr
# Only if the run added packages to package.json
npm installAngular guide: what changes, with a real before and after.
Astro
Text and {expressions} in .astro files become {t('key')}, attributes title={t('key')}, with t from a generated src/i18n module that reads the language from the URL. Each static page gets a copy per language (src/pages/es/about.astro), so every language is a real, indexable page, and layouts set <html lang dir>. localizePath(path, lang) builds links between languages. React, Vue and Svelte islands (from @astrojs/react, /vue, /svelte) are localized in the same run, each with its own library set up and following the page's language.
npm install --save-dev localize-dev
# Save your API key on this machine
npx localize-dev login
# See what would change, without writing anything
npx localize-dev run --dry-run -l es,fr
# Rewrite the code and write the locale files
npx localize-dev run -l es,frAstro guide: what changes, with a real before and after.
Solid
JSX like React, with useTranslation() from a generated src/i18n.ts: i18next behind a language signal, so text updates in place when the language changes. Sentences around links stay one message, rendered by rich(t('key'), { a: (c) => <a href="/terms">{c}</a> }) from the same module.
npm install --save-dev localize-dev
# Save your API key on this machine
npx localize-dev login
# See what would change, without writing anything
npx localize-dev run --dry-run -l es,fr
# Rewrite the code and write the locale files
npx localize-dev run -l es,fr
# Only if the run added packages to package.json
npm installSolid guide: what changes, with a real before and after.
Qwik
JSX in component$ gets const { t } = useTranslation() from a generated src/i18n.ts that reads the language from the URL (Qwik City's useLocation), and each route, dynamic ones too, gets a copy per language under src/routes/es/. Sentences around links stay one message through rich() from the same module.
npm install --save-dev localize-dev
# Save your API key on this machine
npx localize-dev login
# See what would change, without writing anything
npx localize-dev run --dry-run -l es,fr
# Rewrite the code and write the locale files
npx localize-dev run -l es,frQwik guide: what changes, with a real before and after.
Lit
Text and ${expressions} in html`…` templates become ${t('key')}, attributes placeholder=${t('key')}. Components get an I18nController so they re-render when setLanguage() switches language; nested templates, styles and comments are left alone.
npm install --save-dev localize-dev
# Save your API key on this machine
npx localize-dev login
# See what would change, without writing anything
npx localize-dev run --dry-run -l es,fr
# Rewrite the code and write the locale files
npx localize-dev run -l es,frLit guide: what changes, with a real before and after.
Ember
Glimmer templates (.hbs, and <template> in .gjs/.gts) become {{t "key" name=this.name}} with ember-intl, attributes placeholder={{t "key"}}, strings in {{if}} (t "key"), and {{if (eq n 1) "item" "items"}} in a sentence a plural. Messages go to translations/<locale>.json; a generated application route picks the language.
npm install --save-dev localize-dev
# Save your API key on this machine
npx localize-dev login
# See what would change, without writing anything
npx localize-dev run --dry-run -l es,fr
# Rewrite the code and write the locale files
npx localize-dev run -l es,fr
# Only if the run added packages to package.json
npm installEmber guide: what changes, with a real before and after.
Flutter
Text('Hi $name') and arguments like hintText: become AppLocalizations.of(context)!.hiName(name), with messages in lib/l10n/app_en.arb (camelCase keys, ICU plurals, placeholder metadata). const is dropped from widgets that now hold a lookup; strings with no BuildContext in scope are reported. The setup adds flutter_localizations, generate: true, l10n.yaml, the MaterialApp delegates and the iOS language list.
# Save your API key on this machine
npx localize-dev login
# See what would change, without writing anything
npx localize-dev run --dry-run -l es,fr
# Rewrite the code and write the locale files
npx localize-dev run -l es,frNo package.json needed: npx runs the CLI. Flutter guide: what changes, with a real before and after.
Static HTML
The text stays in the page and gets a data-i18n="key" marker (attributes get data-i18n-placeholder and similar). A generated i18n.js loads the locale files and swaps the text; add <select data-i18n-switcher></select> for a language menu. A sentence with inline elements (<strong>, links) is one message, rebuilt from the page's own elements. Translations are also bundled into i18n.js, so pages opened from disk work too. Text from a template engine ({{ }}, {% %}, PHP) is left alone.
Search engines only see the text in the page, so set "htmlPages": true and "siteUrl" in localize.config.json to also write each page translated into every language (es/index.html), linked with hreflang.
npm install --save-dev localize-dev
# Save your API key on this machine
npx localize-dev login
# See what would change, without writing anything
npx localize-dev run --dry-run -l es,fr
# Rewrite the code and write the locale files
npx localize-dev run -l es,frStatic HTML guide: what changes, with a real before and after.
Ruby on Rails
Text in ERB views becomes <%= t('key', name: @user.name) %>, with %{name} placeholders in config/locales/<locale>.yml and plurals called with count:. available_locales and a switch_locale around-action are added.
# Save your API key on this machine
npx localize-dev login
# See what would change, without writing anything
npx localize-dev run --dry-run -l es,fr
# Rewrite the code and write the locale files
npx localize-dev run -l es,frNo package.json needed: npx runs the CLI. Ruby on Rails guide: what changes, with a real before and after.
Django
Templates get {% translate '…' %} and {% blocktranslate %}, translations go into locale/<lang>/LC_MESSAGES/django.po, and settings get LANGUAGES, LOCALE_PATHS and LocaleMiddleware.
# Save your API key on this machine
npx localize-dev login
# See what would change, without writing anything
npx localize-dev run --dry-run -l es,fr
# Rewrite the code and write the locale files
npx localize-dev run -l es,frNo package.json needed: npx runs the CLI. Django guide: what changes, with a real before and after.
Laravel
Blade text becomes {{ __('Hi :name', ['name' => $user->name]) }} with lang/<locale>.json keyed by the text, and a SetLocale middleware picks the language (?locale=, a lang cookie, then Accept-Language).
# Save your API key on this machine
npx localize-dev login
# See what would change, without writing anything
npx localize-dev run --dry-run -l es,fr
# Rewrite the code and write the locale files
npx localize-dev run -l es,frNo package.json needed: npx runs the CLI. Laravel guide: what changes, with a real before and after.
Android
android:text, hint and contentDescription in layouts and menus become @string/…, and Compose Text("Hi $name") inside @Composable functions becomes stringResource(R.string.…, name). View code in Kotlin or Java (label.setText("Hi"), label.text = "Hi") becomes setText(R.string.…). Strings go to res/values-<lang>/strings.xml with numbered %1$s placeholders, and locales_config.xml lists the languages for Android 13+.
# Save your API key on this machine
npx localize-dev login
# See what would change, without writing anything
npx localize-dev run --dry-run -l es,fr
# Rewrite the code and write the locale files
npx localize-dev run -l es,frNo package.json needed: npx runs the CLI. Android guide: what changes, with a real before and after.
iOS
SwiftUI text (Text("Hi \(name)"), Button, .navigationTitle) stays as written, since SwiftUI looks it up in the String Catalog itself; UIKit strings (label.text = "Hi") become String(localized: "Hi"). Everything goes into Localizable.xcstrings with every language in the one file. Add the catalog to your app target in Xcode once.
# Save your API key on this machine
npx localize-dev login
# See what would change, without writing anything
npx localize-dev run --dry-run -l es,fr
# Rewrite the code and write the locale files
npx localize-dev run -l es,frNo package.json needed: npx runs the CLI. iOS guide: what changes, with a real before and after.
Want to look before signing up? npx localize-dev scan lists every string it would extract, and --offline generates keys without translating. Neither needs a key or uses your allowance. A later online run fills in the missing translations without touching existing keys.
Supported codebases
Each framework gets its own scanner and i18n library. What changes in each one is under its name in the quickstart, and in its guide.
Monorepos: run from the root with --workspaces (or the Action's workspaces: true) to localize every app, each with its own locale files. Shared component libraries (packages with no dev or start script) are translated too, in the languages of the apps that depend on them, and their messages are added to those apps' locale files, so the library's t() calls resolve through each app's own setup. To localize just one app, give the Action working_directory: apps/web instead: it reads that app's localize.config.json, code and locale files, and the pull request changes them in place.
The framework is detected from package.json (or pubspec.yaml, or the files when there's neither); set "framework" in localize.config.json to override it. React dictionaries use i18next or ICU placeholders; Vue, Svelte and HTML use ICU-style {name}.
Existing locale files
Already have i18n set up, in any stack? localize-dev translate skips the code and fills in what's missing in your locale files: keys with no translation yet, in every language you already have, or in new ones you name. Existing translations are never changed, and no framework is detected, so it works for any stack, native iOS and Android, Rails and Django included.
# Fill in what's missing in the languages already there
npx localize-dev translate --dry-run
npx localize-dev translate
# Add languages (creates the files)
npx localize-dev translate -l de,ja,pt-BR
# Or as a pull request
npx localize-dev pr --translate| Format | Files | Notes |
|---|---|---|
| JSON | locales/en.json, public/locales/en/*.json | i18next (with _one/_other plurals), ICU (react-intl, next-intl, including =0 matches and select), vue-i18n, ngx-translate, Transloco |
| YAML | config/locales/en.yml, devise.en.yml | Rails, under the language key; one/other plural maps |
| gettext | locale/fr/LC_MESSAGES/django.po | Django, WordPress, PHP, Python. Empty and fuzzy entries are filled; plural slots follow Plural-Forms. New languages are created beside an existing one, with their own Plural-Forms. |
| Flutter | lib/l10n/app_en.arb | ICU messages; @key descriptions become context. gen-l10n picks up the new files. |
| Android | res/values/strings.xml | <string> and <plurals>; translatable="false", <xliff:g> and escapes respected. Writes values-es/, values-pt-rBR/. |
| Apple | Localizable.xcstrings, en.lproj/*.strings | String Catalogs get each language in place, plurals included; .strings files get new .lproj folders (add the languages in Xcode). |
| Browser extensions | _locales/en/messages.json | Placeholders are copied into each language. |
Placeholders in each format's own syntax ({{name}}, %{name}, %1$s, %@, %(name)s, $NAME$) are protected: a translation that loses or adds one, or reorders unnamed ones like %s, is dropped and reported. Plurals get every form the target language needs (Russian gets one, few and many). Comments and descriptions in the files go to the model as context.
Edited copy: localize.lock.json keeps a fingerprint of each source message when it's translated. Change the English and the next run, translate or Action run translates it again in every language; check fails on translations left out of date. Commit the file.
In the GitHub Action, set mode: translate. Each run opens or updates a pull request with whatever is missing, so new keys added in English get translated as they land.
Crowdin, Phrase, Lokalise, Transifex
Working with translators in a TMS? Push your source locale files there and pull their translations back. Add the project to localize.config.json (provider: crowdin, phrase, lokalise or transifex) and put the API token in CROWDIN_TOKEN, PHRASE_TOKEN, LOKALISE_TOKEN or TRANSIFEX_TOKEN (never in the config file):
{
"tms": { "provider": "crowdin", "projectId": "123456" }
}# Upload source files (and, the first time, your existing translations)
npx localize-dev sync push --translations
# Download translations into your locale files
npx localize-dev sync pullJSON, YAML, ARB, Android, .strings and extension files are synced. Crowdin keeps your folders, Phrase keeps each file apart with a tag, Lokalise stores each under its path with the language as %LANG_ISO%, and Transifex gets a resource per file (projectId like o:acme:p:web). Languages are matched to the project's own codes (es → es-ES, pt-BR → pt_BR). For Crowdin Enterprise or Phrase's US data center, set "url" to its API address. gettext and String Catalog files are better served by the TMS's own integrations. A common loop: run localize-dev run or translate for machine translations, push, let reviewers edit, pull.
CLI commands
- localize-dev init
- Writes a localize.config.json with every default spelled out.
- localize-dev init --agent [--pre-commit]
- Sets up coding agents to translate text as they write it: the MCP server for Claude Code and Cursor, an after-edit hook for Claude Code, and instructions in AGENTS.md and a Cursor rule. --pre-commit also checks staged files before each commit. How it works.
- localize-dev login [--api-key ldv_live_…]
- Saves your API key for this machine. Without
--api-keyit prompts, or reads the key from stdin. - localize-dev whoami
- Shows the workspace, plan and usage for the current key.
- localize-dev logout
- Removes the saved key from this machine.
- localize-dev scan [-d src] [-o extracted_strings.json]
- Lists every string that would be extracted, plus the ones skipped and why. Changes nothing; no key needed.
- localize-dev run [--dry-run] [--offline] [--workspaces] [--files a.tsx… | --changed | --staged] [-l es,fr] [-d src] [--api-key …]
- The full pass: extract, name keys, translate, rewrite files, update dictionaries, and set up the i18n library if the app has none. With
--workspaces, every app in a monorepo in turn. - localize-dev translate [--dry-run] [-l de,ja] [-s en] [--api-key …]
- Fills in missing translations in existing locale files, for any stack. Code isn't touched. Formats.
- localize-dev check [--only strings|translations] [--files a.tsx… | --changed | --staged] [--json]
- Fails CI on hardcoded copy, missing translations and translations out of date with their source; reports unused keys and, with a right-to-left language, left/right styles. Details.
- localize-dev prune [--dry-run]
- Removes keys no code refers to from every language's locale file.
- localize-dev rtl [--fix]
- Lists styles pinned to the left or right;
--fixswaps the safe ones for logical ones. Right to left. - localize-dev content [--dry-run] [-l de,ja]
- Translates Markdown and MDX documents into a copy per language. Docs and content.
- localize-dev sync push|pull [--translations] [-l de,ja]
- Pushes source locale files to Crowdin, Phrase, Lokalise or Transifex, or pulls their translations back. Setup.
- localize-dev seo <url> [--limit 500] [--json]
- Checks what search engines see of each language on a site, live or a local build: the sitemap, hreflang links, <html lang>, the canonical address and og:locale. Exits with 1 when it finds a problem, so it can run in CI after a deploy Details.
- localize-dev pr [--translate] [--base main] [--repo owner/name] [--branch name] [--token …]
- Runs the pass and opens (or updates) a pull request on
localize-dev/<base>instead of writing locally. UsesGITHUB_TOKENwhen--tokenis omitted. With--translate, the pull request only fills in missing translations.
Coding agents
localize-dev mcp runs an MCP server, so a coding agent (Claude Code, Cursor, Codex, GitHub Copilot and others) can check and localize the repository it's working in. Lovable, Bolt, v0 and other builders that run in the browser connect to the hosted server at https://uselocalize.dev/api/mcp with an API key. The setup for each agent is on the MCP page. To have the agent translate text as it writes it, run this in the app's folder:
npx localize-dev init --agent # MCP server, Claude Code hook, AGENTS.md, Cursor rule
npx localize-dev init --agent --pre-commit # also check staged files before each commitIt writes these files:
.mcp.jsonand.cursor/mcp.json: the MCP server, for Claude Code and Cursor..claude/settings.json: an after-edit hook that runsnpx -y localize-dev hook. When a file Claude Code edits has text that isn't translated, the hook lists the lines and the agent callslocalizeon that file before moving on.AGENTS.md, and aCLAUDE.mdthat imports it when there's none: when to calllocalizeandcheck. A Cursor rule in.cursor/rules/localize.mdcsays the same for your UI files.- With
--pre-commit:check --stagedin husky's pre-commit hook, or git's own.
In a monorepo, the instructions name the app. Your existing settings, servers and text are kept, and a second run changes nothing. Commit the files so the team and their agents share them. The hook only reads the file, with no key or model, and takes about a second; LOCALIZE_DEV_HOOK=off pauses it. Strings an agent translates through the MCP server show as "While writing" on the usage page.
i18n setup
Vue, Nuxt, Svelte and static HTML are set up as described in Supported codebases. In React, rewritten components call useTranslation(), so the app needs i18next running. When it isn't, the run (and the Action's pull request) adds what's missing:
i18nextandreact-i18nextinpackage.json. The Action also updates your lockfile (npm, pnpm, Yarn or Bun); after a local run, run your install.src/i18n.ts(or.js), which loads the locale files and picks the language from a saved choice, then the browser, then your source locale. With more than three target languages only the source is bundled and the rest load when first used ("lazyLocales"to choose). In Remix apps without v3_routeConfig, pages hydrate in their<html lang>and switch after loading.- An
import './i18n'in your entry file: the script inindex.html, elsesrc/main.*orsrc/index.*. resolveJsonModuleintsconfig.json, so the locale files can be imported.- An import of it in your test setup file (Vitest
setupFiles, JestsetupFilesAfterEnv,src/setupTests), so tests that look for text still find it. Vue gets vue-i18n installed for@vue/test-utils. - A line in
.gitattributesthat merges locale files key by key, so two branches adding keys don't conflict. Turn it on once per clone withgit config merge.localize-dev.driver "npx localize-dev merge-locales %O %A %B %P"(merges on GitHub itself don't run it). src/language-switcher.tsx, exporting<LanguageSwitcher />anduseLanguage()with this app's defaults, andlocalize-devas a dependency. Render the switcher where people pick a language, such as your header; it isn't placed for you. Options.
If any file already initializes i18next, none of this is added and your setup is used as is. The switcher saves the choice in localStorage and restores it on the next visit; to switch from your own code, call i18n.changeLanguage('es') and store lang the same way. Projects set up by an earlier version get the switcher on their next run. In the Next.js Pages Router the import goes in pages/_app.
Next.js App Router
Files under app/ without 'use client' are server components, which can't use hooks. They get const { t } = await getTranslation() instead (the component becomes async if it wasn't), from a generated i18n.server module that picks the language from a lang cookie, then the browser's Accept-Language. Client components keep useTranslation(). The root layout is wrapped in a generated <I18nProvider> that hands client components the same language, and <html lang> follows it. The generated switcher sets the lang cookie and refreshes, so server components re-render in the new language.
Language switcher
<LanguageSwitcher /> is a menu of the languages your app bundles (your source language and the target languages you configured), each with its flag and its own name. It works with the keyboard (arrows, Home/End, Enter, Escape, typing a name) and screen readers, remembers the choice, and sets <html lang> and dir for right-to-left languages.
import { LanguageSwitcher, useLanguage } from '../../../(app)/docs/language-switcher';
<LanguageSwitcher /> // flag + native name
<LanguageSwitcher compact /> // just the flag
<LanguageSwitcher nameStyle="native-english" /> // Español · Spanish
<LanguageSwitcher languages={['en', 'es']} /> // choose and order the list
<LanguageSwitcher regions={{ en: 'GB', pt: 'BR' }} /> // which country's flag
<LanguageSwitcher renderFlag={(l) => <img src={`/flags/${l.code}.svg`} alt="" />} />
<LanguageSwitcher unstyled className="…" buttonClassName="…" menuClassName="…" optionClassName="…" />
// Anywhere else: the current language and the list
const { language, info, languages, setLanguage, isRTL } = useLanguage();
info.flag // "🇪🇸"
info.nativeName // "Español"Other props: showFlag, align (start/end), side (top/bottom), label, disabled, renderButton, renderOption, persist (localStorage, cookie or none), storageKey and onChange. Built-in styles read CSS variables, so a theme or dark mode is a few lines: --ldv-bg, --ldv-fg, --ldv-border, --ldv-hover, --ldv-muted, --ldv-accent, --ldv-radius, --ldv-shadow. Selected and highlighted options carry data-selected and data-active for your own CSS. Outside React, getLanguageInfo('pt-BR') returns the same names, flag and direction.
In the Next.js App Router the generated file saves the choice in the lang cookie and refreshes, so server components follow. Emoji flags show as two letters on Windows; pass renderFlag for images there.
Every other framework gets the same menu, generated for its own components and state, on the <localize-language-switcher> custom element from localize-dev/switcher: it takes the same options as attributes, emits language-change, and is styled with the same --ldv-* variables or ::part(button|menu|option|flag).
Vue src/language-switcher.ts <LanguageSwitcher />, useLanguage()
Nuxt components/LanguageSwitcher.ts auto-imported, with composables/useLanguage.ts
Svelte LanguageSwitcher.svelte the $language store from language.ts
Solid, Qwik src/language-switcher.tsx <LanguageSwitcher />, useLanguage()
Angular language-switcher.component.ts <app-language-switcher />, languageOf(translate)
Astro components/LanguageSwitcher.astro useLanguage(Astro.url) from i18n/language.ts
Lit src/language-switcher.ts <app-language-switcher>, useLanguage()
Ember components/language-switcher <LanguageSwitcher />, the language service
React Native language-switcher.tsx a native picker, useLanguage()
HTML <localize-language-switcher> from the CDN; i18n.js switches on language-change
Rails shared/_language_switcher.html.erb render "shared/language_switcher", current_language
Django language_switcher.html {% include %}, {{ language }} in every template
Laravel <x-language-switcher /> App\Support\Language::current()
Flutter lib/language_switcher.dart LanguageSwitcher(), language.of(context)
iOS LanguageSwitcher.swift LanguageSwitcher(), LanguageStore.shared, .appLanguage()
Android LanguageSwitcher.kt LanguageSwitcher(), showLanguagePicker(context)API keys
Keys look like ldv_live_… and belong to a workspace; every key in a workspace shares its monthly allowance. The CLI looks for a key in this order:
- the
--api-keyflag - the
LOCALIZE_API_KEYenvironment variable (use this in CI) - the key saved by
localize-dev login, in~/.config/localize-dev/credentials.json(readable only by you)
Only a hash of each key is stored on our side, so a secret is shown once, when you create it. Revoke a key from the dashboard and it stops working immediately.
Configuration
Everything is optional. Put overrides in localize.config.json at the project root; CLI flags win over the file.
| Field | Default | Description |
|---|---|---|
| srcDir | "src" | Directory to scan. |
| framework | detected | react, react-native, vue, svelte or html. Detected from package.json, then the files. |
| include / ignore | by framework / tests, stories, .d.ts | Globs relative to srcDir: *.{tsx,jsx}, *.vue, *.svelte or *.html. |
| sourceLocale | "en" | Language of the hardcoded copy. |
| targetLocales | ["es", "fr"] | Languages to translate into. |
| localesPath | "locales/{locale}.json" | Dictionary location, e.g. public/locales/{locale}/common.json. |
| attributes | placeholder, alt, title, aria-label, label, tooltip | Attributes treated as UI copy. React Native adds accessibilityLabel and accessibilityHint. |
| importSource | "react-i18next" | React: where useTranslation is imported from, e.g. next-i18next. |
| interpolation | by framework | i18next writes {{name}} (React); icu writes {name} (Svelte, HTML); vue writes {name} with vue-i18n's special characters escaped. |
| htmlPages | false | Static HTML: also write each page translated per language (es/index.html), for search engines. |
| siteUrl | none | The site's address, e.g. https://example.com. Needed for hreflang links between language versions. |
| localizeFormats | true | Make dates, numbers and prices hardcoded to one locale follow the app's language. |
| currency | "USD" | What a bare $ before an amount stands for when prices are localized, e.g. "CAD". |
| lazyLocales | more than 3 languages | React: bundle only the source language and load the others when first used. |
| content | none | Markdown and MDX documents for localize-dev content: { "include": ["docs/**/*.md"], "output": "{dir}/{name}.{locale}{ext}" }. |
GitHub Action
The Action runs the same pass in CI and opens a pull request against the branch that triggered it. Re-runs update the same branch and PR. Before the first run, store your API key in the repository:
- 1
Copy your API key
It starts withldv_live_and is shown only once. Lost it? Create a new one on the API keys page. - 2
Open the repository’s Actions secrets
On GitHub, open your repository and go to Settings → Secrets and variables → Actions, then click New repository secret. You need admin access to the repository to see Settings. - 3
Add the secret
Name:LOCALIZEDEV_API_KEYSecret: paste your key, with no spaces or line breaks. Then click Add secret. GitHub hides the value from then on; to change it, update the secret. - 4
Without the localize.dev GitHub App: allow the Action to open pull requests
In Settings → Actions → General, under Workflow permissions, tick Allow GitHub Actions to create and approve pull requests and click Save. Without it the run translates everything but fails when opening the pull request. If the option is greyed out, an organization owner has to allow it first under the organization’s Settings → Actions → General.
Then commit the workflow:
name: Localize
on:
push:
branches: [main]
pull_request:
types: [opened, synchronize]
workflow_dispatch: # "Run workflow" button in the Actions tab
permissions:
contents: write # push the localize-dev/<branch> branch
pull-requests: write # open or update the localization PR
# One run per branch at a time; a newer push supersedes the running one.
concurrency:
group: localize-${{ github.head_ref || github.ref_name }}
cancel-in-progress: true
jobs:
localize:
runs-on: ubuntu-latest
timeout-minutes: 60
# Skip localize.dev's own branches, and fork PRs (their token is read-only).
if: >-
!startsWith(github.head_ref || github.ref_name, 'localize-dev/') &&
(github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)
steps:
- name: Checkout
uses: actions/checkout@v5
with:
# On PRs, scan the branch itself rather than the merge commit.
ref: ${{ github.head_ref || github.ref_name }}
- name: Localize
uses: ufortstephen/autolocalize-action@v1
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
api_key: ${{ secrets.LOCALIZEDEV_API_KEY }}
target_locales: 'es,fr,de'
# src_dir: 'src' # default: your framework's (src, app/views, resources/views, lib…)
# locales_path: 'public/locales/{locale}/common.json' # default: your framework's
# working_directory: 'apps/web' # monorepo: localize just this appOther inputs: src_dir, locales_path, base_branch, api_url, offline (no key needed), workspaces (every app in a monorepo), working_directory (one app of a monorepo), tms_pull / tms_push (with tms_token: bring reviewed translations into the pull request, upload source files from the default branch), mode: translate (only fill in existing locale files). Outputs: pr_url, strings_count.
Each run reports back when it finishes: the project's page in the dashboard lists recent runs with their pull request, strings replaced, translations per language, and the error if one failed.
Preview pull request
Want to see it on your own code before setting anything up? Connect the repository in the dashboard and choose Open a preview pull request on its page. localize.dev reads the default branch, localizes up to 200 strings into the project's first language on the server, and opens a pull request from localize-dev/preview. No workflow, API key or checkout is needed; the strings count toward your plan, and the translations show up on the Review tab like any run's. Running it again updates the same pull request.
In a monorepo, each app is localized in turn until the 200 strings are used. Files in Git LFS and submodules aren't in the archive GitHub provides, so they're left out, and a very large repository is only partly read; the pull request says so. The GitHub Action has neither limit.
CI check
localize-dev check fails (exit code 1) when copy is still hardcoded, a language is missing translations, or translations are out of date because their English changed since (from localize.lock.json), and lists each one. It also reports keys no code uses (remove them with localize-dev prune), text in stylesheets (content: "New"), messages that show a stored value as is (Status: {{status}} shows "paid") and, when a target language is right to left, styles pinned to the left or right, and next/font fonts missing a target language's letters; those don't fail the check. A key the code uses that the source locale file lacks does fail it, since people would see the key itself. It reads files only: no API key, nothing sent. On GitHub Actions each problem is also an annotation on the pull request's diff.
npx localize-dev check # both
npx localize-dev check --only strings # hardcoded copy only
npx localize-dev check --only translations # missing translations only
npx localize-dev check --json
npx localize-dev check --staged # files staged for the next commit (pre-commit hook)
npx localize-dev check --changed # files changed since the last commit, and new onesWith --files, --changed or --staged, check looks only at those files: hardcoded copy and keys missing from the source locale file. It skips the project-wide checks, so it runs in about a second, quick enough for a pre-commit hook or an agent's after-edit hook. run takes the same options.
Or in a workflow that runs on pull requests, with the Action:
on: pull_request
jobs:
i18n:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ufortstephen/autolocalize-action@v1
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
mode: checkPseudo-localization
Before paying for a single translation, see where your layout breaks. --pseudo writes an en-XA language: every message accented, about 35% longer (like German or Finnish) and in brackets, with placeholders and tags kept exactly, so the app runs as it would with a real translation. Switch to it and look for clipped buttons, overflowing cards and anything without brackets: that copy is still hardcoded.
npx localize-dev run --pseudo # en-XA: [Šáṽé çĥáñĝéš one two]
npx localize-dev run --pseudo rtl # ar-XB: right to left
npx localize-dev translate --pseudo # from existing locale files, code untouchedNo model and no key: it doesn't use your allowance. Your real languages stay as they are. The playground has it too, as the en-XA language.
Dates, numbers & money
In React, React Native, Electron, Tauri, Solid, Vue and Svelte apps, runs also rewrite dates, numbers and prices that are hardcoded to a locale, so they follow the app's language:
date.toLocaleDateString('en-US', …)andnew Intl.NumberFormat('en-US')take the app's language instead (and so do calls with no locale, which use the browser's).`$${price}`and<span>${price}</span>become a currency format, so$1,234.50reads1.234,50 $in German.€,£,¥,₹,₦,CA$,A$and other symbols map to their currency; a bare$is USD unless"currency"inlocalize.config.jsonsays otherwise.- In Vue templates and scripts the language comes from vue-i18n (
$i18n.locale); in Svelte, from svelte-i18n's$locale.
Dates from date-fns (format(d, 'MMM d, yyyy')), dayjs and moment become Intl.DateTimeFormat with the same parts; relative times (formatDistance, fromNow) are listed for you to switch to Intl.RelativeTimeFormat. localeCompare and upper or lower case shown in JSX use the app's language (Turkish i). Lists follow the language too: {tags.join(', ')} in JSX and a hand-built `${xs.slice(0, -1).join(', ')} and ${xs[xs.length - 1]}` become Intl.ListFormat, so Japanese gets 、 and Spanish its own "y". Pull requests list each change. Turn it off with "localizeFormats": false in localize.config.json. Next.js App Router apps are left as they are for now, since their client components get the language through a provider.
A URL per language
Search engines index each language when it has its own URL. In Next.js App Router apps, the generated proxy.ts (middleware.ts before Next 16) serves /es/about with the /about page in Spanish, without moving your files, and <LanguageAlternates /> in the root layout adds hreflang links between the versions. Unprefixed URLs keep following the lang cookie and the browser, and the language menu moves between prefixed URLs.
Nuxt apps get @nuxtjs/i18n's prefix_except_default URLs with useLocaleHead() in app.vue; set "siteUrl" for absolute links. Static sites get the same from htmlPages. An app with its own proxy or middleware keeps it: the run explains the two headers (x-localize-lang, x-localize-path) to set there.
Page titles and descriptions follow too. Next.js export const metadata becomes a generateMetadata that uses the request's translator (a title template's %s kept), and an existing generateMetadata gets t. In single-page apps (Vite React, Vue, Svelte, Angular, Solid), index.html's <title> and description are translated and set by the generated module when the language changes; the file keeps them as written for the first paint.
For search engines, the root layout also gets a canonical address and og:locale for each language's URL, from the generated i18n-seo.ts. app/sitemap.ts lists every page with a fixed address (no [slug] routes, signed-in areas or private folders) in every language, with hreflang alternates. A robots.ts points to it. Both are written only when the app has neither, and you can edit them. Set "siteUrl" so the sitemap has full addresses. When it isn't set, the address comes from a CNAME file or the homepage in package.json, and on Vercel, Netlify, Render or Railway from the address the host gives the build.
Astro layouts get an I18nHead component in their head, with the same links and og:locale. SvelteKit 2.3 and later serves each language at its own address through a reroute hook in src/hooks.ts, so routes need no [lang] folder, and hooks.server adds the links to each page. Both get a sitemap.xml built from the pages or routes folder, so new pages are listed without running localize again, and a robots.txt when the app has neither.
Qwik City apps get a LanguageHead component in root.tsx with the same links, and the same sitemap and robots routes.
React Router apps (framework mode) get every route again under each language, so /es/about is the about page in Spanish. The routes file passes its routes through withLanguageRoutes from app/i18n-routes.ts, and the root renders each page in the language of its address, with the same links. Links without a language keep the page's language, and the sitemap.xml and robots.txt routes are added when the app has neither. With more than three languages, the ones not in the bundle load in the route's loader, so the server renders them too.
Remix 2 apps get the same when v3_routeConfig is on in vite.config and the routes are in app/routes.ts (Remix's route config). Without it, the run says what to change.
Static sites with htmlPages and siteUrl also get a sitemap.xml listing every page in every language, and a robots.txt when they have none.
The visitor's language is matched exactly, by language, or to a regional variant the app offers: a browser set to pt-PT gets the app's pt-BR.
To see what search engines see, point localize-dev seo at the site. It works on any site, set up by localize.dev or not.
npx localize-dev seo https://example.com # the live site
npx localize-dev seo http://localhost:3000 # a local build, before you deployIt reads robots.txt and the sitemap, then loads every page and the pages its hreflang links name. It reports pages that don't load or redirect, hreflang links without the full address or without x-default, a language whose page doesn't link back, an <html lang> or og:locale that doesn't match the page's language, and a canonical link that points somewhere else. Addresses on another origin (siteUrl, when you check a local build) are loaded from the address you give.
Reviewing translations
Machine translations from GitHub Action runs and CLI pull requests (pr, pr --translate) appear on the project's Review tab, source and translation side by side, filterable by language. Approve them one by one or all at once, or edit one: an edit must keep the source's placeholders, and it replaces the workspace's translation memory entry, so every later run uses the correction. Plural messages show every form the language needs (Russian's one, few, many…) and are edited form by form.
Apply edits to pull request commits your edits to the open localization pull request of the run they came from, in its JSON locale files, through the GitHub App. Edits that can't be placed (other file formats, or a merged pull request) reach the next run through the translation memory.
Each translation keeps a thread of notes for the next reviewer, and shows who approved or edited it and when. When the same correction keeps coming up, the tab suggests a glossary term: a source word that should always translate a certain way (checkout → pago), or a name reviewers keep restoring that should stay untranslated. One click adds it to the project glossary, which every run follows.
Assign a reviewer per language from the workspace's members. When a run brings new translations in their language, they get one email for the run with a link to the tab. Each row links to the source file it came from on GitHub. The model flags translations it isn't sure of (an ambiguous word, an idiom, a formal or informal guess) with its reason, and the tab opens on those, under Needs a look; Approve the rest leaves them for a person. In code shows the lines around where it's used, read from the run's pull request, so the copy can be checked where it's shown.
Glossary
Each project has a glossary on its dashboard page: terms that must never be translated (brand and product names), preferred translations for your vocabulary, and a style note such as "informal; use du in German". It applies to every request from the project's GitHub Action and CLI runs. Translations that change a never-translate term are rejected; preferred translations and the style note guide the model.
Plans & limits
| Plan | Price | Strings / month | Languages |
|---|---|---|---|
| Free | $0 | 1,000 | 3 |
| Pro | $19/month or $190/year | 10,000 | 10 |
| Team | $49/month or $490/year | 30,000 | Unlimited |
A string counts once however many languages it is translated into. Allowances run in 30-day periods: from the day your workspace was created, or from your billing date on a paid plan. The dashboard shows when yours resets. The language limit counts every language translated into in the last 30 days, across your workspaces and projects. If a run would go over the allowance or the language limit, it stops before writing anything, explains why and exits with code 2, so CI fails instead of committing half a translation.
Languages
localize.dev translates into any language the Unicode CLDR knows, more than 600 of them, written as a BCP 47 code: a language (es, ja, sw), with a script or a region when it matters (zh-Hant, sr-Latn, pt-BR, es-419). There is no list to choose from: set sourceLocale and targetLocales in localize.config.json, or pass --locales.
A code that names no language is refused before anything is translated, with what was probably meant: jp → ja, cn → zh. Every valid code is accepted, aliases such as en-UK (read as en-GB) and private-use codes included. The CLI, the GitHub Action, the dashboard and the API check the same way.
- How many languages one run can translate into depends on your plan. A string counts once, however many languages it goes into.
- Translations are strongest in widely used languages. For languages with less text online, have a native speaker review the pull request, and add a glossary for your product’s own terms.
- Every language whose script runs right to left (Arabic, Hebrew, Persian, Urdu, Kurdish, Pashto, Syriac, N’Ko and others) gets
dir="rtl"and the left/right style checks. A code that names its script counts too:pa-Arab. - Plurals follow each language’s own forms (one, few, many…) from the CLDR, so Polish, Arabic and Welsh get every form they need.
- The pseudo-locales
en-XA(accented and longer) andar-XB(right to left) need no model and no key.
Plurals & rich text
A quantity-dependent choice such as {n} {n === 1 ? 'file' : 'files'} left becomes one message (also n > 1 ? …, rules.select(n) === 'one' ? … and helpers like plural(n, 'file', 'files')), rewritten to t('files.left', { count: n }). Each language gets exactly the forms it needs (Spanish three, Polish four, Arabic six), written as files.left_one, files.left_few… for i18next or one ICU plural message, and i18next picks the right one at runtime.
A sentence with two counts, {files} {files === 1 ? 'file' : 'files'} in {folders} {folders === 1 ? 'folder' : 'folders'}, becomes a message per counted phrase ({{count}} file / {{count}} files) placed in one sentence, {{files}} in {{folders}}, so each count gets its own forms and translators can still reorder them. Ordinals from helpers like ordinal(place) or {n}{ordinalSuffix(n)} become i18next ordinal plurals (t('rank.place', { count: place, ordinal: true })), with each language's own ordinal forms: English 1st/2nd/3rd/4th, French 1re/2e, Spanish 1.º.
The same works beyond React: ICU messages (Svelte, Ember) get a selectordinal, vue-i18n gets key_ordinal_one… keys picked by Intl.PluralRules, and in Vue, Svelte, Astro, Lit, Ember, Flutter and Rails each counted phrase becomes a plural call of its own inside the sentence's.
Text around simple inline elements, like Read the <a href="/docs">docs</a> first, becomes one message (Read the <a>docs</a> first) rendered with <Trans>, so translators can move the link. The element keeps its props. Translations that lose or rename a tag are rejected.
Frameworks without a <Trans> get the same, with the element's own text as a message of its own: Vue through <i18n-t> with slots, Svelte through a generated <I18nT> (snippets in Svelte 5, a slot in 3 and 4), Angular through a generated <i18n-t> with ng-template slots (an NgModule before Angular 14), Ember through a generated <I18nT>, Solid and Qwik through rich(). In Rails, a link_to inside a sentence is interpolated into an _html message, so its markup is kept.
What gets translated
- JSX text, with text and simple expressions merged into one message:
Hi {user.name}!→Hi {name}! - Attributes in the allow-list (placeholder, alt, title, aria-label, aria-description, aria-valuetext, aria-roledescription, label, tooltip; configurable), and an SVG's
<title>and<desc> - String and template literals rendered in JSX, including both branches of
a ? 'X' : 'Y'and the right side of&& - Copy in constants that components read (
const NAV = [{ label: 'Home' }]withNAV.map((n) => n.label)): the strings become keys and each read becomest(n.label) - Joined strings (
'Hi ' + name + '!') as one message, and messages passed to state setters, toasts,alertand zod or yup validation (z.string().min(1, 'Required')) - Component props that hold text (
<EmptyState heading="No orders yet" />, Vue'sempty-text="…"), lookup tables read by key (STATUS_LABELS[order.status]), helper functions whose results are rendered, and copy imported from a plain module (nav.ts), whose strings become keys there when every component that imports it can be followed - Gendered sentences (
gender === 'female' ? 'She…' : 'He…') as one message with a variant per gender, so each language words them its own way - Vue and Svelte templates (Vue in HTML or Pug): text,
{{ }}and{ }expressions, attributes (includingtitle="Hi {name}"), and the strings an expression renders, like{{ saving ? 'Saving…' : 'Save' }} - Vue and Svelte scripts: messages that are shown, passed to
alert,confirm, toasts and notifications, or assigned todocument.title, and constants the template shows (const tabs = [{ label: 'Home' }]with{{ tab.label }}): the strings become keys and the template reads them through$t()or$_() - Static HTML: element text, sentences around inline elements as one message, and the same attributes. Text from a template engine or PHP is left alone and reported.
Never translated: URLs and paths, colors, UUIDs, CSS units, emails, file names, snake_case or kebab-case identifiers, symbol-only text, and anything inside <code>, <pre>, <Trans>, translate="no" or data-i18n-ignore.
Every translation is checked before it is written: one that adds, drops or renames a {placeholder} is rejected. Existing translations in your dictionaries are never overwritten.
Right to left
Arabic, Hebrew, Persian and Urdu read right to left, so ml-4 or margin-left ends up on the wrong side. When a target language is right to left, check lists styles pinned to the left or right, and localize-dev rtl --fix swaps the ones with a logical equivalent that looks the same in English:
- Tailwind:
ml-/mr-→ms-/me-,pl-/pr-→ps-/pe-,text-left→text-start, rounded corners and borders, with variants likemd:kept. - CSS:
margin-left→margin-inline-start,padding-right→padding-inline-end,text-align: left→start, borders and corner radii.
left-/right- positions and floats are only reported, since they're often centering tricks. Check the result in ar-XB with localize-dev run --pseudo rtl.
Docs and content
Documentation, blog posts and legal pages are translated as whole documents. localize-dev content translates Markdown and MDX files into a copy per language: prose, headings, list items, table cells and front-matter titles and descriptions are translated; code blocks, inline code, link URLs, MDX imports, components and expressions stay exactly as written. A passage whose translation loses any of those is kept in English and reported.
{
"targetLocales": ["es", "fr"],
"content": {
"include": ["docs/**/*.md", "blog/**/*.mdx"],
"output": "{dir}/{name}.{locale}{ext}"
}
}The default output sits next to each file (intro.es.md), as Nextra, Fumadocs and Hugo expect. For Docusaurus use "i18n/{locale}/docusaurus-plugin-content-docs/current/{path}". Documents unchanged since their copies were made are skipped (their fingerprints are in localize.lock.json), so only edited ones are translated again.
Privacy & data
- Only the extracted strings are sent to the API, with their file path and component as context. Whole files are never sent.
- Scans and offline runs never leave your machine.
- The CLI rewrites files locally; the GitHub Action commits from your own runner with your own token.
- API keys are stored as hashes; the secret is shown only once.
Limitations
- Rich text takes inline elements nested up to three deep (bold text inside a link becomes a nested message). A link's own
title, written out or set from code, stays inside the sentence's component in React. - Plurals are recognised from two-string choices on a count (
===/!==1,>1,<2,Intl.PluralRules) and plural helpers with a count and both forms. Every framework extracts plurals in its own idiom (Django'spluralize, Laravel'sStr::plural, Kotlin'sif … else) and writes its own format (<plurals>, String Catalog variations,msgid_plural,trans_choice; Angular, which has none, picks the key with a generatedpluralFormpipe). A sentence with several counts gets a plural per count everywhere but Django (whoseblocktranslatetakes one) and iOS; ordinals work in the JavaScript frameworks and Angular, not in Flutter, Rails, Django, Laravel, Android or iOS, whose i18n libraries have no ordinal forms. On iOS, a plural needs its number in the text ("\(n) items"), which is what the String Catalog varies by. - Class components are translated: through
withTranslation()when the class is the file's default export, otherwise withrender()running inside<Translation>. Constructors, static members and event handlers use i18next'st, so text a constructor stores follows the language at mount. - In Vue and Svelte scripts, the copy extracted is what's clearly shown:
alert,confirm, toasts and notifications,document.title, and constants the template shows (a string,ref('…'), an object's or a list'slabel/titlefields, passed to child components translated), and whatcomputed(), functions,$:and$derivedreturn. A string constant the script itself uses keeps its text, since the script may compare or send it. In Svelte 4, text a function returns updates on the component's next render after a language switch. - Vue templates in Pug are translated,
#[…]inline tags (three deep) and#{}values included. Templates in other preprocessors (rare outside Pug) are skipped and reported. - Copy outside components (emails, SVG text, messages built on the server) isn't extracted; Markdown and MDX documents are translated whole with
localize-dev content. - The preview pull request reads the default branch's files; Git LFS files and submodules are left out.