@shiftescape/astro-i18n-toolkit

Translation gaps, caught before they ship.

Live i18n debugger in your Astro dev toolbar. Translation coverage map across all locales and a one-click locale switcher. Works with any i18n library — or none at all.

Install GitHub ↗ npm ↗
i18n Toolkit — dev toolbar
Coverage ✗ 3 missing ~ 1 fallback 18 keys total

Locale Complete
fr 94% 17/18
de 83% 15/18
es 72% 13/18

✗ nav.contact missing: de, es
✗ footer.newsletter missing: es
~ hero.subtitle fallback: de
✓ nav.home complete

features

Know your i18n coverage, always.

No more discovering missing translations after a deploy. Catch them in dev.

01
Coverage map

Every key colour-coded: green complete, amber fallback, red missing — per locale.

02
Per-locale %

Coverage percentage per locale so you instantly know which ones need the most work.

03
Locale switcher

One click switches the active locale via middleware. No URL editing required.

04
Searchable

Filter keys by name or reference value in real time across all locales.

05
Library-agnostic

Reads JSON or YAML files directly. Works alongside astro-i18next, Paraglide, or none.

06
Dev-only

Middleware and toolbar stripped in astro build. Zero production footprint.

how the locale switcher works

Switch locales without touching the URL.

A clean three-step flow with no persistent state.

01
Click a locale in the toolbar

The panel shows buttons for every locale in your config.i18n.locales. Click one.

02
Server computes the redirect URL

The integration computes the correct locale-prefixed path and sends it back to the client as a short-lived cookie.

03
Middleware redirects and clears

The injected pre middleware reads the cookie, redirects to the target URL, and immediately expires the cookie — no persistent state.

configuration

Point it at your locale files.

If you use Astro's built-in i18n config, locales are detected automatically.

astro.config.mjs 
import { defineConfig } from 'astro/config'
import i18nToolkit from '@shiftescape/astro-i18n-toolkit'

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr', 'de'],
  },
  integrations: [
    i18nToolkit({
      localesDir:     './src/locales',  // default
      defaultLocale:  'en',             // reference locale
      format:         'json',           // 'json' | 'yaml'
    }),
  ],
})
Option Type Default Description
localesDir string './src/locales' Path to locale files, relative to project root.
defaultLocale string 'en' Reference locale — all others compared against this for the coverage map.
format 'json' | 'yaml' 'json' File format of translation files. YAML support is built-in, no extra deps needed.

install

Works with any i18n setup.

Reads locale files directly from disk — no library coupling, no adapter needed.

npmnpm install -D @shiftescape/astro-i18n-toolkit
pnpmpnpm add -D @shiftescape/astro-i18n-toolkit
yarnyarn add -D @shiftescape/astro-i18n-toolkit
locale file structure 
src/locales/
  en.json   ← reference locale
  fr.json
  de.json

// en.json
{
  "nav": { "home": "Home", "about": "About" },
  "hero": { "title": "Welcome" }
}