Presets

A preset is a group of plugins for one i18n library. It tells x18n which calls are translate calls, how namespaces work, which placeholder syntax the messages use, and which code replaces a hard string.

Detection

With the default presets: 'auto', x18n tests each preset in the order of the table. Most presets apply when the project depends on one of the listed packages. x18n reads the dependencies, dev dependencies and peer dependencies in package.json, and the dependencies in composer.json, pubspec.yaml and Gemfile. The manifests in the parent directories, up to the git root, count too.

More than one preset can apply. Some presets include the plugins of another preset: react-i18next includes everything of i18next, and i18next-shopify includes everything of react-i18next. When two applied presets share a plugin, x18n adds that plugin one time.

A preset can be exclusive. When an exclusive preset applies, x18n tests no preset after it. laravel and php-gettext are exclusive. php-gettext has no detection, so it applies only when you list it.

Run x18n doctor to see the result. Each preset shows as detected, not-detected, listed, or after-exclusive.

List presets

To pick the presets yourself, list them. x18n then applies exactly the listed presets and detects none:

import { general, vueI18n } from '@x18n/cli/presets'
import { defineConfig } from '@x18n/core'

export default defineConfig({
  presets: [vueI18n(), general()],
})

presets: [vue-i18n, general]

In TS, the presets are functions from @x18n/cli/presets: nuxtI18n, vueI18n, fluentVue, i18nextShopify, reactI18next, nextTranslate, nextInternational, i18next, nextIntl, reactIntl, svelteI18n, solidPrimitivesI18n, paraglide, ngxTranslate, transloco, lingui, emberIntl, polyglot, globalize, i18nTag, i18nJs, ui5, chromeExtension, vscodeExtension, laravel, phpJoomla, phpGettext, rubyRails, jekyll, flutter and general. In YAML and JSON, use the names in the first column of the table. presets: [] turns every preset off.

What a preset adds

Each preset page lists what the preset adds:

• Translate calls: the callee names that count as translate calls, and where the key, the namespace and the key prefix come from. These become usage.calls.
• Defaults: namespace rules, derived keys and resource patterns.
• Placeholders: the syntax of the placeholders in messages.
• Extraction templates: the code that replaces a hard string.

Your config adds to these defaults. For example, usage.calls in the config adds callees to the ones of the preset. See How x18n merges the config.

Resource defaults

The resource patterns of all applied presets add up. For example, a project with next-intl and ngx-translate uses the patterns of both presets.

• If your config has resources, x18n uses only your patterns. They replace the patterns of every preset.
• If the patterns of the presets match no file, x18n guesses the locale directories, as it does without presets. See Locale files.
• A pattern without {locale}, such as webapp/i18n/i18n.properties, holds the source locale. To give it another locale, set locale on the resource.

Placeholders

A placeholder syntax tells x18n how placeholders look in messages. The placeholder-mismatch check and x18n apply compare the placeholders of each translation with the source value. Translate prompts list them.

A linked message (@:key) and a nesting placeholder ($t(key)) name another key. That key then counts as used. The invalid-syntax check reports a linked message whose key does not exist, and ICU messages that do not parse or that lack an other case.

Plugins can use all of these syntaxes from @x18n/builtins/placeholders. A YAML plugin can declare a shape such as %{name}.

Extraction templates

x18n extract replaces a hard string with code from a template. A template has these tokens:

Each hard string has a kind, which tells where it is:

x18n picks the first template that matches the kind (kinds) and the file (files). It tries the templates of extract.templates first, then those of the presets, then these defaults:

A template can add imports: lines that x18n adds once to the file when they are missing, such as import { useI18n } from 'vue-i18n'.

import { defineConfig } from '@x18n/core'

export default defineConfig({
  extract: {
    keyPrefix: '{component}',
    templates: [
      {
        template: 'i18n.t(\'{key}\'{args})',
        kinds: ['js-string', 'js-template'],
        files: ['src/server/**'],
        imports: ['import { i18n } from \'~/i18n\''],
      },
    ],
  },
})