fluent-react 0.6.0

  - Allow limited markup in translations. (#101)

    Translations in Fluent can now include simple HTML-like markup. Elements
    found in translations will be matched with props passed to `<Localized>`.
    These props must be React elements. Their content will be replaced by the
    localizable content found for the corrensponding markup in the
    translation.

    This is a breaking change from `fluent-react` 0.4.1. See migration notes
    below.

    ```properties
    send-comment = <confirm>Send</confirm> or <cancel>go back</cancel>.
    ```

    ```js
    <Localized
        id="send-comment"
        confirm={
            <button onClick={sendComment}></button>
        }
        cancel={
            <Link to="/"></Link>
        }
    >
        <p>{'<confirm>Send</confirm> or <cancel>go back</cancel>.'}</p>
    </Localized>
    ```

    The rendered result will include the props interpolated into the
    translation:

    ```js
    <p>
        <button onClick={sendComment}>Send</button> or <Link to="/">go back</Link>.
    </p>
    ```

    When naming markup elements it's possible to use any name which is a
    valid prop name. Translations containing markup will be parsed using a
    hidden `<template>` element. It creates a safe inert `DocumentFragment`
    with a hierarchy of text nodes and HTML elements. Any unknown elements
    (e.g. `cancel` in the example above) are parsed as `HTMLUnknownElements`.
    `fluent-react` then tries to match all elements found in the translation
    with props passed to the `<Localized>` component. If a match is found,
    the element passed as a prop is cloned with the translated text content
    taken from the `DocumentFragment` used as `children`.

  - Filter props with <Localized attrs={{…}}>. (#139, #141)

    The `<Localized>` component now requires the `attrs` prop to set any
    localized attributes as props on the wrapped component. `attrs` should be
    an object with attribute names as keys and booleans as values.

    ```jsx
    <Localized id="type-name" attrs={{placeholder: true}}>
        <input
            type="text"
            placeholder="Localizable placeholder"
            value={name}
            onChange={…}
        />
    </Localized>
    ```

    By default, if `attrs` is not passed, no attributes will be set. This is
    a breaking change compared to the previous behavior: in `fluent-react`
    0.4.1 and before `<Localized>` would set _all_ attributes found in the
    translation.

If you're setting localized attributes as props of elements wrapped in
`<Localized>`, in `fluent-react` 0.6.0 you'll need to also explicitly allow
the props you're interested in using the `attrs` prop. This protects your
components from accidentally gaining props they aren't expecting or from
translations overwriting important props which shouldn't change.

```jsx
// BEFORE (fluent-react 0.4.1)
<Localized id="type-name">
    <input
        type="text"
        placeholder="Localizable placeholder"
        value={name}
        onChange={…}
    />
</Localized>
```

```jsx
// AFTER (fluent-react 0.6.0)
<Localized id="type-name" attrs={{placeholder: true}}>
    <input
        type="text"
        placeholder="Localizable placeholder"
        value={name}
        onChange={…}
    />
</Localized>
```

In `fluent-react` 0.4.1 it was possible to pass React elements as _external
arguments_ to localization via the `$`-prefixed props, just like you'd pass
a number or a date. This was a bad localization practice because it
resulted in the translation being split into multiple strings.

```properties
send-comment-confirm = Send
send-comment-cancel = go back
send-comment = { $confirmButton } or { $cancelLink }.
```

```jsx
// Bad practice. This won't work in fluent-react 0.6.0.
<Localized
    id="send-comment"
    $confirmButton={
        <Localized id="send-comment-confirm">
            <button onClick={sendComment}>{'Send'}</button>
        </Localized>
    }
    $cancelLink={
        <Localized id="send-comment-cancel">
            <Link to="/">{'go back'}</Link>
        </Localized>
    }
>
    <p>{'{ $confirmButton } or { $cancelLink}.'}</p>
</Localized>
```

`fluent-react` 0.6.0 removes support for this feature. It is no longer
possible to pass React elements as `$`-prefixed _arguments_ to translations.
Please migrate your code to use markup in translations and pass React
elements as _props_ to `<Localized>`.

In the example above, change `$confirmButton` to `confirm` and `$cancelLink`
to `cancel`. Note that you don't need to wrap the passed element in another
`<Localized>` anymore. In particular, you don't need to assign a new message
id for it. The text for this element will be taken from the `send-comment`
message which can now include the markup for the button and the link.

```properties
send-comment = <confirm>Send</confirm> or <cancel>go back</cancel>.
```

```jsx
// BEFORE (fluent-react 0.4.1)
<Localized
    id="send-comment"
    $confirmButton={
        <Localized id="send-comment-button">
            <button onClick={sendComment}>{'Send'}</button>
        </Localized>
    }
    $cancelLink={
        <Localized id="send-comment-cancel">
            <Link to="/">{'go back'}</Link>
        </Localized>
    }
>
    <p>{'{ $confirmButton } or { $cancelLink}.'}</p>
</Localized>
```

```jsx
// AFTER (fluent-react 0.6.0)
<Localized
    id="send-comment"
    confirm={
        <button onClick={sendComment}></button>
    }
    cancel={
        <Link to="/"></Link>
    }
>
    <p>{'<confirm>Send</confirm> or <cancel>go back</cancel>.'}</p>
</Localized>
```

`fluent-react` 0.6.0 works best with `fluent` 0.6.0. It might still work with
`fluent` 0.4.x but passing elements as `$`-prefixed arguments to translations
will break your app. You might also run into other issues with translations
with attributes and no values. Upgrading your code to [`fluent` 0.6.0][] and
your localization files to [Fluent Syntax 0.5][] is the best way to avoid
troubles.

[`fluent` 0.6.0]: https://github.com/projectfluent/fluent.js/releases/tag/fluent%400.6.0
[Fluent Syntax 0.5]: https://github.com/projectfluent/fluent/releases/tag/v0.5.0

Author: stasm

fluent-react/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## fluent-react 0.6.0 (Unreleased)
+## fluent-react 0.6.0 (February 1, 2018)
 
   - Allow limited markup in translations. (#101)
 
@@ -50,7 +50,7 @@
     the element passed as a prop is cloned with the translated text content
     taken from the `DocumentFragment` used as `children`.
 
-  - Filter props set by translations with <Localized attrs={{…}}>.
+  - Filter props with <Localized attrs={{…}}>. (#139, #141)
 
     The `<Localized>` component now requires the `attrs` prop to set any
     localized attributes as props on the wrapped component. `attrs` should be
@@ -74,6 +74,8 @@
 
 #### Migrating from `fluent-react` 0.4.1 to 0.6.0
 
+##### Add attrs to Localized.
+
 If you're setting localized attributes as props of elements wrapped in
 `<Localized>`, in `fluent-react` 0.6.0 you'll need to also explicitly allow
 the props you're interested in using the `attrs` prop. This protects your
@@ -104,6 +106,8 @@ translations overwriting important props which shouldn't change.
 </Localized>
 ```
 
+##### Don't pass elements as $arguments.
+
 In `fluent-react` 0.4.1 it was possible to pass React elements as _external
 arguments_ to localization via the `$`-prefixed props, just like you'd pass
 a number or a date. This was a bad localization practice because it
@@ -184,6 +188,18 @@ send-comment = <confirm>Send</confirm> or <cancel>go back</cancel>.
 </Localized>
 ```
 
+##### Use fluent 0.6.0+.
+
+`fluent-react` 0.6.0 works best with `fluent` 0.6.0. It might still work with
+`fluent` 0.4.x but passing elements as `$`-prefixed arguments to translations
+will break your app. You might also run into other issues with translations
+with attributes and no values. Upgrading your code to [`fluent` 0.6.0][] and
+your localization files to [Fluent Syntax 0.5][] is the best way to avoid
+troubles.
+
+[`fluent` 0.6.0]: https://github.com/projectfluent/fluent.js/releases/tag/fluent%400.6.0
+[Fluent Syntax 0.5]: https://github.com/projectfluent/fluent/releases/tag/v0.5.0
+
 ## fluent-react 0.4.1 (June 30, 2017)
 
   - Relax the constraint on Localized only being valid as descendants of

fluent-react/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fluent-react",
   "description": "Fluent bindings for React",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "homepage": "http://projectfluent.org",
   "author": "Mozilla <l10n-drivers@mozilla.org>",
   "license": "Apache-2.0",
@@ -32,7 +32,7 @@
     "node": ">=8.9.0"
   },
   "dependencies": {
-    "fluent": "^0.4.1 || ^0.6.0",
+    "fluent": "^0.4.0 || ^0.6.0",
     "prop-types": "^15.6.0"
   },
   "peerDependencies": {