Config reference
This page lists every option of the config file. Read Configuration first for the file names and how x18n finds them.
YAML and JSON configs are validated with a JSON Schema. Point your editor at it:
- YAML:
# yaml-language-server: $schema=https://x18n.dev/schema/config.jsonas the first line. - JSON:
"$schema": "https://x18n.dev/schema/config.json".
x18n schema config prints the same schema. A default is the value before presets run. Presets add resources, call specs, derived keys and extraction templates on top of it.
Options
$schema
Type: string
URL of the JSON Schema, for validation in the editor. x18n ignores it.
root
Type: string
Default: the directory of the config file
Project root, relative to the config file.
name
Type: string
Default: "default"
Project name in a monorepo. Default: the directory name.
sourceLocale
Type: string
Default: "en"
The locale that is the source of truth for checks, prompts and go to definition.
locales
Type: string[]
Locale codes as written in paths. Filters the found locales.
ignoreLocales
Type: string[]
Default: []
Locale codes to leave out, as written in paths.
localeFallbacks
Type: 'auto' | { [locale: string]: string }
Default: {}
Locale to the locale it falls back to, such as { 'en-GB': 'en' }. A locale with a fallback holds only overrides: a key it lacks or leaves empty is not missing when the fallback chain has it. 'auto' falls back to the nearest parent language that exists: en-US to en, zh-Hant-TW to zh-Hant or zh.
presets
Type: 'auto' | PluginSpecifier[]
Default: 'auto'
'auto' detects built-in presets from the project's dependencies.
plugins
Type: PluginSpecifier[]
Default: []
Plugins to add: a package name, a path to a module or to a YAML plugin, or [specifier, options]. Paths are relative to the config file.
resources
Type: ResourceSpec[]
Default: []
Where the locale files are. Each pattern feeds the pattern locale finder. Without patterns, the patterns of all applied presets add up. If they match no file, x18n looks for directories named like locales.
Each item of resources:
| Field | Type | Description |
|---|---|---|
pattern | string | Path pattern with {locale}, {locale?}, {namespace}, {namespaces} and {ext} tokens and globs. |
format? | string | Format id for the matching files, for example json or yaml. Without it, the file extension picks the format. |
namespace? | string | Fixed namespace for every matching file. |
locale? | string | Fixed locale for every matching file, for patterns without {locale} (package.nls.json). |
execute? | boolean | Run matching JS/TS files in Node instead of reading them statically. Makes them read-only. |
formats
Type: { [extension: string]: string }
Default: {}
Explicit format id per file extension (without dot).
keyStyle
Type: 'auto' | 'nested' | 'flat'
Default: "auto"
Key style of a file that has no keys yet. flat writes "a.b" keys. nested and auto write nested objects. A file that already has keys keeps its own style.
namespace
Type: object
How keys and namespaces relate in code.
namespace.separator
Type: string
Default: "."
Separator between namespace and key in code. . merges the namespace into the key path. Default ..
namespace.default
Type: string
Namespace of keys written without one.
namespace.fallback
Type: string[]
Default: []
Namespaces searched in order when a key written without a namespace is not in its own (i18next fallbackNS).
namespace.byFile
Type: { [glob: string]: string }
Default: {}
Namespace of keys written without one, per glob of source files, before default: { 'packages/admin/**': 'admin' }.
namespace.fromPath
Type: 'dot' | 'slash' | 'camel'
Default: "dot"
How {namespaces} folders name a namespace: dot makes pages/home into pages.home, slash keeps pages/home, camel makes todos-page into todosPage. Default dot.
usage
Type: object
How x18n finds usages in source files.
usage.include
Type: string[]
Default: ["**/*"]
Globs of the source files to scan for usages.
usage.exclude
Type: string[]
Default:
**/node_modules/****/.git/****/dist/****/build/****/coverage/****/.nuxt/****/.output/****/.next/****/.svelte-kit/****/*.d.ts**/*.min.js
Globs of the source files to skip. Your list adds to the default list.
usage.calls
Type: CallSpec[]
Default: []
Translate calls to add to the ones of the presets. See Supported syntax.
Each item of usage.calls:
| Field | Type | Description |
|---|---|---|
callee | string | string[] | Function or member path: 't', '$t', 'i18n.t', 'intl.formatMessage'. |
kind? | 'call' | 'selector' | 'accessor' | 'call' (default): the key is an argument. 'selector': the argument is $ => $.a.b. 'accessor': member chain on a root. |
key? | number | ArgSource | Which argument holds the key. Default 0. |
namespace? | ArgSource | string | Where the namespace comes from (call option, or factory argument when factory is true), or a fixed namespace such as 'shared' for a hook that wraps useTranslation('shared'). |
keyPrefix? | ArgSource | Where a key prefix comes from (keyPrefix option, or next-intl useTranslations('a.b')). |
params? | ParamsSource | Where the params passed to the message are. For factories, those of the returned functions. |
defaultValue? | ArgSource[] | Where a default value written in code comes from; the first string found wins. For factories, that of the returned functions. |
factory? | boolean | The callee is a factory that returns the translate function, for example useI18n() returning { t }. |
returns? | string[] | For factories: the names of the returned translate functions. Default ['t']. |
types? | string[] | Type names that mark a parameter or prop as a translate function: 'TFunction'. |
An ArgSource, as in key, namespace, keyPrefix and defaultValue:
| Field | Type | Description |
|---|---|---|
arg | number | Index of the argument, from 0. |
property? | string | Property of an object argument that holds the value. |
A ParamsSource, as in params:
| Field | Type | Description |
|---|---|---|
arg | number | number[] | Arguments that may hold the params object, in order; string arguments are skipped (t(key, 'Default', { n })). |
options? | string[] | Option names the library reads itself, which a message need not use (ns, defaultValue). |
usage.regex
Type: RegexScannerSpec[]
Default: []
Regex scanners for files that no AST scanner reads, such as PHP or Ruby templates.
Each item of usage.regex:
| Field | Type | Description |
|---|---|---|
extensions | string[] | File extensions, without dot. |
patterns | string[] | Patterns with a {key} placeholder (i18n-ally usageMatchRegex), or a regex whose first group is the key. |
usage.ignoreCallees
Type: string[]
Default: []
Callee names never counted as translate calls.
usage.keysInUse
Type: string[]
Default: []
Keys (globs) that count as used, for example keys built at runtime.
usage.derivedKeys
Type: string[]
Default: []
Rules like {key}_plural: when {key} is used the derived keys count as used. Rules apply repeatedly, so with {key}_* the key a_b_c derives from both a_b and a. * matches one key segment. {plural} and {ordinal} match a plural or ordinal category (one, few, other): each locale then needs the categories of its own language, and categories the language lacks are optional.
write
Type: object
How x18n writes locale files.
write.sort
Type: false | 'binary' | 'locale'
Default: false
Key order when x18n writes a file. binary sorts by code point, locale sorts with a locale-aware compare, false keeps the order.
write.indent
Type: number | 'tab'
Indent of written files: a number of spaces, or tab. Without it, each file keeps its own indent.
write.keepFilled
Type: boolean
Default: false
i18n-ally keepFulfilled: set in one locale adds the key with an empty value to the others.
extract
Type: object
How x18n extract finds hard strings and makes keys.
extract.autoDetect
Type: boolean
Report hard strings as hard-string diagnostics.
extract.keygen
Type: 'slug' | 'source' | 'random' | 'empty'
How x18n extract makes a new key: slug from the text, source uses the text itself, random, or empty. Default slug.
extract.keyCase
Type: 'camel' | 'snake' | 'kebab' | 'dot'
Case of slug keys. Default camel.
extract.keyPrefix
Type: string
Template with {fileName}, {dirName} or {component}.
extract.keyMaxLength
Type: number
Longest slug, in characters. Default 40.
extract.reuseExisting
Type: boolean
Reuse a key when the same text exists as a source value. Default true.
extract.ignore
Type: string[]
Strings never extracted: an exact string such as Elk, or a /regex/flags string such as /^v\d+/i that matches the text.
extract.ignoreByFile
Type: { [glob: string]: string[] }
Strings never extracted in the files of a glob, written as in ignore.
extract.attributes
Type: string[]
Attribute names whose values are text, on top of those whose last word is title, label, text, placeholder, alt, content, description, message and the like. Markup attributes outside this set are never extracted.
extract.ignoreAttributes
Type: string[]
Attribute names whose values are never extracted, even text ones such as alt.
extract.ignoreCallees
Type: string[]
Accepted by the schema. x18n does not read it yet.
extract.templates
Type: (string | ExtractTemplate)[]
Replacement templates, tried before the templates of presets. See Extraction templates.
Each item of extract.templates:
| Field | Type | Description |
|---|---|---|
template | string | Replacement code. {key} is the key, {attr} the attribute name, {args} the arguments of a template string. |
kinds? | string[] | Hard-string kinds the template applies to, for example jsx-text. |
files? | string[] | File globs the template applies to. |
imports? | string[] | Lines added once per file when missing, for example an import. |
checks
Type: { [checkId: string]: CheckSetting }
Default: {}
Overrides on top of the recommended check set.
strict
Type: boolean
Default: false
Turn every warning into an error.
ignoreKeys
Type: string[]
Default: []
Keys (globs) excluded from all checks.
glossary
Type: GlossaryEntry[]
Default: []
Terms with fixed translations. Translate prompts list them, and the glossary check compares values with them.
Each item of glossary:
| Field | Type | Description |
|---|---|---|
term | string | The term as written in source values. |
translations? | { [locale: string]: string } | Translation per locale. |
note? | string | A note for translators. Translate prompts show it. |
doNotTranslate? | boolean | Keep the term as it is in every locale. |
history
Type: boolean | HistoryOptions
Default: true
History providers for stale translations. false turns every provider off. Options of a provider sit under its key, such as git: { maxDepth, since } (or git: false).
review
Type: ReviewOptions
Default: {"enabled":true,"file":".x18n/reviews.yml"}
Review comments, approvals and suggested values on messages, kept in a file tracked in git.
projects
Type: string[]
Monorepo: directories (globs) that are projects inheriting this config.
TypeScript only
defineConfig in x18n.config.ts accepts more than YAML and JSON. These options take plugin objects and functions:
| Option | Type | Description |
|---|---|---|
presets | 'auto' | PresetOption[] | As in YAML, plus preset objects such as vueI18n() from @x18n/builtins/presets/vue-i18n. false and undefined entries are skipped. |
history | boolean | (HistoryOptions & { providers?: HistoryProvider[] | undefined }) | History providers for stale translations: false turns them off; provider options such as git sit under their key; providers adds providers asked first. |
plugins | PluginOption[] | As in YAML, plus plugin and preset objects, for example from definePlugin. |
checks | { [K in keyof CheckIds]?: CheckSetting } & { [checkId: string]: CheckSetting } | As in YAML. Plugins add their check ids to the type, so the editor completes them. |
pluginConfigs | Partial<PluginConfigs> | Options of plugins, under the key that each plugin declares. |
A PluginSpecifier is a string (a built-in preset name, a package name or a path), or [specifier, options]. A CheckSetting is a severity ('error', 'warning', 'info', 'hint' or 'off'), or [severity, options].