eslint-plugin-formatjs

Tradução Beta Não Oficial

Esta página foi traduzida por PageTurner AI (beta). Não é oficialmente endossada pelo projeto. Encontrou um erro? Reportar problema →

Este plugin do ESLint permite impor regras específicas em suas mensagens ICU.

Uso

npm
yarn

npm i -D eslint-plugin-formatjs

yarn add -D eslint-plugin-formatjs

Em seguida, na sua configuração do eslint:

import formatjs from 'eslint-plugin-formatjs'

export default [
  // other configs...
  {
    plugins: {
      formatjs,
    },
    rules: {
      'formatjs/no-offset': 'error',
    },
  },
]

React

Atualmente, ele utiliza intl.formatMessage, defineMessage, defineMessages e <FormattedMessage> do react-intl como hooks para validar a mensagem. Portanto, em seu código utilize um destes mecanismos:

import {defineMessages, defineMessage} from 'react-intl'

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

defineMessage({
  defaultMessage: 'single message',
})

import {FormattedMessage} from 'react-intl'
;<FormattedMessage defaultMessage="foo" description="bar" />

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

Vue

Ele verificará chamadas das funções intl.formatMessage e $formatMessage tanto em arquivos JS/TS quanto em SFCs .vue. Por exemplo:

<template>
  <p>
    {{
      $formatMessage({
        defaultMessage: 'today is {now, date}',
      })
    }}
  </p>
</template>

Configurações Compartilhadas

Essas configurações são aplicadas globalmente a todas as regras do FormatJS quando definidas. Consulte Configurações Compartilhadas para detalhes sobre como configurá-las.

`formatjs.additionalFunctionNames`

Similar ao babel-plugin-formatjs e ao @formatjs/ts-transformer, isso permite especificar nomes de funções adicionais para verificação além de formatMessage e $formatMessage.

`formatjs.additionalComponentNames`

Similar ao babel-plugin-formatjs e ao @formatjs/ts-transformer, isso permite especificar nomes de componentes adicionais para verificação além de FormattedMessage.

Configurações Compartilháveis

O plugin fornece estas duas configurações compartilháveis:

recommended
strict

Ao utilizá-las, você simplifica sua configuração mantendo um conjunto de regras alinhado com seus padrões de qualidade.

Exemplo

import formatjs from 'eslint-plugin-formatjs'

export default [
  formatjs.configs.recommended,
  // Other configs...
]

Regras Disponíveis

`blocklist-elements`

Bloqueia o uso de elementos específicos em mensagens ICU.

Motivo

Alguns fornecedores de tradução não suportam elementos como selectordinal

Elementos disponíveis

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',
}

Exemplo

import formatjs from 'eslint-plugin-formatjs'

export default [
  {
    plugins: {
      formatjs,
    },
    rules: {
      'formatjs/blocklist-elements': [2, ['selectordinal']],
    },
  },
]

`enforce-description`

Exige description no descritor da mensagem.

Motivo

A descrição fornece contexto valioso para tradutores

import {defineMessages} from 'react-intl'

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

Opções

import formatjs from 'eslint-plugin-formatjs'

export default [
  {
    plugins: {
      formatjs,
    },
    rules: {
      'formatjs/enforce-description': ['error', 'literal'],
    },
  },
]

Definir literal força description a ser sempre um literal de string em vez de chamadas de função ou variáveis. Isso ajuda ferramentas de extração que exigem description como literal.

`enforce-default-message`

Exige defaultMessage no descritor da mensagem.

Motivo

Útil para extração de mensagens do código-fonte para tradução, garantindo que defaultMessage não seja esquecido

import {defineMessages} from 'react-intl'

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

Opções

import formatjs from 'eslint-plugin-formatjs'

export default [
  {
    plugins: {
      formatjs,
    },
    rules: {
      'formatjs/enforce-default-message': ['error', 'literal'],
    },
  },
]

Definir literal força defaultMessage a ser sempre um literal de string em vez de chamadas de função ou variáveis. Isso ajuda ferramentas de extração que exigem defaultMessage como literal.

`enforce-placeholders`

Garante que todos os valores sejam passados quando a mensagem contém placeholders (number/date/time/plural/select/selectordinal). Exige que os valores sejam passados como objeto literal (não variável).

// 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)

Opções

import formatjs from 'eslint-plugin-formatjs'

export default [
  {
    plugins: {
      formatjs,
    },
    rules: {
      'formatjs/enforce-placeholders': [
        'error',
        {
          ignoreList: ['foo'],
        },
      ],
    },
  },
]

