docs/templates/configuration.md.yml
configOptions:
- name: locales
type: "string[]"
description: Locales your project supports.
defaultValue: "['en']"
- name: defaultNS
type: "string"
description: Default namespace to use when one is not defined explicitly.
defaultValue: "'translation'"
- name: pluralSeparator
type: "string"
description: |
String you want to use to split plural from keys. See [i18next Configuration options](
https://www.i18next.com/overview/configuration-options#misc).
defaultValue: "'_'"
- name: contextSeparator
type: "string"
description: |
String you want to use to split context from keys. See [i18next Configuration options](
https://www.i18next.com/overview/configuration-options#misc).
defaultValue: "'_'"
- name: keySeparator
type: "string|null"
description: |
String you want to use to split keys. Set to `null` if you don't want to split your keys or
if you want to use keys as value. See [i18next Configuration options](
https://www.i18next.com/overview/configuration-options#misc).
defaultValue: "'.'"
- name: nsSeparator
type: "string|null"
description: |
String you want to use to split namespace from keys. Set to `null` if you don't want to
infer a namespace from key value or if you want to use keys as value. See [i18next
Configuration options](https://www.i18next.com/overview/configuration-options#misc).
defaultValue: "':'"
- name: transKeepBasicHtmlNodesFor
type: "string[]"
description: |
List of tag names that shouldn't be converted to indices when exporting `Trans` component.
The value of this option should reflect the react-i18next configuration in your codebase.
See [react-i18next Trans Component](
https://react.i18next.com/latest/trans-component#additional-options-on-i-18-next-init).
defaultValue: "['br', 'strong', 'i', 'p']"
- name: compatibilityJSON
type: '"v3" | "v4"'
description: |
Compatibility mode of the output JSON file. This option only changes the way plurals are exported.
See [JSONv* format documentation](https://www.i18next.com/misc/json-format#i18next-json-v4) and [why this option exists](https://www.i18next.com/misc/migration-guide#json-format-v4-pluralization).
defaultValue: '"v3"'
- name: i18nextInstanceNames
type: "string[]"
description: |
Possible names for your `i18next` instances. This will be used to detect `i18next.t` calls.
defaultValue: "['i18next', 'i18n']"
examples:
- name: Custom i18next instance name
md: |
```js
/*
{"i18nextInstanceNames": ["myI18next"]}
*/
// This key will be extracted
myI18next.t("key0");
```
- name: tFunctionNames
type: "string[]"
description: |
Possible names for your `t` functions. This will only be used for direct calls to `t`
functions (i.e. `t('key')`, not `foo.t('key')`) and in very last resort.
defaultValue: "['t']"
examples:
- name: Custom t function name
md: |
```js
/*
{"tFunctionNames": ["myT"]}
*/
// This key will be extracted
myT("key0");
```
- name: customTransComponents
type: "[string, string][]"
description: |
This option lets you declare custom `Trans` components (e.g. a HoC of react-i18next's
`Trans` component). It takes an array of source module paths and import names. See the
examples below for usage details.
defaultValue: "[]"
examples:
- name: Declare a local custom Trans component
md: |
```jsx
/*
{
"customTransComponents": [
["./src/customComponents/i18n", "MyOwnTransComponent"]
]}
*/
import {MyOwnTransComponent} from "./customComponents/i18n";
<MyOwnTransComponent>Extracted key</MyOwnTransComponent>;
```
- name: Declare a custom Trans component from a third-party module
md: |
```jsx
/*
{
"customTransComponents": [
["third-party-module", "EnhancedTrans"]
]}
*/
import {EnhancedTrans} from "third-party-module";
<EnhancedTrans>Extracted key</EnhancedTrans>;
```
- name: customUseTranslationHooks
type: "[string, string][]"
description: |
Similarly to `customTransComponents`, this option allows you to declare your
own custom useTranslation hooks which can compose around react-i18next's
useTranslation hook. This option takes an array of source module paths and
import names.
defaultValue: "[]"
examples:
- name: Declare a local custom useTranslation hook
md: |
```jsx
/*
{
"customUseTranslationHooks": [
["./src/customComponents/i18n", "useMyTranslationHook"]
]}
*/
import {useMyTranslationHook} from "./customComponents/i18n";
function MyComponent() {
const t = useMyTranslationHook();
return <span>{t('extracted key')}</span>
}
```
- name: Declare a local custom useTranslation hook using a namespace
md: |
```jsx
/*
{
"customUseTranslationHooks": [
["./src/customComponents/i18n", "useMyTranslationHook"]
]}
*/
import {useMyTranslationHook} from "./customComponents/i18n";
function MyComponentWithNamespace() {
const t = useMyTranslationHook('namespace');
return <span>{t('extracted key in a namespace')}</span>
}
```
- name: defaultContexts
type: "string[]"
description: Context values to use when detecting a translation with context.
defaultValue: "['', '_male', '_female']"
examples:
- name: Usage of default contexts
md: |
```js
/*
{"defaultContexts": ["", "_male", "_female"]}
*/
// Extracts: key0, key0_male, key0_female
t("key0", {context: myCtx});
/*
{"defaultContexts": ["_fruit", "_animal"]}
*/
// Extracts: key0_fruit, key0_animal
t("key0", {context: myCtx});
```
- name: outputPath
type: "string | (locale: string, namespace: string) => string"
description: |
You can pass a string or a function as outputPath :
- **string**: Path where translation keys should be extracted to. You can use `{{ns}}` and `{{locale}}`
placeholders in the value to change the location depending on the namespace or the locale.
- **function**: A function to return custom output path according to the given locale and namespace.
⚠️ **outputPath** as function is only available for javascript babel config.
defaultValue: "extractedTranslations/{{locale}}/{{ns}}.json"
- name: defaultValue
type: "string|null"
description: Default value for extracted keys.
defaultValue: "''"
examples:
- name: Use null as default value
md: |
```js
/*
{"defaultValue": null}
*/
// Extracts: key0 with `null` as default value instead of an empty string.
t("key0");
```
- name: useI18nextDefaultValue
type: "boolean|string[]"
description: |
If `true` and a [i18next default value](
https://www.i18next.com/translation-function/essentials#passing-a-default-value) is set for
the key, use this default value (ignoring `defaultValue` option).
You can also specify an array of locales to apply this behavior only to a specific set
locales (e.g. if your i18next default values are in plain french, you may want to set this
option to `['fr']`).
_Note: For `react-i18next` `Trans` component, the children might also be used as default
value._
defaultValue: "['en']"
examples:
- name: Use i18next default value for all locales
md: |
```js
/*
{"useI18nextDefaultValue": true}
*/
// Extracts: key0 with `Hello world!` as default value.
t("key0", 'Hello world!');
```
- name: Use i18next default value for a specific set of locales
md: |
```js
/*
{"useI18nextDefaultValue": ['fr_FR', 'fr_CA']}
*/
// Extracts: key0 with `Bonjour le monde !` as default value, but
// only for specified french locales ("fr_FR" and "fr_CA").
t("key0", 'Bonjour le monde !');
```
- name: useI18nextDefaultValueForDerivedKeys
type: "boolean"
description: |
If `false` and `useI18nextDefaultValue` is enabled, don't use i18next default value for
derived keys (plural forms or contexts). `defaultValue` option will be used instead.
defaultValue: "false"
examples:
- name: Skip default value for derived keys
md: |
```js
/*
{
"useI18nextDefaultValue": true,
"useI18nextDefaultValueForDerivedKeys": false
}
*/
// Extracts:
// - key0 with `Hello world!` as default value.
// - key0_plural with an empty string as default value.
t("key0", {count: cnt, defaultValue: 'Hello World!'});
// Extracts:
// - key0 with `Hello world!` as default value.
// - key0_male with an empty string as default value.
// - key0_female with an empty string as default value.
t("key0", {context: ctx, defaultValue: 'Hello World!'});
```
- name: keyAsDefaultValue
type: "boolean|string[]"
description: |
If `true`, use the extracted key as defaultValue (ignoring `defaultValue` option). This is
sometimes refered to as "natural keys".
You can also specify an array of locales to apply this behavior only to a specific set
locales (e.g. if your keys are in plain english, you may want to set this option to
`['en']`).
defaultValue: "false"
examples:
- name: Use keys as default value for a set of locales
md: |
```js
/*
{
"keyAsDefaultValue": ['en_US', 'en_GB']
}
*/
// Extracts: `Hello world!` with `Hello world!` as default value
// for the specified english locales (`en_US` and `en_GB`)..
// Other locales will have an empty string as default value instead.
t("Hello world!", 'Hello World!');
```
- name: keyAsDefaultValueForDerivedKeys
type: "boolean"
description: |
If `false` and `keyAsDefaultValue` is enabled, don't use derived keys (plural forms or
contexts) as default value. `defaultValue` option will be used instead.
defaultValue: "true"
examples:
- name: Don't use key as default value for derived keys
md: |
```js
/*
{
"keyAsDefaultValue": ['en'],
"keyAsDefaultValueForDerivedKeys": false
}
*/
// Extracts:
// - "Hello World!" with "Hello World!" as default value for `en` locale.
// - "Hello World!" with an empty string as default value for all other locales.
// - "Hello World!_plural" with an empty string as default value for all locales.
t("Hello world!", {count: cnt, defaultValue: 'Hello World!'});
```
- name: discardOldKeys
type: "boolean"
description: |
When set to `true`, keys that no longer exist are removed from the JSON files. By default,
new keys will be added to the JSON files and never removed.
defaultValue: "false"
- name: jsonSpace
type: "number"
description: Number of indentation space to use in extracted JSON files.
defaultValue: "2"
- name: enableExperimentalIcu
type: "boolean"
description: |
Enable experimental support for [ICU message syntax](
http://userguide.icu-project.org/formatparse/messages). Only plurals and JSONv4 are supported for now.
☠️ *This feature is incomplete and might change or move into an third-party module in the
future. Stay tuned.* ☠️
defaultValue: "false"
- name: excludes
type: "string[]"
description: |
List of regular expressions matching paths that shouldn't be extracted.
Paths are relative to the babel config root and are expressed as POSIX paths (even on Windows).
defaultValue: '["^(../)*node_modules/"]'