A few inconsistencies in JSDoc formatting have been fixed throughout
the project. Many issues remain; these were just the few things that
were easy to fix with a regular expression.
The changes include:
* Using lower-case for primitive types, but capitalizing non-primitive
types
* Separating the parameter identifier and the description with a dash
* Omitting a dash between the return type and the return description
* Ensuring the parameter type is first and the identifier is second (in
a few places it was backwards)
* Using square brackets to denote when a parameter is optional, rather
than putting "(optional)" in the parameter description
* Including a type and identifier with every parameter
* Fixing inconsistent spacing, except where it's used for alignment
* Remove incorrectly formatted `@deprecated` tags that reference non-
existent properties
* Remove lone comment block without accompanying function
Additionally, one parameter was renamed for clarity.
This updated error message shows the key of the message instead of the
message text itself, followed by the locale code.
This will make it easier to filter messages we want to ignore in
Sentry. Currently it's difficult to filter because the message is
radically different for each locale. With this change, we can add a
filter and use a glob for the last part to filter it for all locales.
It's still important to include the locale code in the message, so that
we can catch cases where the message has the wrong number of
substitutions for a specific locale.
* Fix require-unicode-regexp issues
See [`require-unicode-regexp`](https://eslint.org/docs/rules/require-unicode-regexp) for more information.
This change enables `require-unicode-regexp` and fixes the issues raised by the rule.
* Remove case-insensitive flag from regexps
Previously the `getMessage` function would throw if a substitution was
falsey. Now it will accept any substitution, including `undefined`.
A substitution of `null` or `undefined` will still be reported to
Sentry and printed to the console as an error, but it will not
interrupt execution. Any `null` or `undefined` substitutions will be
rendered as empty strings.
Ideally we'd never pass in `null` or `undefined` as a substitution, but
in practice this sometimes just occurs breifly between renders, which
isn't a severe enough problem to justify crashing the UI.
The detection of React component substitutions has been updated as
well, to ensure that `null` values aren't counted as React
substitutions.
We were including the polyfill for the `Intl.RelativeTimeFormat` API,
but we weren't including any locale data. This polyfill doesn't work
without the locale data for whichever locale you're formatting.
The data for all locales we support is now included. The locale data
is loaded from disk as-needed (during app startup, and upon each change
in locale).
The `getMessage` function in `i18n-helper` was assuming that any
substitutions passed into the transaction function were used by the
corresponding localized message. However, some messages are
intentionally ignoring substitutions passed in. This was done to
simplify the UI logic, so the same substitutions could be passed in for
many different messages, even if some don't use them.
For example, `transactionCancelSuccess` is passed two substitutions but
only uses the second one. `transactionErrored` is passed in two, but
uses neither.
`getMessage` has been updated to no longer make that assumption. It
will now only throw an error if the localized message expects a
substitution that was not given. A given substitution that is unused
results in no error.
Previously all browser globals were allowed to be used anywhere by
ESLint because we had set the `env` property to `browser` in the ESLint
config. This has made it easy to accidentally use browser globals
(e.g. #8338), so it has been removed. Instead we now have a short list
of allowed globals.
All browser globals are now accessed as properties on `window`.
Unfortunately this change resulted in a few different confusing unit
test errors, as some of our unit tests setup assumed that a particular
global would be used via `window` or `global`. In particular,
`window.fetch` didn't work correctly because it wasn't patched by the
AbortController polyfill (only `global.fetch` was being patched).
The `jsdom-global` package we were using complicated matters by setting
all of the JSDOM `window` properties directly on `global`, overwriting
the `AbortController` for example.
The `helpers.js` test setup module has been simplified somewhat by
removing `jsdom-global` and constructing the JSDOM instance manually.
The JSDOM window is set on `window`, and a few properties are set on
`global` as well as needed by various dependencies. `node-fetch` and
the AbortController polyfill/patch now work as expected as well,
though `fetch` is only available on `window` now.
* Update i18n-helper to allow substitutions of react components and wrapping of translation substrings
* Simplify code in i18n-helper.js related to substitutions, including react substitutions.
* Remove wrapper support from i18n in favour of using translations in substitutions.
* Fix i18n-helper substitution logic: ensure correct index of substitution is applied
* Throw error if there are not enough substitutions for a translation phrase
* Adds unit tests for now i18n-helper substitution functionality
* Fix grammar, react element line spacing and test layout+readability in i18n-helper.test.js
* Specify type before parameter name
Various JSDoc `@param` entries were specified as `name {type}` rather
than `{type} name`.
A couple of `@return` entries have been given types as well.
* Use JSDoc optional syntax rather than Closure syntax
* Use @returns rather than @return
* Use consistent built-in type capitalization
Primitive types are lower-case, and Object is upper-case.
* Separate param/return description with a dash
Any missing messages in the `en` locale are now reported to Sentry as
errors. They are printed to the console as an error upon the first
encounter as well.
If a missing message is found during e2e testing, the error is thrown.
This will likely break the e2e test even if it isn't looking for
console errors, as the UI with the missing message will fail to render.
The `tOrDefault` method was updated to no longer attempt looking for
messages with a key that is a falsey value (e.g. `undefined`). There
are a few places where they key is determined dynamically, where it's
expected during the normal flow for it to be `undefined` sometimes.
In these cases we don't want the error to be thrown.
* Prevent multiple warnings for the same locale message
Our i18n helper issues warnings whenever a requested message is
missing. These warnings are helpful in assisting translation efforts,
but they can be distracting otherwise. They're especially problematic
for locales that are missing many messages. My browser ended up
crashing on more than one occasion due to the sheer volume of warnings.
The warning has been updated to only be issued once per missing key.
This required updating the method to pass in the current locale. The
current locale was added to the warning itself as well, which could be
helpful for cases where a message is missing in both the current locale
and the fallback ('en').
* Change locale and localeMessages as single action
Updating the current locale and the locale messages resulted in two
renders, and during the first the state was inconsistent (it would say
the locale had changed to the new one, but still be using the old set
of locale messages). Instead the locale is now updated with one atomic
action.
This was required after adding the locale to the missing locale message
warning, as otherwise it would say the message was missing from the
wrong locale.