ignoreList: Lista de nomes de placeholders a ignorar. Funciona com defaultRichTextElements no react-intl para evitar falsos positivos em formatação global de tags.

`enforce-plural-rules`

Exige que certas regras de plural sejam sempre especificadas/proibidas em mensagens.

Motivo

Recomenda-se sempre especificar other como fallback na mensagem.
Alguns fornecedores de tradução aceitam apenas determinadas regras.

Regras disponíveis

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

Exemplo

import formatjs from 'eslint-plugin-formatjs'

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

`no-camel-case`

Esta regra garante que os placeholders não estejam em camel case.

Motivo

Para evitar problemas de sensibilidade a maiúsculas/minúsculas em alguns fornecedores de tradução.

import {defineMessages} from 'react-intl'

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

`no-missing-icu-plural-one-placeholders`

Mensagens no formato {thing, plural, one {1 thing} other {# things}} precisarão ser alteradas para {thing, plural, one {# thing} other {# things}}

Motivo

one é uma categoria para números que se comportam como 1. Em idiomas como ucraniano, russo e polonês, one → números terminados em 1 (como 1, 21, 151) exceto quando terminam em 11 (como 11, 111). Mais informações

`no-emoji`

Esta regra impede o uso de emojis (ou acima de determinada versão Unicode) nas mensagens.

import formatjs from 'eslint-plugin-formatjs'

export default [
  {
    plugins: {
      formatjs,
    },
    rules: {
      'formatjs/no-emoji': ['error'],
    },
  },

  // OR
  {
    plugins: {
      formatjs,
    },
    rules: {
      'formatjs/no-emoji': ['error', {versionAbove: '12.0'}],
    },
  },
]

Motivo

Alguns fornecedores de tradução não processam emojis corretamente.
A codificação multiplataforma de emojis apresenta falhas.

import {defineMessages} from 'react-intl'

const messages = defineMessages({
  // WORKS
  foo: {
    defaultMessage: 'Smileys & People',
  },
  // WORKS with option {versionAbove: '12.0'}
  foo_bar: {
    defaultMessage: '😃 Smileys & People',
  },
  // FAILS
  bar: {
    defaultMessage: '😃 Smileys & People',
  },
  // FAILS with option {versionAbove: '12.0'}
  bar_foo: {
    defaultMessage: '🥹 Smileys & People',
  },
})

`no-literal-string-in-jsx`

Esta regra previne strings não traduzidas em JSX.

Motivo

É comum esquecer de envolver textos JSX em funções/componentes de tradução.
Atributos de acessibilidade (como aria-label) frequentemente são esquecidos nas traduções.

// WORKS
<Button>
  <FormattedMessage defaultMessage="Submit" />
</Button>
// WORKS
<Button>
  {customTranslateFn("Submit")}
</Button>
// WORKS
<input aria-label={intl.formatMessage({defaultMessage: "Label"})} />
// WORKS
<img
  src="/example.png"
  alt={intl.formatMessage({defaultMessage: "Image description"})}
/>
// FAILS
<Button>Submit</Button>
// FAILS
<Button>{'Submit'}</Button>
// FAILS
<Button>{`Te` + 's' + t}</Button>
// FAILS
<input aria-label="Untranslated label" />
// FAILS
<img src="/example.png" alt="Image description" />
// FAILS
<input aria-label={`Untranslated label`} />

Este linter reporta literais de texto ou expressões de string, incluindo concatenações nos filhos JSX. Também verifica atributos JSX personalizáveis.

Exemplo

import formatjs from 'eslint-plugin-formatjs'

export default [
  {
    plugins: {
      formatjs,
    },
    rules: {
      'formatjs/no-literal-string-in-jsx': [
        2,
        {
          // Include or exclude additional prop checks (merged with the default checks)
          props: {
            include: [
              // picomatch style glob pattern for tag name and prop name.
              // check `name` prop of `UI.Button` tag.
              ['UI.Button', 'name'],
              // check `message` of any component.
              ['*', 'message'],
            ],
            // Exclude will always override include.
            exclude: [
              // do not check `message` of the `Foo` tag.
              ['Foo', 'message'],
              // do not check aria-label and aria-description of `Bar` tag.
              ['Bar', 'aria-{label,description}'],
            ],
          },
        },
      ],
    },
  },
]

As props verificadas por padrão são:

{
  include: [
    // check aria attributes that the screen reader announces.
    ['*', 'aria-{label,description,details,errormessage}'],
    // check placeholder and title attribute of all native DOM elements.
    ['[a-z]*([a-z0-9])', '(placeholder|title)'],
    // check alt attribute of the img tag.
    ['img', 'alt'],
  ],
  exclude: []
}

`no-literal-string-in-object`

Esta regra previne strings não traduzidas em propriedades de objeto específicas.

Motivo

É fácil esquecer de envolver strings literais em funções de tradução, quando definidas em campos de objeto como {label: "Untranslated label"}.

const options = () => [
  // FAILS
  {value: 'chocolate', label: 'Chocolate'},
  // WORKS
  {
    value: 'strawberry',
    label: intl.formatMessage({defaultMessage: 'Strawberry'}),
  },
  // WORKS, custom translation function
  {
    value: 'mint',
    label: customTranslateFn('Mint'),
  },
  // FAILS, string concatenation
  {
    value: 'coconut',
    label: 'Coconut' + intl.formatMessage({defaultMessage: 'Ice Cream'}),
  },
  // FAILS, template literal
  {
    value: 'mango',
    label: `Mango ${intl.formatMessage({defaultMessage: 'Ice Cream'})}`,
  },
  // FAILS, conditional rendering
  {
    value: 'recommended',
    label: feelLikeSour
      ? intl.formatMessage({defaultMessage: 'Lime'})
      : 'Vanilla',
  },
]

const MyComponent = () => <Select options={options()} />

Este linter reporta literais de texto ou expressões de string em propriedades de objeto personalizáveis.

Exemplo

import formatjs from 'eslint-plugin-formatjs'

export default [
  {
    plugins: {
      formatjs,
    },
    rules: {
      'formatjs/no-literal-string-in-object': [
        'warn',
        {
          // The object properties to check for untranslated literal strings, default: ['label']
          include: ['label'],
        },
      ],
    },
  },
]

`no-multiple-whitespaces`

Esta regra impede múltiplos espaços consecutivos nas mensagens.

Motivo

Espaços consecutivos são tratados de forma inconsistente entre localidades.
Evita quebras de linha \ em strings JS que geram espaços inadequados.

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`

Esta regra impede múltiplos plurais aninhados na mesma mensagem.

Motivo

Plurais aninhados são complexos para tradução e alguns fornecedores não os suportam.

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`

Esta regra impede o uso de offset em regras de plural.

Motivo

Offset adiciona complexidade lógica que alguns fornecedores de tradução não suportam.

import {defineMessages} from 'react-intl'

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

`enforce-id`

Esta regra exige a definição de ID gerado no MessageDescriptor.

Motivo

Pipelines podem impor geração automática/manual de IDs no nível do linter (autocorreção para inserir ID gerado automaticamente) garantindo esse comportamento.

import {defineMessages} from 'react-intl';

const messages = defineMessages({
  // PASS
  foo: {
    id: '19shaf'
    defaultMessage: '{var, plural, one{one} other{other}}',
  },
  // FAILS
  bar: {
    id: 'something',
    defaultMessage: '{var, plural, offset:1 one{one} other{other}}',
  },
  // FAILS
  bar: {
    defaultMessage: '{var, plural, offset:1 one{one} other{other}}',
  },
});

Opções

import formatjs from 'eslint-plugin-formatjs'

export default [
  {
    plugins: {
      formatjs,
    },
    rules: {
      'formatjs/enforce-id': [
        'error',
        {
          idInterpolationPattern: '[sha512:contenthash:base64:6]',
        },
      ],
    },
  },
]

idInterpolationPattern: Padrão para validação do ID
idWhitelist: Array de strings com expressões regulares. Permite IDs personalizados na lista de permissões. Exemplo: '\\.' permite qualquer ID contendo ponto; '^payment_.*' permite IDs com prefixo payment_. Atenção: barras invertidas \ em strings devem ser escapadas com barra invertida adicional.

`no-invalid-icu`

Bloqueia strings dentro de defaultMessage sintaticamente inválidas.

Motivo

É fácil ignorar strings que parecem corretas para desenvolvedores mas são inválidas na sintaxe ICU. Exemplo que geraria erro no eslint:

formatMessage(
  {
    defaultMessage: '{count, plural one {#} other {# more}}', //Missing a comma!
  },
  {
    count: 1,
  }
)

`no-id`

Bloqueia definição explícita de ID em MessageDescriptor.

Motivo

Recomendamos geração automática de IDs por estes motivos. Esta regra garante que nenhum ID explícito seja definido.

`no-complex-selectors`

Garante que sentenças não sejam excessivamente complexas. Complexidade é determinada pelo número de strings geradas ao "achatar" a sentença considerando seus seletores. Exemplo:

I have {count, plural, one{a dog} other{many dogs}}

tem complexidade 2 pois o achatamento do seletor plural resulta em 2 sentenças: I have a dog e I have many dogs. O limite padrão é 20 (baseado em referência da Smartling).

Opções

import formatjs from 'eslint-plugin-formatjs'

export default [
  {
    plugins: {
      formatjs,
    },
    rules: {
      'formatjs/no-complex-selectors': [
        'error',
        {
          limit: 3,
        },
      ],
    },
  },
]

`no-useless-message`

Bloqueia mensagens que não requerem tradução.

Motivo

Mensagens como {test} não são acionáveis por tradutores. O código deve referenciar test diretamente.

`prefer-formatted-message`

Prefira <FormattedMessage> em vez do imperativo intl.formatMessage(...) quando aplicável.

// Bad
<p>
  {intl.formatMessage({defaultMessage: 'hello'})}
</p>

// Good
<p>
  <FormattedMessage defaultMessage="hello" />
</p>

Motivo

Estilo de código consistente em JSX e menor poluição sintática.

`prefer-pound-in-plural`

Use # no argumento plural para referenciar a contagem em vez de repetir o argumento.

// Bad
I have {count} {
  count, plural,
    one {apple}
    other {apples}
  }
}
// Good
I have {
  count, plural,
    one {# apple}
    other {# apples}
  }
}

// Bad
I have {
  count, plural,
    one {{count} apple}
    other {{count} apples}
  }
}
// Good
I have {
  count, plural,
    one {# apple}
    other {# apples}
  }
}

// Bad
I won the {ranking}{
  count, selectordinal,
    one {st}
    two {nd}
    few {rd}
    other {th}
} place.
// Good
I won the {ranking}{
  count, selectordinal,
    one {#st}
    two {#nd}
    few {#rd}
    other {#th}
} place.

Motivo

Mensagens mais concisas.
Garante formatação correta de números como valores numéricos.

Uso​

React​

Vue​

Configurações Compartilhadas​

formatjs.additionalFunctionNames​

formatjs.additionalComponentNames​

Configurações Compartilháveis​

Exemplo​

Regras Disponíveis​

blocklist-elements​

Motivo​

Elementos disponíveis​

Exemplo​

enforce-description​

Motivo​

Opções​

enforce-default-message​

Motivo​

Opções​

enforce-placeholders​

Opções​

enforce-plural-rules​

Motivo​

Regras disponíveis​

Exemplo​

no-camel-case​

Motivo​

no-missing-icu-plural-one-placeholders​

Motivo​

no-emoji​

Motivo​

no-literal-string-in-jsx​

Motivo​

Exemplo​

no-literal-string-in-object​

Motivo​

Exemplo​

no-multiple-whitespaces​

Motivo​

no-multiple-plurals​

Motivo​

no-offset​

Motivo​

enforce-id​

Motivo​

Opções​

no-invalid-icu​

Motivo​

no-id​

Motivo​

no-complex-selectors​

Opções​

no-useless-message​

Motivo​

prefer-formatted-message​

Motivo​

prefer-pound-in-plural​

Motivo​

Uso

React

Vue

Configurações Compartilhadas

`formatjs.additionalFunctionNames`

`formatjs.additionalComponentNames`

Configurações Compartilháveis

Exemplo

Regras Disponíveis

`blocklist-elements`

Motivo

Elementos disponíveis

Exemplo

`enforce-description`

Motivo

Opções

`enforce-default-message`

Motivo

Opções

`enforce-placeholders`

Opções

`enforce-plural-rules`

Motivo

Regras disponíveis

Exemplo

`no-camel-case`

Motivo

`no-missing-icu-plural-one-placeholders`

Motivo

`no-emoji`

Motivo

`no-literal-string-in-jsx`

Motivo

Exemplo

`no-literal-string-in-object`

Motivo

Exemplo

`no-multiple-whitespaces`

Motivo

`no-multiple-plurals`

Motivo

`no-offset`

Motivo

`enforce-id`

Motivo

Opções

`no-invalid-icu`

Motivo

`no-id`

Motivo

`no-complex-selectors`

Opções

`no-useless-message`

Motivo

`prefer-formatted-message`

Motivo

`prefer-pound-in-plural`

Motivo