Allow developers to create attribute filters for elements wrapped in <Localized>

[stasm]

Part of #103.

Right now <Localized> will apply all attributes found in the translation to the element wrapped inside of it. This may potentially override important props.

We should allow developers to control which attributes will be applied. For the initial release of overlays in fluent-react I think it's OK to err on the side of explicitness and only allow attributes which are explicitly declared by the developer.

button = This button has a title attribute.
    .title = Title
    .other = This attribute will not be applied to the translation.

<Localized id="button" attrs="title">
    <button>{'This button has a title attribute.'}</button>
</Localized>

What should be the type of the attrs prop?

• A string, ssimilar to className: attrs="title placeholder".
• An array: attrs={["title", "placeholder"]}.

[stasm]

@hkasemir, I think this will be useful for your extraction script. I saw you relied on data-l10n-attrs but that's specific to fluent-dom. For fluent-react we can do something more idiomatic :)

[hkasemir]

Very cool!
I would prefer an array.

[stasm]

Some time in the future we could build a list of good defaults, at least for the HTML elements. Something similar to LOCALIZABLE_ATTRIBUTES in fluent-dom.

fluent.js/fluent-dom/src/overlay.js

Lines 18 to 42 in 8c4afcc

	const LOCALIZABLE_ATTRIBUTES = {
	'http://www.w3.org/1999/xhtml': {
	global: ['title', 'aria-label', 'aria-valuetext', 'aria-moz-hint'],
	a: ['download'],
	area: ['download', 'alt'],
	// value is special-cased in isAttrNameLocalizable
	input: ['alt', 'placeholder'],
	menuitem: ['label'],
	menu: ['label'],
	optgroup: ['label'],
	option: ['label'],
	track: ['label'],
	img: ['alt'],
	textarea: ['placeholder'],
	th: ['abbr']
	},
	'http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul': {
	global: [
	'accesskey', 'aria-label', 'aria-valuetext', 'aria-moz-hint', 'label'
	],
	key: ['key', 'keycode'],
	textbox: ['placeholder'],
	toolbarbutton: ['tooltiptext'],
	}
	};

With these defaults built into fluent-react, the attrs prop could amend the defaults on a per-element basis. We could use an object of boolean values where:

• true means allow this attribute even if it's forbidden by default,
• false means forbid this attribute even if it's allowed by default.

<Localized id="input" attrs={{title: true, placeholder: false}}>
    <input placeholder="Not Localizable" />
</Localized>

[stasm]

That said, I don't see much of a use-case for forbidding an attribute that's allowed by default with attrname: false. The defaults should already be very conservative and safe. @Pike, @zbraniecki — do you have an opinion on this?

[zbraniecki]

I have not seen a good example where a default should be disallowed but then again, we mostly worked with HTML which has a standardized list. WC and React may not.

[hkasemir]

One thing that I have found particularly useful is that with react, the attributes have allowed for localizing props of react components that aren't anything like html. For example

<Localized id="favorites_widget" attrs={["description", "header"]}>
    <Widget
      header="Your Favorite Items"
      description="A list of things you've told us you like"
    />
</Localized>

favorites_widget = 
    .header = Your Favorite Items
    .description = A list of things you've told us you like

How would this play into the 'allowed' list? As a dev, I really like this flexibility, rather than having to pass in localization IDs to the widget, or using getString for the props.

[stasm]

Yeah, I definitely agree that's useful. The default list of localizable attributes only makes sense for known HTML attributes. To @zbraniecki's point, for web components and React elements we simply can't know which attributes are localizable. It's a similar problem to the one styled-components have (cf. styled-components/styled-components#439 (comment)).

The HTML5 spec defines title an a few others as global attributes. It means they can be applied to any HTML element. This makes me think that <Localized> should by default allow title on any wrapped React element (HTML or not). Using an object as the value of attrs will make it possible to forbid localizing title with attrs={{title: false}} in some rare cases.

Here's your example rewritten to use an object as the value of attrs. I reads pretty clear to me.

<Localized id="favorites_widget" attrs={{description: true, header: true}}>
    <Widget
      header="Your Favorite Items"
      description="A list of things you've told us you like"
    />
</Localized>

Using an object with attribute names as keys and booleans as values has two more advantages:

• it's explicit, and
• it lends itself well to composition.

import {Localized} from 'fluent-react';

function LocalizedWidget(props) {
    // `header` is a localizable attribute of Widget
    return <Localized {...props} attrs={{header: true, ...props.attrs}} />;
}

function MyApp(props) {
    // Forbid localizing `header` here just this once.
    return <LocalizedWidget attrs={{header: false}}> … </LocalizedWidget>;
}