Debug a plugin

See how x18n understood a project with x18n doctor and explain, and move a YAML plugin to TypeScript with x18n plugin eject.

When a plugin does not work as you expect, ask x18n how it understood the project.

x18n doctor

x18n doctor

# vue-i18n (.)
config: none (detection only)
presets:
  · nuxt-i18n (not-detected)
  ✓ vue-i18n (detected)
  · fluent-vue (not-detected)
  · i18next-shopify (not-detected)
  · react-i18next (not-detected)
  · next-translate (not-detected)
  · next-international (not-detected)
  · i18next (not-detected)
  · next-intl (not-detected)
  · react-intl (not-detected)
  · svelte-i18n (not-detected)
  · ngx-translate (not-detected)
  · transloco (not-detected)
  · lingui (not-detected)
  · ember-intl (not-detected)
  · polyglot (not-detected)
  · globalize (not-detected)
  · i18n-tag (not-detected)
  · i18n-js (not-detected)
  · ui5 (not-detected)
  · chrome-extension (not-detected)
  · vscode-extension (not-detected)
  · laravel (not-detected)
  · php-joomla (not-detected)
  · php-gettext (not-detected)
  · ruby-rails (not-detected)
  · jekyll (not-detected)
  · flutter (not-detected)
  ✓ general (detected)
finders:
  pattern: 2 resources
    src/locales/de.json
    src/locales/en.json
  sfc-blocks: 0 resources
formats:
  json (json): 2 resources
scanners:
  js (js, jsx, mjs, cjs, ts, tsx, mts, cts): 1 files
  vue (vue): 1 files
  svelte (svelte): 0 files
  regex (none): 0 files
config origins:
  usage: plugin:x18n:vue-i18n

The output answers the usual questions:

Question	Section
Did my preset apply?	`presets`: `detected`, `not-detected`, `listed`, or `after-exclusive` after an exclusive preset.
Did x18n find my locale files?	`finders`: the resources of each locale finder.
Which format reads them?	`formats`: the resources per format.
Does a scanner read my source files?	`scanners`: the files per scanner. A regex scanner shows `none` until a spec gives it extensions.
Do two plugins handle the same extension?	`conflicts`: which format wins.
Did a file fail to parse?	`errors`: the code and message per file.
Which plugin set a config value?	`config origins`: `default`, `user`, `parent`, or `plugin:<name>`.

x18n doctor --json prints the same data as JSON. The Project page of the UI shows it too.

The data of x18n doctor comes from project.explain() in @x18n/core. It returns the presets with the reason for each, the plugins, the plugins that were skipped and why, the finders with their resources, the formats, the scanners, the conflicts, the errors, and the final config with the origin of each value.

Check one thing at a time

x18n get <key> shows where x18n found a key and its usages. If a usage is missing, the scanner does not know the callee. Add it to usage.calls or to the plugin.
x18n usages --file <path> lists the usages that x18n found in one file.
x18n check --only <id> runs one check, for example the check of your plugin.

x18n plugin eject

x18n plugin eject x18n/acme.x18n-plugin.yml

The command prints the TypeScript version of a YAML plugin, written with definePlugin and definePreset and the same built-in functions that load the YAML file. Save the output to a .ts file, and list that file in plugins instead of the YAML file. Then extend it with any part of the plugin API.

Read the output before you replace the YAML file. Check that the regular expressions in scanners.regex came through unchanged.

Capabilities

Each part of the plugin API - config hooks, formats, locale finders, scanners, extractors, checks, reporters, placeholders and more.

Publish a plugin

Name a plugin package x18n-plugin-*, export a plugin or a factory, and let YAML and JSON configs load it by name.