Open jwhitlock opened 7 years ago
Agreed, I was relying on the previous behaviour of wrapping the initial
literal with <code>
also.
https://github.com/ben-eb/postcss-reduce-initial/blob/master/src/acquire.js#L20-L21
Thanks for filing this John! We need a design decision here. I'm leaning towards option two "Prefix for prose value", but I have no strong feeling. Any other opinions?
I think I prefer option 2 as well, as it seems like the least amount of effort to maintain and update, and cognitive overhead to understand. There is little in it between 2 and 3, but the syntax of 2 is shorter and easier. I think 1 risks being a bit more confusing than necessary - needing to get the right key as well as the right value.
Two votes for using a prefix, so let's go down that path.
The goal is:
l10n/css.json
, or eventually a gettext string.The implementer would write something like:
if (property === "initial") {
if (value.indexOf('_prose_:') === 0 {
key = value.split('_prose_:')[1];
return l10n_strings_replace(locale, key);
} else {
return '<code>' + value + '</code>';
}
}
I'm not sure _prose_:
should be the marker that ships. Here's some options that spring to mind:
"initial": "_prose_:noPracticalInitialValue"
"initial": "_prose_key_:noPracticalInitialValue"
"initial": "_text_:noPracticalInitialValue"
"initial": "_text_key_:noPracticalInitialValue"
"initial": "_text_description_:noPracticalInitialValue"
"initial": "_l10n_key_:noPracticalInitialValue"
Any favorites? Other ideas?
__l10nkey:noPracticalInitialValue
?
(I'm thinking of __compat
which we use over in https://github.com/mdn/browser-compat-data )
"initial": ":noPracticalInitialValue"
or "initial": "!noPracticalInitialValue"
). Anyway, any prefix looks like a hack, not a solution.literal
type object should be an optional and a regular string should be an alternative (i.e. "initial": "value"
and "initial": { "type": "literal", "value": "value" }
should be the same).When choosing a solution, it's worth considering that the solution must be scalable. The problem described also applies to other fields. For example, media
field for all
property contains "noPracticalMedia"
value (I suppose "none"
and "visualInContinuousMediaNoEffectInOverflowColumns"
values are special cases too). Therefore solution based on additional keys in definition doesn't work since we'll get too many extra fields.
So my choice is using an object definition for special cases and left others as is. It's better over solution with prefixes for some reasons. One of them, we can define a JSON schema to validate it (I think it would be great to have a schema anyway).
PS While writing the comment, I found some media
values have the same problem. I think it should be fixed and I've created a separate issue for that #63
I think we all agree that additional keys is not the solution, no need for further beating of that straw man.
I prefer __l10nkey:
as a prefix because:
!
is a boolean operator in JavaScript!important
rule in CSS:active
, :link
, :hover
, and :visited
. ::first-letter
is a current value in border-width
and others.I don't like optional objects because I don't like having two ways to say the same thing. It makes parsing more complex and can lead to ambiguities. However, it would be an acceptable compromise for readability, since we're hoping for manual contributions. I agree that the short version should imply literal values.
JSON Schema is good for structural validation, but I don't think it is sufficient for validation of these keys into the string structure. For example, I think JSON Schema would be OK with "initial": {"type": "l10nkey", "value": "itsATrap"}
, even if the key "itsATrap"
doesn't appear in l10n/css.json. An additional validator is required, and that validator works just as well with prefixes as it does with expanded objects.
That's a long way of saying my preference is still a prefix of "__l10nkey:"
, and writing a validator in addition to the JSON Schema.
See #67 for what the css/properties.json would look like with the prefixes applied everywhere. Some notable things:
yes
, no
, and all
are lookup keys, which may be unexpected.-webkit-border-before
and possibly others have a mixed list:
"initial": [
"border-width",
"border-style",
"__l10nkey:color"
],
My thoughts about changes in #67:
l10n.json
so prefix to be confusing.media
, stays untouched.initial
, computed
etc) it's a list of references to properties rather than a l10n key, so "__l10nkey:color"
in your example is incorrect.Thanks for your feedback. I think some of it would be clearer on #67, where you can add your comments to specific lines of the changed JSON, and I can refine the PR to be more correct. There's some issues that you have identified that need fixed.
After thinking about it for a while, I'm 👎 on using the prefix, and I like the idea of a different key for prose descriptions more, such as:
"align-self": {
"initial": "auto"
},
"all": {
"initialText": "There is no practical initial value for it."
},
"animation": {
"initial": [
"animation-name",
"animation-duration",
"animation-timing-function",
"animation-delay",
"animation-iteration-count",
"animation-direction",
"animation-fill-mode",
"animation-play-state"
]
}
So the default of initial
means "This is a literal value. Display in <code> in HTML" . The new initialText
would mean "This is an English string describing the initial value. Localize it if you wish." This is a bigger change, but I think it will be more compatible with Pontoon-based translations.
@jwhitlock How does the connection to our localization then look like?
Sebastian
I was thinking something like this:
*Text
name, or we have an extra config file that says what keys are English strings (css/properties.json:*.initialText
). Strings are stored in https://github.com/mozilla-l10n/mdn-l10n, under data.po
files.po
files or as JSONMy plan may change as I implement localization in the KumaScript macros. I plan to get this working for .ejs
files first, but we have .json
files there as well (overview
in GroupData.json looks like it should be localized in some contexts). I'd want to tackle strings in this repo after the main Kumascript repo.
In data/css/properties.json, the
initial
value can be:0
,0% 0%
,none
, orauto
. This used to be wrapped like<code>0</code>
noneButOverriddenInUserAgentCSS
ornoPracticalInitialValue
.I've proposed https://github.com/mozilla/kumascript/pull/162 to distinguish between cases 1 and 2, but it would be better to have a clearer signal in the data. Some straw man suggestions:
Different Keys for literal vs. prose initial values. Advantage - unambiguous. Disadvantage - users must update.
Prefix for prose value, none for literals. Advantage - same key, quick check for literal vs prose. Disadvantage - pick a universal prefix, users must process to get prose key.
Initial objects instead of strings. Advantage - unambiguous, allows for future expansion, mixing literals and prose. Disadvantage - detect object vs list, overly wordy.