@pico-intl-dev/ts-plugin

TypeScript Language Service plugin for pico-intl: autocomplete, hover, diagnostics, and go-to-definition for translation function calls.

Experimental editor tooling. The plugin has automated TypeScript LanguageService coverage, but it should not be considered stable until it has broader IDE coverage across real editor versions.

Features

| Feature | Description | | --- | --- | | Autocomplete | t('nav.') shows matching keys with translated values | | Hover info | Hovering t('nav.home') shows the base-locale value | | Go to definition | Cmd/Ctrl-click jumps to the locale JSON key | | Diagnostics | Optional warnings on unknown keys, missing params, extra params, and obvious number mismatches through strictMode | | Auto-reload | Registry reloads when locale JSON files change |

Param diagnostics are intentionally conservative. They run on literal object arguments and avoid guessing when params are built dynamically. They understand pico-intl core placeholders and common full ICU MessageFormat params, including nested plural/select trees, selectordinal, and number/date/time arguments.

Install

npm install --save-dev @pico-intl-dev/ts-plugin

Configuration

Add the plugin to tsconfig.json:

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@pico-intl-dev/ts-plugin",
        "localesDir": "./locales",
        "baseLocale": "en",
        "functions": ["t", "i18n.t", "$t"],
        "strictMode": false
      }
    ]
  }
}

VS Code

The plugin requires the workspace TypeScript version, not VS Code's built-in TypeScript.

Add to .vscode/settings.json:

{
  "typescript.tsserver.pluginPaths": ["./node_modules"]
}

Then run TypeScript: Select TypeScript Version and choose Use Workspace Version.

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | localesDir | string | "./locales" | Path to locale JSON files | | baseLocale | string | "en" | Locale used for hover display values | | functions | string[] | ["t","i18n.t","$t","useT"] | Function call patterns to detect | | strictMode | boolean | false | Show warning diagnostics for unknown keys and literal param mistakes |

Examples

Autocomplete:

t('nav.')
// Suggestions include:
// nav.home
// nav.about
// nav.contact

Hover:

t('nav.home')
// "Home" [en]
// pico-intl key: nav.home
// File: ./locales/en.json

Strict diagnostics:

t('nav.doesnotexist')
// [pico-intl] Translation key "nav.doesnotexist" not found in en.json

t('user.greeting')
// [pico-intl] Translation key "user.greeting" requires params: name: value

t('user.greeting', {})
// [pico-intl] Missing param "name" for translation key "user.greeting"

t('user.greeting', { name: 'Ana', unused: true })
// [pico-intl] Extra param "unused" is not used by translation key "user.greeting"

t('billing.price', { price: '12' })
// [pico-intl] Param "price" for translation key "billing.price" should be a number

t('activity.feed', { gender: 'female' })
// [pico-intl] Missing param "count" for translation key "activity.feed"

Architecture

The plugin is loaded by tsserver, not by your application runtime. It:

1. Reads locale JSON files from localesDir at startup.
2. Watches the locale directory and reloads keys after changes.
3. Decorates the TypeScript LanguageService proxy for completions, hover, definitions, and diagnostics.
4. Has zero runtime cost in the app because all work happens in the language server process.

Verification

From the repository root:

npm run test:ts-plugin

The test creates a real TypeScript LanguageService, loads the plugin, and verifies completions, hover, unknown-key diagnostics, param diagnostics, go-to-definition, external locale file registration, malformed locale file tracking, and locale reload behavior.

Production notes

• Treat this as assistive editor tooling, not build enforcement.
• Use pico-intl validate --strict, pico-intl check --src ./src --strict --complete, or pico-intl doctor --src ./src --ci for release-blocking catalog validation.
• Editor behavior can differ across VS Code, TypeScript versions, and workspace plugin settings.

License

MIT