fluent-react 0.6.0 (February 1, 2018)

• 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.

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

  <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:

  <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 . (#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.

  <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.

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 components from accidentally gaining props they aren't expecting or from translations overwriting important props which shouldn't change.

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

// AFTER (fluent-react 0.6.0)
<Localized id="type-name" attrs={{placeholder: true}}>
    <input
        type="text"
        placeholder="Localizable placeholder"
        value={name}
        onChange={…}
    />
</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 resulted in the translation being split into multiple strings.

# Bad practice. This won't work in fluent-react 0.6.0.
send-comment-confirm = Send
send-comment-cancel = go back
send-comment = { $confirmButton } or { $cancelLink }.

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

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

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

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

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 (January 31, 2018)

• Implement Fluent Syntax 0.5.

  • Add support for terms.
  • Add support for #, ## and ### comments.
  • Remove support for tags.
  • Add support for = after the identifier in message and term defintions.
  • Forbid newlines in string expressions.
  • Allow trailing comma in call expression argument lists.

  In fluent 0.6.x the new Syntax 0.5 is supported alongside the old Syntax 0.4. This should make migrations easier. The parser will correctly parse Syntax 0.4 comments (prefixed with //), sections and message definitions without the = after the identifier. The one exception are tags which are no longer supported. Please use attributed defined on terms instead.

• Add mapContextAsync. (#125)

  This is the async counterpart to mapContextSync. Given an async iterable of MessageContext instances and an array of ids (or a single id), it maps each identifier to the first MessageContext which contains the message for it.

  An ordered interable of MessageContext instances can represent the current negotiated fallback chain of languages. This iterable can be used to find the best existing translation for a given identifier.

  The iterable of MessageContexts can now be async, allowing code like this:

  async formatString(id, args) {
      const ctx = await mapContextAsync(contexts, id);
  
      if (ctx === null) {
          return id;
      }
  
      const msg = ctx.getMessage(id);
      return ctx.format(msg, args);
  }

  The iterable of MessageContexts should always be wrapped in CachedIterable to optimize subsequent calls to mapContextSync and mapContextAsync.

  Because mapContextAsync uses asynchronous iteration you'll likely need the regenerator runtime provided by babel-polyfill to run the compat builds of fluent.

• Expose the ftl dedent helper.

  The ftl template literal tag can be used to conveniently include FTL snippets in other code. It strips the common indentation from the snippet allowing it to be indented on the level dictated by the current code indentation.

  ctx.addMessages(ftl`
      foo = Foo
      bar = Bar
  );

• Remove MessageContext.formatToParts.

  It's only use-case was passing React elements as arguments to translations which is now possible thanks to DOM overlays (#101).

• Rename FluentType.valueOf to FluentType.toString.

  Without MessageContext.formatToParts, all use-cases for FluentType.valueOf boil down to stringification.

• Remove FluentType.isTypeOf.

  fluent-react's markup overlays (#101) removed the dependency on fluent's FluentType which was hardcoded as an import from fluent/compat. Without this dependency all imports from fluent are in the hands of developers again and they can decide to use the ES2015+ or the compat builds as they wish. As long as they do it consistently, regular instanceof checks will work well.

fluent-syntax 0.6.0 (January 31, 2018)

• Implement Fluent Syntax 0.5.

  • Add support for terms.
  • Add support for #, ## and ### comments.
  • Remove support for tags.
  • Add support for = after the identifier in message and term defintions.
  • Forbid newlines in string expressions.
  • Allow trailing comma in call expression argument lists.

  In fluent-syntax 0.6.x the new Syntax 0.5 is supported alongside the old Syntax 0.4. This should make migrations easier.

  FluentParser will correctly parse Syntax 0.4 comments (prefixed with //), sections and message definitions without the = after the identifier. The one exception are tags which are no longer supported. Please use attributed defined on terms instead.

  FluentSerializer always serializes using the new Syntax 0.5.

• Add AST.Placeable (#64)

  Added in Syntax Spec 0.4, AST.Placeable provides exact span data about the opening and closing brace of placeables.

• Expose FluentSerializer.serializeExpression. (#134)

• Serialize standalone comments with surrounding white-space.

• Allow blank lines inside of messages. (#76)

• Trim trailing newline from Comments. (#77)