eslint-plugin-formatjs

What is eslint-plugin-formatjs?

eslint-plugin-formatjs is an ESLint plugin that provides linting rules for the FormatJS library, which is used for internationalization (i18n) in JavaScript applications. The plugin helps ensure that your usage of FormatJS is consistent and follows best practices.

What are eslint-plugin-formatjs's main functionalities?

Enforce id attribute in messages

This rule ensures that all messages have an 'id' attribute, which is useful for consistency and maintainability in large projects.

module.exports = {
  'rules': {
    'formatjs/enforce-id': ['error', { 'idInterpolationPattern': '[sha512:contenthash:base64:6]' }]
  }
};

No multiple plurals

This rule prevents the use of multiple plural forms in a single message, which can lead to confusion and errors in translations.

module.exports = {
  'rules': {
    'formatjs/no-multiple-plurals': 'error'
  }
};

No id in define messages

This rule disallows the use of 'id' attributes in defineMessages, promoting the use of defaultMessage instead.

module.exports = {
  'rules': {
    'formatjs/no-id-in-define-messages': 'error'
  }
};

Other packages similar to eslint-plugin-formatjs

eslint-plugin-i18n

eslint-plugin-i18n is another ESLint plugin that provides rules for internationalization. It focuses on ensuring that i18n best practices are followed, such as checking for missing translations and enforcing consistent message formats. Compared to eslint-plugin-formatjs, it is more general and not specifically tied to FormatJS.

eslint-plugin-react-intl

eslint-plugin-react-intl is an ESLint plugin specifically for React applications using the react-intl library. It provides rules to enforce best practices and consistency in the use of react-intl. While eslint-plugin-formatjs can be used with any JavaScript project, eslint-plugin-react-intl is tailored for React projects.

README

eslint-plugin-formatjs

This eslint plugin allows you to enforce certain rules in your ICU message. This is currently under development

Usage

npm install eslint-plugin-formatjs

Then in your eslint config:

{
  "plugins": ["formatjs"],
  "rules": {
    "formatjs/no-offset": "error"
  }
}

Currently this uses intl.formatMessage, defineMessages, <FormattedMessage> from react-intl, or _ from @formatjs/macro as hooks to verify the message. Therefore, in your code use 1 of the following mechanisms:

import {_} from '@formatjs/macro';

const message = _({
  defaultMessage: 'foo',
  description: 'bar',
});

import {defineMessages} from 'react-intl';

const messages = defineMessages({
  foo: {
    defaultMessage: 'foo',
    description: 'bar',
  },
});

import {FormattedMessage} from 'react-intl';

<FormattedMessage defaultMessage="foo" description="bar" />;

function foo() {
  intl.formatMessage({
    defaultMessage: 'foo',
  });
}

Available Rules

blacklist-elements

This blacklists usage of specific elements in ICU message.

Why

• Certain translation vendors cannot handle things like selectordinal

Available elements

enum Element {
  // literal text, like `defaultMessage: 'some text'`
  literal = 'literal',
  // placeholder, like `defaultMessage: '{placeholder} var'`
  argument = 'argument',
  // number, like `defaultMessage: '{placeholder, number} var'`
  number = 'number',
  // date, like `defaultMessage: '{placeholder, date} var'`
  date = 'date',
  // time, like `defaultMessage: '{placeholder, time} var'`
  time = 'time',
  // select, like `defaultMessage: '{var, select, foo{one} bar{two}} var'`
  select = 'select',
  // selectordinal, like `defaultMessage: '{var, selectordinal, one{one} other{two}} var'`
  selectordinal = 'selectordinal',
  // plural, like `defaultMessage: '{var, plural, one{one} other{two}} var'`
  plural = 'plural',
}

Example

{
  "plugins": ["formatjs"],
  "rules": {
    "formatjs/blacklist-elements": [2, ["selectordinal"]]
  }
}

enforce-description

This enforces description in the message descriptor.

Why

• Description provides helpful context for translators

import {defineMessages} from 'react-intl';

const messages = defineMessages({
  // WORKS
  foo: {
    defaultMessage: 'foo',
    description: 'bar',
  },
  // FAILS
  bar: {
    defaultMessage: 'bar',
  },
});

enforce-default-message

This enforces defaultMessage in the message descriptor.

Why

• Can be usefull in case we want to extract messages for translations from source code. This way can make sure people won't forget about defaultMessage

import {defineMessages} from 'react-intl';

