| Category: React / Miscellaneous |
| Watchers: 132 |
| Star: 13.8k |
| Fork: 1.4k |
| Last update: Sep 15, 2023 |
This repository is the home of FormatJS and related libraries.
Slack: Join us on Slack at formatjs.slack.com for help, general conversation and more
Development is currently being done against the latest Node LTS. This repository leverages Lerna for package management.
Releases can be done with the following steps:
> lerna publish
Cross-browser Testing Platform and Open Source <3 Provided by Sauce Labs
UPDATED: 2015-11-11
React Intl v2 has been in development for several months and the current release is v2.0.0-beta-1 โ the first v2 beta release โ v2 has been promoted from preview release to beta because we feel it's now feature complete and ready to move forward towards a release candidate once the test suite has been filled out and the docs have been updated.
With v1 being out almost a year we've received tons of great feedback from everyone using React Intl and with these changes we're addressing 20+ issues that have been raised โ they're label: fixed-by-v2. While 20-some issues doesn't seem like a lot, many of these are very long discussions fleshing out better ways to approach i18n in React and web apps in general. With v2 we're rethinking what it means to internationalize softwareโฆ
ECMA 402 has the following definition of internationalization:
"Internationalization of software means designing it such that it supports or can be easily adapted to support the needs of users speaking different languages and having different cultural expectations [...]"
The usual implementation looks something like this:
This ends up leading to an unpleasant dev experience and problems:
There's a great discussion in #89 on the problems listed above and how to resolve them. With v2, we've rethought this premise of needing to define strings external to the React Components where they're usedโฆ
Implementation of Internationalization with React Intl v2:
This new approach leads to a more pleasant dev experience and the following benefits:
React Intl v2 has a new message descriptor concept which is used to define your app's default messages/strings:
id: A unique, stable identifier for the messagedescription: Context for the translator about how it's used in the UIdefaultMessage: The default message (probably in English)The <FormattedMessage> component's props now map to a message descriptor, plus any values to format the message with:
<FormattedMessage
id="greeting"
description="Welcome greeting to the user"
defaultMessage="Hello, {name}! How are you today?"
values={{name: this.props.name}}
/>
defineMessages() can also be used to pre-declare messages which can then be formatted now or later:
const messages = defineMessages(
greeting: {
id: 'greeting',
description: 'Welcome greeting to the user',
defaultMessage: 'Hello, {name}! How are you today?',
}
});
<FormattedMessage {...messages.greeting} values={{name: this.props.name}} />
Now that your app's default messages can be declared and defined inside the React components where they're used, you'll need a way to extract them.
The extraction works via a Babel plugin: babel-plugin-react-intl. This plugin will visit all of your JavaScript (ES6) modules looking for ones which import either: FormattedMessage, FormattedHTMLMessage, or defineMessage from "react-intl". When it finds one of these being used, it will extract the default message descriptors into a JSON file and leave the source untouched.
Using the greeting example above, the Babel plugin will create a JSON file with the following contents:
[
{
"id": "greeting",
"description": "Welcome greeting to the user",
"defaultMessage": "Hello, {name}! How are you today?"
}
]
With the extracted message descriptors you can now aggregate and process them however you'd like to prepare them for your translators.
Once all of your app's default messages have been translated, you can provide them to React Intl via the new <IntlProvider> component (which you'd normally wrap around your entire app):
const esMessages = {
"greeting": "ยกHola, {name}! ยฟCรณmo estรกs hoy?"
};
ReactDOM.render(
<IntlProvider locale="es" messages={esMessages}>
<App />
</IntlProvider>,
document.getElementById('container')
);
Note: In v2 things have been simplified to use a flat messages object. Please let us know if you think this would be problematic. (See: https://github.com/yahoo/react-intl/issues/193#issuecomment-152019363)
Try: The Translations example in the repo to see how all this works (be sure to check the contents of the build/ dir after you run the build.)
Another great benefit to come out of this approach is automatic fallback to the default message if a translation is missing or something goes wrong when formatting the translated message. A major pain-point we faced at Yahoo which every app experienced was not wanting to wait for new translations to be finished before deploying, or placeholders like {name} getting translated to {nombre} accidentally.
Message formatting in v2 now follows this algorithm:
For v2, React Intl has been completely re-thought re-written here are the highlights of the major changes:
React Intl is useful for all apps, even those which only need to support one language. In v2 we've created a simpler model developer's building single-language apps to integrate React Intl. The message formatting features in React Intl are the most complex and are most useful for multi-language apps, but all apps will use pluralization.
In v2 the lower-level pluralization features that message formatting are built on are now exposed as a first-class feature. This allows a single-language app to have pluralization support without the complexity of messages:
<p>
Hello <b>{name}</b>, you have {' '}
<FormattedNumber value={unreadCount} /> {' '}
<FormattedPlural value={unreadCount}
one="message"
other="messages"
/>.
</p>
You can think of <FormattedPlural> like a switch statement on its value, with: zero, one, two, few, and many props as cases and other as the default case. This matches the standard ICU Pluralization rules.
Note: Both cardinal and ordinal formatting are supported via the style prop, cardinal is the default.
Try: The Hello World example in the repo to see <FormattedPlural> in action.
<IntlProvider>This is the new top-level component which your app's root component should be a child of. It replaces the adding the mixin to your app's root component and provides React Intl's API to decedents via React's component context. It takes the following props to configure the intl API and context (all optional):
locale: The user's current locale (now singular, defaults to "en")formats: Object of custom named format options for the current localemessages: {id: 'translation'} collection of translated messages for the current localedefaultLocale: The app's default locale used in message formatting fallbacks (defaults to "en")defaultFormats: Object of custom named format options for the defaultLocaleinitialNow: A reference time for "now" used on initial render of <FormattedRelative> components.For this component to work the context needs to be setup properly. In React 0.14 context switched to parent-based from owner-based, so <IntlProvider> must be your app's parent/ancestor in React 0.14. React Intl v2 will not support React 0.13.
<IntlProvider>
<App />
</IntlProvider>
Note: How there's no defaultMessages prop, that's because it's assumed the default message descriptors live co-located to where the messages are being formatted.
See: The Providing Translations to React Intl section above for how it's used.
There have been many discussions around customizing the rendering of the <Formatted*> components around styling, supporting extras props, and changing the <span> elements that they return. We think of <Fromatted*> components as representations of text.
Our guidance thus far has been to wrap them and style the wrapper. Thinking forward to a single React Intl for both React [Web] and React Native, we want to be more flexible. Also, issues come when rendering a <span> inside an SVG tree, and requires a <tspan>. To remedy this, in v2 all <Formatted*> components support function-as-child, which receives a React node type value. Which enables the following:
let now = Date.now();
<FormattedDate value={now}>
{(formattedNow) => (
<time dateTime={now} className="fancy-date">{formattedNow}</time>
)}
</FormattedDate>
Of course you can always do the following instead, and its valid (and recommended for this example):
let now = Date.now();
<time dateTime={now} className="fancy-date">
<FormattedDate value={now} />
</time>
The above will yield an inner <span>, and that's okay here. But sometimes it's not okay, e.g. when rending an <option> you should use the function-as-child pattern because you don't want the extra <span> since it'll be rendered as literal text:
let num = 10000;
<FormattedNumber value={num}>
{(formattedNum) => (
<option value={num}>{formattedNum}</option>
)}
</FormattedNumber>
This pattern can work well for targeted use-cases, but sometimes you just want to call an API to format some data and get a string back, e.g., when rending formatted messages in title or aria attributes; this is where using the new API might be a better choiceโฆ
The IntlMixin is gone! And there's a new API to replace it.
The API works very similar to the one provided by the old mixin, but it now live's on this.context.intl and is created by the <IntlProvider> component and can be passed to your custom components via props by wrapping custom components with injectIntl(). It contains all of the config values passed as props to <IntlProvider> plus the following format*(), all of which return strings:
formatDate(value, [options])formatTime(value, [options])formatRelative(value, [options])formatNumber(value, [options])formatPlural(value, [options])formatMessage(messageDescriptor, [values])formatHTMLMessage(messageDescriptor, [values])These functions are all bound to the props and state of the <IntlProvider> and are used under the hood by the <Formatted*> components. This means the formatMessage() function implements the automatic translation fallback algorithm (explained above).
injectIntl()This function is used to wrap a component and will inject the intl context object created by the <IntlProvider> as a prop on the wrapped component. Using the HOC factory function alleviates the need for context to be a part of the public API.
When you need to use React Intl's API in your component, you can wrap with with injectIntl() (e.g. when you need to format data that will be used in an ARIA attribute and you can't the a <Formatted*> component). To make sure its of the correct object-shape, React Intl v2 has an intlShape module export. Here's how you access and use the API:
import React, {Component, PropTypes} from 'react';
import {defineMessages, injectIntl, intlShape, FormattedMessage} from 'react-intl';
const messages = defineMessages({
label: {
id: 'send_button.label',
defaultMessage: 'Send',
},
tooltip: {
id: 'send_button.tooltip',
defaultMessage: 'Send the message'
}
});
class SendButton extends Component {
render() {
const {formatMessage} = this.props.intl;
return (
<button
onClick={this.props.onClick}
title={formatMessage(messages.tooltip)}
>
<FormattedMessage {...messages.label} />
</button>
);
}
}
SendButton.propTypes = {
intl : intlShape.isRequired,
onClick: PropTypes.func.isRequired,
};
export default injectIntl(SendButton);
<IntlProvider> uses an initialNow prop to stabilize the reference time when formatting relative times during the initial render. This prop should be set when rendering a universal/isomorphic React app on the server and client so the initial client render will match the server's checksum.
On the server, Date.now() should be captured before calling ReactDOM.renderToString() and passed to <IntlProvider>. This "now" value needs to be serialized to the client so it can also pass the same value to <IntlProvider> when it calls React.render().
Relatives times formatted via <FormattedRelative> will now "tick" and stay up to date over time. The <FormattedRelative> has an initialNow prop to match and override the same prop on <IntlProvider>. It also has a new updateInterval prop which accepts a number of milliseconds for the maximum speed at which relative times should be updated (defaults to 10 seconds).
Special care has been taken in the scheduling algorithm to display accurate information while reducing unnecessary re-renders. The algorithm will update the relative time at its next "interesting" moment; e.g., "1 minute ago" to "2 minutes ago" will use a delay of 60 seconds even if updateInterval is set to 1 second.
See: #186
React Intl requires that locale data be loaded and added to the library in order to support a locale. Previously this was done via modules which caused side-effects by automatically adding data to React Intl when they were loaded. This anti-pattern has been replaced with modules that export the locale data, and a new public addLocaleData() function which registers the locale data with the library.
This new approach will make it much simpler for developers whose apps only support a couple locales and they just want to bundle the locale data for those locales with React Intl and their app code. Doing would look this like:
import {addLocaleData} from 'react-intl';
import en from 'react-intl/locale-data/en';
import es from 'react-intl/locale-data/es';
import fr from 'react-intl/locale-data/fr';
addLocaleData(en);
addLocaleData(es);
addLocaleData(fr);
Now when this file is bundled, it will include React Intl with en, es, and fr locale data.
Note: The dist/locale-data/ has UMD files which expose the data at: ReactIntlLocaleData.<lang>. Previously the locale data files would automatically call addLocaleData() on the ReactIntl global. This decouples the loading of the locale data files from the loading of the library and allows them to be loaded async.
<script async src="/path/to/react-intl/dist/react-intl.min.js"></script>
<script async src="/path/to/react-intl/dist/locale-data/fr.js"></script>
<script>
window.addEventListener('load', function () {
ReactIntl.addLocaleData(ReactIntlLocaleData.fr);
});
</script>
This is just a preview release so there's still more work to do until the v2 final release, but we've already begun integrating this code into Yahoo apps that use React Intl.
shouldComponentUpdate() is needed.min.js filesWe'd love for you to try out this early version of React Intl v2 and give us feedback, it'll be much appreciated!
$ npm install react-intl@next
This PR aims at using the new context API introduced with react 16.3.1. It's 100% API compatible and tested.
3.0.0-beta-1As I understand injectIntl provides the imperative API inside a React component class, but I couldn't find a way to use that API ouside a component, for example in a helper or a utility class. Is there any way to do so?
There is upcoming change in React 16.3: New Version of Context
Is there any plan for new (probably major / may be minor) release of react-intl supporting this new API?
The only problem with usage in React Native is span inside components. React Native needs Text. We can fix it easily. Add textElement into intlConfigPropTypes.
// In React Native
<IntlProvider
textElement={Text}
// ...
/>
Then all components can use textElement from the context if available.
I was looking for an example that sets up i18n for anything other than english and shows how to create and setup translation files, but it looks like every example in the repo only sets up english and there are no translation files of any kind.
Am I missing something ?
@formatjs/[email protected]
Tested with @formatjs/[email protected] too and issues is still there
We have a message that looks like this which contains 2 plural rules and each makes use of the # hash placeholder to have the plural value as part of the message
<FormattedMessage
id="reproduction.example"
defaultMessage="{topicCount, plural, one {# topic} other {# topics}} and {noteCount, plural, one {# note} other {# notes}}"
description="Show when manager has completed all items for the upcoming 1-1"
values={{
topicCount: 1,
noteCount: 4,
}}
/>
When flatten is disable, we get the correct message
Here is the extracted message
"reproduction.example": {
"description": "Show when manager has completed all items for the upcoming 1-1",
"message": "{topicCount, plural, one {# topic} other {# topics}} and {noteCount, plural, one {# note} other {# notes}}"
}
And this is what is rendered on the page
When flateen is enable, the message is incorrect
Here is the extracted message. Note that the extracted message became plural rules nested within plural rules
"reproduction.example": {
"description": "Show when manager has completed all items for the upcoming 1-1",
"message": "{topicCount,plural,one{{noteCount,plural,one{# topic and # note} other{# topic and # notes}}} other{{noteCount,plural,one{# topics and # note} other{# topics and # notes}}}}"
}
And this is what is rendered on the page for that message. It looks like because in the extracted message, as hash placedholer is being used, # ended up using the value of noteCount as we have plural rule nested in another one
For your reference, this is how we are using @formatjs/cli-lib. This is a small portion of the code that we have as we don't want to share everything for security reasons but should be enough.
import { extract } from "@formatjs/cli-lib"
const files = await glob("{src,pages}/**/*.ts*", {
ignore: ["**/*.d.ts", "**/*.{spec,test}.tsx"],
})
const extracted = await extract(files, {
format: "smartling",
flatten: true,
})
You can reproduce based on the above information
Please include a codesandbox URL if possible
Steps to reproduce the behavior: This is included in the description.
We expect after flatten, the messages should still work with hash placeholder with multi plural rules
I have attached screenshots above as it is easier to follow the sequence there
Add any other context about the problem here.
Unable to install into existing project due to dependancy issues with typescript 5.2.2. Log output below
npm ERR! code ERESOLVE npm ERR! ERESOLVE could not resolve npm ERR! npm ERR! While resolving: [email protected] npm ERR! Found: [email protected] npm ERR! node_modules/typescript npm ERR! peer typescript@">= 2.7" from [email protected] npm ERR! node_modules/fork-ts-checker-webpack-plugin npm ERR! fork-ts-checker-webpack-plugin@"^6.5.0" from [email protected] npm ERR! node_modules/react-dev-utils npm ERR! react-dev-utils@"^12.0.1" from [email protected] npm ERR! node_modules/react-scripts npm ERR! react-scripts@"5.0.1" from the root project npm ERR! peer typescript@">=2.8.0 || >= 3.2.0-dev || >= 3.3.0-dev || >= 3.4.0-dev || >= 3.5.0-dev || >= 3.6.0-dev || >= 3.6.0-beta || >= 3.7.0-dev || >= 3.7.0-beta" from [email protected] npm ERR! node_modules/tsutils npm ERR! tsutils@"^3.21.0" from @typescript-eslint/[email protected] npm ERR! node_modules/@typescript-eslint/eslint-plugin npm ERR! @typescript-eslint/eslint-plugin@"^5.5.0" from [email protected] npm ERR! node_modules/eslint-config-react-app npm ERR! eslint-config-react-app@"^7.0.1" from [email protected] npm ERR! node_modules/react-scripts npm ERR! 1 more (eslint-plugin-jest) npm ERR! tsutils@"^3.21.0" from @typescript-eslint/[email protected] npm ERR! node_modules/@typescript-eslint/type-utils npm ERR! @typescript-eslint/type-utils@"5.62.0" from @typescript-eslint/[email protected] npm ERR! node_modules/@typescript-eslint/eslint-plugin npm ERR! @typescript-eslint/eslint-plugin@"^5.5.0" from [email protected] npm ERR! node_modules/eslint-config-react-app npm ERR! 1 more (eslint-plugin-jest) npm ERR! 1 more (@typescript-eslint/typescript-estree) npm ERR! 3 more (the root project, react-intl, @formatjs/intl) npm ERR! npm ERR! Could not resolve dependency: npm ERR! peerOptional typescript@"^3.2.1 || ^4" from [email protected] npm ERR! node_modules/react-scripts npm ERR! react-scripts@"5.0.1" from the root project npm ERR! npm ERR! Conflicting peer dependency: [email protected] npm ERR! node_modules/typescript npm ERR! peerOptional typescript@"^3.2.1 || ^4" from [email protected] npm ERR! node_modules/react-scripts npm ERR! react-scripts@"5.0.1" from the root project npm ERR!
Existing project using the following packages listed below. Project does not introduce any non-public libraries that could be interfering with anything. Simply posting the full dependancy list just in case, I don't think anything here will actually be helpful other than the typescript version. @emotion/react ^11.11.1 @emotion/styled ^11.11.0 @emotion/types ^0.7.0 @mui/icons-material ^5.14.9 @mui/material ^5.14.9 @mui/types ^7.2.4 @reduxjs/toolkit ^1.9.5 @testing-library/jest-dom ^5.17.0 @testing-library/react ^13.4.0 @testing-library/user-event ^13.5.0 @types/enzyme ^3.10.13 @types/jest ^29.5.5 @types/node ^20.6.2 @types/react ^18.2.21 @types/react-dom ^18.2.7 @types/react-redux ^7.1.26 @types/react-router ^5.1.20 @types/react-router-dom ^5.3.3 axios ^1.5.0 enzyme ^3.11.0 formik ^2.4.4 moment ^2.29.4 react ^18.2.0 react-dom ^18.2.0 react-redux ^8.1.2 react-router ^6.16.0 react-router-dom ^6.16.0 react-scripts 5.0.1 typescript ^5.2.2 web-vitals ^2.1.4
cli-lib
Running compile-folder with the --skip-errors flag (as documented here) throws error: unknown option '--skip-errors'
Looks like that option is not defined for the compile-folder command in packages/cli-lib/src/cli.ts
Hi, is there any way change the behaviour for parsing quotes when using Intl MessageFormat?
This section in the docs says:
Supports escape sequences for message syntax chars, e.g.: "'{foo}'" will output: "{foo}" in the formatted output instead of interpreting it as a foo argument.
const msg = new IntlMessageFormat("Email: '{email}'").format({email: "[email protected]"})
// -> Email: {email}
const msg = new IntlMessageFormat("Email: '{email}'").format({email: "[email protected]"})
// -> Email: '[email protected]'
How can I accomplish the desired behaviour? Thanks.
Just changed the format.
This PR contains the following updates:
| Package | Change | Age | Adoption | Passing | Confidence |
|---|---|---|---|---|---|
| @โbazel/ibazel | 0.16 -> 0.23 | |
|
|
|
๐ Schedule: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).
๐ฆ Automerge: Disabled by config. Please merge this manually once you are satisfied.
โป Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.
๐ Ignore: Close this PR and you won't be reminded about this update again.
This PR has been generated by Mend Renovate. View repository job log here.
Note: Version bump only for package vue-intl
Note: Version bump only for package react-intl
Note: Version bump only for package intl-messageformat
Note: Version bump only for package babel-plugin-formatjs
Note: Version bump only for package @formatjs/intl
Note: Version bump only for package @formatjs/intl-datetimeformat
