Semantic Comments Proposal: Meta information

[zbraniecki]

This is part of the series of proposals spanning out of the meta #16.

Meta information

Meta information lies at the core of the semantic comments proposal. The idea is to enable us to encode information about the file, group or particular message, that is not critical for runtime to know, but can be used as an additional clue for linters, tooling and localizers.

It can also help organizing information already present in the comment. While a human can read a message like this:

# This message is going to be displayed on a button in the
# UI for license acceptance. Please, use formal and polite tone
# and don't use any HTML since it will be stripped.
#
# Firefox brand should be adjusted within the Firefox Brand Policy.
#
license-accept-button = I have read Firefox Policy and accept the license terms

for all of our tooling this is basically useless. On the other hand this:

# A message displayed in the UI for license acceptance
#
# @context button
# @tone formal, polite
# @mode simple
# @policy firefox-brand-policy
license-accept-button = I have read Firefox Policy and accept the license terms

can be interpreted by both Pontoon, and our checks to aid the localizer in getting the translation right. What's more, translation memory can also help prioritize terms that come from the same context or use the same tone tags over unrelated terms.

The example above is pretty extreme and serves just as an example. Agreeing on the meta-information proposal doesn't require us to standardize any particular keyword, but establishes a framework within which we can discuss each one of them separately.

Those are of course just examples. My intention is to initially collect use cases, and settle on what open ended syntax we'd like to use.

Use cases

• UI context of the message
• Tone/formality of the message
• Mode/Toolkit - HTML, React, no-html, simple etc.
• License ID
• Policy meta-information (brand usage etc.)
• Message versions (tier 2) (Semantic Comments Proposal: String Versions #141)
• Variables (Semantic Comments Proposal: Variables #140)
• ...

Implementation

I'm not very opinionated on the exact syntax we'll use. I'd like to initially seek agreement that there's a value in formalizing such meta information system, and then identify the exact data model we'd like to use.
We can look at prior work like JSDoc and consider a simple key-value, or more complex key-value-type-description, or anything in between.

Prior work

• JSDoc
• ...

[zbraniecki]

Another use case added by @msujaws today. A semantic comment on a file level could set some sort of dependencies or requirements on other resources or message ids.

That would allow us to write tools to find cases where a context is build for a document with a file but not its dependency.

[JohnHeitmann]

There should be a way for a file to indicate that it inherits its metadata from some other file so that translations don't have to maintain duplicate metadata. Duplicate metadata might be onerous to keep in sync for some workflows, and might also cause tool confusion if type information disagrees.