const messages = defineMessages({
  // WORKS
  foo: {
    defaultMessage: 'This is default message',
    description: 'bar',
  },
  // FAILS
  bar: {
    description: 'bar',
  },
});

enforce-placeholders

Makes sure all values are passed in if message has placeholders (number/date/time/plural/select/selectordinal). This requires values to be passed in as literal object (not a variable).

// WORKS, no error
<FormattedMessage
  defaultMessage="this is a {placeholder}"
  values={{placeholder: 'dog'}}
/>

// WORKS, no error
intl.formatMessage({
  defaultMessage: 'this is a {placeholder}'
}, {placeholder: 'dog'})

// WORKS, error bc no values were provided
<FormattedMessage
  defaultMessage="this is a {placeholder}"
/>

// WORKS, error bc no values were provided
intl.formatMessage({
  defaultMessage: 'this is a {placeholder}'
})

// WORKS, error bc `placeholder` is not passed in
<FormattedMessage
  defaultMessage="this is a {placeholder}"
  values={{foo: 1}}
/>

// WORKS, error bc `placeholder` is not passed in
intl.formatMessage({
  defaultMessage: 'this is a {placeholder}'
}, {foo: 1})

// DOESN'T WORK
<FormattedMessage
  defaultMessage="this is a {placeholder}"
  values={someVar}
/>

// DOESN'T WORK
intl.formatMessage({
  defaultMessage: 'this is a {placeholder}'
}, values)

enforce-plural-rules

Enforce certain plural rules to always be specified/forbidden in a message.

Why

• It is recommended to always specify other as fallback in the message.
• Some translation vendors only accept certain rules.

Available rules

enum LDML {
  zero = 'zero',
  one = 'one',
  two = 'two',
  few = 'few',
  many = 'many',
  other = 'other',
}

Example

{
  "plugins": ["formatjs"],
  "rules": {
    "formatjs/enforce-plural-rules": [
      2,
      {
        "one": true,
        "other": true,
        "zero": false
      }
    ]
  }
}

no-camel-case

This make sure placeholders are not camel-case.

Why

• This is to prevent case-sensitivity issue in certain translation vendors.

import {defineMessages} from 'react-intl';

const messages = defineMessages({
  // WORKS
  foo: {
    defaultMessage: 'foo {snake_case} {nothing}',
  },
  // FAILS
  bar: {
    defaultMessage: 'foo {camelCase}',
  },
});

no-emoji

This prevents usage of emoji in message.

Why

• Certain translation vendors cannot handle emojis.
• Cross-platform encoding for emojis are faulty.

import {defineMessages} from 'react-intl';

const messages = defineMessages({
  // WORKS
  foo: {
    defaultMessage: 'Smileys & People',
  },
  // FAILS
  bar: {
    defaultMessage: '😃 Smileys & People',
  },
});

no-multiple-whitespaces

This prevents usage of multiple consecutive whitespaces in message.

Why

• Consecutive whitespaces are handled differently in different locales.
• Prevents \ linebreaks in JS string which results in awkward whitespaces.

import {defineMessages} from 'react-intl';

const messages = defineMessages({
  // WORKS
  foo: {
    defaultMessage: 'Smileys & People',
  },
  // FAILS
  bar: {
    defaultMessage: 'Smileys &   People',
  },
  // FAILS
  baz: {
    defaultMessage: 'this message is too long \
    so I wanna line break it.',
  },
});

no-multiple-plurals

This prevents specifying multiple plurals in your message.

Why

• Nested plurals are hard to translate across languages so some translation vendors don't allow it.

import {defineMessages} from 'react-intl'

const messages = defineMessages({
    // WORKS
    foo: {
        defaultMessage: '{p1, plural, one{one}}',
    },
    // FAILS
    bar: {
        defaultMessage: '{p1, plural, one{one}} {p2, plural, one{two}}',
    }
    // ALSO FAILS
    bar2: {
        defaultMessage: '{p1, plural, one{{p2, plural, one{two}}}}',
    }
})

no-offset

This prevents specifying offset in plural rules in your message.

Why

• Offset has complicated logic implication so some translation vendors don't allow it.

import {defineMessages} from 'react-intl';

const messages = defineMessages({
  // WORKS
  foo: {
    defaultMessage: '{var, plural, one{one} other{other}}',
  },
  // FAILS
  bar: {
    defaultMessage: '{var, plural, offset:1 one{one} other{other}}',
  },
});

supported-datetime-skeleton

Since formatjs only supports a subset of DateTime Skeleton. This rule exists to make sure you don't use a unsupported pattern.