npm package: @splunk/eslint-plugin-i18n
Description: Splunk ESLint rules for i18n
Author: Splunk Inc.
Latest version: 0.5.0

# @splunk/eslint-plugin-i18n

To make a given string available for translations it needs to be passed to one of those functions:
* `_`
* `gettext`
* `ungettext`

This plugin aims to help you remember to call them and to help you use them correctly.

See [ui-utils/Internationalization](https://splunkui.splunk.com/Packages/ui-utils/Internationalization) and [Format](https://splunkui.splunkdev.page/Packages/ui-utils/Format) to learn more.

This package provides extendable ESLint configuration objects. Currently, the following configs are available:

* `'plugin:@splunk/eslint-plugin-i18n/react'` - **Recommended**
* `'plugin:@splunk/eslint-plugin-i18n/all'` - For brand new projects


## Install

Install the package and its dependencies.
ESLint requires dependencies to be installed as peer dependencies. See [this issue on github](https://github.com/eslint/eslint/issues/3458) for more background.

### Yarn

1. Install the peer dependencies:
    ```
    yarn add -D eslint@^8
    ```
2. Install the package:
    ```
    yarn add -D @splunk/eslint-plugin-i18n
    ```

### NPM

1. Install the peer dependencies:
    ```
    npm install --save-dev eslint@^8
    ```
2. Install the package:
    ```
    npm install --save-dev @splunk/eslint-plugin-i18n
    ```


## Usage

Add the appropriate entry to your eslint configuration:
```js
{
    extends: ['plugin:@splunk/eslint-plugin-i18n/react'],
    plugins: ['@splunk/eslint-plugin-i18n'],
}
```


You can enable or disable the rules independently, as well as overwrite any rules e.g.: for test files:
```js
{
    extends: ['plugin:@splunk/eslint-plugin-i18n/react'],
    plugins: ['@splunk/eslint-plugin-i18n'],
    rules: {
        '@splunk/i18n/translating-variable': 2, // Enable additional rule
    },
    overrides: [
        {
            files: ['**/*.unit.*'],
            rules: {
                // disable them when appropriate
                '@splunk/i18n/translating-variable': 0,
                '@splunk/i18n/jsx-text': 0,
                '@splunk/i18n/jsx-attributes': 0,
                '@splunk/i18n/string-value': 0,
                '@splunk/i18n/sprintf-text': 0,
            },
        },
    ],
}
```

## Rules

### @splunk/i18n/translating-variable

Passing variables into translation won't work correctly when extracting them later for the translation.

Example of **incorrect** code for this rule:
```js
    const SOME_TEXT = "Something that should be translated";
    function PrintTips2() {
        return (<h1>{_(SOME_TEXT)}</h1>)
    }
```

Example of **correct** code for this rule:
```js
    function PrintTips2() {
        return (<h1>{_("Something that should be translated")}</h1>)
    }
```

Beware: it clashes with underscore library and will report on code like:
```js
_(someArray).map(function(n){ return n * 2; });
```
In that case it's probably best to disable this rule.

### @splunk/i18n/jsx-text

Example of **incorrect** code for this rule:
```js
    function PrintTips2() {
        return (<h1>{"something2"}</h1>)
    }
```

Example of **correct** code for this rule:
```js
    function PrintTips2() {
        return (<h1>{_("something2")}</h1>)
    }
```

If will ignore empty strings or one character strings like `" % "`. But, if you're concatenating strings then you should use variable substitution with [sprintf](https://splunkui.splunk.com/Packages/ui-utils/Format) instead.

### @splunk/i18n/jsx-attributes

[Translatable HTML attributes](https://html.spec.whatwg.org/multipage/dom.html#translatable-attributes) and [Aria attributes](https://www.w3.org/TR/wai-aria-1.3/#translatable-attributes) must have translated values:
```
    'abbr',
    'alt',
    'aria-label',
    'aria-placeholder',
    'aria-roledescription',
    'aria-valuetext',
    'content',
    'download',
    'help',
    'label',
    'lang',
    'placeholder',
    'screenReaderText',
    'title',
    'tooltip',
```

Example of **incorrect** code for this rule:
```js
    function PrintTips3() {
        return (<h1 title={'something3'}></h1>)
    }
```

Example of **correct** code for this rule:
```js
    function PrintTips3() {
        return (<h1 title={_('something3')}></h1>)
    }
```

### @splunk/i18n/string-value

This rule will trigger on any string variable that's not wrapped in a translation function.
If will ignore empty strings or one character strings like: `""`, `"."` or `"-"`, but it will generate a lot of false-positives if you happen to work a lot with hardcoded text values.

Example of **incorrect** code for this rule:
```js
const SOME_TEXT = "Not translated";
```

Example of **correct** code for this rule:
```js
const SOME_TEXT = _("Not translated");
```

### @splunk/i18n/sprintf-text

This rule will trigger on any string variable passed directly to [sprintf](https://splunkui.splunkdev.page/Packages/ui-utils/Format).
If will ignore empty strings ones that mostly concatenate variables: `"%s:%s"`, but you should enable it only for user-facing parts of the codebase.

Example of **incorrect** code for this rule:
```js
sprintf("User %s", name)
```

Example of **correct** code for this rule:
```js
sprintf(_("User %s"), name)
```